@purista/harness 1.2.6 → 1.5.1

package/dist/sessions/index.js

@@ -1,28 +1,58 @@
-import { InternalError, OperationCancelledError, OperationTimeoutError, HarnessError, SessionBusyError, ValidationError, serializeError } from '../errors/index.js';
+import { InternalError, OperationCancelledError, OperationTimeoutError, HarnessError, SessionBusyError, ValidationError, DelegationPolicyError, serializeError } from '../errors/index.js';
 import { ulid } from '../ulid/index.js';
 import { runDefaultAgent } from '../agents/index.js';
 import { runWorkflow } from '../workflows/index.js';
 import { createMemoryFacade, createSessionMemory } from '../ports/memory.js';
 import { beginDurableWorkflow, DURABLE_RUN_ID_PATTERN, isExecutableDurableRuntime } from '../runtime/sessionDurable.js';
+import { runStepWithRetry } from '../runtime/steps.js';
 import { HarnessConfigError } from '../errors/catalog.js';
 import { loadSkillsSync } from '../skills/index.js';
 import { createModelRegistry } from '../models/registry.js';
 import { createMetrics, createTelemetryShim } from '../telemetry/index.js';
+import { metadataSpanAttrs } from '../telemetry/span-attrs.js';
+import { abortError } from '../runtime/abort.js';
 import { createMcpRunnerRegistry } from '../tools/mcp/runner.js';
 const NEVER_ABORT_SIGNAL = new AbortController().signal;
+const DEFAULT_MAX_CHILD_AGENT_CALLS = 32;
+const DEFAULT_MAX_PARALLEL_CHILD_AGENT_CALLS = 8;
+const DEFAULT_MAX_DELEGATION_DEPTH = 1;
+/**
+ * Workflows invoke leaf agents directly, so every child-agent call runs at
+ * depth 1 (spec 10 "Delegation policy": `maxDepth` default `1`, `0` disables
+ * child-agent delegation).
+ */
+const CHILD_DELEGATION_DEPTH = 1;
 function now() {
     return new Date().toISOString();
 }
 const STREAM_MAX_BUFFERED_EVENTS = 1024;
-const STREAM_TERMINAL_EVENT_TYPES = new Set(['run.finished', 'agent.finished']);
+/**
+ * Event types that must never be dropped from the relay queue.
+ *
+ * Only `run.finished` qualifies: it occurs at most once per run and is the
+ * terminal event consumers key off to know the run is complete. `agent.finished`
+ * is emitted once per agent invocation (including every child-agent delegation
+ * call), so it can appear many times and must remain droppable to keep the
+ * queue bounded when a slow consumer falls behind during a delegation-heavy run.
+ */
+const STREAM_UNDROPPABLE_EVENT_TYPES = new Set(['run.finished']);
 /**
  * Relay run events from an in-process run to a stream consumer.
  *
- * The unread events live in a bounded queue: consumed events are removed (no
- * growing cursor over a shared array), and on overflow the oldest non-terminal
- * unread event is dropped and counted, so a slow consumer never silently skips
- * an unread event. Delivery is promise-notified rather than time-polled, so
- * there is no fixed per-event latency or periodic timer.
+ * The unread events live in a bounded queue (cap: STREAM_MAX_BUFFERED_EVENTS):
+ * consumed events are removed (no growing cursor over a shared array), and on
+ * overflow the oldest droppable unread event is dropped and counted, so a slow
+ * consumer never silently skips an event without an accompanying
+ * `stream.overflow` notice. Only `run.finished` is undroppable; all other
+ * event types — including `agent.finished` — may be evicted under pressure.
+ * If no droppable event exists when the queue is full, the incoming event is
+ * discarded (counted) rather than growing the queue past the cap. Delivery is
+ * promise-notified rather than time-polled, so there is no fixed per-event
+ * latency or periodic timer.
+ *
+ * Abandoning the stream (`break` / `iterator.return()`) only detaches that
+ * consumer. It does not abort `relaySignal`; callers must pass `opts.signal`
+ * when they intend to cancel the underlying run.
  */
 export async function* relayRunEvents(run) {
     const queue = [];
@@ -31,6 +61,8 @@ export async function* relayRunEvents(run) {
     let done = false;
     let failure;
     let wake;
+    const relayController = new AbortController();
+    let completedNormally = false;
     const notify = () => {
         const resolve = wake;
         wake = undefined;
@@ -40,16 +72,23 @@ export async function* relayRunEvents(run) {
         if ('runId' in event)
             liveRunId = event.runId;
         if (queue.length >= STREAM_MAX_BUFFERED_EVENTS) {
-            const dropIndex = queue.findIndex((candidate) => !STREAM_TERMINAL_EVENT_TYPES.has(candidate.type));
+            const dropIndex = queue.findIndex((candidate) => !STREAM_UNDROPPABLE_EVENT_TYPES.has(candidate.type));
             if (dropIndex >= 0) {
                 queue.splice(dropIndex, 1);
                 dropped += 1;
             }
+            else {
+                // Every queued event is undroppable; discard the incoming event to keep
+                // the queue bounded rather than growing past the cap.
+                dropped += 1;
+                notify();
+                return Promise.resolve();
+            }
         }
         queue.push(event);
         notify();
         return Promise.resolve();
-    })
+    }, relayController.signal)
         .catch((error) => {
         failure = error;
         return undefined;
@@ -73,6 +112,7 @@ export async function* relayRunEvents(run) {
             }
             if (queue.length === 0 && dropped === 0) {
                 if (done) {
+                    completedNormally = true;
                     break;
                 }
                 // No await between the empty check and installing `wake`, so a producer
@@ -84,7 +124,12 @@ export async function* relayRunEvents(run) {
         }
     }
     finally {
-        await result.catch(() => undefined);
+        if (completedNormally) {
+            await result.catch(() => undefined);
+        }
+        else {
+            void result.catch(() => undefined);
+        }
     }
     if (failure)
         throw failure;
@@ -133,7 +178,7 @@ export function createSessionHarness(definition) {
             ...(definition.defaults.historyWindow !== undefined ? { historyWindow: definition.defaults.historyWindow } : {})
         }
     };
-    configureHarnessAdapters(adapterContext, definition.models, definition.state, definition.sandbox, definition.memory, definition.tools);
+    configureHarnessAdapters(adapterContext, definition.models, definition.state, definition.sandbox, definition.memory, definition.tools, definition.runtime, definition.workspaceStore, definition.checkpoints);
     const modelRegistry = createModelRegistry(definition.models, { telemetry, harnessName: definition.name });
     const mcpRegistry = createMcpRunnerRegistry();
     async function ensureSessionRecord(sessionId) {
@@ -253,6 +298,54 @@ export function createSessionHarness(definition) {
         }
         return definition.runtime;
     }
+    function createContextCheckpoints(args) {
+        const store = definition.checkpoints;
+        const requireStore = () => {
+            if (!store) {
+                throw new ValidationError('No context checkpoint store is configured.', {
+                    where: 'invoke_options',
+                    issues: { reason: 'context_checkpoint_store_missing' }
+                });
+            }
+            return store;
+        };
+        const baseQuery = {
+            runId: args.runId,
+            sessionId: args.sessionId,
+            ...(args.workflowId ? { workflowId: args.workflowId } : {}),
+            ...(args.agentId ? { agentId: args.agentId } : {})
+        };
+        return {
+            async write(input) {
+                const json = JSON.stringify(input.payload);
+                if (json === undefined) {
+                    throw new ValidationError('Context checkpoint payload must be JSON-serializable.', {
+                        where: 'invoke_options',
+                        issues: { reason: 'non_json_context_checkpoint_payload' }
+                    });
+                }
+                const checkpoint = {
+                    ...baseQuery,
+                    sequence: input.sequence,
+                    kind: input.kind,
+                    payload: input.payload,
+                    payloadSizeBytes: Buffer.byteLength(json, 'utf8'),
+                    createdAt: now(),
+                    ...(input.metadata ? { metadata: input.metadata } : {})
+                };
+                await requireStore().write(checkpoint, { signal: args.signal });
+            },
+            async list(query = {}) {
+                return requireStore().list({ ...baseQuery, ...query, signal: args.signal });
+            },
+            async read(ref) {
+                return requireStore().read({ runId: args.runId, sessionId: args.sessionId, sequence: ref.sequence, kind: ref.kind });
+            },
+            async delete(ref) {
+                await requireStore().delete({ runId: args.runId, sessionId: args.sessionId, sequence: ref.sequence, kind: ref.kind });
+            }
+        };
+    }
     return {
         inspect() {
             return definition.inspection;
@@ -326,9 +419,13 @@ export function createSessionHarness(definition) {
                     }
                 },
                 async close() {
+                    if (state.busy) {
+                        throw new SessionBusyError('Session is busy.', { session_id: sessionId, reason: 'concurrent_run' });
+                    }
                     await definition.state.closeSession(sessionId);
                     sessionStates.delete(sessionId);
                     sessionStateOpenings.delete(sessionId);
+                    await mcpRegistry.closeForSandboxKey(sessionId);
                     await state.sandboxSession.close();
                 }
             };
@@ -367,7 +464,11 @@ export function createSessionHarness(definition) {
         $infer: {}
     };
     async function* streamAgentCall(sessionId, agentId, agent, input, opts) {
-        yield* relayRunEvents((onEvent) => runAgentCall(sessionId, agentId, agent, input, opts, onEvent));
+        yield* relayRunEvents((onEvent, relaySignal) => {
+            const combined = combineSignals(relaySignal, opts?.signal);
+            return runAgentCall(sessionId, agentId, agent, input, { ...opts, signal: combined.signal }, onEvent)
+                .finally(() => combined.cleanup());
+        });
     }
     async function runAgentCall(sessionId, agentId, agent, input, opts, onEvent) {
         validateInvokeOptions(opts);
@@ -377,44 +478,43 @@ export function createSessionHarness(definition) {
         if (opts?.signal?.aborted) {
             throw new OperationCancelledError('Run was cancelled before start.', { scope: 'run' });
         }
-        const runSignal = createRunSignal(opts?.signal, opts?.timeoutMs ?? definition.defaults.runTimeoutMs);
+        // Busy check precedes createRunSignal so an early SessionBusyError cannot
+        // leak the run-timeout timer or the caller-signal abort listener.
         const state = await getSessionState(sessionId);
         if (state.busy) {
             throw new SessionBusyError('Session is busy.', { session_id: sessionId, reason: 'concurrent_run' });
         }
         state.busy = true;
+        const runSignal = createRunSignal(opts?.signal, opts?.timeoutMs ?? definition.defaults.runTimeoutMs);
         const startedAt = now();
         const runId = ulid();
-        const memory = memoryFacade({
-            sessionId,
-            runId,
-            agentId,
-            signal: runSignal.signal,
-            sandboxSession: state.sandboxSession,
-            metadata: opts?.metadata ?? {}
-        });
-        const runRecord = {
-            id: runId,
-            sessionId,
-            kind: 'agent',
-            target: agentId,
-            startedAt,
-            status: 'running',
-            input: input
-        };
         const emit = async (event) => {
             const eventAt = 'at' in event ? event.at : now();
             await onEvent?.(event);
             await appendEvents(runId, [{ id: ulid(), runId, at: eventAt, type: event.type, payload: sanitizeEventForPersistence(event) }]);
         };
+        let runCreated = false;
         try {
+            const memory = memoryFacade({
+                sessionId,
+                runId,
+                agentId,
+                signal: runSignal.signal,
+                sandboxSession: state.sandboxSession,
+                metadata: opts?.metadata ?? {}
+            });
+            const checkpoints = createContextCheckpoints({ sessionId, runId, agentId, signal: runSignal.signal });
+            const runRecord = {
+                id: runId,
+                sessionId,
+                kind: 'agent',
+                target: agentId,
+                startedAt,
+                status: 'running',
+                input: input
+            };
             await definition.state.createRun(runRecord);
-        }
-        catch (error) {
-            state.busy = false;
-            throw error;
-        }
-        try {
+            runCreated = true;
             const result = await withIncomingTraceContext(telemetry, opts, definition.logger, async () => telemetry.span('harness.session.agent_prompt', {
                 'harness.name': definition.name,
                 'harness.session.id': sessionId,
@@ -444,6 +544,7 @@ export function createSessionHarness(definition) {
                     mcpRegistry,
                     session: state.sandboxSession,
                     memory,
+                    checkpoints,
                     mountedSkills: state.mountedSkills,
                     ...(resolvedHistoryWindow !== undefined ? { historyWindow: resolvedHistoryWindow } : {}),
                     maxSteps: definition.defaults.agentMaxIterations ?? 16,
@@ -469,6 +570,9 @@ export function createSessionHarness(definition) {
         }
         catch (error) {
             const finalError = normalizeRunError(error, runSignal.signal);
+            if (!runCreated) {
+                throw finalError;
+            }
             const finishedAt = now();
             const serialized = serializeError(finalError);
             const log = finalError instanceof OperationCancelledError ? definition.logger.warn.bind(definition.logger) : definition.logger.error.bind(definition.logger);
@@ -505,7 +609,11 @@ export function createSessionHarness(definition) {
         }
     }
     async function* streamWorkflowCall(sessionId, workflowId, workflow, input, opts) {
-        yield* relayRunEvents((onEvent) => runWorkflowCall(sessionId, workflowId, workflow, input, opts, onEvent));
+        yield* relayRunEvents((onEvent, relaySignal) => {
+            const combined = combineSignals(relaySignal, opts?.signal);
+            return runWorkflowCall(sessionId, workflowId, workflow, input, { ...opts, signal: combined.signal }, onEvent)
+                .finally(() => combined.cleanup());
+        });
     }
     async function runWorkflowCall(sessionId, workflowId, workflow, input, opts, onEvent) {
         validateInvokeOptions(opts);
@@ -513,22 +621,16 @@ export function createSessionHarness(definition) {
         if (opts?.signal?.aborted) {
             throw new OperationCancelledError('Run was cancelled before start.', { scope: 'run' });
         }
-        const runSignal = createRunSignal(opts?.signal, opts?.timeoutMs ?? definition.defaults.runTimeoutMs);
+        // Busy check precedes createRunSignal so an early SessionBusyError cannot
+        // leak the run-timeout timer or the caller-signal abort listener.
         const state = await getSessionState(sessionId);
         if (state.busy) {
             throw new SessionBusyError('Session is busy.', { session_id: sessionId, reason: 'concurrent_run' });
         }
         state.busy = true;
+        const runSignal = createRunSignal(opts?.signal, opts?.timeoutMs ?? definition.defaults.runTimeoutMs);
         const startedAt = now();
         const runId = opts?.durable ? opts.durable.runId : ulid();
-        const memory = memoryFacade({
-            sessionId,
-            runId,
-            workflowId,
-            signal: runSignal.signal,
-            sandboxSession: state.sandboxSession,
-            metadata: opts?.metadata ?? {}
-        });
         const runRecord = {
             id: runId,
             sessionId,
@@ -543,14 +645,16 @@ export function createSessionHarness(definition) {
             await onEvent?.(event);
             await appendEvents(runId, [{ id: ulid(), runId, at: eventAt, type: event.type, payload: sanitizeEventForPersistence(event) }]);
         };
-        try {
-            await definition.state.createRun(runRecord);
-        }
-        catch (error) {
-            state.busy = false;
-            throw error;
-        }
         let durableBinding;
+        let runSandboxSession = state.sandboxSession;
+        let runMountedSkills = state.mountedSkills;
+        let closeRunSandbox = false;
+        let runCreated = false;
+        const delegationState = {
+            totalChildAgentCalls: 0,
+            activeChildAgentCalls: 0,
+            inFlightChildCalls: new Set()
+        };
         try {
             if (durableRuntime && opts?.durable) {
                 durableBinding = await beginDurableWorkflow({
@@ -565,7 +669,23 @@ export function createSessionHarness(definition) {
                     logger: definition.logger,
                     harnessName: definition.name
                 });
+                if (definition.workspaceStore) {
+                    runSandboxSession = await definition.sandbox.open({ sessionId, runId, signal: runSignal.signal });
+                    runMountedSkills = new Set();
+                    closeRunSandbox = true;
+                }
             }
+            const memory = memoryFacade({
+                sessionId,
+                runId,
+                workflowId,
+                signal: runSignal.signal,
+                sandboxSession: runSandboxSession,
+                metadata: opts?.metadata ?? {}
+            });
+            const checkpoints = createContextCheckpoints({ sessionId, runId, workflowId, signal: runSignal.signal });
+            await definition.state.createRun(runRecord);
+            runCreated = true;
             const result = await withIncomingTraceContext(telemetry, opts, definition.logger, async () => telemetry.span('harness.session.prompt', {
                 'harness.name': definition.name,
                 'harness.session.id': sessionId,
@@ -582,11 +702,13 @@ export function createSessionHarness(definition) {
                     'harness.run.id': runId,
                     'harness.workflow.id': workflowId
                 });
+                const delegationPolicy = resolveDelegationPolicy(workflow);
                 const workflowArgs = {
                     workflowId,
                     workflow,
                     input,
                     ctx: {
+                        log: definition.logger,
                         signal: runSignal.signal,
                         runId,
                         sessionId,
@@ -599,12 +721,47 @@ export function createSessionHarness(definition) {
                         metadata: opts?.metadata ?? {},
                         metrics: workflowMetrics,
                         memory,
+                        checkpoints,
                         step: durableBinding ? durableBinding.step : passthroughStep,
                         agents: Object.fromEntries(Object.entries(definition.agents).map(([agentId, agent]) => [
                             agentId,
                             async (agentInput, agentOpts) => {
-                                const agentSignal = combineSignals(runSignal.signal, agentOpts?.signal);
-                                try {
+                                // Spec 10 "Cancellation": starting a child-agent call after
+                                // abort throws OperationCancelledError synchronously, before
+                                // policy checks run or budgets are consumed.
+                                if (runSignal.signal.aborted) {
+                                    throw abortError(runSignal.signal, 'run', 'Run was cancelled.');
+                                }
+                                if (agentOpts?.signal?.aborted) {
+                                    throw new OperationCancelledError('Child-agent call was cancelled before start.', { scope: 'run' }, agentOpts.signal.reason);
+                                }
+                                validateInvokeOptions(agentOpts);
+                                if (agentOpts?.durable) {
+                                    throw new ValidationError('Durable execution is only supported for workflow runs.', { where: 'invoke_options', issues: { durable: 'agent_run' } });
+                                }
+                                // An unknown per-call model alias is an invoke-option mistake;
+                                // it must not pass the delegation gate or consume call budget.
+                                if (agentOpts?.model !== undefined && !(agentOpts.model in definition.models)) {
+                                    throw new ValidationError('Unknown model alias for child-agent call.', { where: 'invoke_options', issues: { model: agentOpts.model } });
+                                }
+                                const selectedModelAlias = agentOpts?.model ?? agent.model;
+                                assertDelegationAllowed({
+                                    policy: delegationPolicy,
+                                    state: delegationState,
+                                    workflowId,
+                                    agentId,
+                                    modelAlias: selectedModelAlias
+                                });
+                                // Compose signals before consuming budget so a composition
+                                // failure can never leak an active delegation slot.
+                                const combinedSignal = combineSignals(runSignal.signal, agentOpts?.signal);
+                                const agentSignal = agentOpts?.timeoutMs !== undefined
+                                    ? createRunSignal(combinedSignal.signal, agentOpts.timeoutMs)
+                                    : combinedSignal;
+                                delegationState.totalChildAgentCalls += 1;
+                                delegationState.activeChildAgentCalls += 1;
+                                const delegationCallId = `delegate_${ulid()}`;
+                                const childCall = (async () => {
                                     const resolvedHistoryWindow = agentOpts?.historyWindow ?? opts?.historyWindow ?? definition.defaults.historyWindow;
                                     const agentMetadata = { ...(opts?.metadata ?? {}), ...(agentOpts?.metadata ?? {}) };
                                     const agentMemory = memoryFacade({
@@ -613,31 +770,37 @@ export function createSessionHarness(definition) {
                                         workflowId,
                                         agentId,
                                         signal: agentSignal.signal,
-                                        sandboxSession: state.sandboxSession,
+                                        sandboxSession: runSandboxSession,
                                         metadata: agentMetadata
                                     });
+                                    const agentCheckpoints = createContextCheckpoints({ sessionId, runId, workflowId, agentId, signal: agentSignal.signal });
                                     const run = await runDefaultAgent({
                                         harnessName: definition.name,
                                         agentId,
                                         runId,
                                         sessionId,
                                         workflowId,
+                                        delegationCallId,
+                                        delegationDepth: CHILD_DELEGATION_DEPTH,
                                         input: agentInput,
                                         history: await definition.state.listMessages(sessionId),
                                         agent: agent,
+                                        modelAlias: selectedModelAlias,
                                         models: withRunEventModelRegistry(modelRegistry, {
                                             harnessName: definition.name,
                                             sessionId,
                                             runId,
                                             workflowId,
-                                            agentId
+                                            agentId,
+                                            modelAlias: selectedModelAlias
                                         }, emit),
                                         skills: resolvedSkills,
                                         customTools: definition.tools,
                                         mcpRegistry,
-                                        session: state.sandboxSession,
+                                        session: runSandboxSession,
                                         memory: agentMemory,
-                                        mountedSkills: state.mountedSkills,
+                                        checkpoints: agentCheckpoints,
+                                        mountedSkills: runMountedSkills,
                                         ...(resolvedHistoryWindow !== undefined ? { historyWindow: resolvedHistoryWindow } : {}),
                                         maxSteps: definition.defaults.agentMaxIterations ?? 16,
                                         signal: agentSignal.signal,
@@ -652,9 +815,17 @@ export function createSessionHarness(definition) {
                                         await definition.state.appendMessages(sessionId, run.emitted);
                                     }
                                     return run.output;
+                                })();
+                                delegationState.inFlightChildCalls.add(childCall);
+                                try {
+                                    return await childCall;
                                 }
                                 finally {
+                                    delegationState.inFlightChildCalls.delete(childCall);
+                                    delegationState.activeChildAgentCalls -= 1;
                                     agentSignal.cleanup();
+                                    if (agentSignal !== combinedSignal)
+                                        combinedSignal.cleanup();
                                 }
                             }
                         ]))
@@ -671,6 +842,11 @@ export function createSessionHarness(definition) {
                     ...(opts ? { opts: { ...opts, signal: runSignal.signal } } : { opts: { signal: runSignal.signal } })
                 }));
             }));
+            // A resolved handler may still have child-agent calls in flight; settle
+            // them before terminalizing so no run events trail run.finished.
+            if (delegationState.inFlightChildCalls.size > 0) {
+                await Promise.allSettled([...delegationState.inFlightChildCalls]);
+            }
             const finishedAt = now();
             if (durableBinding) {
                 await guardDurableStep({ sessionId, runId, workflowId, operation: 'finish_success' }, () => durableBinding.finishSuccess(result));
@@ -684,8 +860,18 @@ export function createSessionHarness(definition) {
         }
         catch (error) {
             const finalError = normalizeRunError(error, runSignal.signal);
+            // A handler rejection mid-Promise.all must not orphan in-flight child
+            // agents: cancel them through the run signal and await settlement before
+            // run.finished is emitted and the session busy lock is released.
+            if (delegationState.inFlightChildCalls.size > 0) {
+                runSignal.abort(finalError);
+                await Promise.allSettled([...delegationState.inFlightChildCalls]);
+            }
             const finishedAt = now();
             const serialized = serializeError(finalError);
+            if (!runCreated) {
+                throw finalError;
+            }
             if (durableBinding && finalError instanceof OperationCancelledError) {
                 await guardDurableStep({ sessionId, runId, workflowId, operation: 'finish_cancelled' }, () => durableBinding.finishCancelled(finalError));
             }
@@ -722,13 +908,91 @@ export function createSessionHarness(definition) {
             // id can resume; a no-op once the run was settled (success/cancel).
             if (durableBinding)
                 await durableBinding.dispose();
+            if (closeRunSandbox) {
+                try {
+                    await runSandboxSession.close();
+                }
+                catch (error) {
+                    definition.logger.warn('Failed to close durable run sandbox.', {
+                        harness: definition.name,
+                        session_id: sessionId,
+                        run_id: runId,
+                        workflow_id: workflowId,
+                        error: serializeError(error)
+                    });
+                }
+            }
             runSignal.cleanup();
             state.busy = false;
         }
     }
     /** Pass-through step used when a workflow runs without durable execution. */
-    function passthroughStep(_stepId, fn) {
-        return fn();
+    function passthroughStep(_stepId, fn, options = {}) {
+        return runStepWithRetry(fn, options.retry);
+    }
+    function resolveDelegationPolicy(workflow) {
+        const configured = workflow.delegation;
+        const policy = configured ?? {};
+        const enabled = configured ? policy.enabled !== false : definition.defaults.delegation?.enabled === true;
+        return {
+            enabled,
+            ...(policy.agents ? { allowedAgents: new Set(policy.agents) } : {}),
+            maxChildAgentCalls: policy.maxChildAgentCalls ?? definition.defaults.delegation?.maxChildAgentCalls ?? DEFAULT_MAX_CHILD_AGENT_CALLS,
+            maxParallelChildAgentCalls: policy.maxParallelChildAgentCalls ?? definition.defaults.delegation?.maxParallelChildAgentCalls ?? DEFAULT_MAX_PARALLEL_CHILD_AGENT_CALLS,
+            maxDepth: policy.maxDepth ?? definition.defaults.delegation?.maxDepth ?? DEFAULT_MAX_DELEGATION_DEPTH,
+            ...(policy.modelAliases ? { modelAliases: new Set(policy.modelAliases) } : {}),
+            agentModelAliases: new Map(Object.entries(policy.agentModelAliases ?? {}).map(([agentId, aliases]) => [agentId, new Set(aliases)]))
+        };
+    }
+    function assertDelegationAllowed(args) {
+        const { policy, state, workflowId, agentId, modelAlias } = args;
+        if (!policy.enabled) {
+            throw new DelegationPolicyError('Workflow child-agent delegation is disabled.', {
+                workflow_id: workflowId,
+                agent_id: agentId,
+                reason: 'delegation_disabled'
+            });
+        }
+        if (policy.allowedAgents && !policy.allowedAgents.has(agentId)) {
+            throw new DelegationPolicyError('Workflow is not allowed to invoke this child agent.', {
+                workflow_id: workflowId,
+                agent_id: agentId,
+                reason: 'agent_not_allowed'
+            });
+        }
+        if (CHILD_DELEGATION_DEPTH > policy.maxDepth) {
+            throw new DelegationPolicyError('Workflow child-agent delegation depth exceeded.', {
+                workflow_id: workflowId,
+                agent_id: agentId,
+                reason: 'max_delegation_depth_exceeded',
+                limit: policy.maxDepth
+            });
+        }
+        if (state.totalChildAgentCalls >= policy.maxChildAgentCalls) {
+            throw new DelegationPolicyError('Workflow child-agent call budget exceeded.', {
+                workflow_id: workflowId,
+                agent_id: agentId,
+                reason: 'max_child_agent_calls_exceeded',
+                limit: policy.maxChildAgentCalls
+            });
+        }
+        if (state.activeChildAgentCalls >= policy.maxParallelChildAgentCalls) {
+            throw new DelegationPolicyError('Workflow parallel child-agent call budget exceeded.', {
+                workflow_id: workflowId,
+                agent_id: agentId,
+                reason: 'max_parallel_child_agent_calls_exceeded',
+                limit: policy.maxParallelChildAgentCalls
+            });
+        }
+        const allowedModels = policy.agentModelAliases.get(agentId) ?? policy.modelAliases;
+        if (allowedModels && !allowedModels.has(modelAlias)) {
+            throw new DelegationPolicyError('Workflow is not allowed to invoke this child agent with the selected model alias.', {
+                workflow_id: workflowId,
+                agent_id: agentId,
+                reason: 'model_alias_not_allowed',
+                model_alias: modelAlias
+            });
+        }
     }
     /**
      * Runs a durable finalization side effect (runtime finish / workspace lifecycle)
@@ -874,7 +1138,7 @@ function isObjectPartialChunk(chunk) {
 function isObjectFinishChunk(chunk) {
     return Boolean(chunk && typeof chunk === 'object' && chunk.kind === 'finish' && Object.prototype.hasOwnProperty.call(chunk, 'object'));
 }
-function configureHarnessAdapters(context, models, state, sandbox, memory, tools) {
+function configureHarnessAdapters(context, models, state, sandbox, memory, tools, runtime, workspaceStore, checkpoints) {
     const seen = new Set();
     for (const alias of Object.values(models)) {
         configureOne(alias.provider, context, seen);
@@ -882,11 +1146,16 @@ function configureHarnessAdapters(context, models, state, sandbox, memory, tools
     configureOne(state, context, seen);
     configureOne(sandbox, context, seen);
     configureOne(memory, context, seen);
+    configureOne(runtime, context, seen);
+    configureOne(workspaceStore, context, seen);
+    configureOne(checkpoints, context, seen);
     for (const tool of Object.values(tools)) {
         configureOne(tool, context, seen);
     }
 }
 function configureOne(adapter, context, seen) {
+    if (!adapter)
+        return;
     const configurable = adapter;
     if (!configurable.configureHarnessContext || seen.has(adapter))
         return;
@@ -933,26 +1202,6 @@ function resolveContentCaptureMode(options) {
         return envValue;
     return 'NO_CONTENT';
 }
-function metadataSpanAttrs(metadata) {
-    const attrs = {};
-    for (const [key, value] of Object.entries(metadata ?? {})) {
-        if (!/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(key))
-            continue;
-        if (typeof value === 'string') {
-            if (value.length <= 256)
-                attrs[`harness.metadata.${key}`] = value;
-            continue;
-        }
-        if (typeof value === 'number' && Number.isFinite(value)) {
-            attrs[`harness.metadata.${key}`] = value;
-            continue;
-        }
-        if (typeof value === 'boolean') {
-            attrs[`harness.metadata.${key}`] = value;
-        }
-    }
-    return attrs;
-}
 function isValidTraceparent(traceparent) {
     const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(traceparent);
     if (!match)
@@ -1030,10 +1279,10 @@ function sanitizeEventForPersistence(event) {
                 ...(event.error ? { error: event.error } : {})
             };
         case 'agent.started':
-            return { agentId: event.agentId };
+            return agentRunEventMeta(event);
         case 'agent.finished':
             return {
-                agentId: event.agentId,
+                ...agentRunEventMeta(event),
                 ...(event.output !== undefined ? { output: '[redacted]' } : {}),
                 ...(event.error ? { error: event.error } : {})
             };
@@ -1091,6 +1340,16 @@ function modelStreamEventMeta(event) {
         ...(event.streamId ? { streamId: event.streamId } : {})
     };
 }
+function agentRunEventMeta(event) {
+    return {
+        agentId: event.agentId,
+        ...(event.workflowId ? { workflowId: event.workflowId } : {}),
+        ...(event.parentAgentId ? { parentAgentId: event.parentAgentId } : {}),
+        ...(event.delegationCallId ? { delegationCallId: event.delegationCallId } : {}),
+        ...(event.delegationDepth !== undefined ? { delegationDepth: event.delegationDepth } : {}),
+        ...(event.modelAlias ? { modelAlias: event.modelAlias } : {})
+    };
+}
 function isJsonRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -1121,6 +1380,8 @@ function createRunSignal(parent, timeoutMs) {
         : undefined;
     return {
         signal: controller.signal,
+        /** Harness-initiated abort, e.g. to cancel in-flight child-agent calls. */
+        abort: (reason) => controller.abort(runAbortReason(reason)),
         cleanup: () => {
             if (timeout)
                 clearTimeout(timeout);