@arnilo/prism-supervisor 0.0.24 → 0.0.25

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

package/README.md

@@ -28,4 +28,4 @@ console.log((await supervisor.delegate({ childId: "research", input: "Check sour
 
 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/supervisor.js

@@ -1,9 +1,13 @@
-import { AgentRunError, assertIdentityActive, assertIdentityMatchesOwnership, 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);
@@ -117,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) {
@@ -132,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));
@@ -139,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);
@@ -164,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;
@@ -182,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, AgentIdentity, AgentRunResult, OwnershipScope, PermissionPolicy, SecretRedactor, ToolEffectStore } 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;
@@ -99,9 +99,23 @@ export interface CreateSupervisorOptions {
     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.24",
+  "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.24"
+    "@arnilo/prism": "0.0.25"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../.."