@arnilo/prism-supervisor 0.0.23 → 0.0.25

package/CHANGELOG.md

@@ -1,11 +1,30 @@
 # Changelog
 
+## [0.0.25] - 2026-08-06
+
+### Added
+- Durable child approvals: `checkpoints` + `definitionRevision` on supervisor; `resumeNestedRun` routes hashed attributed decisions without widening child permission.
+
+### Changed
+- Released with exact 0.0.25 graph.
+
+See [migration guide](../../docs/migration.md) for the 0.0.24 → 0.0.25 notes.
+
+## [0.0.24] - 2026-08-04
+
+### Added
+- Durable `AgentEventSource` (memory + PostgreSQL LISTEN/NOTIFY), recoverable `ToolEffectStore`, and AG-UI MCP/MCP Apps/A2A fronting for Phase 7.
+
+### Changed
+- Publishable graph remains **47** manifests at **0.0.24**; peers and lockfile move together.
+
+See [migration guide](../../docs/migration.md) for the 0.0.23 → 0.0.24 notes.
+
 ## [0.0.23] - 2026-08-03
 
 ### Changed
 - Released with exact 0.0.23 graph.
 
-
 ## [0.0.22] - 2026-07-31
 
 ### Changed
@@ -16,14 +35,11 @@
 ### Changed
 - Released with exact 0.0.21 graph.
 
-
-
 ## [0.0.20] - 2026-07-31
 
 ### Changed
 - Released with exact 0.0.20 graph.
 
-
 ## [0.0.19] - 2026-07-30
 
 ### Changed

package/README.md

@@ -26,6 +26,6 @@ const supervisor = createSupervisor({
 console.log((await supervisor.delegate({ childId: "research", input: "Check sources" })).text);
 ```
 
-Also exports bounded A2A 1.0 cards, handler/client, rich one-of parts, host-owned `A2ATaskLifecycle`, reconnect subscriptions, and push-config CRUD. Direct text invocation remains compatible; durable get/list/cancel/subscribe and rich raw/data/URL parts require explicit adapters/policy. URL parts are validated but never fetched. Push persistence/network/credentials and exact-owner checks remain host-owned; explicit `deliverA2APushEvent()` only bounds attempts/time and forwards stable event IDs for host idempotency. Returned configs omit secrets. JSON-RPC/HTTPS is the only binding.
+Also exports bounded A2A 1.0 cards, handler/client, rich one-of parts, `client.streamMessage()` for verified task/message stream records, host-owned `A2ATaskLifecycle`, `createA2AAgentEventSource()` for shared durable run→task subscriptions, reconnect subscriptions, and push-config CRUD. Direct text invocation remains compatible; durable get/list/cancel/subscribe and rich raw/data/URL parts require explicit adapters/policy. URL parts are validated but never fetched. Push persistence/network/credentials and exact-owner checks remain host-owned; explicit `deliverA2APushEvent()` only bounds attempts/time and forwards stable event IDs for host idempotency. Returned configs omit secrets. JSON-RPC/HTTPS is the only binding.
 
-See [Supervisors](../../docs/supervisors.md) and [A2A interoperability](../../docs/a2a.md).
+Pass `checkpoints` + `definitionRevision` for durable child approvals (`resumeNestedRun` routes hashed attributed decisions without widening permission). See [Supervisors](../../docs/supervisors.md) and [A2A interoperability](../../docs/a2a.md).

package/dist/a2a-client.js

@@ -70,17 +70,17 @@ export function createA2AClient(options) {
             return taskResult(parseTaskResult(rpc.result), options);
         });
     }
-    async function* stream(input, call = {}) {
+    async function* streamMessage(message, call = {}) {
         if (active >= limits.maxConcurrentRequests)
             throw new A2AError("A2A client concurrency exceeded", 429, "ERR_PRISM_A2A_CONCURRENCY");
         active += 1;
         const owned = ownedSignal(call.signal, limits.timeoutMs);
         let reader;
         try {
-            assertInput(input, limits.maxRequestBytes);
+            assertMessage(message, limits.maxRequestBytes);
             await getCardWithin(owned.signal);
             const id = ++requestId;
-            const body = JSON.stringify(requestBody(id, "SendStreamingMessage", input));
+            const body = JSON.stringify({ jsonrpc: "2.0", id, method: "SendStreamingMessage", params: { message } });
             if (new TextEncoder().encode(body).byteLength > limits.maxRequestBytes)
                 throw new A2AError("A2A request exceeds max bytes", 413, "ERR_PRISM_A2A_REQUEST_LIMIT");
             const authHeaders = await abortable(Promise.resolve(options.authorize?.({ endpoint: endpoint.href, signal: owned.signal }) ?? {}), owned.signal);
@@ -100,6 +100,7 @@ export function createA2AClient(options) {
                 throw new A2AError("A2A stream request failed", response.status, "ERR_PRISM_A2A_REMOTE");
             reader = response.body.getReader();
             let terminal = false;
+            let count = 0;
             for await (const data of readA2AStreamData(reader, limits, owned.signal)) {
                 if (terminal)
                     throw new A2AError("A2A stream continued after terminal task state", 502, "ERR_PRISM_A2A_REMOTE");
@@ -115,19 +116,17 @@ export function createA2AClient(options) {
                 const rpc = parseRpcResponse(parsed, id);
                 if (rpc.error)
                     throw new A2AError(safeRemote(rpc.error.message, options), 502, "ERR_PRISM_A2A_REMOTE");
-                const task = parseTaskResult(rpc.result);
-                if (task.status.state === "TASK_STATE_FAILED" ||
-                    task.status.state === "TASK_STATE_CANCELED" ||
-                    task.status.state === "TASK_STATE_REJECTED")
-                    throw new A2AError("Remote A2A stream task failed", 502, "ERR_PRISM_A2A_REMOTE");
-                if (task.status.state === "TASK_STATE_INPUT_REQUIRED" || task.status.state === "TASK_STATE_AUTH_REQUIRED")
-                    throw new A2AError(`Remote A2A task interrupted: ${task.status.state}`, 409, "ERR_PRISM_A2A_INTERRUPTED");
-                if (task.status.state === "TASK_STATE_COMPLETED")
+                const event = parseA2AStreamEvent(rpc.result, `stream-${++count}`);
+                const status = eventStatus(event);
+                if (status === "TASK_STATE_FAILED" ||
+                    status === "TASK_STATE_CANCELED" ||
+                    status === "TASK_STATE_REJECTED" ||
+                    status === "TASK_STATE_INPUT_REQUIRED" ||
+                    status === "TASK_STATE_AUTH_REQUIRED")
+                    terminal = true;
+                if (status === "TASK_STATE_COMPLETED")
                     terminal = true;
-                for (const artifact of task.artifacts ?? [])
-                    for (const part of artifact.parts)
-                        if (typeof part.text === "string")
-                            yield options.redactor?.redact(part.text) ?? part.text;
+                yield event;
             }
             if (!terminal)
                 throw new A2AError("A2A stream ended before terminal task state", 502, "ERR_PRISM_A2A_REMOTE");
@@ -138,6 +137,18 @@ export function createA2AClient(options) {
             active -= 1;
         }
     }
+    async function* stream(input, call = {}) {
+        assertInput(input, limits.maxRequestBytes);
+        for await (const event of streamMessage({ role: "user", messageId: "stream-input", parts: [{ text: input }] }, call)) {
+            const status = eventStatus(event);
+            if (status === "TASK_STATE_FAILED" || status === "TASK_STATE_CANCELED" || status === "TASK_STATE_REJECTED")
+                throw new A2AError("Remote A2A stream task failed", 502, "ERR_PRISM_A2A_REMOTE");
+            if (status === "TASK_STATE_INPUT_REQUIRED" || status === "TASK_STATE_AUTH_REQUIRED")
+                throw new A2AError(`Remote A2A task interrupted: ${status}`, 409, "ERR_PRISM_A2A_INTERRUPTED");
+            for (const text of streamEventText(event))
+                yield options.redactor?.redact(text) ?? text;
+        }
+    }
     async function getCardWithin(signal) {
         const response = await fetcher(cardUrl, {
             method: "GET",
@@ -226,15 +237,16 @@ export function createA2AClient(options) {
             if (!response.ok || !response.body || !response.headers.get("content-type")?.startsWith("text/event-stream"))
                 throw new A2AError("A2A subscribe request failed", response.status, "ERR_PRISM_A2A_REMOTE");
             reader = response.body.getReader();
-            let previous = "", count = 0;
+            const seen = new Set();
+            let count = 0;
             for await (const data of readA2AStreamData(reader, limits, owned.signal)) {
                 const rpc = parseRpcResponse(JSON.parse(data), request);
                 if (rpc.error)
                     throw remoteProtocolError(rpc.error.code, rpc.error.message, options);
                 const event = parseTaskEvent(rpc.result);
-                if (event.eventId === previous)
+                if (seen.has(event.eventId))
                     continue;
-                previous = event.eventId;
+                seen.add(event.eventId);
                 if (++count > limits.maxReplayEvents)
                     throw new A2AError("A2A replay exceeds event limit", 507, "ERR_PRISM_A2A_STREAM_LIMIT");
                 yield event;
@@ -269,6 +281,7 @@ export function createA2AClient(options) {
         send,
         sendMessage,
         stream,
+        streamMessage,
         getTask,
         listTasks,
         cancelTask,
@@ -433,6 +446,7 @@ function parseTaskResult(value) {
         status: {
             state: task.status.state,
             timestamp: typeof task.status.timestamp === "string" ? task.status.timestamp : new Date(0).toISOString(),
+            ...(task.status.message === undefined ? {} : { message: parseRemoteMessage(task.status.message) }),
         },
         artifacts,
         history,
@@ -487,6 +501,31 @@ function parseRemoteMessage(value) {
         taskId: typeof value.taskId === "string" ? value.taskId : undefined,
     };
 }
+function parseA2AStreamEvent(value, fallbackEventId) {
+    if (isRecord(value) && isRecord(value.message))
+        return { eventId: fallbackEventId, message: parseRemoteMessage(value.message) };
+    if (isRecord(value) && !Object.hasOwn(value, "eventId") && (isRecord(value.task) || typeof value.id === "string")) {
+        return { eventId: fallbackEventId, task: parseTaskResult(value) };
+    }
+    return parseTaskEvent(value);
+}
+function eventStatus(event) {
+    if ("task" in event)
+        return event.task.status.state;
+    if ("statusUpdate" in event)
+        return event.statusUpdate.status.state;
+    return undefined;
+}
+function streamEventText(event) {
+    const parts = "message" in event
+        ? event.message.parts
+        : "task" in event
+            ? (event.task.artifacts?.flatMap((artifact) => artifact.parts) ?? [])
+            : "artifactUpdate" in event
+                ? event.artifactUpdate.artifact.parts
+                : [];
+    return parts.flatMap((part) => (typeof part.text === "string" ? [part.text] : []));
+}
 function parseTaskEvent(value) {
     if (!isRecord(value) || typeof value.eventId !== "string" || !value.eventId)
         throw new A2AError("Malformed A2A task event", 502, "ERR_PRISM_A2A_REMOTE");
@@ -688,6 +727,19 @@ function assertInput(input, maxBytes) {
     if (new TextEncoder().encode(input).byteLength > maxBytes)
         throw new A2AError("A2A input exceeds max bytes", 413, "ERR_PRISM_A2A_REQUEST_LIMIT");
 }
+function assertMessage(message, maxBytes) {
+    if (!message.messageId || !Array.isArray(message.parts) || message.parts.length === 0)
+        throw new A2AError("Invalid A2A outbound message", 400, "ERR_PRISM_A2A_MESSAGE");
+    let encoded;
+    try {
+        encoded = JSON.stringify(message);
+    }
+    catch {
+        throw new A2AError("Invalid A2A outbound message", 400, "ERR_PRISM_A2A_MESSAGE");
+    }
+    if (Buffer.byteLength(encoded, "utf8") > maxBytes)
+        throw new A2AError("A2A input exceeds max bytes", 413, "ERR_PRISM_A2A_REQUEST_LIMIT");
+}
 function headersObject(headers) {
     return Object.fromEntries(new Headers(headers).entries());
 }

package/dist/a2a-event-source.d.ts

@@ -0,0 +1,42 @@
+import type { AgentEventSource, AgentRunRef, DurableAgentEventRecord } from "@arnilo/prism";
+import type { A2AAuthorization, A2ATask, A2ATaskEvent } from "./a2a-types.js";
+export type A2ATaskEventPayload = {
+    readonly task: A2ATask;
+} | {
+    readonly statusUpdate: Extract<A2ATaskEvent, {
+        readonly statusUpdate: unknown;
+    }>["statusUpdate"];
+} | {
+    readonly artifactUpdate: Extract<A2ATaskEvent, {
+        readonly artifactUpdate: unknown;
+    }>["artifactUpdate"];
+};
+export interface A2AAgentEventTask {
+    readonly task: A2ATask;
+    readonly run: AgentRunRef;
+}
+export interface A2AAgentEventSourceOptions {
+    readonly source: AgentEventSource;
+    /** Resolves only host-owned task state and its exact Prism run. */
+    readonly resolveTask: (input: {
+        readonly id: string;
+        readonly authorization: A2AAuthorization;
+        readonly signal: AbortSignal;
+    }) => A2AAgentEventTask | undefined | Promise<A2AAgentEventTask | undefined>;
+    /** Maps at most one durable Prism record to one A2A update. Event IDs stay source-owned cursors. */
+    readonly map: (input: {
+        readonly record: DurableAgentEventRecord;
+        readonly task: A2ATask;
+        readonly authorization: A2AAuthorization;
+    }) => A2ATaskEventPayload | undefined | Promise<A2ATaskEventPayload | undefined>;
+}
+export interface A2AAgentEventSource {
+    subscribe(input: {
+        readonly id: string;
+        readonly afterEventId?: string;
+        readonly authorization: A2AAuthorization;
+        readonly signal: AbortSignal;
+    }): AsyncIterable<A2ATaskEvent>;
+}
+/** Host-selected durable task stream over AgentEventSource; owns no task database or worker. */
+export declare function createA2AAgentEventSource(options: A2AAgentEventSourceOptions): A2AAgentEventSource;

package/dist/a2a-event-source.js

@@ -0,0 +1,40 @@
+import { A2AError } from "./errors.js";
+/** Host-selected durable task stream over AgentEventSource; owns no task database or worker. */
+export function createA2AAgentEventSource(options) {
+    return {
+        subscribe(input) {
+            return {
+                async *[Symbol.asyncIterator]() {
+                    input.signal.throwIfAborted();
+                    const resolved = await options.resolveTask(input);
+                    if (!resolved?.run.sessionId || resolved.task.id !== input.id) {
+                        throw new A2AError("Task unavailable", 404, "ERR_PRISM_A2A_TASK");
+                    }
+                    let first = true;
+                    for await (const item of options.source.subscribe({
+                        ownership: input.authorization.ownership,
+                        sessionId: resolved.run.sessionId,
+                        runId: resolved.run.runId,
+                        after: input.afterEventId,
+                        signal: input.signal,
+                    })) {
+                        if (!item.record.redacted)
+                            throw new A2AError("Task event unavailable", 500, "ERR_PRISM_A2A_TASK");
+                        const payload = await options.map({ record: item.record, task: resolved.task, authorization: input.authorization });
+                        if (!payload)
+                            continue;
+                        if (first && input.afterEventId === undefined && !("task" in payload)) {
+                            throw new A2AError("Initial task event required", 500, "ERR_PRISM_A2A_TASK");
+                        }
+                        first = false;
+                        yield { eventId: item.cursor, ...payload };
+                    }
+                    if (first && input.afterEventId === undefined) {
+                        throw new A2AError("Initial task event required", 500, "ERR_PRISM_A2A_TASK");
+                    }
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=a2a-event-source.js.map

package/dist/a2a-types.d.ts

@@ -113,6 +113,11 @@ export type A2ATaskEvent = {
         readonly lastChunk?: boolean;
     };
 };
+/** A streaming response may be a task lifecycle or one direct message. */
+export type A2AStreamEvent = A2ATaskEvent | {
+    readonly eventId: string;
+    readonly message: A2AMessage;
+};
 export type A2ARequestId = string | number | null;
 export interface A2AJsonRpcRequest {
     readonly jsonrpc: "2.0";
@@ -286,6 +291,10 @@ export interface A2AClient {
     stream(input: string, options?: {
         readonly signal?: AbortSignal;
     }): AsyncIterable<string>;
+    /** Rich `SendStreamingMessage` events. Host-supplied messages remain subject to client bounds/card verification. */
+    streamMessage(message: A2AMessage, options?: {
+        readonly signal?: AbortSignal;
+    }): AsyncIterable<A2AStreamEvent>;
     getTask(id: string, options?: {
         readonly signal?: AbortSignal;
         readonly historyLength?: number;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./a2a-card.js";
+export * from "./a2a-event-source.js";
 export * from "./a2a-client.js";
 export * from "./a2a-parts.js";
 export * from "./a2a-push.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./a2a-card.js";
+export * from "./a2a-event-source.js";
 export * from "./a2a-client.js";
 export * from "./a2a-parts.js";
 export * from "./a2a-push.js";

package/dist/supervisor.js

@@ -1,9 +1,17 @@
-import { AgentRunError, createAgent, createEventMultiplexer, } from "@arnilo/prism";
+import { AgentDelegationSuspendedError, AgentRunError, assertIdentityActive, assertIdentityMatchesOwnership, createAgent, createEventMultiplexer, resumeAgentRun, } from "@arnilo/prism";
 import { SupervisorDeniedError, SupervisorError, SupervisorLimitError, SupervisorValidationError } from "./errors.js";
 import { narrowSupervisorLimits, resolveSupervisorLimits } from "./limits.js";
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const DELEGATION_NAMESPACE = "prism.supervisor-delegation";
 export function createSupervisor(options) {
     requireOwnership(options.ownership);
+    if (options.checkpoints && !options.definitionRevision?.trim()) {
+        throw new SupervisorValidationError("definitionRevision is required when checkpoints are configured");
+    }
+    if (options.identity) {
+        assertIdentityActive(options.identity);
+        assertIdentityMatchesOwnership(options.identity, options.ownership);
+    }
     const id = options.id ?? "supervisor";
     if (!ID.test(id))
         throw new SupervisorValidationError("Supervisor id is invalid");
@@ -80,6 +88,8 @@ export function createSupervisor(options) {
                 depth,
                 path,
                 ownership: options.ownership,
+                identity: options.identity,
+                effectStore: options.effectStore,
                 resourceId,
                 threadId,
                 permission: preliminaryPermission,
@@ -90,6 +100,8 @@ export function createSupervisor(options) {
                 ...childAgent.config,
                 permission: intersectPolicies(preliminaryPermission, childAgent.config.permission),
                 ownership: options.ownership,
+                identity: options.identity ?? childAgent.config.identity,
+                effectStore: options.effectStore ?? childAgent.config.effectStore,
                 redactor: options.redactor ?? childAgent.config.redactor,
             });
             const session = agent.createSession({
@@ -109,6 +121,16 @@ export function createSupervisor(options) {
                     ownership: options.ownership,
                     redactor: options.redactor,
                     metadata: { ...request.metadata, supervisorId: id, delegationId, resourceId, threadId, depth },
+                    ...(options.checkpoints
+                        ? {
+                            runState: {
+                                checkpoints: options.checkpoints,
+                                definitionRevision: options.definitionRevision,
+                                interruptBeforeTool: true,
+                                resumeNestedRun,
+                            },
+                        }
+                        : {}),
                 }), controller.signal);
             }
             catch (error) {
@@ -124,6 +146,24 @@ export function createSupervisor(options) {
                 }
                 throw error;
             }
+            if (result.status === "suspended") {
+                // Child approvals surface on the hosting root run: persist the rebuild mapping, then
+                // signal core with the child's pending decisions (core hashes/attributes the ids).
+                const pending = result.interruption?.pendingDecisions;
+                const version = result.runState?.version;
+                if (!pending?.length || version === undefined) {
+                    throw new SupervisorError("Child run suspended without a pending-decision set");
+                }
+                await saveMapping(result.runId, {
+                    childId: request.childId,
+                    delegationId,
+                    threadId,
+                    path,
+                    version,
+                    input,
+                });
+                throw new AgentDelegationSuspendedError({ runId: result.runId, sessionId: result.sessionId }, pending, path);
+            }
             const totalTokens = result.usage?.totalTokens ?? (result.usage?.inputTokens ?? 0) + (result.usage?.outputTokens ?? 0);
             events.publish({ type: "delegation_finished", childId: request.childId, delegationId, depth, status: result.status, totalTokens });
             await complete(toCompletion(result, request.childId, delegationId, depth, options));
@@ -131,6 +171,8 @@ export function createSupervisor(options) {
             return result;
         }
         catch (error) {
+            if (error instanceof AgentDelegationSuspendedError)
+                throw error;
             if (!(error instanceof SupervisorDeniedError && completionSent)) {
                 const result = error instanceof AgentRunError ? error.result : undefined;
                 const message = safeError(error, options);
@@ -156,6 +198,91 @@ export function createSupervisor(options) {
             activeChildren -= 1;
         }
     }
+    async function saveMapping(runId, mapping) {
+        const existing = await options.checkpoints.loadCheckpoint({ namespace: DELEGATION_NAMESPACE, key: runId });
+        await options.checkpoints.saveCheckpoint({
+            namespace: DELEGATION_NAMESPACE,
+            key: runId,
+            version: (existing?.version ?? 0) + 1,
+            expectedVersion: existing?.version,
+            value: mapping,
+        });
+    }
+    const resumeNestedRun = async (nested, decisions) => {
+        const checkpoints = options.checkpoints;
+        if (!checkpoints || !options.definitionRevision) {
+            throw new SupervisorValidationError("Nested-run resume requires supervisor checkpoints and definitionRevision");
+        }
+        const record = await checkpoints.loadCheckpoint({ namespace: DELEGATION_NAMESPACE, key: nested.ref.runId });
+        const mapping = record?.value;
+        // Non-enumerating: unknown and foreign run ids share one error.
+        if (!mapping || typeof mapping.childId !== "string" || typeof mapping.version !== "number") {
+            throw new SupervisorDeniedError("Unknown delegated run");
+        }
+        const child = options.children[mapping.childId];
+        if (!child)
+            throw new SupervisorDeniedError("Unknown delegated run");
+        const depth = mapping.path.length;
+        const controller = new AbortController();
+        let limits = narrowSupervisorLimits(baseLimits, child.limits);
+        let hookPermission;
+        // The before-hook re-runs at resume so its narrowing applies exactly as it did to the
+        // original run; hooks must be idempotent (same contract as core resume guardrails).
+        if (options.hooks?.before) {
+            const decision = await options.hooks.before(Object.freeze({
+                childId: mapping.childId,
+                delegationId: mapping.delegationId,
+                depth,
+                path: mapping.path,
+                input: mapping.input,
+                limits,
+                metadata: undefined,
+                signal: controller.signal,
+            }));
+            if (decision.allowed === false) {
+                return { status: "failed", code: "delegation_denied", message: safeError(decision.reason ?? "Delegation denied", options) };
+            }
+            limits = narrowSupervisorLimits(limits, decision.limits);
+            hookPermission = decision.permission;
+        }
+        const resourceId = `${id}/${mapping.delegationId}/${mapping.childId}`;
+        const permission = intersectPolicies(options.permission, child.permission, hookPermission, toolBudgetPolicy(limits.maxToolCalls));
+        const childAgent = await child.createAgent(Object.freeze({
+            childId: mapping.childId,
+            delegationId: mapping.delegationId,
+            depth,
+            path: mapping.path,
+            ownership: options.ownership,
+            identity: options.identity,
+            effectStore: options.effectStore,
+            resourceId,
+            threadId: mapping.threadId,
+            permission,
+            signal: controller.signal,
+            delegate: (nestedRequest) => delegate(nestedRequest, { path: mapping.path, signal: controller.signal }),
+        }));
+        const agent = createAgent({
+            ...childAgent.config,
+            permission: intersectPolicies(permission, childAgent.config.permission),
+            ownership: options.ownership,
+            identity: options.identity ?? childAgent.config.identity,
+            effectStore: options.effectStore ?? childAgent.config.effectStore,
+            redactor: options.redactor ?? childAgent.config.redactor,
+        });
+        const result = await resumeAgentRun(agent, { runId: nested.ref.runId, ...(nested.ref.sessionId ? { sessionId: nested.ref.sessionId } : {}) }, { decisions, expectedVersion: mapping.version }, { checkpoints, definitionRevision: options.definitionRevision, ownership: options.ownership, resumeNestedRun });
+        if (result.status === "suspended") {
+            await saveMapping(nested.ref.runId, { ...mapping, version: result.runState?.version ?? mapping.version });
+            return { status: "suspended", pendingDecisions: result.interruption?.pendingDecisions ?? [] };
+        }
+        if (result.status === "succeeded") {
+            return { status: "completed", value: options.redactor?.redact(result.text) ?? result.text };
+        }
+        return {
+            status: "failed",
+            code: result.status === "denied" ? "delegation_denied" : "delegation_failed",
+            message: safeError(result.error?.message ?? `Delegated run ${result.status}`, options),
+        };
+    };
     async function complete(value) {
         if (!options.hooks?.after)
             return;
@@ -174,6 +301,7 @@ export function createSupervisor(options) {
     }
     return {
         delegate: (request) => delegate(request),
+        resumeNestedRun,
         subscribe: () => events.subscribe(),
         get activeChildren() {
             return activeChildren;

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentRunResult, OwnershipScope, PermissionPolicy, SecretRedactor } from "@arnilo/prism";
+import type { Agent, AgentIdentity, AgentRunResult, CheckpointStore, OwnershipScope, PermissionPolicy, ResumeNestedRun, SecretRedactor, ToolEffectStore } from "@arnilo/prism";
 import type { ResolvedSupervisorLimits, SupervisorLimits } from "./limits.js";
 export interface DelegationRequest {
     readonly childId: string;
@@ -14,6 +14,10 @@ export interface DelegationChildContext {
     readonly depth: number;
     readonly path: readonly string[];
     readonly ownership: OwnershipScope;
+    /** Parent-verified identity; child factories cannot widen it. */
+    readonly identity?: AgentIdentity;
+    /** One shared durable effect store for every child run. */
+    readonly effectStore?: ToolEffectStore;
     readonly resourceId: string;
     readonly threadId: string;
     readonly permission: PermissionPolicy;
@@ -86,14 +90,32 @@ export type SupervisorEvent = {
 export interface CreateSupervisorOptions {
     readonly id?: string;
     readonly ownership: OwnershipScope;
+    /** Optional parent-verified identity, propagated unchanged to every child. */
+    readonly identity?: AgentIdentity;
+    /** Optional parent effect store, propagated unchanged to every child. */
+    readonly effectStore?: ToolEffectStore;
     readonly children: Readonly<Record<string, SupervisorChild>>;
     readonly permission?: PermissionPolicy;
     readonly limits?: SupervisorLimits;
     readonly hooks?: SupervisorHooks;
     readonly redactor?: SecretRedactor;
+    /**
+     * Durable child runs: with `checkpoints` + `definitionRevision`, every child runs with
+     * `interruptBeforeTool`; a child that suspends on pending decisions throws
+     * `AgentDelegationSuspendedError` so the hosting root run can surface them.
+     */
+    readonly checkpoints?: CheckpointStore;
+    /** Host-authored revision shared by child durable runs; bump on policy/definition change. */
+    readonly definitionRevision?: string;
 }
 export interface Supervisor {
     delegate(request: DelegationRequest): Promise<AgentRunResult>;
+    /**
+     * Routes root-run decisions back to the suspended child. Pass as `resumeNestedRun` in the
+     * root run's `runState` (sticky auto-apply) and every `resumeAgentRun` options object.
+     * Throws when `checkpoints`/`definitionRevision` are not configured.
+     */
+    readonly resumeNestedRun: ResumeNestedRun;
     subscribe(): AsyncIterable<SupervisorEvent>;
     readonly activeChildren: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-supervisor",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "Bounded supervisor delegation and A2A 1.0 durable task, rich-part, reconnect, and push interoperability.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.23"
+    "@arnilo/prism": "0.0.25"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../.."