@arnilo/prism-supervisor 0.0.96 → 0.1.0

package/dist/a2a-types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRunResult, AgentSession, OwnershipScope, SecretRedactor } from "@arnilo/prism";
+import type { AgentIdentity, AgentRunResult, AgentSession, OwnershipScope, SecretRedactor } from "@arnilo/prism";
 export declare const A2A_PROTOCOL_VERSION = "1.0";
 export interface A2AAgentInterface {
     readonly url: string;
@@ -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";
@@ -132,6 +137,8 @@ export interface A2AJsonRpcResponse {
 }
 export interface A2AAuthorization {
     readonly ownership: OwnershipScope;
+    /** Host-verified identity; when set must project onto ownership without widening. */
+    readonly identity?: AgentIdentity;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export type A2AAuthorizer = (input: {
@@ -284,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/errors.js

@@ -7,13 +7,22 @@ export class SupervisorError extends Error {
     }
 }
 export class SupervisorValidationError extends SupervisorError {
-    constructor(message) { super(message, "ERR_PRISM_SUPERVISOR_VALIDATION"); this.name = "SupervisorValidationError"; }
+    constructor(message) {
+        super(message, "ERR_PRISM_SUPERVISOR_VALIDATION");
+        this.name = "SupervisorValidationError";
+    }
 }
 export class SupervisorLimitError extends SupervisorError {
-    constructor(message) { super(message, "ERR_PRISM_SUPERVISOR_LIMIT"); this.name = "SupervisorLimitError"; }
+    constructor(message) {
+        super(message, "ERR_PRISM_SUPERVISOR_LIMIT");
+        this.name = "SupervisorLimitError";
+    }
 }
 export class SupervisorDeniedError extends SupervisorError {
-    constructor(message = "Delegation denied") { super(message, "ERR_PRISM_SUPERVISOR_DENIED"); this.name = "SupervisorDeniedError"; }
+    constructor(message = "Delegation denied") {
+        super(message, "ERR_PRISM_SUPERVISOR_DENIED");
+        this.name = "SupervisorDeniedError";
+    }
 }
 export class A2AError extends SupervisorError {
     status;

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/limits.js

@@ -37,6 +37,9 @@ export function narrowSupervisorLimits(parent, input) {
     if (!input)
         return parent;
     const requested = resolveSupervisorLimits({ ...parent, ...input });
-    return Object.fromEntries(Object.keys(SPECS).map((key) => [key, Math.min(parent[key], requested[key])]));
+    return Object.fromEntries(Object.keys(SPECS).map((key) => [
+        key,
+        Math.min(parent[key], requested[key]),
+    ]));
 }
 //# sourceMappingURL=limits.js.map

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,9 +100,14 @@ 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({ id: `${delegationId}-session`, metadata: { supervisorId: id, delegationId, resourceId, threadId } });
+            const session = agent.createSession({
+                id: `${delegationId}-session`,
+                metadata: { supervisorId: id, delegationId, resourceId, threadId },
+            });
             let result;
             try {
                 result = await abortable(session.run(input, {
@@ -106,37 +121,72 @@ 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) {
                 if (error instanceof AgentRunError && error.result.limit) {
-                    const label = error.result.limit.limit === "maxTotalTokens" ? "token"
-                        : error.result.limit.limit === "maxToolCalls" ? "tool-call"
-                            : error.result.limit.limit === "maxWallTimeMs" ? "timeout"
+                    const label = error.result.limit.limit === "maxTotalTokens"
+                        ? "token"
+                        : error.result.limit.limit === "maxToolCalls"
+                            ? "tool-call"
+                            : error.result.limit.limit === "maxWallTimeMs"
+                                ? "timeout"
                                 : "run";
                     throw new SupervisorLimitError(`Delegation ${label} limit exceeded`);
                 }
                 throw error;
             }
-            const totalTokens = result.usage?.totalTokens ?? ((result.usage?.inputTokens ?? 0) + (result.usage?.outputTokens ?? 0));
+            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));
             completionSent = true;
             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);
                 events.publish({ type: "delegation_error", childId: request.childId, delegationId, depth, error: message });
-                await complete(result ? toCompletion(result, request.childId, delegationId, depth, options) : {
-                    childId: request.childId,
-                    delegationId,
-                    depth,
-                    status: controller.signal.aborted ? "aborted" : "rejected",
-                    text: "",
-                    error: message,
-                });
+                await complete(result
+                    ? toCompletion(result, request.childId, delegationId, depth, options)
+                    : {
+                        childId: request.childId,
+                        delegationId,
+                        depth,
+                        status: controller.signal.aborted ? "aborted" : "rejected",
+                        text: "",
+                        error: message,
+                    });
             }
             if (error instanceof AgentRunError || error instanceof SupervisorError)
                 throw error;
@@ -148,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;
@@ -155,10 +290,23 @@ export function createSupervisor(options) {
             await options.hooks.after(Object.freeze(value));
         }
         catch (error) {
-            events.publish({ type: "delegation_error", childId: value.childId, delegationId: value.delegationId, depth: value.depth, error: safeError(error, options) });
+            events.publish({
+                type: "delegation_error",
+                childId: value.childId,
+                delegationId: value.delegationId,
+                depth: value.depth,
+                error: safeError(error, options),
+            });
         }
     }
-    return { delegate: (request) => delegate(request), subscribe: () => events.subscribe(), get activeChildren() { return activeChildren; } };
+    return {
+        delegate: (request) => delegate(request),
+        resumeNestedRun,
+        subscribe: () => events.subscribe(),
+        get activeChildren() {
+            return activeChildren;
+        },
+    };
 }
 function toCompletion(result, childId, delegationId, depth, options) {
     return Object.freeze({
@@ -173,23 +321,27 @@ function toCompletion(result, childId, delegationId, depth, options) {
 }
 function intersectPolicies(...policies) {
     const active = policies.filter((policy) => policy !== undefined);
-    return { async check(request) {
+    return {
+        async check(request) {
             for (const policy of active) {
                 const decision = await policy.check(request);
                 if (!decision.allowed)
                     return decision;
             }
             return { allowed: true };
-        } };
+        },
+    };
 }
 function toolBudgetPolicy(max) {
     let count = 0;
-    return { check(request) {
+    return {
+        check(request) {
             if (request.kind !== "tool" || request.action !== "execute")
                 return { allowed: true };
             count += 1;
             return count <= max ? { allowed: true } : { allowed: false, reason: "Delegation tool-call limit exceeded" };
-        } };
+        },
+    };
 }
 function linkSignals(controller, ...signals) {
     const removers = [];
@@ -204,8 +356,10 @@ function linkSignals(controller, ...signals) {
             removers.push(() => signal.removeEventListener("abort", abort));
         }
     }
-    return () => { for (const remove of removers)
-        remove(); };
+    return () => {
+        for (const remove of removers)
+            remove();
+    };
 }
 function abortable(promise, signal) {
     if (signal.aborted)
@@ -221,10 +375,10 @@ function assertBytes(value, max, label) {
         throw new SupervisorLimitError(`${label} exceeds max bytes`);
 }
 function requireOwnership(ownership) {
-    if (!ownership.tenantId?.trim()
-        || (ownership.accountId !== undefined && !ownership.accountId.trim())
-        || (ownership.userId !== undefined && !ownership.userId.trim())
-        || (!ownership.accountId && !ownership.userId))
+    if (!ownership.tenantId?.trim() ||
+        (ownership.accountId !== undefined && !ownership.accountId.trim()) ||
+        (ownership.userId !== undefined && !ownership.userId.trim()) ||
+        (!ownership.accountId && !ownership.userId))
         throw new SupervisorValidationError("tenantId and non-empty accountId or userId are required");
 }
 function safeError(error, options) {

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.96",
+  "version": "0.1.0",
   "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.96"
+    "@arnilo/prism": "0.1.0"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../.."