@purista/harness 1.2.6 → 1.5.1

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,11 @@ 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];
-    if (!model)
-        throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: args.agent.model } });
+    const selectedModelAlias = args.modelAlias ?? args.agent.model;
+    if (!args.models[selectedModelAlias])
+        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 +143,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 +151,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'];
@@ -180,6 +174,7 @@ async function runDefaultAgentInner(args) {
     });
     const mcpSpecs = args.mcpRegistry ? await getMcpToolSpecs(args.customTools, enabledCustomTools, { registry: args.mcpRegistry, signal: args.signal, toolTimeoutMs: args.toolTimeoutMs, sandbox: args.session, sandboxKey: args.sessionId }) : [];
     const customSpecs = [...tsCustomSpecs, ...mcpSpecs];
+    const allToolSpecs = [...builtinSpecs, ...customSpecs];
     const nonSystem = args.history.filter((m) => m.role !== 'system');
     const system = args.history.filter((m) => m.role === 'system');
     const cappedNonSystem = args.historyWindow === undefined ? nonSystem : args.historyWindow === 0 ? [] : nonSystem.slice(-args.historyWindow);
@@ -193,36 +188,79 @@ 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)
                 throw abortError(args.signal, 'run', 'Run was cancelled.');
             if (steps >= maxSteps)
                 throw new AgentLoopBudgetError('Agent loop budget exceeded.', { agent_id: args.agentId, reason: 'iterations_exceeded', limit: maxSteps });
+            const prepared = await args.agent.prepareStep?.({
+                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,
+                step: steps,
+                model: selectedModelAlias,
+                messages: modelMessages,
+                tools: allToolSpecs
+            });
+            const stepModelAlias = prepared?.model ?? selectedModelAlias;
+            const model = args.models[stepModelAlias];
+            if (!model)
+                throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: stepModelAlias } });
+            const stepTools = filterActiveTools(allToolSpecs, prepared?.activeTools, args.agentId);
+            const stepMessages = prepared?.messages ? [...prepared.messages] : modelMessages;
+            const stepInstructions = prepared?.instructions ?? instructions;
             const response = await model.object({
                 messages: [
-                    { role: 'system', content: instructions },
-                    ...modelMessages
+                    { role: 'system', content: stepInstructions },
+                    ...stepMessages
                 ],
-                tools: [...builtinSpecs, ...customSpecs],
-                schema: z.toJSONSchema(outputSchema)
+                tools: stepTools,
+                schema: z.toJSONSchema(outputSchema),
+                ...(prepared?.call ? { call: prepared.call } : {})
             }, args.signal, {
                 harnessName: args.harnessName,
                 sessionId: args.sessionId,
                 runId: args.runId,
                 ...(args.workflowId ? { workflowId: args.workflowId } : {}),
-                agentId: args.agentId
+                agentId: args.agentId,
+                modelAlias: stepModelAlias
             });
             // 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: stepModelAlias,
+                object: (response.object ?? null),
+                usage: response.usage
+            });
             const toolCalls = (response.toolCalls ?? []);
+            if (await shouldStopAgentLoop(args, parsedInput, stepModelAlias, steps, modelMessages, allToolSpecs, response, toolCalls)) {
+                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, ...agentEventMeta });
+                return { output: validated, emitted };
+            }
             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 +276,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 +287,47 @@ 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) {
+function filterActiveTools(tools, activeTools, agentId) {
+    if (!activeTools)
+        return [...tools];
+    const requested = new Set(activeTools);
+    const filtered = tools.filter((tool) => requested.has(tool.name));
+    if (filtered.length !== requested.size) {
+        const available = new Set(tools.map((tool) => tool.name));
+        const unknown = [...requested].filter((name) => !available.has(name));
+        throw new ValidationError('prepareStep referenced an unknown active tool.', {
+            where: 'agent_input',
+            issues: { agentId, activeTools: unknown }
+        });
+    }
+    return filtered;
+}
+async function shouldStopAgentLoop(args, input, selectedModelAlias, step, messages, tools, response, toolCalls) {
+    if (!args.agent.stopWhen)
+        return false;
+    return args.agent.stopWhen({
+        input,
+        runId: args.runId,
+        sessionId: args.sessionId,
+        history: { list: async () => args.history },
+        memory: args.memory,
+        checkpoints: args.checkpoints,
+        metadata: args.metadata ?? {},
+        metrics: args.metrics,
+        step,
+        model: selectedModelAlias,
+        messages,
+        tools,
+        response,
+        toolCalls
+    });
+}
+/** 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 +335,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 +405,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')