@plimsollmark/client weekly downloads statistics

@plimsollmark/client

A TypeScript client for plimsolld, plus three add-ons that give an agent an executeCode tool backed by plimsoll: one for the Vercel AI SDK, one for Trigger.dev chat agents and one for Mastra agents. All three sit on the same client and the same per-conversation sandbox layer, so they behave the same way.

The client has no runtime dependencies (Node >= 22.18). It speaks Connect's JSON protocol over fetch and keeps the promises the Go client keeps:

• it states the protocol number on every request; • it checks every answer's run record: it recomputes the request and result digests from what it sent and received (run-records.md), and an answer that does not check, or has no record, is a data_loss error with the result attached, because the code may have run; • it checks the reported isolation tier against the caller's floor the same way; • in a session it tracks the chain of records, so a call made by anyone else who holds the session ID is caught at the next call, and at close; • an error says whether anything ran: notDispatched is set only when the daemon stated that nothing did, and only then is a retry safe; • every request carries a fresh Plimsoll-Request-Id and an answer counts only if it carries the ID back: one that does not (another request's answer, served by an intermediary, or a daemon older than protocol 3) has answerNotBound set and no notDispatched, and a success of that kind is a data_loss error.

The tier it reports is configuration and provider evidence, never runtime attestation (the README's provider table says what each tier means).

Install

The package's version is the plimsoll release it ships in: version X.Y.Z was built and tested against plimsolld vX.Y.Z. The add-ons need their framework installed beside it: ai and zod for /ai-sdk, @trigger.dev/sdk, ai and zod for /trigger, @mastra/core and zod for /mastra.

This package has no dependencies, so it brings nothing into your installation; the frameworks do. One worth knowing about: @trigger.dev/sdk 4.7 pins socket.io-client 4.7.5, whose engine.io-client resolves a ws affected by two advisories fixed in 8.21.0 (GHSA-58qx-3vcg-4xpx and GHSA-96hv-2xvq-fx4p, EXTERNAL · advisory ↗). npm applies overrides only from your application's own package.json, so this package's override cannot reach your installation. Until Trigger.dev moves, add one there, as this repository's tests do:

The client

A cell's files are written into the session's work directory, the interpreter's working directory, before the code runs. Its result adds interpreterStarted (this call began with a fresh interpreter, so nothing defined earlier exists) and interpreterEnded; its exit code is 0 when the code ran, 1 when it raised and 124 at the deadline. Python needs python3 in the daemon's image (plimsoll/sandbox-python has it, with NumPy and SciPy); describe() lists the languages the daemon proved on environments.project.languages.

close() sends one CloseSession however many times it is called, and every later call gets the first one's summary or error: the daemon forgets a session at its first close and would answer a second with NotFound. A close refused not dispatched (aborted before it was sent, say) closed nothing, so a later close() tries again.

Cleartext HTTP is accepted only to a loopback address unless you pass insecureHttp: true.

executeCode for an agent: CodeSandboxes

The executeCode tool takes code, a language ("python" or "javascript"; the languages option sets which the tool offers and the default, Python first unless you say otherwise) and optional files: text files written into the working directory before the code runs, so the model can hand the code another tool's output by path instead of pasting it into the source. The value of the code's last expression is printed, as in a notebook.

Every call of a conversation runs in the same sandbox, so code one call ran can change what later calls see: a call's output is only as trustworthy as the calls before it in that conversation (what a session gives up). The tool's calls are cells, which carry no grant, so no API access is shared between them.

The key decides who shares a sandbox, so derive it from identities you verified. A sandbox holds one trust domain: everything one call leaves there, later calls with the same key see. plimsoll ties a session to the credential that opened it, not to the users behind that credential, so if your service runs many users' code through one plimsoll credential, two users with the same key share one sandbox, files and variables included. Build the key from your own authenticated user and conversation (or job) IDs, never from a string a user or the model supplies, or give each customer a plimsoll credential of their own (who may share a session).

A key is a SandboxKey: either a string (the Trigger.dev add-on passes its run ID) or { owner, conversation }, the user a conversation belongs to and the conversation's ID (the AI SDK add-on passes { owner: userId, conversation: conversationId }, the Mastra add-on { owner: resourceId, conversation: threadId }). The parts are encoded as a JSON array, never joined with a separator, so no user's IDs can spell another user's key or a string key. The owner is what maxSessionsPerOwner counts (below).…

Description from the npm listing.