@purista/harness 1.2.6 → 1.5.0

package/README.md

@@ -15,6 +15,12 @@ Telemetry defaults to dual GenAI and OpenInference attributes with no content
 capture. `InvokeOptions.traceparent` and `tracestate` accept inbound W3C Trace
 Context so application traces can parent harness run spans.
 
+Workflows can orchestrate typed child agents with `ctx.agents.<id>(input)`.
+Child-agent calls are disabled until a workflow declares `delegation` or the
+harness opts in with `defaults.delegation.enabled: true`. Opted-in workflows get
+bounded fan-out, agent allowlists, per-agent model alias overrides, and
+lineage-rich run events.
+
 See [Evaluating Prompts](https://github.com/puristajs/harness/blob/main/docs/guides/evaluating-prompts.md)
 for the execution model, scorer limits, and privacy behavior.
 

package/dist/agents/index.d.ts

@@ -1,7 +1,7 @@
 import type { Logger } from '../logger/index.js';
 import type { JsonValue } from '../models/json.js';
 import type { Message } from '../models/state.js';
-import type { AgentDefinition, ResolvedSkill, RunEvent, ToolsConfig } from '../harness/defineHarness.js';
+import type { AgentDefinition, ContextCheckpoints, ResolvedSkill, RunEvent, ToolsConfig } from '../harness/defineHarness.js';
 import type { MemoryFacade } from '../ports/memory.js';
 import type { SandboxSession } from '../sandbox/index.js';
 import { type TelemetryShim } from '../telemetry/index.js';
@@ -12,15 +12,19 @@ export declare function runDefaultAgent(args: {
     runId: string;
     sessionId: string;
     workflowId?: string;
+    delegationCallId?: string;
+    delegationDepth?: number;
     input: unknown;
     history: Message[];
     agent: AgentDefinition<any>;
+    modelAlias?: string;
     models: Record<string, any>;
     skills: Record<string, ResolvedSkill>;
     customTools: ToolsConfig;
     mcpRegistry?: McpRunnerRegistry;
     session: SandboxSession;
     memory: MemoryFacade;
+    checkpoints: ContextCheckpoints;
     mountedSkills: Set<string>;
     historyWindow?: number;
     maxSteps: number;
@@ -35,3 +39,5 @@ export declare function runDefaultAgent(args: {
     output: JsonValue;
     emitted: Message[];
 }>;
+/** Runs `fn` over `items` with bounded concurrency, preserving input order. */
+export declare function runLimited<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/dist/agents/index.js

@@ -7,6 +7,7 @@ import { BUILTIN_ALIAS_TO_CANONICAL, getBuiltinToolSpecs, invokeBuiltinTool } fr
 import { getMcpToolSpecs, invokeMcpTool, isMcpToolDefinition } from '../tools/mcp/runner.js';
 import { ulid } from '../ulid/index.js';
 import { abortError, withAbortSignal } from '../runtime/abort.js';
+import { metadataSpanAttrs } from '../telemetry/span-attrs.js';
 function stringifyInput(input) { return typeof input === 'string' ? input : JSON.stringify(input); }
 function isReadonlyBuiltin(name) { return ['read', 'list', 'glob', 'grep'].includes(name); }
 async function checkPermission(agentId, runId, sessionId, def, toolName, input) {
@@ -93,6 +94,8 @@ export async function runDefaultAgent(args) {
         'harness.session.id': args.sessionId,
         'harness.run.id': args.runId,
         ...(args.workflowId ? { 'harness.workflow.id': args.workflowId } : {}),
+        ...(args.delegationCallId ? { 'harness.agent.delegation_call_id': args.delegationCallId } : {}),
+        ...(args.delegationDepth !== undefined ? { 'harness.agent.delegation_depth': args.delegationDepth } : {}),
         'harness.agent.id': args.agentId,
         'gen_ai.operation.name': 'invoke_agent',
         'openinference.span.kind': 'AGENT',
@@ -100,33 +103,24 @@ export async function runDefaultAgent(args) {
         'metadata.agent_id': args.agentId,
         [ATTR_GEN_AI_AGENT_NAME]: args.agentId,
         [ATTR_GEN_AI_AGENT_ID]: args.agentId,
-        'harness.agent.model': args.agent.model,
+        'harness.agent.model': args.modelAlias ?? args.agent.model,
+        ...(args.modelAlias && args.modelAlias !== args.agent.model ? { 'harness.agent.default_model': args.agent.model } : {}),
         'harness.agent.has_handler': args.agent.handler !== undefined,
         ...metadataSpanAttrs(args.metadata)
     };
     const metrics = createMetrics(args.telemetry, agentAttrs);
-    const execute = () => runDefaultAgentInner({ ...args, metrics });
-    return args.telemetry.span(`invoke_agent ${args.agentId}`, agentAttrs, execute);
-}
-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;
+    // Spec 08 §9: the harness tracks activated skill names per run when the
+    // `read` tool loads `/skills/<name>/SKILL.md`. Only the count is emitted —
+    // skill names stay out of telemetry.
+    const activatedSkills = new Set();
+    return args.telemetry.span(`invoke_agent ${args.agentId}`, agentAttrs, async (span) => {
+        try {
+            return await runDefaultAgentInner({ ...args, metrics, activatedSkills });
         }
-        if (typeof value === 'boolean') {
-            attrs[`harness.metadata.${key}`] = value;
+        finally {
+            span.setAttribute('harness.agent.skills_activated', activatedSkills.size);
         }
-    }
-    return attrs;
+    });
 }
 async function runDefaultAgentInner(args) {
     if (args.signal.aborted)
@@ -134,12 +128,12 @@ async function runDefaultAgentInner(args) {
     const inputSchema = args.agent.input ?? z.string();
     const outputSchema = args.agent.output ?? z.string();
     const parsedInput = parseAgentSchema(inputSchema, args.input, 'agent_input');
-    const model = args.models[args.agent.model];
+    const selectedModelAlias = args.modelAlias ?? args.agent.model;
+    const model = args.models[selectedModelAlias];
     if (!model)
-        throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: args.agent.model } });
+        throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: selectedModelAlias } });
     const skillIds = args.agent.skills ?? [];
     await mountSkillsOnce(args.session, args.mountedSkills, args.skills, skillIds);
-    const activatedSkills = new Set();
     if (args.agent.handler) {
         const handler = args.agent.handler;
         const output = await withAbortSignal(args.signal, 'run', 'Run was cancelled.', () => handler({
@@ -150,6 +144,7 @@ async function runDefaultAgentInner(args) {
             sessionId: args.sessionId,
             history: { list: async () => args.history },
             memory: args.memory,
+            checkpoints: args.checkpoints,
             metadata: args.metadata ?? {},
             metrics: args.metrics
         }));
@@ -157,7 +152,7 @@ async function runDefaultAgentInner(args) {
         return { output: validated, emitted: [{ id: `msg_${ulid()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() }] };
     }
     const baseInstructions = typeof args.agent.instructions === 'function'
-        ? args.agent.instructions({ input: parsedInput, runId: args.runId, sessionId: args.sessionId, history: { list: async () => args.history }, memory: args.memory, metadata: args.metadata ?? {}, metrics: args.metrics })
+        ? args.agent.instructions({ input: parsedInput, runId: args.runId, sessionId: args.sessionId, history: { list: async () => args.history }, memory: args.memory, checkpoints: args.checkpoints, metadata: args.metadata ?? {}, metrics: args.metrics })
         : args.agent.instructions;
     const instructions = `${baseInstructions}${buildSkillIndex(args.skills, skillIds)}`;
     const enabledBuiltins = args.agent.builtinTools === false ? [] : args.agent.builtinTools?.slice() ?? ['bash', 'read', 'write', 'edit', 'glob', 'grep', 'list'];
@@ -193,7 +188,13 @@ async function runDefaultAgentInner(args) {
     const emitted = [];
     const maxSteps = Math.min(args.agent.maxSteps ?? args.maxSteps, 64);
     let steps = 0;
-    await args.emitEvent?.({ type: 'agent.started', runId: args.runId, agentId: args.agentId, at: new Date().toISOString() });
+    const agentEventMeta = {
+        ...(args.workflowId ? { workflowId: args.workflowId } : {}),
+        ...(args.delegationCallId ? { delegationCallId: args.delegationCallId } : {}),
+        ...(args.delegationDepth !== undefined ? { delegationDepth: args.delegationDepth } : {}),
+        modelAlias: selectedModelAlias
+    };
+    await args.emitEvent?.({ type: 'agent.started', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), ...agentEventMeta });
     try {
         while (true) {
             if (args.signal.aborted)
@@ -217,12 +218,20 @@ async function runDefaultAgentInner(args) {
             // Emit one usage-bearing model event per model round-trip (including
             // tool-call steps) so run-summary modelCalls and tokenTotals are accurate
             // for multi-step runs.
-            await args.emitEvent?.({ type: 'model.object', runId: args.runId, agentId: args.agentId, object: (response.object ?? null), usage: response.usage });
+            await args.emitEvent?.({
+                type: 'model.object',
+                runId: args.runId,
+                agentId: args.agentId,
+                ...(args.workflowId ? { workflowId: args.workflowId } : {}),
+                modelAlias: selectedModelAlias,
+                object: (response.object ?? null),
+                usage: response.usage
+            });
             const toolCalls = (response.toolCalls ?? []);
             if (toolCalls.length === 0) {
                 const validated = parseAgentSchema(outputSchema, response.object, 'agent_output');
                 emitted.push({ id: `msg_${ulid()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() });
-                await args.emitEvent?.({ type: 'agent.finished', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), output: validated });
+                await args.emitEvent?.({ type: 'agent.finished', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), output: validated, ...agentEventMeta });
                 return { output: validated, emitted };
             }
             const assistantMsg = {
@@ -238,8 +247,7 @@ async function runDefaultAgentInner(args) {
             });
             const outcomes = await runLimited(toolCalls, args.maxParallelToolCalls, (call) => executeToolCall({
                 ...args,
-                enabledCustomTools,
-                activatedSkills
+                enabledCustomTools
             }, call));
             for (const outcome of outcomes) {
                 emitted.push(outcome.emitted);
@@ -250,11 +258,12 @@ async function runDefaultAgentInner(args) {
     }
     catch (error) {
         // Pair every agent.started with an agent.finished, even on error/cancel/budget.
-        await args.emitEvent?.({ type: 'agent.finished', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), error: serializeError(error) });
+        await args.emitEvent?.({ type: 'agent.finished', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), error: serializeError(error), ...agentEventMeta });
         throw error;
     }
 }
-async function runLimited(items, limit, fn) {
+/** Runs `fn` over `items` with bounded concurrency, preserving input order. */
+export async function runLimited(items, limit, fn) {
     const concurrency = Math.max(1, Math.min(limit, items.length));
     const results = new Array(items.length);
     let next = 0;
@@ -262,10 +271,10 @@ async function runLimited(items, limit, fn) {
         while (true) {
             const index = next;
             next += 1;
-            const item = items[index];
-            if (item === undefined)
+            // Index-based termination: an `undefined` element must not truncate the batch.
+            if (index >= items.length)
                 return;
-            results[index] = await fn(item);
+            results[index] = await fn(items[index]);
         }
     }
     await Promise.all(Array.from({ length: concurrency }, () => worker()));
@@ -332,9 +341,18 @@ async function executeToolCall(args, call) {
     catch (error) {
         const failure = normalizeToolFailure(canonical, error, toolKind);
         if (failure instanceof OperationCancelledError) {
-            if (args.signal.aborted)
-                throw new OperationCancelledError('Run was cancelled.', { scope: 'run' }, args.signal.reason ?? failure);
-            throw failure;
+            const cancellation = args.signal.aborted
+                ? new OperationCancelledError('Run was cancelled.', { scope: 'run' }, args.signal.reason ?? failure)
+                : failure;
+            // Pair tool.started with a best-effort tool.finished even on cancellation,
+            // matching the deliberate started/finished pairing policy above.
+            try {
+                await args.emitEvent?.({ type: 'tool.finished', runId: args.runId, agentId: args.agentId, toolId: canonical, callId: call.id, error: serializeError(cancellation) });
+            }
+            catch {
+                // Best-effort: never mask the cancellation with an emit failure.
+            }
+            throw cancellation;
         }
         result = { error: serializeError(failure) };
     }

package/dist/errors/catalog.d.ts

@@ -62,7 +62,12 @@ export declare class ModelError extends HarnessError {
         model: string;
         method: string;
         status?: number;
-        reason?: 'http_error' | 'network' | 'unstructured_response' | 'malformed_response' | 'context_length_exceeded' | 'embedding_count_mismatch' | 'rerank_result_mismatch';
+        reason?: 'http_error' | 'network' | 'rate_limited' | 'provider_unavailable' | 'unstructured_response' | 'malformed_response' | 'context_length_exceeded' | 'embedding_count_mismatch' | 'rerank_result_mismatch';
+        retryKind?: 'none' | 'active' | 'deferred';
+        retryAfterMs?: number;
+        retryAttempt?: number;
+        retryMaxAttempts?: number;
+        rateLimit?: unknown;
         providerCode?: string;
         providerType?: string;
         providerParam?: string;
@@ -98,6 +103,7 @@ export declare class ToolNotFoundError extends HarnessError {
 export declare class SkillNotFoundError extends HarnessError {
     constructor(message: string, meta: {
         skill_id: string;
+        agent_id?: string;
     }, cause?: unknown);
 }
 /** Skill manifest/frontmatter/config validation failure. */
@@ -124,6 +130,16 @@ export declare class AgentLoopBudgetError extends HarnessError {
         limit: number;
     }, cause?: unknown);
 }
+/** Workflow child-agent delegation was denied or exceeded a configured budget. */
+export declare class DelegationPolicyError extends HarnessError {
+    constructor(message: string, meta: {
+        workflow_id: string;
+        agent_id: string;
+        reason: 'delegation_disabled' | 'agent_not_allowed' | 'max_child_agent_calls_exceeded' | 'max_parallel_child_agent_calls_exceeded' | 'max_delegation_depth_exceeded' | 'model_alias_not_allowed';
+        limit?: number;
+        model_alias?: string;
+    }, cause?: unknown);
+}
 /** Session attempted to invoke unknown workflow id. */
 export declare class WorkflowNotFoundError extends HarnessError {
     constructor(message: string, meta: {
@@ -146,7 +162,7 @@ export declare class SessionBusyError extends HarnessError {
 /** State backend operation failed. */
 export declare class StateError extends HarnessError {
     constructor(message: string, meta: {
-        op: 'getSession' | 'upsertSession' | 'closeSession' | 'appendMessages' | 'listMessages' | 'clearMessages' | 'createRun' | 'finishRun' | 'getRun' | 'listRuns' | 'appendEvents' | 'listEvents' | 'memory.get' | 'memory.set' | 'memory.delete' | 'memory.list' | 'memory.search';
+        op: 'getSession' | 'upsertSession' | 'closeSession' | 'appendMessages' | 'listMessages' | 'clearMessages' | 'replaceMessages' | 'createRun' | 'finishRun' | 'getRun' | 'listRuns' | 'appendEvents' | 'listEvents' | 'contextCheckpointWrite' | 'contextCheckpointRead' | 'contextCheckpointList' | 'contextCheckpointDelete' | 'memory.get' | 'memory.set' | 'memory.delete' | 'memory.list' | 'memory.search';
         reason?: 'duplicate_message_id' | string;
         adapter?: 'memory' | string;
         memory_provider?: string;

package/dist/errors/catalog.js

@@ -33,7 +33,11 @@ export class SandboxNoExecutorError extends HarnessError {
 export class ModelError extends HarnessError {
     constructor(message, meta, cause) {
         const retriable = meta.reason === 'network'
+            || meta.reason === 'rate_limited'
+            || meta.reason === 'provider_unavailable'
             || meta.status === 429
+            || meta.status === 408
+            || meta.status === 409
             || (typeof meta.status === 'number' && meta.status >= 500);
         super({ code: 'MODEL_ERROR', category: 'model', retriable, message, meta, cause });
     }
@@ -87,6 +91,12 @@ export class AgentLoopBudgetError extends HarnessError {
         super({ code: 'AGENT_LOOP_BUDGET_EXCEEDED', category: 'validation', retriable: false, message, meta, cause });
     }
 }
+/** Workflow child-agent delegation was denied or exceeded a configured budget. */
+export class DelegationPolicyError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'DELEGATION_POLICY_ERROR', category: 'validation', retriable: false, message, meta, cause });
+    }
+}
 /** Session attempted to invoke unknown workflow id. */
 export class WorkflowNotFoundError extends HarnessError {
     constructor(message, meta, cause) {

package/dist/eval/index.d.ts

@@ -28,7 +28,7 @@ export interface ScorerResult {
     passed: boolean;
     evidence?: JsonValue;
 }
-export interface PromptCandidate<I = unknown> {
+export interface PromptCandidate {
     id: string;
     prompt: string;
     metadata?: Record<string, JsonValue>;
@@ -47,10 +47,10 @@ export interface CandidateScore {
     scorerCount: number;
 }
 export interface EvaluatePromptCandidatesInput<I = unknown> {
-    candidates: PromptCandidate<I>[];
+    candidates: PromptCandidate[];
     items: EvaluationItem<I>[];
     scorer: (target: ScorerTarget, signal: AbortSignal) => Promise<ScorerResult>;
-    runCandidate: (candidate: PromptCandidate<I>, item: EvaluationItem<I>, signal: AbortSignal) => Promise<unknown>;
+    runCandidate: (candidate: PromptCandidate, item: EvaluationItem<I>, signal: AbortSignal) => Promise<unknown>;
     signal: AbortSignal;
 }
 export declare function evaluateDeterministicScorer(definition: DeterministicScorerDefinition, target: ScorerTarget): ScorerResult;

package/dist/eval/index.js

@@ -167,8 +167,22 @@ function matchesType(value, type) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/** Structural deep equality, insensitive to object key order. */
 function deepEqual(a, b) {
-    return JSON.stringify(a) === JSON.stringify(b);
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((entry, index) => deepEqual(entry, b[index]));
+    }
+    if (isRecord(a) && isRecord(b)) {
+        const keysA = Object.keys(a);
+        if (keysA.length !== Object.keys(b).length)
+            return false;
+        return keysA.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key]));
+    }
+    return false;
 }
 function toJsonValue(value) {
     if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')

package/dist/harness/defineHarness.d.ts

@@ -6,6 +6,8 @@ import type { Metrics, TelemetryShim } from '../telemetry/index.js';
 import type { HarnessAdapterContext } from '../ports/harness-context.js';
 import type { MemoryAdapter, MemoryFacade, SessionMemory } from '../ports/memory.js';
 import type { DurableWorkspaceStore } from '../ports/workspace.js';
+import type { ContextCheckpointStore } from '../ports/context-checkpoints.js';
+import type { ContextCheckpoint, ContextCheckpointQuery } from '../ports/context-checkpoints.js';
 import type { JsonValue } from '../models/json.js';
 import type { Message } from '../models/state.js';
 import type { RunStatus } from '../models/state.js';
@@ -43,6 +45,32 @@ export interface HarnessDefaults {
      * `undefined` keeps all history, `0` keeps only system messages.
      */
     historyWindow?: number;
+    /** Default workflow child-agent delegation budgets. */
+    delegation?: DelegationDefaults;
+}
+/** Workflow child-agent delegation defaults. Delegation is disabled unless explicitly enabled. */
+export interface DelegationDefaults {
+    /**
+     * Enable workflow child-agent calls for workflows that do not declare their
+     * own `delegation` policy. Default: `false`.
+     */
+    enabled?: boolean;
+    /**
+     * Maximum child-agent calls one workflow run may start. Default: `32`.
+     * Set per workflow with `workflow.delegation.maxChildAgentCalls`.
+     */
+    maxChildAgentCalls?: number;
+    /**
+     * Maximum child-agent calls active at the same time inside one workflow run.
+     * Default: `8`.
+     */
+    maxParallelChildAgentCalls?: number;
+    /**
+     * Maximum local delegation depth. Default: `1`.
+     * Current harness workflows invoke leaf agents, so `1` allows normal
+     * workflow-to-agent calls and `0` disables child-agent delegation.
+     */
+    maxDepth?: number;
 }
 /** Top-level harness options passed to {@link defineHarness}. */
 export interface HarnessOptions {
@@ -333,21 +361,43 @@ export interface AgentContextMinimal<S extends BuilderState, I> {
     runId: string;
     history: ConversationHistory;
     memory: MemoryFacade;
+    checkpoints: ContextCheckpoints;
     metadata: Readonly<Record<string, JsonValue>>;
     metrics: Metrics;
 }
+/** Run-bound facade for explicit long-horizon context checkpoints. */
+export interface ContextCheckpoints {
+    write(input: {
+        sequence: number;
+        kind: ContextCheckpoint['kind'];
+        payload: JsonValue;
+        metadata?: Record<string, JsonValue>;
+    }): Promise<void>;
+    list(query?: Omit<ContextCheckpointQuery, 'runId' | 'sessionId' | 'workflowId' | 'agentId' | 'signal'>): Promise<readonly ContextCheckpoint[]>;
+    read(ref: {
+        sequence: number;
+        kind: ContextCheckpoint['kind'];
+    }): Promise<ContextCheckpoint | undefined>;
+    delete(ref: {
+        sequence: number;
+        kind: ContextCheckpoint['kind'];
+    }): Promise<void>;
+}
 /** Full context passed to workflow handlers. */
 export interface WorkflowContext<S extends BuilderState, I, O> {
     input: I;
     agents: {
-        [K in keyof NonNullable<S['agents']>]: (input: AgentInput<S, K>, opts?: InvokeOptions) => Promise<AgentOutput<S, K>>;
+        [K in keyof NonNullable<S['agents']>]: (input: AgentInput<S, K>, opts?: WorkflowAgentInvokeOptions<S, K>) => Promise<AgentOutput<S, K>>;
     };
     models: ModelHandles<S>;
+    /** Harness logger scoped for workflow handler code (spec 10 `WorkflowContext`). */
+    log: Logger;
     signal: AbortSignal;
     runId: string;
     sessionId: string;
     metadata: Readonly<Record<string, JsonValue>>;
     memory: MemoryFacade;
+    checkpoints: ContextCheckpoints;
     metrics: Metrics;
     /**
      * Runs `fn` as a durable step. Under a durable invocation the output is
@@ -357,6 +407,15 @@ export interface WorkflowContext<S extends BuilderState, I, O> {
     step<T extends JsonValue>(stepId: string, fn: () => Promise<T>): Promise<T>;
     output?: O;
 }
+/** Invoke options accepted by workflow-local child-agent calls. */
+export type WorkflowAgentInvokeOptions<S extends BuilderState, K extends keyof NonNullable<S['agents']>> = InvokeOptions & {
+    /**
+     * Optional model alias override for this child-agent call.
+     * The alias must exist on the harness model registry and be allowed by the
+     * workflow delegation policy.
+     */
+    model?: keyof NonNullable<S['models']> & string;
+};
 /** Full context passed to custom agent handlers. */
 export interface AgentContext<S extends BuilderState, I, O> extends AgentContextMinimal<S, I> {
     models: ModelHandles<S>;
@@ -381,6 +440,7 @@ export interface AgentDefinition<S extends BuilderState, I extends z.ZodTypeAny
 export interface WorkflowDefinition<S extends BuilderState, I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny> {
     input?: I;
     output?: O;
+    delegation?: WorkflowDelegationPolicy<S>;
     handler: (ctx: WorkflowContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 }
 type AgentSchemaFields = {
@@ -423,8 +483,26 @@ type WorkflowSchemaFields = {
 type WorkflowDefinitionResolved<S extends BuilderState, I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
     input?: I;
     output?: O;
+    delegation?: WorkflowDelegationPolicy<S>;
     handler: (ctx: WorkflowContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 };
+/** Policy for workflow-local child-agent delegation through `ctx.agents`. */
+export interface WorkflowDelegationPolicy<S extends BuilderState = BuilderState> {
+    /** Enable or disable child-agent calls for this workflow. A policy object without this field enables delegation. */
+    enabled?: boolean;
+    /** Child agent ids this workflow may call. Omit to allow all registered agents. */
+    agents?: readonly (keyof NonNullable<S['agents']> & string)[];
+    /** Per-run child-agent call limit. Overrides `defaults.delegation.maxChildAgentCalls`. */
+    maxChildAgentCalls?: number;
+    /** Per-run active child-agent call limit. Overrides `defaults.delegation.maxParallelChildAgentCalls`. */
+    maxParallelChildAgentCalls?: number;
+    /** Maximum local delegation depth. Overrides `defaults.delegation.maxDepth`. */
+    maxDepth?: number;
+    /** Model aliases allowed for every child-agent call in this workflow, including calls running on the agent's default `model`. */
+    modelAliases?: readonly (keyof NonNullable<S['models']> & string)[];
+    /** Per-child-agent model alias allowlists. These replace `modelAliases` for the named agent. */
+    agentModelAliases?: Partial<Record<keyof NonNullable<S['agents']> & string, readonly (keyof NonNullable<S['models']> & string)[]>>;
+}
 type WorkflowDefinitionFor<S extends BuilderState, D> = D extends {
     input: infer I extends z.ZodTypeAny;
     output: infer O extends z.ZodTypeAny;
@@ -576,11 +654,21 @@ export type RunEvent = {
     runId: string;
     agentId: string;
     at: string;
+    workflowId?: string;
+    parentAgentId?: string;
+    delegationCallId?: string;
+    delegationDepth?: number;
+    modelAlias?: string;
 } | {
     type: 'agent.finished';
     runId: string;
     agentId: string;
     at: string;
+    workflowId?: string;
+    parentAgentId?: string;
+    delegationCallId?: string;
+    delegationDepth?: number;
+    modelAlias?: string;
     output?: JsonValue;
     error?: SerializedError;
 } | {
@@ -657,6 +745,7 @@ export interface HarnessBuilder<S extends BuilderState = {}> {
     memory(adapter: MemoryAdapter): HarnessBuilder<S>;
     runtime(runtime: DurableRuntimeAdapter): HarnessBuilder<S>;
     workspaceStore(store: DurableWorkspaceStore): HarnessBuilder<S>;
+    checkpoints(store: ContextCheckpointStore): HarnessBuilder<S>;
     requires(capabilities: readonly AdapterCapability[]): HarnessBuilder<S>;
     defaults(defaults: HarnessDefaults): HarnessBuilder<S>;
     models<const M extends ModelsConfig>(models: M): HarnessBuilder<S & {
@@ -745,6 +834,7 @@ export interface HarnessBuilder<S extends BuilderState = {}> {
  *     summarize_ticket: {
  *       input: z.object({ ticket: z.string() }),
  *       output: z.string(),
+ *       delegation: { agents: ['summarize'] },
  *       handler: (ctx) => ctx.agents.summarize(ctx.input.ticket)
  *     }
  *   })