nexus-ai-pro 2.10.0 → 2.11.0

package/API_STABILITY.md

@@ -41,6 +41,36 @@ 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.

package/CHANGELOG.md

@@ -4,6 +4,76 @@ 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.
@@ -2694,7 +2764,8 @@ 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.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

package/README.md

@@ -299,14 +299,18 @@ 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.
 
 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.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(