nexus-ai-pro 2.10.0 → 2.12.0

package/API_STABILITY.md

@@ -41,6 +41,80 @@ 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.12 stage (2.12.0)
+
+Everything 2.12 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/tracing/spool`: `spoolingExporter()`, `SpoolingExporter`, `SpoolingExporterOptions`,
+  `TraceBatchSender`, `SpoolStats`, and `SpoolDrainReport`;
+- `OtlpTraceExporter.send()`;
+- `RunManagerOptions.tracer` and `AgentServerOptions.tracer`, and `RunRecord.traceId`;
+- `Deployments.evaluationWorker()` and `DeploymentEvaluationWorkerOptions`; `RunEvaluationOptions`
+  gains `traces`, `operations`, `pollMs`, and the worker's options, and `RunEvaluationReport` gains
+  `failed`;
+- in `nexus-ai-pro/evaluate`: `traceEvidence()`, `mediaParts()`, `EvaluationTrace`, `MediaPart`,
+  `TraceToolCall`, `TraceRetrieval`, `TraceDocument`, `TraceModelCall`, `TraceMedia`, and
+  `EvaluationContext.trace`;
+- `OnlineEvaluationWorkerOptions.withTrace`, `onScored`, and `onError`, and `OnlineScored`;
+- `traceRetriever()`, `RetrieverLike`, and `Tracer.within()`;
+- `nexus-ai-pro/evaluate/automation`: `automationRules()`, `deploymentScores()`, `traceScores()`,
+  `memoryScores()`, `openReview()`, `sendWebhook()`, `markUnhealthy()`, `AutomationRule`,
+  `AutomationRules`, `AutomationRulesOptions`, `AutomationEvent`, `AutomationAction`,
+  `AutomationStatus`, `AutomationWebhookOptions`, `ScoreSample`, `ScoreSource`, `MemoryScoreSource`,
+  `ReviewOpener`, and `RuleStatistic`;
+- `Deployments.markUnhealthy()`, `markHealthy()`, and `scores()`, `RunScore`, the `health`
+  `DeploymentChange`, `DeploymentRecord.unhealthy`, `RevisionHealthMark`,
+  `DeploymentChangeRecord.revision` and `healthy`, and `CanaryDecision.unhealthy`;
+- `nexus-ai-pro/evaluate/media`: `mediaChecks()`, `mediaJudge()`, `mediaOf()`, `resolveMedia()`,
+  `MediaCheckOptions`, `MediaJudgeOptions`, `MediaResolveOptions`, `MediaSelection`, `MediaRange`,
+  `ResolvedMedia`, and `MediaSubjectKind`;
+- `nexus-ai-pro/media/catalog`: `mediaCatalog()`, `catalogedAssetStore()`, `MediaCatalog`,
+  `MediaCatalogOptions`, `MediaCatalogEntry`, `MediaCatalogQuery`, `MediaCatalogPage`,
+  `MediaCatalogStats`, `MediaCatalogRecordOptions`, `CatalogScore`, `CatalogMediaKind`, and
+  `CatalogedAssetStoreOptions`;
+- `nexus-ai-pro/tracing/otlp-grpc`: `OtlpGrpcTraceExporter`, `OtlpGrpcTraceExporterOptions`, and
+  `OtlpGrpcError`;
+- in `nexus-ai-pro/tracing/otlp`: `OtlpTraceExporterOptions.protocol`, `encodeOtlpTraceRequest()`,
+  `decodeOtlpTraceResponse()`, `OtlpExportRequest`, `OtlpKeyValue`, `OtlpAttributeValue`,
+  `OtlpPartialSuccess`, and `OtlpPartialSuccessError`.
+
+Changed: `DeploymentChange` gains a `health` action, so a `switch` over its actions that must be
+exhaustive needs a case for it.
+
+Changed: `Deployments.evaluate()` runs through the online-evaluation worker, scoring up to 4 runs at
+once rather than one, so evaluators that are not safe to call concurrently need `concurrency: 1`.
+
+## 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.

package/CHANGELOG.md

@@ -4,6 +4,191 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-10-18
+
+Observability that loses nothing, and media you can evaluate.
+
+### Added
+
+- **Spans that a collector being down cannot lose.** `spoolingExporter()`, on the new
+  `nexus-ai-pro/tracing/spool`, keeps each batch the collector refuses in an operation store (the
+  memory, Redis, Postgres, or SQLite one), retries it with backoff, and dead-letters it only once it is
+  too old or has failed too often, under a bound on what waits. Every replica on the store drains the
+  same spool, each batch once. `writeAhead` spools each batch before sending it. `stats()` reports
+  what was exported, retried, spooled, dropped, and dead-lettered, and the age of the oldest batch
+  waiting.
+- `OtlpTraceExporter.send()`: sends runs as one batch now, and rejects when the collector refuses
+  them.
+- **A deployment judged by what its runs did.** An agent server given a `tracer` makes each run the
+  root of a trace, with its input and output, and everything the assistant traces through the same
+  tracer beneath it; the run records the trace as `RunRecord.traceId`. `Deployments.evaluate()`
+  given those `traces` hands each evaluator the run's input and an `EvaluationTrace` of its tool
+  calls, retrievals, model calls, and media, read by the new `traceEvidence()`, which `mediaParts()`
+  backs. An assistant that traces itself is found by the run id it records.
+- `Deployments.evaluationWorker()`: the online-evaluation worker over a deployment's runs, to start
+  on every replica, scoring each run once between them as it finishes.
+- `onlineEvaluationWorker()` takes `withTrace`, which gives evaluators `context.trace`, and
+  `onScored`, which hears each run's scores once they are written, with `onError` for its failures.
+- `traceRetriever()`: every retrieval as a `retriever` run, with the query and the documents.
+- **Media you can evaluate.** On the new `nexus-ai-pro/evaluate/media`, `mediaChecks()` reads the
+  media an evaluation is about, from bytes, base64, a data URL, a URL it is allowed to fetch, a path,
+  or an asset store, and scores each check asked: the count, kind, MIME type, size, dimensions,
+  aspect ratio, and a WAV's duration. `mediaJudge()` shows them to a vision or audio model beside a
+  rubric and the brief, a stored asset sent as its bytes, and records the judge in an experiment.
+  `mediaOf()` finds the media in an output, or in what the run's trace says it produced, and
+  `resolveMedia()` reads one.
+- **Automation rules.** On the new `nexus-ai-pro/evaluate/automation`, `automationRules()` judges
+  a score over each revision's most recent runs, and when it falls below a threshold over enough
+  samples (optionally by the upper bound of a confidence interval), acts once, across every replica
+  sharing its `state`: `openReview()` sends the worst runs to people, `sendWebhook()` posts a signed
+  event, and `markUnhealthy()` marks the revision unhealthy, which rolls a canary back. Rules read
+  scores a deployment's run records hold (`deploymentScores()`), a trace store's
+  (`traceScores()`), or this process's (`memoryScores()`), and `observe()` judges them as an online
+  evaluation writes them. A rule fires once per fall, recovers, and can repeat.
+- **A revision's health.** `Deployments.markUnhealthy()` and `markHealthy()`: a `health` change in
+  the deployment's history, kept in `DeploymentRecord.unhealthy`. A canary marked unhealthy is rolled
+  back at once, and a canary guard rolls back any canary marked since it began, its `CanaryDecision`
+  carrying the mark. The studio shows each revision's health and marks one from the deployment view.
+  `Deployments.scores()` reads the scores of an assistant's runs.
+- **A catalog of every stored asset.** `mediaCatalog()`, on the new `nexus-ai-pro/media/catalog`,
+  keeps one record of each stored asset in any long-term store (Postgres, SQLite, Redis, or memory):
+  what it is, who made it, for which run, its tags, and its latest score per key, written by
+  compare-and-set. `catalogedAssetStore()` wraps any asset store so every asset stored through it is
+  recorded and every one deleted is forgotten, an entry expiring with its asset. `list()` finds
+  entries by kind, type, provider, model, run, store, tag, time, and score, a page at a time;
+  `attach()` scores the assets a run's output refers to; `stats()`, `purgeExpired()`, and
+  `reconcile()` keep account.
+- **OTLP over gRPC.** `OtlpGrpcTraceExporter`, on the new `nexus-ai-pro/tracing/otlp-grpc`, sends
+  spans to a collector's port 4317 with no gRPC library: the trace service's `Export` call framed by
+  hand over Node's HTTP/2 client, gzip-compressed, with metadata, a deadline, TLS options, one
+  connection kept and reopened, and a failed call rejecting with an `OtlpGrpcError` so a spool keeps
+  the batch. `OtlpTraceExporter` takes `protocol: 'http/protobuf'`, and both read a collector's
+  partial success into an `OtlpPartialSuccessError` for `onError`. `encodeOtlpTraceRequest()` and
+  `decodeOtlpTraceResponse()` are OTLP's protobuf encoding, written by hand, on any runtime.
+- `Tracer.within()`: runs a function with a run started by `startRun()` in scope.
+
+### Changed
+
+- `Deployments.evaluate()` runs through the online-evaluation worker, drained once, instead of beside
+  it. Replicas given one `operations` store score each run once between them, even calling at the
+  same moment, where before two calls could score a run twice; it takes the worker's budget, review
+  queue, and concurrency (4 at a time by default, one before), and `RunEvaluationReport` counts
+  `failed` evaluations. Which runs a `sampleRate` picks is unchanged.
+
+### Proof
+
+- `tests/trace-spool.test.ts`: a collector stopped for an hour while a span finishes every second,
+  and the process restarted halfway: every one of the 3,600 spans reaches it, once, on the memory,
+  SQLite, Postgres, and Redis operation stores. The bound, dead letters, two replicas on one spool,
+  and write-ahead through a process that dies mid-send. Without the spool, its bound, its claim, its
+  dead letters, write-ahead, or taking over a lapsed lease, a test fails.
+- `tests/media-evaluation.test.ts`: checks that read PNG, GIF, WAV, and PDF media from a store,
+  base64, a data URL, and a fetch only when allowed; a judge model shown a stored asset as its bytes
+  beside the rubric and the brief; media found through the trace; and an experiment over a target
+  that draws. Without the sniffing, the store, the wildcard, the tolerance, the duration, the size
+  limit, the count, the media shown, the brief, or the trace fallback, a test fails.
+- `tests/automation-rules.test.ts`: the proof that a canary is rolled back on a media evaluator's
+  score. A designer assistant's canary draws its banners square; two replicas score 80 runs with a
+  media judge shown each banner, and a rule on the judge's score marks the canary unhealthy, rolling
+  it back, opening review items for the five worst banners, and sending one signed webhook, once
+  between the replicas. The live revision is untouched, new runs go to it, and the media catalog
+  finds each of the canary's banners by its score. Then minimum samples, scopes, windows, the
+  confidence bound, the pass rate, recovery, repeats, filters, sources, failing actions, and a guard
+  rolling back a canary a rule only marked. Without the rollback, the guard's mark, the stale-mark
+  check, the claim, the minimum, the window, recovery, the bound, counting each run once, the
+  revision scope, the signature, or the repeat, a test fails.
+- `tests/media-catalog.test.ts`: on the memory, SQLite, Postgres, and Redis stores, forty assets of
+  five kinds, two providers, and two tenants, some deleted and some expiring: every page lists each
+  remaining asset once, every filter finds exactly its assets, expired ones are never read and are
+  purged with their assets, and ten evaluators scoring one asset at once keep all ten scores. An
+  asset deleted around the catalog is reconciled away, and one the catalog cannot record is not left
+  stored. Without the forgetting, the expiry, the purge, compare-and-set, the cursor, the filters,
+  the compensation, or the reconciliation, a test fails.
+- `tests/otlp-grpc.test.ts`: the OpenTelemetry Collector itself, in a container, takes spans over
+  gRPC and sends every one on as it came, ids, times, kinds, attributes, and status. Against a gRPC
+  server of the test's, with a protobuf reader written apart from the encoder: compression and
+  metadata, a refusal, a deadline, a partial success, a collector that is down, one that restarts
+  under a live connection, and a spool that keeps what is refused. Without the compressed flag, the
+  status, the deadline, the metadata, the parent span, the status message, typed values, the
+  reconnection, or the retry on a dropped connection, a test fails.
+- `tests/deployment-trace-evaluation.test.ts`: a traced server whose assistant retrieves a policy,
+  calls a tool, and asks a model about a photo; its evaluators see the input, the tool call, the
+  documents, the model call, and the photo once. Two replicas evaluating at once over one operation
+  store score each of 40 runs once, where queues of their own score runs twice. A worker scores runs
+  as they finish and hears each score once, and an assistant tracing itself is found. Without the
+  trace, the input, the run scope, the shared queue, the fallback, the media deduplication, or the
+  trace written before the run settles, a test fails.
+
+## [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.
@@ -2694,7 +2879,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.10.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.12.0...HEAD
+[2.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.11.0...v2.12.0
+[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

package/README.md

@@ -299,14 +299,22 @@ Shipped so far:
   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.
+  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;
+- 2.12 observability that loses nothing, and media you can evaluate: spans spooled through a collector
+  outage, OTLP over gRPC, deployment evaluation that reads each run's whole trace, evaluators that
+  read and judge images, documents, audio, and video, a catalog of every stored asset, and automation
+  rules that roll a canary back when a score falls.
 
 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.11 separates where an agent's files live from where its code runs, with workspaces, and
-completes telephony: a second provider, messaging, recording, conference, and transfer. Pinecone,
-images, the Gemini embedding batch tier, media understanding, and video graduate once the live
-workflow passes against each. The
+Next, 2.13 runs agents across regions, keeps each tenant's requests and data in the region they
+require, and resolves provider keys per tenant from a secret manager. 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(