@arnilo/prism-supervisor 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.3.2] - 2026-08-29 (plan 050)
+
+### Added
+- **FEATURE-4 (Clay integration findings)**: opt-in child event passthrough.
+  `createSupervisor({ childEvents: true })` projects a redacted, capped milestone
+  subset of child `AgentEvent`s (`agent_started`/`finished`/`suspended`/`denied`
+  and tool-execution events) onto the supervisor stream as `delegation_child_event`
+  tagged with `childId`/`delegationId`/`depth`. Default off (stream unchanged).
+  Caps `maxChildEventsPerDelegation` (256/4096) and `maxChildEventBytes`
+  (32 KiB/256 KiB); overflow drops further child events and emits one
+  `delegation_child_events_capped` marker. Live passthrough is the initial
+  `delegate()` session; `resumeNestedRun` rebuilds are not projected in v1.
+
+### Fixed
+- **BUG-2 (Clay integration findings)**: both child-factory consumption sites
+  (initial delegation and durable resume rebuild) now validate the factory
+  result shape (`config` object + `createSession` function) before any policy
+  intersection is read. A factory returning a session or any non-`Agent` value
+  fails closed at `delegate()`/resume time with
+  `SupervisorError: child "<id>" factory must return an Agent, got <type>`
+  (constructor name, e.g. `RuntimeAgentSession`) instead of a cryptic
+  `Cannot read properties of undefined (reading 'permission')` TypeError.
+
 ## [0.3.1] - 2026-08-29
 
 ### Changed

package/dist/limits.d.ts

@@ -14,6 +14,10 @@ export declare const DEFAULT_DELEGATION_TIMEOUT_MS = 60000;
 export declare const HARD_DELEGATION_TIMEOUT_MS: number;
 export declare const DEFAULT_MAX_SUPERVISOR_QUEUED_EVENTS = 128;
 export declare const HARD_MAX_SUPERVISOR_QUEUED_EVENTS = 4096;
+export declare const DEFAULT_MAX_CHILD_EVENTS_PER_DELEGATION = 256;
+export declare const HARD_MAX_CHILD_EVENTS_PER_DELEGATION = 4096;
+export declare const DEFAULT_MAX_CHILD_EVENT_BYTES: number;
+export declare const HARD_MAX_CHILD_EVENT_BYTES: number;
 export interface SupervisorLimits {
     readonly maxDepth?: number;
     readonly maxActiveChildren?: number;
@@ -23,6 +27,10 @@ export interface SupervisorLimits {
     readonly maxTokens?: number;
     readonly timeoutMs?: number;
     readonly maxQueuedEvents?: number;
+    /** Milestone child events projected per delegation when `childEvents` is on. */
+    readonly maxChildEventsPerDelegation?: number;
+    /** Serialized byte ceiling for one projected child event. */
+    readonly maxChildEventBytes?: number;
 }
 export interface ResolvedSupervisorLimits {
     readonly maxDepth: number;
@@ -33,6 +41,8 @@ export interface ResolvedSupervisorLimits {
     readonly maxTokens: number;
     readonly timeoutMs: number;
     readonly maxQueuedEvents: number;
+    readonly maxChildEventsPerDelegation: number;
+    readonly maxChildEventBytes: number;
 }
 export declare function resolveSupervisorLimits(input?: SupervisorLimits): ResolvedSupervisorLimits;
 export declare function narrowSupervisorLimits(parent: ResolvedSupervisorLimits, input?: SupervisorLimits): ResolvedSupervisorLimits;

package/dist/limits.js

@@ -15,6 +15,10 @@ export const DEFAULT_DELEGATION_TIMEOUT_MS = 60_000;
 export const HARD_DELEGATION_TIMEOUT_MS = 30 * 60_000;
 export const DEFAULT_MAX_SUPERVISOR_QUEUED_EVENTS = 128;
 export const HARD_MAX_SUPERVISOR_QUEUED_EVENTS = 4096;
+export const DEFAULT_MAX_CHILD_EVENTS_PER_DELEGATION = 256;
+export const HARD_MAX_CHILD_EVENTS_PER_DELEGATION = 4096;
+export const DEFAULT_MAX_CHILD_EVENT_BYTES = 32 * 1024;
+export const HARD_MAX_CHILD_EVENT_BYTES = 256 * 1024;
 const SPECS = {
     maxDepth: [DEFAULT_MAX_DELEGATION_DEPTH, HARD_MAX_DELEGATION_DEPTH],
     maxActiveChildren: [DEFAULT_MAX_ACTIVE_CHILDREN, HARD_MAX_ACTIVE_CHILDREN],
@@ -24,6 +28,8 @@ const SPECS = {
     maxTokens: [DEFAULT_MAX_DELEGATION_TOKENS, HARD_MAX_DELEGATION_TOKENS],
     timeoutMs: [DEFAULT_DELEGATION_TIMEOUT_MS, HARD_DELEGATION_TIMEOUT_MS],
     maxQueuedEvents: [DEFAULT_MAX_SUPERVISOR_QUEUED_EVENTS, HARD_MAX_SUPERVISOR_QUEUED_EVENTS],
+    maxChildEventsPerDelegation: [DEFAULT_MAX_CHILD_EVENTS_PER_DELEGATION, HARD_MAX_CHILD_EVENTS_PER_DELEGATION],
+    maxChildEventBytes: [DEFAULT_MAX_CHILD_EVENT_BYTES, HARD_MAX_CHILD_EVENT_BYTES],
 };
 export function resolveSupervisorLimits(input = {}) {
     return Object.fromEntries(Object.entries(SPECS).map(([key, [fallback, hard]]) => {

package/dist/supervisor.js

@@ -3,6 +3,75 @@ import { SupervisorDeniedError, SupervisorError, SupervisorLimitError, Superviso
 import { narrowSupervisorLimits, resolveSupervisorLimits } from "./limits.js";
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const DELEGATION_NAMESPACE = "prism.supervisor-delegation";
+/**
+ * BUG-2 guard (Clay integration findings): a child factory returning a session
+ * (or anything non-Agent) used to crash at `.config.permission` with a cryptic
+ * TypeError. One shared shape check at both factory-result consumption sites;
+ * constructor name ("AgentSession", "Object", ...) names the received type.
+ */
+function assertChildAgent(value, childId) {
+    const candidate = value;
+    if (!candidate ||
+        typeof candidate !== "object" ||
+        !candidate.config ||
+        typeof candidate.config !== "object" ||
+        typeof candidate.createSession !== "function") {
+        const name = value === null || value === undefined
+            ? String(value)
+            : typeof value === "object" || typeof value === "function"
+                ? (value.constructor?.name ?? typeof value)
+                : typeof value;
+        throw new SupervisorError(`child "${childId}" factory must return an Agent, got ${name}`);
+    }
+}
+/** Milestone subset for v1 child-event passthrough (tool calls + run start/finish). */
+const MILESTONE_CHILD_EVENT_TYPES = new Set([
+    "agent_started",
+    "agent_finished",
+    "agent_suspended",
+    "agent_denied",
+    "tool_execution_started",
+    "tool_execution_finished",
+    "tool_execution_error",
+    "tool_execution_blocked",
+]);
+/** FEATURE-4: wrap a child session subscribe with filter + redact + cap + tag. */
+function startChildEventPump(session, tags, limits, redactor, publish) {
+    const iterator = session.subscribe()[Symbol.asyncIterator]();
+    let emitted = 0;
+    let capped = false;
+    const pump = (async () => {
+        try {
+            for (;;) {
+                const next = await iterator.next();
+                if (next.done)
+                    break;
+                const event = next.value;
+                if (!MILESTONE_CHILD_EVENT_TYPES.has(event.type) || capped)
+                    continue;
+                const payload = redactor ? redactor.redact(event) : event;
+                if (emitted >= limits.maxChildEventsPerDelegation || JSON.stringify(payload).length > limits.maxChildEventBytes) {
+                    capped = true;
+                    publish({
+                        type: "delegation_child_events_capped",
+                        ...tags,
+                        maxChildEvents: limits.maxChildEventsPerDelegation,
+                    });
+                    continue;
+                }
+                emitted += 1;
+                publish({ type: "delegation_child_event", ...tags, childEvent: payload });
+            }
+        }
+        catch {
+            // subscriber closed with the delegation
+        }
+    })();
+    return async () => {
+        await iterator.return?.();
+        await pump;
+    };
+}
 export function createSupervisor(options) {
     requireOwnership(options.ownership);
     if (options.checkpoints && !options.definitionRevision?.trim()) {
@@ -96,6 +165,7 @@ export function createSupervisor(options) {
                 signal: controller.signal,
                 delegate: (nested) => delegate(nested, { path, signal: controller.signal }),
             }))), controller.signal);
+            assertChildAgent(childAgent, request.childId);
             const agent = createAgent({
                 ...childAgent.config,
                 permission: intersectPolicies(preliminaryPermission, childAgent.config.permission),
@@ -108,6 +178,9 @@ export function createSupervisor(options) {
                 id: `${delegationId}-session`,
                 metadata: { supervisorId: id, delegationId, resourceId, threadId },
             });
+            const stopChildEvents = options.childEvents === true
+                ? startChildEventPump(session, { childId: request.childId, delegationId, depth }, limits, options.redactor, (event) => events.publish(event))
+                : undefined;
             let result;
             try {
                 result = await abortable(session.run(input, {
@@ -146,6 +219,9 @@ export function createSupervisor(options) {
                 }
                 throw error;
             }
+            finally {
+                await stopChildEvents?.();
+            }
             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).
@@ -261,6 +337,7 @@ export function createSupervisor(options) {
             signal: controller.signal,
             delegate: (nestedRequest) => delegate(nestedRequest, { path: mapping.path, signal: controller.signal }),
         }));
+        assertChildAgent(childAgent, mapping.childId);
         const agent = createAgent({
             ...childAgent.config,
             permission: intersectPolicies(permission, childAgent.config.permission),

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentIdentity, AgentRunResult, CheckpointStore, OwnershipScope, PermissionPolicy, ResumeNestedRun, SecretRedactor, ToolEffectStore } from "@arnilo/prism";
+import type { Agent, AgentEvent, AgentIdentity, AgentRunResult, CheckpointStore, OwnershipScope, PermissionPolicy, ResumeNestedRun, SecretRedactor, ToolEffectStore } from "@arnilo/prism";
 import type { ResolvedSupervisorLimits, SupervisorLimits } from "./limits.js";
 export interface DelegationRequest {
     readonly childId: string;
@@ -86,6 +86,18 @@ export type SupervisorEvent = {
     readonly delegationId: string;
     readonly depth: number;
     readonly error: string;
+} | {
+    readonly type: "delegation_child_event";
+    readonly childId: string;
+    readonly delegationId: string;
+    readonly depth: number;
+    readonly childEvent: AgentEvent;
+} | {
+    readonly type: "delegation_child_events_capped";
+    readonly childId: string;
+    readonly delegationId: string;
+    readonly depth: number;
+    readonly maxChildEvents: number;
 };
 export interface CreateSupervisorOptions {
     readonly id?: string;
@@ -99,6 +111,13 @@ export interface CreateSupervisorOptions {
     readonly limits?: SupervisorLimits;
     readonly hooks?: SupervisorHooks;
     readonly redactor?: SecretRedactor;
+    /**
+     * Opt-in: project a redacted, capped milestone subset of child `AgentEvent`s
+     * (`agent_started`/`finished`/`suspended`/`denied` and tool-execution events)
+     * onto the supervisor stream as `delegation_child_event`. Default off — the
+     * stream is unchanged when unset/false. Full per-token streaming is out of scope.
+     */
+    readonly childEvents?: boolean;
     /**
      * Durable child runs: with `checkpoints` + `definitionRevision`, every child runs with
      * `interruptBeforeTool`; a child that suspends on pending decisions throws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-supervisor",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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.3.1"
+    "@arnilo/prism": "^0.3.2"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../.."