nexus-ai-pro 2.9.0 → 2.11.0

package/API_STABILITY.md

@@ -41,6 +41,79 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.11 stage (2.11.0)
+
+Everything 2.11 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/agent/workspace`: `Workspace`, `WorkspaceGlobOptions`, `WorkspaceGrepOptions`,
+  `WorkspaceMatch`, `WorkspacePathError`, `WorkspaceReadOnlyError`, `resolveWorkspacePath()`,
+  `memoryWorkspace()`, `fileWorkspace()`, `storeWorkspace()`, `readOnlyWorkspace()`,
+  `compositeWorkspace()` and their options, `WorkspaceMount`, `workspaceTools()` and
+  `WorkspaceToolsOptions`, and `runWorkspaceConformance()` with its report and check;
+- `DeepAgentOptions.workspace`;
+- `nexus-ai-pro/telephony/telnyx`, with `TelnyxTelephonyProvider` and its config;
+- on `nexus-ai-pro/telephony`: `TelephonyManager.answer()`, `transferCall()`, `joinConference()`,
+  `startRecording()`, `stopRecording()`, `parseRecordingCallback()`, `downloadRecording()`,
+  `deleteRecording()`, `sendMessage()`, and `parseMessageWebhook()`, the matching optional
+  `TelephonyProvider` methods, their request and result types, `TelephonyDialConfig`,
+  `TelephonyConferenceConfig`, and `TelephonyResponseRequest.dial`; `recordingKeeper()` with
+  `RecordingKeeper`, `RecordingKeeperOptions`, `RecordingRetention`, and `KeptRecording`;
+  `telnyxRealtimeAudioOptions()`; the `TelephonyProviderInfo.supports` flags `transfer`,
+  `conference`, `recording`, and `messaging`; `TelephonyWebhookValidationRequest.publicKey`;
+- `NexusAI.telephony`; the operation family `messaging`;
+- `Sandbox` extends `Workspace`, so it gains `writeBytes()`, optional; `SandboxGlobOptions`,
+  `SandboxGrepOptions`, and `SandboxMatch` are the workspace's types under their old names, and
+  `SandboxPathError` is a `WorkspacePathError`.
+
+Changed, each to keep a promise the surface already made:
+- A sandbox's file methods take a leading `/` as the sandbox's root, as the workspace contract
+  says; a path that leaves the root is still refused. The container sandbox rejects reading a
+  missing file with `ENOENT`.
+
+## 2.10 stage (2.10.0)
+
+Everything 2.10 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- on `nexus-ai-pro/protocols/a2a`: `A2aHandler`, which `a2aHandler()` now returns, with `owner`,
+  `recover()`, and `close()`; `A2aRecoveryReport`; `A2aTaskLease` and `A2aTaskRun`, and
+  `A2aTaskRecord.lease`, `run`, and `version`; `A2aTaskStore.claim()`, optional;
+  `A2aServerOptions.lease` and `recoverEveryMs`. The handler is still the request function it was;
+- on `nexus-ai-pro/protocols/acp`: `AcpTurnRecord` and `AcpSessionRecord.turn`;
+- on `nexus-ai-pro/deep-agent`: `DeepSubagent.remote`, `DeepRemoteHelper`, and `DeepRemoteRunResult`;
+- `CompiledGraph.continueWith()`, and `ProtocolGraph.continueWith()` and `state()`, both optional;
+- on `nexus-ai-pro/lifecycle`: `ProviderHealthOutcome`, `OperationLifecycle.reportHealth()`,
+  `OperationLifecycleLike.reportHealth()`, optional, and `LifecycleRuntime.providerHealth`;
+- on `nexus-ai-pro/realtime`: `RealtimeSessionConfig.tenantId`, `userId`, `principal`,
+  `traceContext`, `conversationStore`, and `resume`; `RealtimeConversationOptions.replayItems`;
+  `RealtimeConversationStore`, `MemoryRealtimeConversationStore`, `storeRealtimeConversations()`,
+  `replayRealtimeConversation()`, and `REALTIME_REPLAY_PREFIX`; `GeminiLiveProvider` and
+  `GeminiLiveProviderOptions`; `RealtimeSession.sendImage()` and `sendVideoFrame()`,
+  `RealtimeSessionConfig.video`, `RealtimeImageInput`, `RealtimeImageOptions`, and
+  `RealtimeVideoOptions`; `RealtimeTransport.sendVideo()`, optional;
+- `RealtimeConversationOptions.retainRawAudio`, `RealtimeConversationReducerOptions.inPlace`, and
+  `RealtimePeerConnectionLike.addTransceiver()`, optional;
+- `nexus-ai-pro/realtime/gemini-live`, with `GeminiLiveTransport` and `GeminiLiveTransportOptions`;
+- `nexus-ai-pro/realtime/openai-sip`, with `answerOpenAISipCalls()` and its types, also on
+  `nexus-ai-pro/realtime`;
+- on `nexus-ai-pro/realtime/openai-server` and `nexus-ai-pro/realtime`: `acceptOpenAIRealtimeCall()`,
+  `rejectOpenAIRealtimeCall()`, `referOpenAIRealtimeCall()`, `hangupOpenAIRealtimeCall()`,
+  `verifyOpenAIWebhook()`, `OpenAIRealtimeCallOptions`, `OpenAIWebhookEvent`, `OpenAIWebhookHeaders`,
+  and `OpenAIWebhookVerifyOptions`; `OpenAIWebSocketTransportOptions.callId`.
+
+The realtime family stays experimental, and all of these with it.
+
+Changed, each to keep a promise the surface already made:
+- A realtime session's raw events keep an audio event's size, `delta_bytes`, in place of its audio,
+  unless `retainRawAudio`: a session held every frame it played, about 13 MB a 3-minute call. The
+  `openai-events` export follows.
+- A realtime session announces `conversation.updated` only to a listener, as before, but no longer
+  copies its record for each event when none is listening.
+- A realtime session given a lifecycle runs each turn as a `realtime.turn` operation and charges it
+  as it finishes; its `realtime.session` operation reports the total and charges nothing more. Its
+  usage and cost are the sum of its turns', where each turn's replaced the last before.
+
 ## 2.9 stage (2.9.0)
 
 Everything 2.9 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,211 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.11.0] - 2026-10-18
+
+Workspaces, and telephony in full.
+
+### Added
+
+- **Workspaces: where an agent's files live, apart from where its code runs.** A `Workspace`, on
+  the new `nexus-ai-pro/agent/workspace`, reads, writes, and lists files, and optionally searches
+  them, removes them, and holds bytes, with paths that mean the same in every one. Five ship:
+  `memoryWorkspace()`, `fileWorkspace()`, `storeWorkspace()` on any long-term `Store` (each file its
+  contents and a small tree entry, so listing reads no contents), `readOnlyWorkspace()`, and
+  `compositeWorkspace()`, which mounts several at paths of its own, read-only or not, and searches
+  across them. `workspaceTools()` gives the file tools over any of them, and
+  `runWorkspaceConformance()` holds any workspace to the contract. A `Sandbox` is now a workspace
+  that can also run commands. A deep agent takes `workspace` apart from `sandbox`: its files, skills,
+  instruction files, and offloaded results live in the workspace, and its commands run in the sandbox.
+- `Workspace.writeBytes()`, optional, which the process sandbox now has.
+- **Telephony in full, on a second provider.** `TelnyxTelephonyProvider`, on the new
+  `nexus-ai-pro/telephony/telnyx`, on Telnyx's own call-control protocol: calls placed and answered
+  by command, Ed25519-signed webhooks verified with Web Crypto, media streams that read as Twilio's
+  do, phone numbers, and everything below. `TelephonyManager.answer()` answers a call webhook the same
+  way on either provider: TwiML on Twilio, commands on Telnyx.
+- **Transfer and conferences** on both: `transferCall()` and `joinConference()`, and a `dial` in a
+  webhook answer, rendered as `<Dial>` on Twilio.
+- **Call recordings kept on your terms.** `startRecording()`, `stopRecording()`,
+  `parseRecordingCallback()`, `downloadRecording()`, and `deleteRecording()` on both, and
+  `recordingKeeper()`, which keeps each finished recording in an `AssetStore` to expire under a
+  `RecordingRetention`, deletes the provider's copy, keeps a retried callback's recording once, and
+  sweeps what expired.
+- **Messages, as their own operation family.** `sendMessage()` (SMS and MMS) and
+  `parseMessageWebhook()` on both, running through the client's lifecycle as `messaging` operations.
+- `NexusAI.telephony`, the client's telephony manager; `telnyxRealtimeAudioOptions()`;
+  `TelephonyWebhookValidationRequest.publicKey`.
+- The weekly live workflow runs a Gemini Live session that calls a tool, OpenAI's SIP call control,
+  and the phone numbers of Twilio and Telnyx, where the repository's secrets are set.
+
+### Fixed
+
+- A realtime session's `whenIdle()` resolved while a tool it ran on its own was still running, so
+  the tool's result could be missing from the record, and from the model, after it. It now waits for
+  running tools and their results, though not for a call waiting on a person's confirmation.
+
+### Changed
+
+- A sandbox's file methods take a leading `/` as its root, as every workspace does: the process
+  sandbox and the container sandbox refused such a path unless it was already under their root.
+  `/etc/passwd` is now the workspace's own file, never the container's or the host's.
+- The container sandbox rejects reading a missing file with `ENOENT`, as every workspace does, and
+  passes the workspace conformance suite.
+- The file tools describe their files as the workspace's, not the sandbox's.
+
+### Proof
+
+- `tests/workspaces.test.ts`: every workspace the package ships passes the workspace conformance
+  suite: in memory, on disk, in the memory, SQLite, Postgres, and Redis stores, the process sandbox,
+  and a composite. A composite's shadowing, read-only mounts, and search across mounts.
+- `tests/phone-agent.test.ts`: one phone agent on Twilio and on Telnyx: answered the same way,
+  recorded, streamed through the bridge to a realtime session that hears the caller, answers aloud,
+  texts a receipt, and transfers the call; its recording kept in memory, on disk, and in S3, deleted
+  at the provider, kept once on a retried callback, there the day before its retention ends and gone
+  after the day after's sweep. Without the claim, the expiry, the provider delete, the answer by
+  command, the messaging family, or `whenIdle()` waiting for tools, it fails.
+- `tests/telephony-providers.test.ts`: both providers against stand-ins for their APIs, and Telnyx's
+  webhooks verified with a real Ed25519 key pair: signed, altered, stale, and unsigned.
+- `tests/deep-agent-workspaces.test.ts`: one deep agent does the same work over every workspace and
+  each ends holding the same files; and an agent whose code is in a sandbox, notes in a store, and
+  docs read-only finds each where it belongs. Without the composite's shadowing, its read-only
+  mounts, the store's directory filter, or the agent taking its files from the workspace, a test
+  fails.
+
+## [2.10.0] - 2026-10-16
+
+Durable conversations, and a second realtime provider.
+
+### Added
+
+- **A2A tasks that outlive their replica.** A working task's record now holds an `A2aTaskLease` and
+  an `A2aTaskRun`. The lease names the replica running the task, which renews it every third of
+  `lease.ms` (30 seconds); the run says what the task was asked to do. `a2aHandler()` returns an
+  `A2aHandler`: the request handler, plus `recover()` and `close()`. `recover()` takes over working
+  tasks whose lease lapsed, and carries each run on in one of three ways:
+  - from the graph's last checkpoint;
+  - by answering its questions again, when a resume never reached the graph;
+  - from the start, when the run left no checkpoint.
+
+  `recoverEveryMs` runs it on a timer. `A2aTaskStore.claim()` takes a lease in one step, so two
+  replicas recovering at once take a task once. `MemoryA2aTaskStore` has it, and `storeA2aTasks()`
+  builds it on `putIfVersion()`. A replica that finds its lease taken stops its run, and never
+  records its result over the other's.
+- **ACP turns that outlive the agent.** While a prompt runs, its session record holds an
+  `AcpTurnRecord`. When the editor reopens the session with `session/load`, the agent carries the
+  turn on, streaming its updates: from the graph's last checkpoint, by answering again, or from the
+  start. A turn stopped while the editor was deciding an approval asks for it again.
+- **Realtime on the client's lifecycle.** A session given `ai.lifecycle` runs as `realtime.session`,
+  and each model turn as `realtime.turn`, carrying the session's `tenantId`, `userId` (the
+  `principal`'s by default), and `traceContext`. A turn is admitted as it starts, rate-limited,
+  authorized, and holding the average turn cost against the budget, and charged its cost when it
+  finishes. A turn the lifecycle refuses is cancelled before the model runs it, and the session ends
+  with `lifecycle_refused`. Connections are reported to the client's provider health and circuit
+  breaker through the new `reportHealth()`, on `OperationLifecycleLike` and `OperationLifecycle`,
+  with `ProviderHealthOutcome` and `LifecycleRuntime.providerHealth`.
+- **Realtime conversations that outlive their process.** `conversationStore`, a
+  `RealtimeConversationStore`, keeps the record after each committed turn:
+  `MemoryRealtimeConversationStore`, or `storeRealtimeConversations()` on any `Store`. `resume`
+  carries a conversation on, from its record or its id: same id, items, metrics, and metadata. On
+  connecting, the provider is given what was said and what the tools returned before anything new,
+  through `replayRealtimeConversation()`. Echoes carry `REALTIME_REPLAY_PREFIX` and are not recorded
+  twice. `conversation.replayItems` caps the replay.
+- **Gemini Live, behind the same realtime session.** `GeminiLiveTransport`, on the new
+  `nexus-ai-pro/realtime/gemini-live`, speaks Gemini's Live API, and `GeminiLiveProvider`, on
+  `nexus-ai-pro/realtime`, creates sessions on it for `createRealtimeAgent()`. The session's
+  configuration becomes Gemini's setup; audio, messages, and tool results become its realtime input,
+  turns, and tool responses; and its audio, transcripts, tool calls, interruptions, and usage become
+  the events the session already reads. It takes an API key on a server or an ephemeral token
+  anywhere, and reconnects a dropped socket with Gemini's latest resumption handle.
+- **Helpers on another server, whose runs outlive their worker.** A `DeepSubagent` with `remote`, a
+  `DeepRemoteHelper` such as `createRemoteGraph()` returns, runs on another agent server, as a run
+  leased to the worker that runs it: when that worker stops, another takes it over. The agent starts
+  the run under a key made from the call that started it, so delegating again or collecting it, in
+  this process or another, finds the same run; a background task is marked on its thread first, so a
+  run that never reached the server is started by the process that collects it. Its answer comes from
+  a `DeepRemoteRunResult`.
+- **Phone calls answered by a realtime agent, over SIP.** `answerOpenAISipCalls()`, on the new
+  `nexus-ai-pro/realtime/openai-sip`, handles OpenAI's `realtime.call.incoming` webhook: it verifies
+  each delivery, claims it so a retry answers its call once, and answers the call with the session
+  `answer()` chooses from the caller, which attaches to the call and runs it with its tools,
+  record, and lifecycle; or declines it with a SIP status. `OpenAISipCall` transfers and hangs up.
+  The call control is on `nexus-ai-pro/realtime/openai-server` too: `acceptOpenAIRealtimeCall()`,
+  `rejectOpenAIRealtimeCall()`, `referOpenAIRealtimeCall()`, `hangupOpenAIRealtimeCall()`, and
+  `verifyOpenAIWebhook()`, on Web Crypto. `OpenAIWebSocketTransportOptions.callId` attaches a
+  transport to a call.
+- **A published method and budget for realtime turn latency and session load.** `npm run
+  bench:realtime`, in the release gate, holds what a session adds to a message (under 5 ms at p99 for
+  one call, under 20 ms with 250 calls at real time), that a turn late in a long call costs what an
+  early one does, that 250 calls at real time keep up, the heap each session holds, and that ended
+  sessions leave nothing. Budgets are in `realtime-budget.json`.
+- **Realtime over real WebRTC in a browser.** `npm run test:browser:realtime`, in `npm test`, drives a
+  session in headless Chromium against a peer connection in the page that plays the provider: real
+  SDP, ICE, DTLS, and data channel, the microphone up, the model's voice down, a tool call, and a
+  session with no microphone.
+- `retainRawAudio` on a realtime conversation's options, `inPlace` on
+  `RealtimeConversationReducerOptions`, and `addTransceiver()`, optional, on
+  `RealtimePeerConnectionLike`.
+- **Video and images in a realtime session.** `sendVideoFrame()` streams camera or screen frames:
+  as realtime video on Gemini Live, as images in the conversation elsewhere, spaced by
+  `RealtimeVideoOptions.minIntervalMs`. `sendImage()` adds an image, with text, to the conversation.
+  `RealtimeTransport.sendVideo()`, optional, is what a transport with video input implements.
+- `continueWith()` on a compiled graph: `continue()`, returning the final result.
+  `ProtocolGraph.continueWith()` and `state()`, both optional, are what A2A and ACP carry a run on
+  with.
+
+### Fixed
+
+- The WebRTC transport trimmed the SDP answer's final line break, and Chromium refuses a description
+  whose last line has none, so a session in Chrome or Edge never connected.
+- A WebRTC session that sent no microphone offered no audio to receive, so it never heard the model.
+- A realtime session copied its whole conversation record twice for every event, so each event cost
+  more as the call went on: a turn took 39 ms by the 500th, and 250 calls took half a core. It now
+  applies events in place and copies the record only for a `conversation.updated` listener.
+- An A2A `SendMessage` with `returnImmediately`, whose store failed while the task ran, raised an
+  unhandled rejection, which ends a Node process by default. A store that cannot record a task's
+  failure now leaves the task working, with its lease, for the replica that takes it over.
+- A realtime session's usage and estimated cost are the sum of its responses'. Before, each
+  response's usage replaced the last, so a session recorded, and settled, only its last turn.
+
+### Proof
+
+- `tests/conversation-crash.test.ts`: an A2A task, an ACP turn, and a realtime conversation are each
+  killed at every write a clean run makes, and taken over elsewhere. Each ends as the clean run did,
+  or its caller was told it never started; nothing is left half done, and nothing is recorded twice.
+  The suite found three defects before they shipped, each fixed: an unhandled rejection from a
+  failing store; a task submitted to a replica that stopped before starting it, which no replica
+  would ever start; and a reopened session's save that dropped the turn it was about to carry on.
+- `tests/deep-agent-remote-helpers.test.ts`: against two replicas of a real agent server, the agent's
+  process and the worker running its remote helper both die; the second replica takes the run over,
+  and the agent, resumed in a new process, collects that same run: one run, its answer, and the
+  agent's note not written again. Without the key, the resumed agent starts a second run, and the
+  proof fails.
+- `tests/realtime-sip.test.ts`: a signed incoming-call delivery is accepted with the agent's session,
+  chosen from the caller's number; the session attaches by the call's id, books a table through its
+  tool when the caller asks, and hangs up. Forged, altered, and stale deliveries answer nothing; a
+  retry after a failed accept answers the call, and a duplicate, on one replica or two, answers it
+  once. Without the signature check, the claim, or the release, a test fails.
+- `tests/realtime-gemini.test.ts`: one agent definition (instructions, a tool, conversation settings)
+  runs on OpenAI's realtime API and on Gemini Live, each over its own scripted wire protocol. The two
+  records match item for item: what the person asked, the tool call and its result, and what the model
+  answered, with the same usage, and the tool runs once on each. Without the tool response, or with
+  the request for a response not dropped after it, the proof fails.
+- `tests/realtime-lifecycle.test.ts`: through a real client with a five-cent budget, two
+  two-cent turns run, and the third is cancelled as it starts and ends the session; the budget holds
+  four cents, and every operation names the tenant and user. Connection failures open the client's
+  circuit. Without the admission at the turn's start, the proof fails.
+- `tests/realtime-resume.test.ts`: a session's process is killed mid-conversation on the memory and
+  SQLite stores. Another resumes it by id on a new transport, and gives the provider what was said
+  before anything new. The conversation goes on under its own id with nothing recorded twice.
+  Without the replay, or without skipping the echoes, the proof fails.
+- `tests/a2a-takeover.test.ts`: a task whose replica dies halfway through a tool is taken over, on
+  the memory, SQLite, Postgres, and Redis stores. The model call the dead replica finished is not
+  made again, and the email it never sent is sent once. Two replicas recovering at the same moment
+  take the task over once, and a lease renewed while a slow task works is never taken. Without the
+  lease check, or carried on from the start instead of the checkpoint, the proof fails.
+- `tests/acp-turns.test.ts`: an agent stopped halfway through a tool is started again and its
+  session reopened; the turn goes on without repeating the finished model call, and sends the email
+  once. A turn stopped during an approval asks again. Without the recovery on load, the proof fails.
+
 ## [2.9.0] - 2026-10-15
 
 Video, and everything shipped, proven.
@@ -2559,7 +2764,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.9.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.11.0...HEAD
+[2.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.10.0...v2.11.0
+[2.10.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.9.0...v2.10.0
 [2.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.8.0...v2.9.0
 [2.8.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.7.0...v2.8.0
 [2.7.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.6.0...v2.7.0

package/README.md

@@ -294,14 +294,23 @@ Shipped so far:
   priced per second; online evaluation that reads every run however many share a millisecond, and
   budget reservations a dead worker leaves settled by what its call did; a deep agent's helper limit
   across processes; a media index that remembers what it holds; and the experimental families run
-  against their live services every week.
+  against their live services every week;
+- 2.10 durable conversations, and a second realtime provider: A2A tasks, ACP turns, and realtime
+  sessions taken over by another worker when theirs dies, each proven killed at every write; realtime
+  on the client's lifecycle; Gemini Live behind the same session, with video and images; phone calls
+  answered over SIP; helpers on another server whose runs outlive their worker; and realtime over
+  real WebRTC in a browser, with published budgets for turn latency and session load;
+- 2.11 workspaces, and telephony in full: an agent's files apart from where its code runs, in memory,
+  on disk, in any long-term store, read-only, or a composite of several; and a second phone provider,
+  Telnyx, beside Twilio, both answering, transferring, conferencing, recording under a retention
+  policy, and sending and receiving messages.
 
 Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
 [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
-Next, 2.10 makes every conversation that runs on a worker durable, A2A tasks, ACP turns, and
-realtime sessions, and adds Gemini Live as a second realtime provider; Pinecone, images, the Gemini
-embedding batch tier, media understanding, and video graduate once the live workflow passes against
-each. The
+Next, 2.12 makes observability lose nothing, with spans spooled when the collector is down and
+deployment evaluation that reads the whole trace, and makes media something you can evaluate.
+Pinecone, images, the Gemini embedding batch tier, media understanding, video, Gemini Live, SIP, and
+both phone providers graduate once the live workflow passes against each. The
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
 applications ask for it.
 

package/dist/agent/files.d.ts

@@ -0,0 +1,36 @@
+/** The file methods of a directory on disk. */
+export interface DirectoryFiles {
+    readFile(file: string): Promise<string>;
+    writeFile(file: string, content: string): Promise<void>;
+    listFiles(directory?: string): Promise<string[]>;
+    removeFile(file: string): Promise<void>;
+    glob(pattern: string, options?: {
+        cwd?: string;
+        limit?: number;
+    }): Promise<string[]>;
+    grep(pattern: string, options?: {
+        cwd?: string;
+        glob?: string;
+        ignoreCase?: boolean;
+        limit?: number;
+    }): Promise<Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>>;
+    readBytes(file: string): Promise<Uint8Array>;
+    writeBytes(file: string, bytes: Uint8Array): Promise<void>;
+}
+/** The files under `root`, refusing a path outside it with the error `refuse` makes. */
+export declare function directoryFiles(rootDirectory: string, refuse: (path: string) => Error): DirectoryFiles & {
+    ready: Promise<DirectoryHandle>;
+};
+/** What a directory's file methods hold once Node's modules have loaded. */
+export interface DirectoryHandle {
+    fs: typeof import('node:fs/promises');
+    dirname: typeof import('node:path').dirname;
+    join: typeof import('node:path').join;
+    relative: typeof import('node:path').relative;
+    root: string;
+    inside: (file: string) => string;
+}

package/dist/agent/files.js

@@ -0,0 +1,112 @@
+import { GREP_FILE_BYTES, GREP_TOTAL_BYTES, globMatcher, matchingLines, SKIPPED_DIRECTORIES, WALK_LIMIT, } from './glob.js';
+export function directoryFiles(rootDirectory, refuse) {
+    const ready = (async () => {
+        const [fs, { dirname, isAbsolute, join, relative, resolve }] = await Promise.all([
+            import('node:fs/promises'),
+            import('node:path'),
+        ]);
+        const root = resolve(rootDirectory);
+        await fs.mkdir(root, { recursive: true });
+        const outside = (fromRoot) => fromRoot.startsWith('..') || isAbsolute(fromRoot);
+        const inside = (file) => {
+            let resolved = resolve(root, file);
+            if (outside(relative(root, resolved)) && /^[\\/]/.test(file))
+                resolved = resolve(root, file.replace(/^[\\/]+/, ''));
+            if (outside(relative(root, resolved)))
+                throw refuse(file);
+            return resolved;
+        };
+        return { fs, dirname, join, relative, root, inside };
+    })();
+    ready.catch(() => undefined);
+    const walk = async (directory) => {
+        const { fs, join, relative, root, inside } = await ready;
+        const start = inside(directory);
+        const slash = (path) => path.replace(/\\/g, '/');
+        const files = [];
+        const queue = [start];
+        let walked = 0;
+        while (queue.length > 0 && walked < WALK_LIMIT) {
+            const current = queue.shift();
+            const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                walked += 1;
+                if (walked > WALK_LIMIT)
+                    break;
+                const full = join(current, entry.name);
+                if (entry.isDirectory()) {
+                    if (!SKIPPED_DIRECTORIES.has(entry.name))
+                        queue.push(full);
+                }
+                else if (entry.isFile()) {
+                    files.push({ full, fromRoot: slash(relative(root, full)), fromStart: slash(relative(start, full)) });
+                }
+            }
+        }
+        return files.sort((a, b) => (a.fromRoot < b.fromRoot ? -1 : a.fromRoot > b.fromRoot ? 1 : 0));
+    };
+    return {
+        ready,
+        async readFile(file) {
+            const { fs, inside } = await ready;
+            return fs.readFile(inside(file), 'utf8');
+        },
+        async writeFile(file, content) {
+            const { fs, dirname, inside } = await ready;
+            const target = inside(file);
+            await fs.mkdir(dirname(target), { recursive: true });
+            await fs.writeFile(target, content, 'utf8');
+        },
+        async listFiles(directory = '.') {
+            const { fs, inside } = await ready;
+            return (await fs.readdir(inside(directory))).sort();
+        },
+        async removeFile(file) {
+            const { fs, root, inside } = await ready;
+            const target = inside(file);
+            if (target === root)
+                throw refuse(file);
+            await fs.rm(target, { recursive: true, force: true });
+        },
+        async glob(pattern, options = {}) {
+            const matches = globMatcher(pattern);
+            return (await walk(options.cwd ?? '.'))
+                .filter((file) => matches(file.fromStart))
+                .slice(0, options.limit ?? 1_000)
+                .map((file) => file.fromRoot);
+        },
+        async grep(pattern, options = {}) {
+            const { fs } = await ready;
+            const expression = new RegExp(pattern, options.ignoreCase ? 'i' : '');
+            const only = options.glob ? globMatcher(options.glob) : undefined;
+            const limit = options.limit ?? 200;
+            const found = [];
+            let scanned = 0;
+            for (const file of await walk(options.cwd ?? '.')) {
+                if (only && !only(file.fromStart))
+                    continue;
+                const size = (await fs.stat(file.full).catch(() => undefined))?.size;
+                if (size === undefined || size > GREP_FILE_BYTES)
+                    continue;
+                scanned += size;
+                if (scanned > GREP_TOTAL_BYTES)
+                    break;
+                const lines = matchingLines(await fs.readFile(file.full), expression, limit - found.length);
+                found.push(...lines.map((match) => ({ file: file.fromRoot, ...match })));
+                if (found.length >= limit)
+                    break;
+            }
+            return found;
+        },
+        async readBytes(file) {
+            const { fs, inside } = await ready;
+            return new Uint8Array(await fs.readFile(inside(file)));
+        },
+        async writeBytes(file, bytes) {
+            const { fs, dirname, inside } = await ready;
+            const target = inside(file);
+            await fs.mkdir(dirname(target), { recursive: true });
+            await fs.writeFile(target, bytes);
+        },
+    };
+}

package/dist/agent/middleware/filesystem.d.ts

@@ -1,7 +1,7 @@
 import type { AgentMiddleware } from '../create-agent.js';
-import type { Sandbox } from '../sandbox.js';
-/** Where `filesystemContext()` reads and writes: a `Sandbox`, or anything with the same file methods. */
-export type FilesystemContextSource = Pick<Sandbox, 'readFile'> & Partial<Pick<Sandbox, 'writeFile' | 'listFiles'>>;
+import type { Workspace } from '../workspace.js';
+/** Where `filesystemContext()` reads and writes: a `Workspace` or a `Sandbox`, or anything with the same file methods. */
+export type FilesystemContextSource = Pick<Workspace, 'readFile'> & Partial<Pick<Workspace, 'writeFile' | 'listFiles'>>;
 /** Where large tool results go instead of the transcript. */
 export interface ContextOffloadOptions {
     /** Results longer than this, in characters, are offloaded. Defaults to 20,000. */

package/dist/agent/sandbox-container.js

@@ -12,7 +12,8 @@ export function containerSandbox(options) {
         if (unified.includes('\0'))
             throw new SandboxPathError(file);
         const parts = [];
-        for (const segment of (unified.startsWith('/') ? unified : `${workdir}/${unified}`).split('/')) {
+        const rooted = unified === workdir || unified.startsWith(`${workdir}/`);
+        for (const segment of (rooted ? unified : `${workdir}/${unified.replace(/^\/+/, '')}`).split('/')) {
             if (segment === '' || segment === '.')
                 continue;
             if (segment !== '..')
@@ -147,9 +148,10 @@ export function containerSandbox(options) {
     };
     const readBytes = async (file) => {
         const result = await shell('cat "$1"', [inside(file)]);
-        if (result.code !== 0)
-            throw failed(`Reading ${file}`, result);
-        return result.stdout;
+        if (result.code === 0)
+            return result.stdout;
+        const error = failed(`Reading ${file}`, result);
+        throw /no such file/i.test(result.stderr) ? Object.assign(error, { code: 'ENOENT', path: file }) : error;
     };
     return {
         name: `container (${binary} ${options.image})`,

package/dist/agent/sandbox.d.ts

@@ -1,5 +1,6 @@
 /**
- * The sandbox contract: where an agent's commands and code run, and where its files live.
+ * The sandbox contract: where an agent's commands and code run. A sandbox is a `Workspace` that can
+ * also run commands, and says how it is isolated, so its files are the files its commands see.
  *
  * The package ships the contract and a conformance suite, not the isolation: a container, a VM, a
  * remote interpreter, or a hosted sandbox fills the `Sandbox` interface. `processSandbox()` is a
@@ -7,6 +8,7 @@
  * `isolation`, and is never a security boundary.
  */
 import type { ToolDefinition } from '../types/messages.js';
+import { type Workspace, type WorkspaceGlobOptions, type WorkspaceGrepOptions, type WorkspaceMatch, WorkspacePathError } from './workspace.js';
 /** Options for one command. */
 export interface SandboxExecOptions {
     /** The working directory, inside the sandbox. Defaults to its root. */
@@ -33,33 +35,12 @@ export interface SandboxExecResult {
     /** How long it ran, in milliseconds. */
     durationMs: number;
 }
-/** Options for `Sandbox.glob()`. */
-export interface SandboxGlobOptions {
-    /** The directory to search, inside the sandbox. Defaults to its root. */
-    cwd?: string;
-    /** The most paths returned. Defaults to 1,000. */
-    limit?: number;
-}
-/** Options for `Sandbox.grep()`. */
-export interface SandboxGrepOptions {
-    /** The directory to search, inside the sandbox. Defaults to its root. */
-    cwd?: string;
-    /** Searches only the files whose paths, relative to `cwd`, match this glob. */
-    glob?: string;
-    /** Matches without regard to case. */
-    ignoreCase?: boolean;
-    /** The most matching lines returned. Defaults to 200. */
-    limit?: number;
-}
-/** One line `Sandbox.grep()` matched. */
-export interface SandboxMatch {
-    /** The file, relative to the sandbox's root. */
-    file: string;
-    /** The line's number, counting from 1. */
-    line: number;
-    /** The line, cut to 300 characters. */
-    text: string;
-}
+/** Options for `Sandbox.glob()`: a workspace's. */
+export type SandboxGlobOptions = WorkspaceGlobOptions;
+/** Options for `Sandbox.grep()`: a workspace's. */
+export type SandboxGrepOptions = WorkspaceGrepOptions;
+/** One line `Sandbox.grep()` matched: a workspace's match. */
+export type SandboxMatch = WorkspaceMatch;
 /** What a sandbox claims to isolate. The conformance suite checks the claims it can observe. */
 export interface SandboxIsolation {
     /** Commands cannot read or write the host's files. */
@@ -69,42 +50,20 @@ export interface SandboxIsolation {
     /** Commands cannot see or signal the host's processes. */
     processes: boolean;
 }
-/** Where an agent's commands, code, and files go. The application provides one. */
-export interface Sandbox {
-    /** Names the sandbox in reports. */
-    readonly name: string;
+/**
+ * Where an agent's commands and code run: a workspace that can also run commands, and says what it
+ * isolates. The application provides one.
+ */
+export interface Sandbox extends Workspace {
     /** What it isolates. */
     readonly isolation: SandboxIsolation;
-    /** Runs a command line in the sandbox. */
+    /** Runs a command line in the sandbox, where its files are. */
     exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
-    /** Reads a file, by a path inside the sandbox. */
-    readFile(file: string): Promise<string>;
-    /** Writes a file, creating its directory. */
-    writeFile(file: string, content: string): Promise<void>;
-    /** Lists a directory's entries. */
-    listFiles?(directory?: string): Promise<string[]>;
-    /** Removes a file or directory. */
-    removeFile?(file: string): Promise<void>;
-    /**
-     * The files under a directory whose paths match a glob, such as `src/**\/*.ts`, sorted. The glob
-     * matches paths relative to `cwd`; the paths returned are relative to the root, as `readFile`
-     * takes them. Returns at most `limit`.
-     */
-    glob?(pattern: string, options?: SandboxGlobOptions): Promise<string[]>;
-    /**
-     * The lines matching a regular expression in the files under a directory, at most `limit`. Large
-     * files and binary files are skipped.
-     */
-    grep?(pattern: string, options?: SandboxGrepOptions): Promise<SandboxMatch[]>;
-    /** Reads a file's bytes, for an image, audio, or a document. */
-    readBytes?(file: string): Promise<Uint8Array>;
     /** Releases the sandbox. */
     dispose?(): Promise<void>;
 }
-/** Raised when a path would leave the sandbox. */
-export declare class SandboxPathError extends Error {
-    /** The path that was refused. */
-    readonly path: string;
+/** Raised when a path would leave the sandbox: a `WorkspacePathError` whose code is `SANDBOX_PATH`. */
+export declare class SandboxPathError extends WorkspacePathError {
     /** Always `SANDBOX_PATH`. */
     readonly code = "SANDBOX_PATH";
     constructor(