@nylorun/harness 0.11.1-beta → 0.13.0-beta

package/dist/definition/registry.js

@@ -0,0 +1,48 @@
+import { bindTool } from "./bind-tool.js";
+import { HarnessError } from "../errors.js";
+import { canonical } from "../utils/canonical.js";
+import { copyJson } from "../utils/immutable.js";
+/** Definition-only lookup; no per-run selections or progress live here. */
+export class ToolRegistry {
+    tools = new Map();
+    owners = new WeakMap();
+    constructor(middleware) {
+        for (const capability of middleware) {
+            for (const tool of capability.tools ?? []) {
+                const key = JSON.stringify([capability.id, tool.name]);
+                if (this.tools.has(key) || this.owners.has(tool))
+                    throw new HarnessError("tool.invalid", `Duplicate registered tool '${tool.name}' in '${capability.id}'`);
+                this.tools.set(key, bindTool(tool, { middlewareId: capability.id, slot: capability.id }));
+                this.owners.set(tool, capability.id);
+            }
+        }
+    }
+    reference(tool) {
+        const capabilityId = this.owners.get(tool.source);
+        if (!capabilityId)
+            throw new HarnessError("tool.unregistered", `Tool '${tool.name}' is not registered. Declare it in capability.tools.`);
+        const reference = copyJson({
+            capabilityId,
+            toolName: tool.source.name,
+            descriptor: descriptor(tool),
+        });
+        this.restore(reference);
+        return reference;
+    }
+    restore(reference) {
+        if ("familyId" in reference || "binding" in reference || "version" in reference)
+            throw new HarnessError("execution.incompatible", "Saved state uses a removed tool-family reference. Register an ordinary tool and start a new execution.");
+        const registered = this.tools.get(JSON.stringify([reference.capabilityId, reference.toolName]));
+        if (!registered || canonical(descriptor(registered)) !== canonical(reference.descriptor))
+            throw new HarnessError("execution.incompatible", `Missing or changed registered tool '${reference.toolName}'`);
+        return registered;
+    }
+}
+function descriptor(tool) {
+    return {
+        name: tool.name,
+        ...(tool.description === undefined ? {} : { description: tool.description }),
+        inputSchema: tool.inputSchema.jsonSchema,
+        ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema.jsonSchema }),
+    };
+}

package/dist/{build → definition}/schema.d.ts

@@ -1,8 +1,8 @@
-import type { BoundToolSchema, ToolDefinition, ToolSchema, ToolSchemaSource } from "../types/tool.js";
+import type { ToolDefinition, ToolSchema, ToolSchemaSource } from "../types/tool.js";
 export type { SchemaValidation } from "../types/tool.js";
 interface NormalizedToolSchemas {
-    readonly inputSchema: BoundToolSchema<unknown>;
-    readonly outputSchema?: BoundToolSchema<unknown>;
+    readonly inputSchema: ToolSchema<unknown>;
+    readonly outputSchema?: ToolSchema<unknown>;
 }
 /** Creates a portable, explicitly validated schema source from raw JSON Schema. */
 export declare function defineSchema<T>(value: ToolSchema<T>): ToolSchema<T>;
@@ -11,4 +11,4 @@ export declare function prepareTool<T extends ToolDefinition>(definition: T): T;
 /** Returns cached normalized contracts, preparing raw definitions on first bind. */
 export declare function normalizedSchemasFor(definition: ToolDefinition): NormalizedToolSchemas;
 /** Converts an accepted tool schema source into Harness's immutable runtime representation. */
-export declare function normalizeSchema<T>(source: ToolSchemaSource<T>, role: "input" | "output"): BoundToolSchema<T>;
+export declare function normalizeSchema<T>(source: ToolSchemaSource<T>, role: "input" | "output"): ToolSchema<T>;

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** Machine-readable error raised by Harness-owned code. */
-export type HarnessErrorCode = "agent.build-failed" | "agent.lifecycle-sealed" | "capability.state.create-failed" | "capability.state.undeclared" | "context.invalid-item" | "context.invalid-item-type" | "context.invalid-order" | "context.invalid-reason" | "context.invalid-slot" | "interaction.invalid" | "interaction.missing-resume" | "interaction.uncorrelated-resume" | "input.invalid-content" | "output.invalid" | "output.invalid-schema" | "json.invalid-data" | "json.invalid-object" | "middleware.next-after-return" | "middleware.next-called-twice" | "middleware.request-mutators-revoked" | "model.candidate-missing" | "model.adapter-invalid-options" | "model.adapter-invalid-response" | "model.invalid-candidate" | "model.invalid-directive" | "model.unsupported-content" | "model.unsupported-output-schema" | "configuration.duplicate-tool-name" | "configuration.invalid" | "configuration.invalid-instructions" | "configuration.invalid-order" | "configuration.invalid-reason" | "configuration.invalid-slot" | "configuration.invalid-tools" | "configuration.model-selection-conflict" | "response.invalid-replacement" | "session.invalid-seed" | "session.record-failed" | "session.stale-result" | "tool.invalid" | "tool.invalid-arguments" | "tool.invalid-output" | "tool.invalid-name" | "tool.invalid-schema" | "tool.invalid-tool-result";
+export type HarnessErrorCode = "execution.invalid-state" | "execution.invalid-input" | "execution.incompatible" | "execution.record-failed" | "tool.unregistered" | "tool.invalid-binding" | "agent.build-failed" | "agent.lifecycle-sealed" | "context.invalid-item" | "context.invalid-item-type" | "context.invalid-order" | "context.invalid-reason" | "context.invalid-slot" | "interaction.invalid" | "interaction.missing-resume" | "interaction.uncorrelated-resume" | "input.invalid-content" | "output.invalid" | "output.invalid-schema" | "json.invalid-data" | "json.invalid-object" | "middleware.next-after-return" | "middleware.next-called-twice" | "middleware.request-mutators-revoked" | "model.candidate-missing" | "model.adapter-invalid-options" | "model.adapter-invalid-response" | "model.invalid-candidate" | "model.invalid-directive" | "model.unsupported-content" | "model.unsupported-output-schema" | "configuration.duplicate-tool-name" | "configuration.invalid" | "configuration.invalid-instructions" | "configuration.invalid-order" | "configuration.invalid-reason" | "configuration.invalid-slot" | "configuration.invalid-tools" | "configuration.model-selection-conflict" | "response.invalid-replacement" | "tool.invalid" | "tool.invalid-arguments" | "tool.invalid-output" | "tool.invalid-name" | "tool.invalid-schema" | "tool.invalid-tool-result";
 export type HarnessErrorDetails = Readonly<Record<string, string | number | boolean>>;
 export interface HarnessErrorOptions {
     readonly cause?: unknown;

package/dist/execution/dispatch.d.ts

@@ -0,0 +1,2 @@
+import type { Invocation } from "./invocation.js";
+export declare function dispatchPlan(invocation: Invocation): Promise<"paused" | undefined>;

package/dist/execution/dispatch.js

@@ -0,0 +1,164 @@
+import { HarnessError, isHarnessError } from "../errors.js";
+import { createId } from "../utils/ids.js";
+import { copyJson } from "../utils/immutable.js";
+import { toolResult } from "./tool-result.js";
+export async function dispatchPlan(invocation) {
+    const { signal, definitions, options, observe, record } = invocation;
+    let plan = invocation.state.plan;
+    if (plan.calls.some((call) => call.status === "interaction" && call.interactionPhase === "before")) {
+        for (const call of plan.calls)
+            if (call.status === "interaction")
+                observe({
+                    type: "interaction.required",
+                    turnId: plan.turnId,
+                    stepId: plan.stepId,
+                    interactionId: call.interaction.id,
+                    kind: call.interaction.kind,
+                    callId: call.callId,
+                    toolName: call.toolName,
+                    phase: "interaction",
+                    attributes: {
+                        prompt: call.interaction.prompt,
+                        ...(call.interaction.metadata ? { metadata: call.interaction.metadata } : {}),
+                    },
+                });
+        return "paused";
+    }
+    signal.throwIfAborted();
+    const pending = plan.calls.filter((call) => call.status === "pending");
+    if (pending.length) {
+        invocation.state = {
+            ...invocation.state,
+            plan: {
+                ...plan,
+                calls: plan.calls.map((call) => call.status === "pending" ? { ...call, status: "active" } : call),
+            },
+        };
+        await record();
+        signal.throwIfAborted();
+        const settled = await Promise.all(pending.map(async (call) => {
+            const definition = definitions.get(call.invocationId);
+            const eventIds = {
+                executionId: invocation.state.executionId,
+                turnId: plan.turnId,
+                stepId: plan.stepId,
+                callId: call.callId,
+                invocationId: call.invocationId,
+                toolName: call.toolName,
+                middlewareId: call.reference.capabilityId,
+                slot: definition.owner.slot,
+            };
+            observe({ type: "tool.started", ...eventIds, attributes: { args: call.args } });
+            let outcome;
+            try {
+                signal.throwIfAborted();
+                outcome = await definition.execute(call.args, {
+                    executionId: invocation.state.executionId,
+                    turnId: plan.turnId,
+                    stepId: plan.stepId,
+                    callId: call.callId,
+                    invocationId: call.invocationId,
+                    signal,
+                    info: options.info,
+                    onModelCall: options.onModelCall,
+                    ...(call.resume ? { resume: call.resume } : {}),
+                });
+                if (!outcome || typeof outcome !== "object")
+                    throw new HarnessError("tool.invalid-tool-result", "Tool returned an invalid outcome");
+                if (outcome.kind === "interaction-required") {
+                    if (!["approval", "response"].includes(outcome.interaction.kind) ||
+                        typeof outcome.interaction.prompt !== "string")
+                        throw new HarnessError("tool.invalid-tool-result", "Tool returned an invalid interaction");
+                    return copyJson({
+                        ...call,
+                        status: "interaction",
+                        interaction: {
+                            ...outcome.interaction,
+                            id: outcome.interaction.id ?? createId("interaction"),
+                        },
+                        interactionPhase: "execute",
+                        ...(outcome.token === undefined ? {} : { token: outcome.token }),
+                    });
+                }
+                if (outcome.kind === "deferred") {
+                    observe({
+                        type: "tool.deferred",
+                        ...eventIds,
+                        attributes: outcome.token === undefined ? {} : { token: outcome.token },
+                    });
+                    return copyJson({
+                        ...call,
+                        status: "deferred",
+                        ...(outcome.token === undefined ? {} : { token: outcome.token }),
+                    });
+                }
+                const result = toolResult(call, definition, outcome);
+                observe({
+                    type: "tool.completed",
+                    ...eventIds,
+                    outcome: result.kind,
+                    attributes: result,
+                });
+                return copyJson({ ...call, status: "settled", result });
+            }
+            catch (cause) {
+                const result = {
+                    callId: call.callId,
+                    toolName: call.toolName,
+                    kind: "failed",
+                    code: signal.aborted
+                        ? "tool.cancelled"
+                        : isHarnessError(cause)
+                            ? cause.code
+                            : "tool.execution-failed",
+                    message: cause instanceof Error ? cause.message : String(cause),
+                };
+                observe({
+                    type: "tool.completed",
+                    ...eventIds,
+                    outcome: result.kind,
+                    attributes: result,
+                });
+                return copyJson({ ...call, status: "settled", result });
+            }
+        }));
+        const byId = new Map(settled.map((call) => [call.invocationId, call]));
+        plan = { ...plan, calls: plan.calls.map((call) => byId.get(call.invocationId) ?? call) };
+        invocation.state = { ...invocation.state, plan };
+        await record();
+    }
+    signal.throwIfAborted();
+    if (plan.calls.some((call) => call.status === "interaction" || call.status === "deferred")) {
+        for (const call of plan.calls)
+            if (call.status === "interaction")
+                observe({
+                    type: "interaction.required",
+                    turnId: plan.turnId,
+                    stepId: plan.stepId,
+                    interactionId: call.interaction.id,
+                    kind: call.interaction.kind,
+                    callId: call.callId,
+                    toolName: call.toolName,
+                    phase: call.interactionPhase === "before" ? "interaction" : "execute",
+                    attributes: {
+                        prompt: call.interaction.prompt,
+                        ...(call.interaction.metadata ? { metadata: call.interaction.metadata } : {}),
+                    },
+                });
+        return "paused";
+    }
+    const results = [
+        ...plan.immediate,
+        ...plan.calls.flatMap((call) => (call.result ? [call.result] : [])),
+    ];
+    const ordered = plan.order.map((item) => results.find((result) => result.callId === item.callId && result.toolName === item.toolName));
+    const { plan: _, ...rest } = invocation.state;
+    invocation.state = {
+        ...rest,
+        transcript: [
+            ...invocation.state.transcript,
+            { kind: "tool-results", turnId: plan.turnId, stepId: plan.stepId, results: ordered },
+        ],
+    };
+    await record();
+}

package/dist/execution/initial-state.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { ExecutionState } from "../types/execution.js";
+export declare function initializeExecutionState(agent: AgentDefinition): ExecutionState;

package/dist/execution/initial-state.js

@@ -0,0 +1,14 @@
+import { copyJson } from "../utils/immutable.js";
+import { createId } from "../utils/ids.js";
+export function initializeExecutionState(agent) {
+    return copyJson({
+        version: 1,
+        agentId: agent.id,
+        executionId: createId("execution"),
+        revision: 0,
+        turnCount: 0,
+        transcript: [],
+        status: "ready",
+        ...(agent.output ? { outputContract: agent.output.schema.jsonSchema } : {}),
+    });
+}

package/dist/execution/invocation.d.ts

@@ -0,0 +1,21 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { BoundToolDefinition } from "../definition/bound.js";
+import type { ExecutionState, RunOptions } from "../types/execution.js";
+import type { ObserveEvent } from "../types/observe.js";
+import { type ExecutionOutcomeEvent, type ObserveEmit } from "./observe.js";
+export interface Invocation {
+    readonly agent: AgentDefinition;
+    readonly options: RunOptions<any>;
+    readonly signal: AbortSignal;
+    readonly definitions: Map<string, BoundToolDefinition>;
+    state: ExecutionState;
+    observe: ObserveEmit;
+    emit(event: ObserveEvent | ExecutionOutcomeEvent): void;
+    record(): Promise<void>;
+}
+export declare function createInvocation(input: {
+    readonly agent: AgentDefinition;
+    readonly options: RunOptions<any>;
+    readonly state: ExecutionState;
+    readonly definitions: Map<string, BoundToolDefinition>;
+}): Invocation;

package/dist/execution/invocation.js

@@ -0,0 +1,32 @@
+import { HarnessError } from "../errors.js";
+import { copyJson } from "../utils/immutable.js";
+import { createId } from "../utils/ids.js";
+import { createObservationSink } from "./observe.js";
+export function createInvocation(input) {
+    const invocation = {
+        agent: input.agent,
+        options: input.options,
+        signal: input.options.signal ?? new AbortController().signal,
+        definitions: input.definitions,
+        state: input.state,
+    };
+    const sink = createObservationSink({
+        listener: input.options.onEvent,
+        executionId: () => invocation.state.executionId,
+        runId: createId("run"),
+    });
+    invocation.observe = sink.observe;
+    invocation.emit = sink.emit;
+    invocation.record = async () => {
+        invocation.state = copyJson({ ...invocation.state, revision: invocation.state.revision + 1 });
+        if (!input.options.record)
+            return;
+        try {
+            await input.options.record(copyJson(invocation.state));
+        }
+        catch (cause) {
+            throw new HarnessError("execution.record-failed", "Recording failed. Execution stopped; reconcile any external effects before retrying.", { cause });
+        }
+    };
+    return invocation;
+}

package/dist/{model → execution/model}/adapters.d.ts

@@ -1,5 +1,5 @@
-import type { ModelAdapter, ModelAdapterContext, ModelCall, ModelCandidate } from "../types/model.js";
-import type { JsonObject } from "../types/shared.js";
+import type { ModelAdapter, ModelAdapterContext, ModelCall, ModelCandidate } from "../../types/model.js";
+import type { JsonObject } from "../../types/shared.js";
 export type ChatCompletionsMessage = {
     readonly role: "system";
     readonly content: string;

package/dist/{model → execution/model}/adapters.js

@@ -1,5 +1,5 @@
-import { HarnessError } from "../errors.js";
-import { copyJsonObject } from "../utils/immutable.js";
+import { HarnessError } from "../../errors.js";
+import { copyJsonObject } from "../../utils/immutable.js";
 import { preparedModel } from "./prepared.js";
 /** Translate a Harness call to the OpenAI Chat Completions request shape. */
 export function toChatCompletions(call) {

package/dist/{model → execution/model}/normalize.d.ts

@@ -1,5 +1,5 @@
-import { HarnessError } from "../errors.js";
-import type { ModelCandidate, ModelDirective, ModelOutputBlock } from "../types/model.js";
+import { HarnessError } from "../../errors.js";
+import type { ModelCandidate, ModelDirective, ModelOutputBlock } from "../../types/model.js";
 export declare function normalizeDirective(value: unknown): ModelDirective | HarnessError;
 export declare function sameDirective(left: ModelDirective, right: ModelDirective): boolean;
 export declare function textFromOutput(output: readonly ModelOutputBlock[]): string;

package/dist/{model → execution/model}/normalize.js

@@ -1,5 +1,5 @@
-import { HarnessError, isHarnessError } from "../errors.js";
-import { assertJson, copyJson, copyJsonObject } from "../utils/immutable.js";
+import { HarnessError, isHarnessError } from "../../errors.js";
+import { assertJson, copyJson, copyJsonObject } from "../../utils/immutable.js";
 const FINISH_REASONS = new Set([
     "stop",
     "length",

package/dist/{model → execution/model}/prepared.d.ts

@@ -1,5 +1,5 @@
-import type { ModelAdapter, ModelAdapterContext, ModelCandidate, ModelCall } from "../types/model.js";
-import type { DeferredOutcome, JsonValue } from "../types/shared.js";
+import type { ModelAdapter, ModelAdapterContext, ModelCandidate, ModelCall } from "../../types/model.js";
+import type { JsonValue } from "../../types/shared.js";
 export interface PreparedModelOptions<Wire> {
     readonly adapter: string;
     prepare(call: ModelCall, context: ModelAdapterContext): Promise<{
@@ -7,7 +7,7 @@ export interface PreparedModelOptions<Wire> {
         readonly observed: JsonValue;
     }>;
     send(request: Wire, call: ModelCall, context: ModelAdapterContext): Promise<unknown>;
-    decode(response: unknown, call: ModelCall): ModelCandidate | string | DeferredOutcome;
+    decode(response: unknown, call: ModelCall): ModelCandidate | string;
 }
 /**
  * Builds a ModelAdapter that reports the provider request derived from Harness's canonical call.

package/dist/{step → execution/model}/project.d.ts

@@ -1,2 +1,2 @@
-import type { ModelCall, ModelRequest } from "../types/model.js";
+import type { ModelCall, ModelRequest } from "../../types/model.js";
 export declare function projectModelCall(request: ModelRequest): ModelCall;

package/dist/{step → execution/model}/project.js

@@ -1,4 +1,4 @@
-import { copyJson } from "../utils/immutable.js";
+import { copyJson, freezeGraph } from "../../utils/immutable.js";
 export function projectModelCall(request) {
     return freezeGraph({
         prompt: Object.freeze([
@@ -13,7 +13,7 @@ export function projectModelCall(request) {
         }))),
         ...(request.model === undefined ? {} : { model: copyJson(request.model) }),
         ...(request.outputSchema === undefined ? {} : { outputSchema: copyJson(request.outputSchema) }),
-        sessionId: request.sessionId,
+        executionId: request.executionId,
     });
 }
 function projectInstructions(instructions) {
@@ -121,11 +121,3 @@ function freezeItem(item) {
         content: Object.freeze(item.content.map((part) => Object.freeze(part))),
     });
 }
-function freezeGraph(value, seen = new WeakSet()) {
-    if (!value || typeof value !== "object" || seen.has(value))
-        return value;
-    seen.add(value);
-    for (const item of Object.values(value))
-        freezeGraph(item, seen);
-    return Object.freeze(value);
-}

package/dist/execution/observe.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutionEvent } from "../types/execution.js";
+import type { ObserveEvent, Observer } from "../types/observe.js";
+import type { JsonValue } from "../types/shared.js";
+export type ObserveEmit = (event: ObserveEvent | (() => ObserveEvent)) => void;
+export type ExecutionOutcomeEvent = {
+    type: "execution.completed" | "execution.paused" | "execution.cancelled" | "execution.failed" | "observation.failed";
+    attributes?: Record<string, JsonValue>;
+};
+export declare function createObservationSink(input: {
+    readonly listener?: (event: ExecutionEvent) => void | Promise<void>;
+    readonly executionId: () => string;
+    readonly runId: string;
+}): {
+    readonly observe: ObserveEmit;
+    readonly emit: (event: ObserveEvent | ExecutionOutcomeEvent) => void;
+};
+export declare function emitObserve(listener: Observer | undefined, event: ObserveEvent | (() => ObserveEvent)): void;

package/dist/execution/observe.js

@@ -0,0 +1,53 @@
+import { copyJson } from "../utils/immutable.js";
+export function createObservationSink(input) {
+    let sequence = 0;
+    let reportingFailure = false;
+    const emit = (event) => {
+        if (!input.listener)
+            return;
+        const value = copyJson({
+            ...event,
+            executionId: input.executionId(),
+            runId: input.runId,
+            sequence: ++sequence,
+        });
+        const failed = () => {
+            if (reportingFailure || event.type === "observation.failed")
+                return;
+            reportingFailure = true;
+            emit({
+                type: "observation.failed",
+                attributes: { message: "Execution observer failed; execution is continuing" },
+            });
+            reportingFailure = false;
+        };
+        try {
+            const result = input.listener(value);
+            if (result)
+                void Promise.resolve(result).catch(failed);
+        }
+        catch {
+            failed();
+        }
+    };
+    return {
+        emit,
+        observe(source) {
+            if (!input.listener)
+                return;
+            emit(typeof source === "function" ? source() : source);
+        },
+    };
+}
+export function emitObserve(listener, event) {
+    if (!listener)
+        return;
+    try {
+        const result = listener(typeof event === "function" ? event() : event);
+        if (result)
+            void Promise.resolve(result).catch(() => undefined);
+    }
+    catch {
+        // Observation is deliberately fail-open for ObserveEvent-only callers.
+    }
+}

package/dist/execution/options.d.ts

@@ -0,0 +1,10 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { BoundToolDefinition } from "../definition/bound.js";
+import type { ExecutionState, RunOptions } from "../types/execution.js";
+import { normalizeInput } from "./state.js";
+export declare function validateRunOptions(options: RunOptions<any>): void;
+export declare function openExecution(agent: AgentDefinition, options: RunOptions<any>): {
+    readonly state: ExecutionState;
+    readonly input: ReturnType<typeof normalizeInput>;
+    readonly definitions: Map<string, BoundToolDefinition>;
+};

package/dist/execution/options.js

@@ -0,0 +1,49 @@
+import { initializeExecutionState } from "./initial-state.js";
+import { canonical } from "../utils/canonical.js";
+import { HarnessError } from "../errors.js";
+import { normalizeInput, validateExecutionState } from "./state.js";
+const acceptedOptions = new Set([
+    "state",
+    "input",
+    "onModelCall",
+    "info",
+    "signal",
+    "onEvent",
+    "record",
+]);
+export function validateRunOptions(options) {
+    if (!options || typeof options.onModelCall !== "function")
+        throw new HarnessError("execution.invalid-input", "run() requires input and onModelCall");
+    for (const key of Object.keys(options))
+        if (!acceptedOptions.has(key))
+            throw new HarnessError("execution.invalid-input", `Unknown run option '${key}'`);
+    for (const key of ["record", "onEvent"])
+        if (options[key] !== undefined && typeof options[key] !== "function")
+            throw new HarnessError("execution.invalid-input", `${key} must be a function`);
+    if (options.signal !== undefined &&
+        (!options.signal ||
+            typeof options.signal.throwIfAborted !== "function" ||
+            typeof options.signal.addEventListener !== "function"))
+        throw new HarnessError("execution.invalid-input", "signal must be an AbortSignal");
+}
+export function openExecution(agent, options) {
+    const state = options.state === undefined
+        ? initializeExecutionState(agent)
+        : validateExecutionState(options.state);
+    if (state.agentId !== agent.id ||
+        canonical(state.outputContract) !== canonical(agent.output?.schema.jsonSchema))
+        throw new HarnessError("execution.incompatible", "Saved state requires the original compatible agent and outputSchema");
+    if ((state.status !== "paused" && state.plan !== undefined) ||
+        state.status === "active" ||
+        state.plan?.calls.some((call) => call.status === "active"))
+        throw new HarnessError("execution.invalid-state", "Execution was interrupted with possibly active effects. Reconcile it before starting another run; automatic replay is not supported.");
+    const definitions = new Map();
+    for (const call of state.plan?.calls ?? []) {
+        const definition = agent.registry.restore(call.reference);
+        const validation = definition.inputSchema.validate(call.rawArgs);
+        if (!validation.ok || canonical(validation.value) !== canonical(call.args))
+            throw new HarnessError("execution.incompatible", "Saved tool arguments differ from their accepted contract");
+        definitions.set(call.invocationId, definition);
+    }
+    return { state, input: normalizeInput(options.input), definitions };
+}

package/dist/execution/resume.d.ts

@@ -0,0 +1,4 @@
+import type { BoundToolDefinition } from "../definition/bound.js";
+import type { ExecutionState } from "../types/execution.js";
+import type { normalizeInput } from "./state.js";
+export declare function applyResume(state: ExecutionState, input: ReturnType<typeof normalizeInput>, definitions: Map<string, BoundToolDefinition>): ExecutionState;

package/dist/execution/resume.js

@@ -0,0 +1,52 @@
+import { HarnessError } from "../errors.js";
+import { copyJson } from "../utils/immutable.js";
+import { toolResult } from "./tool-result.js";
+export function applyResume(state, input, definitions) {
+    const plan = state.plan;
+    let matched = false;
+    const calls = plan.calls.map((call) => {
+        if (input.kind === "settle" &&
+            call.status === "deferred" &&
+            call.invocationId === input.invocationId) {
+            matched = true;
+            return {
+                ...call,
+                status: "settled",
+                result: toolResult(call, definitions.get(call.invocationId), input.outcome),
+            };
+        }
+        if ((input.kind === "approve" || input.kind === "respond") &&
+            call.status === "interaction" &&
+            call.interaction.id === input.interactionId) {
+            if ((input.kind === "approve") !== (call.interaction.kind === "approval"))
+                throw new HarnessError("execution.invalid-input", "Interaction response kind does not match the saved request");
+            matched = true;
+            const { interaction: _, interactionPhase: __, resume: ___, ...rest } = call;
+            if (input.kind === "approve" && !input.approved)
+                return {
+                    ...rest,
+                    status: "settled",
+                    result: {
+                        kind: "denied",
+                        callId: call.callId,
+                        toolName: call.toolName,
+                        reason: "Approval rejected",
+                    },
+                };
+            return {
+                ...rest,
+                status: "pending",
+                resume: {
+                    interactionId: input.interactionId,
+                    kind: input.kind === "approve" ? "approval" : "response",
+                    ...(input.kind === "approve" ? { approved: input.approved } : { value: input.value }),
+                    ...(call.token === undefined ? {} : { token: call.token }),
+                },
+            };
+        }
+        return call;
+    });
+    if (!matched)
+        throw new HarnessError("execution.invalid-input", "Input does not match a pending approval, response, or deferred invocation");
+    return copyJson({ ...state, plan: { ...plan, calls } });
+}

package/dist/execution/run.d.ts

@@ -0,0 +1,5 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { RunOptions, RunResult } from "../types/execution.js";
+import type { JsonValue } from "../types/shared.js";
+/** All mutable progress belongs to this invocation and is discarded when it settles. */
+export declare function execute(agent: AgentDefinition, options: RunOptions<any>): Promise<RunResult<JsonValue>>;