@nylorun/harness 0.12.0-beta → 0.15.0-beta

package/dist/loop/options.js

@@ -0,0 +1,69 @@
+import { checkCompatibility } from "../definition/compatibility.js";
+import { initializeExecutionState } from "./initial-state.js";
+import { canonical } from "@nylorun/core/define";
+import { HarnessError } from "@nylorun/core/define";
+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)
+        throw new HarnessError("execution.incompatible", "Saved state requires the original compatible agent and outputSchema");
+    if (canonical(state.outputContract) !== canonical(agent.output?.schema.jsonSchema))
+        throw new HarnessError("execution.incompatible", "Saved state requires the original compatible agent and outputSchema");
+    if (state.manifestHash) {
+        const compatibility = checkCompatibility(agent.manifest, state);
+        if (!compatibility.ok)
+            throw compatibility.error;
+    }
+    const hasActive = state.status === "active" || state.plan?.calls.some((call) => call.status === "active");
+    // Crash-continue: allow resume when a prior run left active work; mark redelivery.
+    if (hasActive && options.input && typeof options.input === "object" && "kind" in options.input) {
+        const kind = options.input.kind;
+        if (kind !== "continue" && kind !== "settle" && kind !== "approve" && kind !== "respond")
+            throw new HarnessError("execution.invalid-state", "Execution was interrupted with possibly active effects. Resume with continue/settle/approve/respond; automatic replay is not supported.");
+    }
+    else if (hasActive) {
+        throw new HarnessError("execution.invalid-state", "Execution was interrupted with possibly active effects. Reconcile it before starting another run; automatic replay is not supported.");
+    }
+    if (state.status !== "paused" && state.plan !== undefined && !hasActive)
+        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,
+        redelivery: Boolean(hasActive),
+    };
+}

package/dist/loop/resume.d.ts

@@ -0,0 +1,4 @@
+import type { BoundToolDefinition } from "@nylorun/core/define";
+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/loop/resume.js

@@ -0,0 +1,52 @@
+import { HarnessError } from "@nylorun/core/define";
+import { copyJson } from "@nylorun/core/define";
+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/loop/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 "@nylorun/core/define";
+/** 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>>;

package/dist/loop/run.js

@@ -0,0 +1,264 @@
+import { HostSuspension } from "./host-suspension.js";
+import { HarnessError, isHarnessError } from "@nylorun/core/define";
+import { runStep } from "./step/run.js";
+import { createId } from "../utils/ids.js";
+import { dispatchPlan } from "./dispatch.js";
+import { createInvocation } from "./invocation.js";
+import { openExecution, validateRunOptions } from "./options.js";
+import { applyResume } from "./resume.js";
+/** All mutable progress belongs to this invocation and is discarded when it settles. */
+export async function execute(agent, options) {
+    validateRunOptions(options);
+    const opened = openExecution(agent, options);
+    let { state } = opened;
+    const { input, definitions } = opened;
+    if (state.status === "paused" && !(input.kind === "continue" && options.signal?.aborted)) {
+        state = applyResume(state, input, definitions);
+        if (input.kind === "approve" || input.kind === "respond")
+            state = {
+                ...state,
+                transcript: [
+                    ...state.transcript,
+                    { kind: "input", turnId: state.plan.turnId, event: input },
+                ],
+            };
+    }
+    else if (input.kind === "approve" || input.kind === "respond" || input.kind === "settle") {
+        throw new HarnessError("execution.invalid-input", "There is no matching paused operation for this input");
+    }
+    const invocation = createInvocation({ agent, options, state, definitions });
+    const { signal, observe, record } = invocation;
+    const finish = (result) => finishInvocation(invocation, result);
+    try {
+        signal.throwIfAborted();
+        let turnId;
+        let stepNumber;
+        let arrivals = [];
+        let toolResults = [];
+        if (invocation.state.plan) {
+            turnId = invocation.state.plan.turnId;
+            stepNumber = invocation.state.plan.stepNumber + 1;
+            invocation.state = { ...invocation.state, status: "active" };
+            await record();
+            if ((await dispatchPlan(invocation)) === "paused")
+                return finish({ status: "paused" });
+            toolResults = lastResults(invocation.state);
+        }
+        else {
+            turnId = createId("turn");
+            stepNumber = 1;
+            if (input.kind !== "continue" && input.kind !== "settle")
+                arrivals = [input];
+            invocation.state = {
+                ...invocation.state,
+                status: "active",
+                turnCount: invocation.state.turnCount + 1,
+                transcript: [
+                    ...invocation.state.transcript,
+                    ...arrivals.map((event) => ({ kind: "input", turnId, event })),
+                ],
+            };
+            await record();
+        }
+        for (;; stepNumber++) {
+            signal.throwIfAborted();
+            const stepId = createId("step");
+            const snapshot = {
+                id: invocation.state.executionId,
+                status: "running",
+                revision: invocation.state.revision,
+                turnCount: invocation.state.turnCount,
+                transcript: invocation.state.transcript,
+            };
+            const result = await runStep({
+                agent: {
+                    middleware: agent.middleware,
+                    invoke: options.onModelCall,
+                    registry: agent.registry,
+                    definition: agent,
+                    sessionState: invocation.sessionBag,
+                    recordAfterDynamics: async () => {
+                        await record();
+                    },
+                },
+                state: snapshot,
+                executionId: invocation.state.executionId,
+                turnId,
+                stepId,
+                turnNumber: invocation.state.turnCount,
+                stepNumber,
+                arrivals,
+                toolResults,
+                signal,
+                info: options.info,
+                observe,
+                output: agent.output,
+            });
+            signal.throwIfAborted();
+            if (result.candidate) {
+                invocation.state = {
+                    ...invocation.state,
+                    transcript: [
+                        ...invocation.state.transcript,
+                        { kind: "candidate", turnId, stepId, candidate: result.candidate },
+                    ],
+                };
+                observe({
+                    type: "model.completed",
+                    turnId,
+                    stepId,
+                    ...(result.modelInvocationId ? { invocationId: result.modelInvocationId } : {}),
+                    ...(result.requestedModelId === undefined
+                        ? {}
+                        : { requestedModelId: result.requestedModelId }),
+                    attributes: result.candidate,
+                });
+            }
+            if (result.output.kind === "tripwire") {
+                observe({
+                    type: "tripwire",
+                    turnId,
+                    stepId,
+                    code: result.output.tripwire.code,
+                    scope: result.output.tripwire.scope ?? "step",
+                    attributes: { message: result.output.tripwire.message },
+                });
+                return finish({ status: "failed", error: result.output.tripwire });
+            }
+            if (result.output.kind === "final") {
+                invocation.state = {
+                    ...invocation.state,
+                    transcript: [
+                        ...invocation.state.transcript,
+                        { kind: "final", turnId, stepId, output: result.output.output },
+                    ],
+                };
+                observe({
+                    type: "turn.completed",
+                    turnId,
+                    stepId,
+                    attributes: { output: result.output.output },
+                });
+                return finish({ status: "completed", output: result.output.output });
+            }
+            const plan = result.output.plan;
+            const calls = plan.executable.map((entry) => {
+                const reference = agent.registry.reference(entry.definition);
+                definitions.set(entry.invocationId, agent.registry.restore(reference));
+                return {
+                    callId: entry.call.callId,
+                    toolName: entry.call.toolName,
+                    args: entry.call.args,
+                    rawArgs: entry.rawArgs,
+                    invocationId: entry.invocationId,
+                    reference,
+                    status: entry.interaction ? "interaction" : "pending",
+                    ...(entry.interaction
+                        ? { interaction: entry.interaction, interactionPhase: "before" }
+                        : {}),
+                };
+            });
+            invocation.state = {
+                ...invocation.state,
+                plan: {
+                    turnId,
+                    stepId,
+                    stepNumber,
+                    order: plan.order,
+                    immediate: plan.immediateResults,
+                    calls,
+                },
+            };
+            observe({
+                type: "tool.sealed",
+                turnId,
+                stepId,
+                attributes: {
+                    executable: plan.executable.map((entry) => ({
+                        callId: entry.call.callId,
+                        toolName: entry.call.toolName,
+                        args: entry.call.args,
+                        rawArgs: entry.rawArgs,
+                        invocationId: entry.invocationId,
+                        owner: entry.owner,
+                        ...(entry.interaction ? { interaction: entry.interaction } : {}),
+                    })),
+                    immediate: plan.immediateResults,
+                },
+            });
+            await record();
+            if ((await dispatchPlan(invocation)) === "paused")
+                return finish({ status: "paused" });
+            toolResults = lastResults(invocation.state);
+            arrivals = [];
+        }
+    }
+    catch (error) {
+        if (error instanceof HostSuspension)
+            throw error;
+        if (isHarnessError(error) && error.code === "execution.record-failed")
+            throw error;
+        if (signal.aborted)
+            return finish({ status: "cancelled" });
+        return finish({
+            status: "failed",
+            error: {
+                code: isHarnessError(error) ? error.code : "execution.failed",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+async function finishInvocation(invocation, result) {
+    if (result.status === "cancelled" && invocation.state.plan) {
+        const plan = invocation.state.plan;
+        const results = [
+            ...plan.immediate,
+            ...plan.calls.map((call) => call.result ?? {
+                kind: "failed",
+                callId: call.callId,
+                toolName: call.toolName,
+                code: "tool.cancelled",
+                message: "Invocation cancelled; external effects are not automatically retried",
+            }),
+        ];
+        const { plan: _, ...rest } = invocation.state;
+        invocation.state = {
+            ...rest,
+            cancelledCalls: [
+                ...(rest.cancelledCalls ?? []),
+                ...plan.calls.filter((call) => !call.result),
+            ],
+            transcript: [
+                ...invocation.state.transcript,
+                {
+                    kind: "tool-results",
+                    turnId: plan.turnId,
+                    stepId: plan.stepId,
+                    results: plan.order.map((item) => results.find((result) => result.callId === item.callId && result.toolName === item.toolName)),
+                },
+            ],
+        };
+    }
+    invocation.state = { ...invocation.state, status: result.status };
+    await invocation.record();
+    invocation.emit({
+        type: `execution.${result.status}`,
+        ...(result.status === "completed"
+            ? { attributes: { output: result.output } }
+            : result.status === "failed"
+                ? { attributes: { error: result.error } }
+                : {}),
+    });
+    if (result.status === "paused")
+        return {
+            status: "paused",
+            state: invocation.state,
+            pending: invocation.state.plan.calls.filter((call) => call.status === "interaction" || call.status === "deferred"),
+        };
+    return { ...result, state: invocation.state };
+}
+function lastResults(state) {
+    const entry = state.transcript[state.transcript.length - 1];
+    return entry?.kind === "tool-results" ? entry.results : [];
+}

package/dist/loop/state.d.ts

@@ -0,0 +1,8 @@
+import type { BuiltAgent } from "@nylorun/core/define";
+import type { ExecutionInput, ExecutionState } from "../types/execution.js";
+import type { InputEvent } from "@nylorun/core/define";
+export declare function createExecutionState<Info, Output>(agent: BuiltAgent<Info, Output>): ExecutionState;
+export declare function validateExecutionState(value: unknown): ExecutionState;
+export declare function normalizeInput(value: ExecutionInput): InputEvent | Extract<ExecutionInput, {
+    kind: "continue" | "settle";
+}>;

package/dist/loop/state.js

@@ -0,0 +1,218 @@
+import { z } from "zod";
+import { HarnessError } from "@nylorun/core/define";
+import { assertJson, copyJson } from "@nylorun/core/define";
+import { definitionFor } from "../definition/agent-definition.js";
+import { initializeExecutionState } from "./initial-state.js";
+import { validateTranscript } from "./transcript.js";
+const id = z.string().min(1);
+const json = z.unknown().refine((value) => {
+    try {
+        assertJson(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, "Expected JSON data");
+const interaction = z
+    .object({
+    id,
+    kind: z.enum(["approval", "response"]),
+    prompt: z.string(),
+    metadata: json.optional(),
+})
+    .strict();
+const outcome = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("completed"), output: json }).strict(),
+    z.object({ kind: z.literal("denied"), reason: z.string() }).strict(),
+    z.object({ kind: z.literal("failed"), code: id, message: z.string() }).strict(),
+]);
+const reference = z
+    .object({
+    capabilityId: id,
+    toolName: id,
+    descriptor: z
+        .object({
+        name: id,
+        description: z.string().optional(),
+        inputSchema: z.record(z.string(), json),
+        outputSchema: z.record(z.string(), json).optional(),
+    })
+        .strict(),
+})
+    .strict();
+const call = z
+    .object({
+    callId: id,
+    invocationId: id,
+    toolName: id,
+    args: json,
+    rawArgs: json,
+    reference,
+    status: z.enum(["pending", "active", "settled", "interaction", "deferred"]),
+    result: json.optional(),
+    interaction: interaction.optional(),
+    interactionPhase: z.enum(["before", "execute"]).optional(),
+    resume: z
+        .discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("approval"),
+            interactionId: id,
+            approved: z.boolean(),
+            token: json.optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal("response"),
+            interactionId: id,
+            value: json,
+            token: json.optional(),
+        })
+            .strict(),
+    ])
+        .optional(),
+    token: json.optional(),
+    wait: z
+        .object({
+        kind: z.enum(["ask", "approve", "sleep", "waitFor"]),
+        waitId: id,
+        name: z.string().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const schema = z
+    .object({
+    version: z.literal(1),
+    agentId: id,
+    manifestHash: id.optional(),
+    executionId: id,
+    outputContract: z.record(z.string(), json).optional(),
+    revision: z.number().int().nonnegative(),
+    turnCount: z.number().int().nonnegative(),
+    transcript: z.array(json),
+    status: z.enum(["ready", "active", "completed", "paused", "cancelled", "failed"]),
+    cancelledCalls: z.array(call).optional(),
+    state: z.record(z.string(), json).optional(),
+    plan: z
+        .object({
+        turnId: id,
+        stepId: id,
+        stepNumber: z.number().int().positive(),
+        order: z.array(z.object({ callId: id, toolName: id }).strict()),
+        immediate: z.array(json),
+        calls: z.array(call),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+export function createExecutionState(agent) {
+    return initializeExecutionState(definitionFor(agent));
+}
+function omitLegacyExecutionVersion(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return value;
+    if (!("executionVersion" in value))
+        return value;
+    const { executionVersion: _ignored, ...rest } = value;
+    return rest;
+}
+export function validateExecutionState(value) {
+    try {
+        assertJson(value);
+        const parsed = schema.parse(omitLegacyExecutionVersion(value));
+        validateTranscript(parsed.transcript);
+        const plan = parsed.plan;
+        if (parsed.status === "paused" && !plan)
+            throw new HarnessError("execution.invalid-state", "Paused execution requires a pending plan");
+        if (plan) {
+            const ids = new Set();
+            const invocations = new Set();
+            const interactions = new Set();
+            const ordered = new Set(plan.order.map((item) => item.callId));
+            if (ordered.size !== plan.order.length ||
+                plan.order.length !== plan.calls.length + plan.immediate.length)
+                throw new HarnessError("execution.invalid-state", "Plan order must identify every result exactly once");
+            for (const result of plan.immediate) {
+                if (ids.has(result.callId) ||
+                    !plan.order.some((item) => item.callId === result.callId && item.toolName === result.toolName))
+                    throw new HarnessError("execution.invalid-state", "Invalid immediate result identity");
+                ids.add(result.callId);
+            }
+            for (const item of plan.calls) {
+                if (ids.has(item.callId) || invocations.has(item.invocationId))
+                    throw new HarnessError("execution.invalid-state", "Duplicate pending call identity");
+                ids.add(item.callId);
+                invocations.add(item.invocationId);
+                if (!plan.order.some((order) => order.callId === item.callId && order.toolName === item.toolName))
+                    throw new HarnessError("execution.invalid-state", "Pending call missing from plan order");
+                if (item.toolName !== item.reference.descriptor.name)
+                    throw new HarnessError("execution.invalid-state", "Pending tool name differs from its contract");
+                if (item.toolName !== item.reference.toolName)
+                    throw new HarnessError("execution.invalid-state", "Pending tool name differs from its reference");
+                if (item.interaction) {
+                    if (interactions.has(item.interaction.id))
+                        throw new HarnessError("execution.invalid-state", "Duplicate interaction identity");
+                    interactions.add(item.interaction.id);
+                }
+                if (item.status !== "settled" && item.result)
+                    throw new HarnessError("execution.invalid-state", "Unsettled call cannot contain a result");
+                if (item.status === "settled" && !item.result)
+                    throw new HarnessError("execution.invalid-state", "Settled call requires a result");
+                if (item.status === "interaction" && (!item.interaction || !item.interactionPhase))
+                    throw new HarnessError("execution.invalid-state", "Missing interaction state");
+                if (item.result &&
+                    (item.result.callId !== item.callId || item.result.toolName !== item.toolName))
+                    throw new HarnessError("execution.invalid-state", "Result identity mismatch");
+            }
+            validateTranscript([
+                {
+                    kind: "tool-results",
+                    turnId: plan.turnId,
+                    stepId: plan.stepId,
+                    results: [
+                        ...plan.immediate,
+                        ...plan.calls.flatMap((item) => (item.result ? [item.result] : [])),
+                    ],
+                },
+            ]);
+            if (parsed.status === "paused" &&
+                (plan.calls.some((item) => item.status === "active") ||
+                    !plan.calls.some((item) => item.status === "interaction" || item.status === "deferred")))
+                throw new HarnessError("execution.invalid-state", "Invalid paused plan");
+        }
+        return copyJson(parsed);
+    }
+    catch (cause) {
+        throw new HarnessError("execution.invalid-state", `Invalid execution state: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+}
+export function normalizeInput(value) {
+    try {
+        if (typeof value === "string")
+            return { kind: "user-message", text: value };
+        assertJson(value);
+        if ("kind" in value && value.kind === "continue")
+            return z
+                .object({ kind: z.literal("continue") })
+                .strict()
+                .parse(value);
+        if ("kind" in value && value.kind === "settle")
+            return z
+                .object({ kind: z.literal("settle"), invocationId: id, outcome })
+                .strict()
+                .parse(value);
+        const event = "kind" in value ? value : { kind: "user-message", ...value };
+        const validated = validateTranscript([
+            { kind: "input", turnId: "validation", event: event },
+        ]);
+        return validated[0].event;
+    }
+    catch (cause) {
+        throw new HarnessError("execution.invalid-input", `Invalid input: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+}

package/dist/{step → loop/step}/canonicalize.d.ts

@@ -1,5 +1,5 @@
-import type { ModelCandidate, ModelOutputBlock, ModelToolCall } from "../types/model.js";
-import type { JsonObject } from "../types/shared.js";
+import type { ModelCandidate, ModelOutputBlock, ModelToolCall } from "@nylorun/core/define";
+import type { JsonObject } from "@nylorun/core/define";
 export interface CanonicalCall {
     readonly id: string;
     readonly name: string;

package/dist/{step → loop/step}/canonicalize.js

@@ -1,5 +1,5 @@
-import { createId } from "../utils/ids.js";
-import { copyJson } from "../utils/immutable.js";
+import { createId } from "../../utils/ids.js";
+import { copyJson } from "@nylorun/core/define";
 export function canonicalizeCalls(calls) {
     const idCounts = new Map();
     for (const call of calls) {

package/dist/{step → loop/step}/compose.d.ts

@@ -1,4 +1,5 @@
-import type { BoundMiddleware, StepResponse } from "../types/middleware.js";
-import type { ObserveEmit } from "../utils/observe.js";
+import type { BoundMiddleware } from "@nylorun/core/define";
+import type { StepResponse } from "@nylorun/core/define";
+import type { ObserveEmit } from "../observe.js";
 import { StepContext } from "./step-context.js";
 export declare function runMiddleware(middleware: readonly BoundMiddleware[], context: StepContext, terminal: () => Promise<StepResponse>, observe: ObserveEmit): Promise<StepResponse>;