nexus-ai-pro 2.9.0 → 2.10.0

package/API_STABILITY.md

@@ -41,6 +41,49 @@ 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.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,141 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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 +2694,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.9.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.10.0...HEAD
+[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,19 @@ 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.
 
 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.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
 [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/core/lifecycle.d.ts

@@ -1,5 +1,5 @@
 import type { RateLimitConfig } from '../types/config.js';
-import type { LifecycleConfig, LifecycleStage, OperationDescriptor, OperationLifecycleLike, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext } from '../types/lifecycle.js';
+import type { ProviderHealthOutcome, LifecycleConfig, LifecycleStage, OperationDescriptor, OperationLifecycleLike, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext } from '../types/lifecycle.js';
 import type { AuditLogger } from '../ops/audit-logger.js';
 import type { MetricsCollector } from '../ops/metrics.js';
 import { type RateLimiter } from '../ops/rate-limiter.js';
@@ -45,6 +45,11 @@ export interface LifecycleRuntime {
     config?: LifecycleConfig;
     /** Default milliseconds an operation may run before its signal aborts. */
     timeoutMs?: number;
+    /** Where `reportHealth()` goes: the client's provider health and circuit breaker. */
+    providerHealth?: {
+        recordSuccess(provider: string, latencyMs: number): void;
+        recordFailure(provider: string, error: unknown): void;
+    };
 }
 /** The family's part of one operation: what each stage does for it. Every stage but `execute` is optional. */
 export interface OperationPlan<T> {
@@ -99,6 +104,11 @@ export declare class OperationLifecycle implements OperationLifecycleLike {
     }, plan: OperationPlan<T>, options?: OperationStartOptions & {
         audit?: Record<string, unknown>;
     }): Promise<T>;
+    /**
+     * Reports how a provider answered a call a family made itself, such as a realtime connection, to the
+     * client's provider health and circuit breaker.
+     */
+    reportHealth(provider: string, outcome: ProviderHealthOutcome): void;
     /** True when nothing is configured, so a caller may skip work that only feeds the lifecycle. */
     get inert(): boolean;
     private checkRateLimit;

package/dist/core/lifecycle.js

@@ -91,6 +91,15 @@ export class OperationLifecycle {
             throw error;
         }
     }
+    reportHealth(provider, outcome) {
+        const health = this.runtime.providerHealth;
+        if (!health || !provider)
+            return;
+        if (outcome.ok)
+            health.recordSuccess(provider, outcome.latencyMs);
+        else
+            health.recordFailure(provider, outcome.error);
+    }
     get inert() {
         const config = this.runtime.config;
         return (!this.runtime.metrics?.enabled &&

package/dist/core/nexus.js

@@ -75,6 +75,10 @@ export class NexusAI {
             rateLimiter: this.rateLimiter,
             rateLimit: this.config.rateLimit,
             config: this.config.lifecycle,
+            providerHealth: {
+                recordSuccess: (provider, latencyMs) => this.attemptHooks.onAttemptSuccess(provider, latencyMs),
+                recordFailure: (provider, error) => this.attemptHooks.onAttemptFailure(provider, error),
+            },
         });
         const familyRuntime = {
             metrics: this.metrics,

package/dist/deep-agent/helpers.d.ts

@@ -10,6 +10,10 @@
  * The helpers an agent creates are recorded on a thread of their own beside its own, before the call
  * that creates one returns, so an agent resumed in another process counts them against its `max` and
  * delegates to them again by name.
+ *
+ * A remote helper runs on another agent server, as a run that server's workers lease: when the worker
+ * running it stops, another takes it over. The agent starts it under a key made from the call that
+ * started it, so delegating again or collecting it, in this process or another, finds that same run.
  */
 import { type CreateAgentOptions } from '../agent/create-agent.js';
 import type { PermissionPolicyLike } from '../agent/permissions.js';
@@ -29,6 +33,33 @@ export interface DeepHelperLimits {
     /** How many helpers the agent may create in one thread. Defaults to 5. */
     max?: number;
 }
+/** How a run on another agent server ended, as `createRemoteGraph()` reports it. */
+export interface DeepRemoteRunResult {
+    /** The run's id on that server. */
+    runId: string;
+    /** Where it ended: `succeeded`, `failed`, `cancelled`, `expired`, or `awaiting_input`. */
+    status: string;
+    /** What it produced. */
+    output?: unknown;
+    /** Why it failed. */
+    error?: {
+        message?: string;
+    };
+}
+/**
+ * A helper on another agent server: what `createRemoteGraph()` returns, or anything that runs an input
+ * there and waits for it.
+ */
+export interface DeepRemoteHelper {
+    /**
+     * Runs an input there and waits for it to end. A second call with the same `idempotencyKey` waits
+     * for the run the first started, as the agent server does, rather than starting another.
+     */
+    invoke(input: unknown, options: {
+        idempotencyKey: string;
+        signal?: AbortSignal;
+    }): Promise<DeepRemoteRunResult>;
+}
 /** What the deep agent hands the helper tools. */
 export interface HelperSetup {
     /** The helpers the application declared. */
@@ -39,6 +70,7 @@ export interface HelperSetup {
         tools?: readonly string[];
         model?: string;
         maxIterations?: number;
+        remote?: DeepRemoteHelper;
     }>;
     /** Limits on created helpers, when the agent may create them. */
     create?: DeepHelperLimits;

package/dist/deep-agent/helpers.js

@@ -59,6 +59,7 @@ export function helperTools(setup) {
                 ...(helper.model ? { model: helper.model } : {}),
                 maxIterations: helper.maxIterations ?? 20,
                 created: false,
+                ...(helper.remote ? { remote: helper.remote } : {}),
             };
         }
         await loadCreated(thread);
@@ -144,9 +145,50 @@ export function helperTools(setup) {
         return { helper, ok: false, error: `The ${helper} helper stopped: ${why ?? 'it did not run'}` };
     };
     const thread = (parent, task) => `${parent ?? 'thread'}/helper/${task}`;
+    const remoteRun = async (helper, remote, task, key, signal) => {
+        const run = await remote.invoke(agentInput(`${helper.instructions}\n\n${task}`), {
+            idempotencyKey: key,
+            ...(signal ? { signal } : {}),
+        });
+        if (run.status === 'succeeded')
+            return { helper: helper.name, ok: true, answer: remoteAnswer(run.output) };
+        const why = run.status === 'awaiting_input' ? 'it stopped to ask for input' : (run.error?.message ?? run.status);
+        return { helper: helper.name, ok: false, error: `The ${helper.name} helper stopped: ${why}` };
+    };
+    const markRemote = async (helper, task, threadId) => {
+        await setup.checkpointer?.put({
+            version: 2,
+            id: `${threadId}:remote`,
+            threadId,
+            step: 0,
+            state: {},
+            next: [],
+            tasks: [],
+            status: 'running',
+            interrupts: [],
+            createdAt: new Date().toISOString(),
+            metadata: { [MARK]: { name: helper.name, created: false, remote: true, task } },
+        });
+    };
     const start = async (helper, task, threadId, context) => {
         if (live.has(threadId))
             return;
+        if (helper.remote) {
+            if (task !== undefined)
+                await markRemote(helper, task, threadId);
+            const entry = { helper: helper.name, settled: false, outcome: Promise.resolve(undefined) };
+            entry.outcome = remoteRun(helper, helper.remote, task ?? '', threadId)
+                .catch((error) => ({
+                helper: helper.name,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }))
+                .finally(() => {
+                entry.settled = true;
+            });
+            live.set(threadId, entry);
+            return;
+        }
         const runner = graph(helper, true);
         const stored = setup.checkpointer ? await runner.state(threadId) : undefined;
         let ready = () => { };
@@ -220,6 +262,12 @@ export function helperTools(setup) {
             const helper = await spec(String(args.agent ?? ''), typeof args.instructions === 'string' ? args.instructions : undefined, context.threadId ?? '');
             const task = String(args.task ?? '');
             const call = context.toolCallId ?? Math.random().toString(36).slice(2, 10);
+            if (args.background !== true && helper.remote) {
+                const ended = await remoteRun(helper, helper.remote, task, thread(context.threadId, `${helper.name}@${call}`), context.signal);
+                if (!ended.ok)
+                    throw new Error(ended.error);
+                return ended.answer;
+            }
             if (args.background !== true) {
                 const result = await graph(helper, false).invoke(agentInput(task), runOptions(context, `${helper.name}@${call}`, context.signal ? { signal: context.signal } : {}));
                 return (result.state.answer || `The ${helper.name} helper finished without an answer (${result.state.stopReason}).`);
@@ -265,7 +313,7 @@ export function helperTools(setup) {
                 const helper = mark?.created
                     ? await spec(name, mark.instructions, context.threadId ?? '')
                     : await spec(name, undefined, context.threadId ?? '');
-                await start(helper, undefined, threadId, context);
+                await start(helper, mark?.remote ? (mark.task ?? '') : undefined, threadId, context);
             }
             const entry = live.get(threadId);
             const waitMs = Math.min(Math.max(Number(args.wait_seconds) || 0, 0), 120) * 1_000;
@@ -285,3 +333,16 @@ export function helperTools(setup) {
     };
     return [delegate, collect];
 }
+function remoteAnswer(output) {
+    if (typeof output === 'string')
+        return output;
+    if (output && typeof output === 'object') {
+        const record = output;
+        if (typeof record.answer === 'string' && record.answer)
+            return record.answer;
+        const last = record.messages?.filter((message) => message.role === 'assistant').at(-1);
+        if (typeof last?.content === 'string' && last.content)
+            return last.content;
+    }
+    return JSON.stringify(output ?? null);
+}

package/dist/deep-agent/index.d.ts

@@ -13,8 +13,8 @@ import { type ContextOffloadOptions } from '../agent/middleware/filesystem.js';
 import { type ToolSelectorOptions } from '../agent/middleware/tool-selector.js';
 import { type PermissionPolicyLike } from '../agent/permissions.js';
 import { type Sandbox } from '../agent/sandbox.js';
-import { type DeepHelperLimits } from './helpers.js';
-export type { DeepHelperLimits } from './helpers.js';
+import { type DeepHelperLimits, type DeepRemoteHelper } from './helpers.js';
+export type { DeepHelperLimits, DeepRemoteHelper, DeepRemoteRunResult } from './helpers.js';
 /** A helper the deep agent can hand a self-contained piece of work to, with a fresh context. */
 export interface DeepSubagent {
     /** Its name, as the agent delegates to it. */
@@ -33,6 +33,14 @@ export interface DeepSubagent {
     model?: string;
     /** Model calls it may make. Defaults to 20. */
     maxIterations?: number;
+    /**
+     * Runs it on another agent server instead, such as `createRemoteGraph()` reaches: it is sent its
+     * `instructions` and the task, and its run's output is its answer. The run is leased to the
+     * server's worker that runs it, so another worker takes it over when that one stops, and the agent
+     * finds the same run again by the call that started it. `tools`, `model`, and `maxIterations` are
+     * the remote assistant's own.
+     */
+    remote?: DeepRemoteHelper;
 }
 /** Instructions the agent loads only when a task needs them: a procedure, a checklist, a house style. */
 export interface DeepSkill {

package/dist/graph/graph.d.ts

@@ -110,6 +110,11 @@ export declare class CompiledGraph<S extends ChannelSchema, I extends keyof S =
     resumeInterruptsWith(threadId: string, answers: Record<string, unknown>, runOptions?: GraphRunOptions): Promise<GraphResult<S, O>>;
     /** Continues a thread that stopped for any other reason, such as the step limit. */
     continue(threadId: string, runOptions?: GraphRunOptions): AsyncIterable<GraphStepEvent<S>>;
+    /**
+     * Like `continue`, but returns the final result rather than the stream: what a replica calls to
+     * finish a run whose process stopped, from the last checkpoint it wrote.
+     */
+    continueWith(threadId: string, runOptions?: GraphRunOptions): Promise<GraphResult<S, O>>;
     /**
      * Rewinds to an earlier superstep and runs forward from there.
      *

package/dist/graph/graph.js

@@ -253,6 +253,12 @@ export class CompiledGraph {
             return { ...checkpoint, status: 'running', error: undefined, drained: undefined };
         });
     }
+    async continueWith(threadId, runOptions = {}) {
+        let last;
+        for await (const event of this.continue(threadId, runOptions))
+            last = event;
+        return this.toResult(threadId, last);
+    }
     resumeFrom(threadId, step, runOptions = {}) {
         return this.run(threadId, runOptions, async () => {
             const stored = await this.checkpointer()?.get(threadId, step);

package/dist/lifecycle/index.d.ts

@@ -5,4 +5,4 @@
  */
 export { BudgetExceededError, LIFECYCLE_STAGES, type LifecycleRuntime, OperationDeniedError, OperationLifecycle, type OperationPlan, } from '../core/lifecycle.js';
 export { type BudgetLedgerOptions, type BudgetLedgerWithReport, type BudgetReservationChange, type BudgetUsageStore, budgetLedger, MemoryBudgetUsage, } from './budget.js';
-export type { BudgetLedger, BudgetPeriod, BudgetRecoverOptions, BudgetRecoveryReport, BudgetReservation, BudgetReservationOutcome, BudgetReservationRecord, BudgetReservationStatus, LifecycleConfig, LifecycleHooks, LifecycleStage, OperationDescriptor, OperationFamily, OperationLifecycleLike, OperationOutcome, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext, } from '../types/lifecycle.js';
+export type { BudgetLedger, BudgetPeriod, BudgetRecoverOptions, BudgetRecoveryReport, BudgetReservation, BudgetReservationOutcome, BudgetReservationRecord, BudgetReservationStatus, LifecycleConfig, LifecycleHooks, LifecycleStage, OperationDescriptor, OperationFamily, OperationLifecycleLike, OperationOutcome, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext, ProviderHealthOutcome, } from '../types/lifecycle.js';

package/dist/protocols/a2a.d.ts

@@ -176,6 +176,33 @@ export interface A2aTaskRecord {
     push?: A2aPushNotificationConfig[];
     /** ISO-8601 time it was last written. */
     updatedAt: string;
+    /**
+     * Who is running the task, and until when, while it works. The replica running it renews the lease;
+     * once it lapses, another replica's `recover()` may take the task over.
+     */
+    lease?: A2aTaskLease;
+    /** What the working run was asked to do, so a replica that takes it over can carry it on. */
+    run?: A2aTaskRun;
+    /** Bumped by every claim of the lease, so two replicas claiming one task cannot both win. */
+    version?: number;
+}
+/** A replica's hold on a working task. */
+export interface A2aTaskLease {
+    /** The replica holding it. */
+    owner: string;
+    /** ISO-8601 time it lapses unless renewed. */
+    expiresAt: string;
+}
+/** A working run, as kept with its task: started by a message, or answering the task's questions. */
+export interface A2aTaskRun {
+    /** `invoke` for a run a message started, `resume` for one answering a paused task's questions. */
+    kind: 'invoke' | 'resume';
+    /** The message that started it. */
+    message: A2aMessage;
+    /** The answers it resumed with, by interrupt id. */
+    answers?: Record<string, unknown>;
+    /** Who it runs for. */
+    principal?: Principal;
 }
 /** Which tasks `A2aTaskStore.list()` returns. */
 export interface A2aTaskQuery {
@@ -209,6 +236,16 @@ export interface A2aTaskStore {
     conversation(contextId: string): Promise<Message[] | undefined> | Message[] | undefined;
     /** Writes a conversation's transcript. */
     saveConversation(contextId: string, messages: Message[]): Promise<void> | void;
+    /**
+     * Takes, or renews, the lease of a working task, or of one submitted and not yet started, in one
+     * step: when the task has no lease, its lease has lapsed by `lease.now`, or `lease.owner` already
+     * holds it. Resolves to the record as claimed,
+     * or `undefined` when another replica holds it. Optional; without it, a claim is a read and a write,
+     * and two replicas recovering at once may both take one task.
+     */
+    claim?(taskId: string, lease: A2aTaskLease & {
+        now: string;
+    }): Promise<A2aTaskRecord | undefined> | A2aTaskRecord | undefined;
 }
 /** Tasks and conversations in this process: the default, for one replica. */
 export declare class MemoryA2aTaskStore implements A2aTaskStore {
@@ -231,6 +268,10 @@ export declare class MemoryA2aTaskStore implements A2aTaskStore {
     conversation(contextId: string): Message[] | undefined;
     /** Writes a conversation's transcript. */
     saveConversation(contextId: string, messages: Message[]): void;
+    /** Takes or renews a working task's lease, in one step. */
+    claim(taskId: string, lease: A2aTaskLease & {
+        now: string;
+    }): A2aTaskRecord | undefined;
 }
 /**
  * Tasks and conversations in any long-term `Store`: the memory, Redis, Postgres, or SQLite store, so
@@ -293,9 +334,51 @@ export interface A2aServerOptions {
     extendedCard?: (principal: Principal) => Partial<A2aAgentCard> | Promise<Partial<A2aAgentCard>>;
     /** How often `SubscribeToTask` reads a task another replica runs, in milliseconds. Defaults to 1 second. */
     pollMs?: number;
+    /**
+     * The lease a replica holds on each task it runs: renewed every third of `ms` (30 seconds by
+     * default), and taken over by another replica's `recover()` once it lapses. `owner` names this
+     * replica; it defaults to a random id.
+     */
+    lease?: {
+        ms?: number;
+        owner?: string;
+    };
+    /**
+     * Runs `recover()` every this many milliseconds, so a task a stopped replica was working on is taken
+     * over without a caller asking. Off by default; `close()` stops it.
+     */
+    recoverEveryMs?: number;
     /** Receives push delivery failures, which never fail a task. */
     onError?: (error: unknown) => void;
 }
+/** What one `recover()` did. */
+export interface A2aRecoveryReport {
+    /** Tasks whose lease had lapsed, taken over and carried on here. */
+    tookOver: string[];
+    /** Tasks another replica claimed first, or that finished meanwhile. */
+    skipped: number;
+}
+/**
+ * An A2A agent's HTTP handler, with what keeps its tasks alive across replicas: `recover()` takes over
+ * the working tasks whose replica stopped renewing their lease, and `close()` stops the recovery timer.
+ */
+export interface A2aHandler {
+    /** Answers one HTTP request: `GET` the card, `POST` JSON-RPC. */
+    (request: Request): Promise<Response>;
+    /** This replica's name in the leases it holds. */
+    readonly owner: string;
+    /**
+     * Takes over working tasks whose lease lapsed, up to `limit` (10), and carries each on: from the
+     * graph's last checkpoint, by answering its questions again when the run was a resume that never
+     * reached the graph, or from the start when the run left no checkpoint. Resolves once they are
+     * claimed, not finished.
+     */
+    recover(options?: {
+        limit?: number;
+    }): Promise<A2aRecoveryReport>;
+    /** Stops the recovery timer `recoverEveryMs` started. Tasks running here carry on. */
+    close(): void;
+}
 /**
  * An HTTP handler that serves a graph as an A2A agent: `GET` the card, `POST` JSON-RPC. Mount it
  * at the card's `url`; it answers the well-known card path under the same origin too.
@@ -306,7 +389,7 @@ export interface A2aServerOptions {
  * });
  * ```
  */
-export declare function a2aHandler(graph: ProtocolGraph, options: A2aServerOptions): (request: Request) => Promise<Response>;
+export declare function a2aHandler(graph: ProtocolGraph, options: A2aServerOptions): A2aHandler;
 /** Options for `a2aClient()`. */
 export interface A2aClientOptions {
     /** The agent: its card's URL, or its JSON-RPC endpoint, whose origin serves the card. */