@nylorun/harness 0.12.0-beta → 0.15.0-beta

package/dist/loop/dispatch.js

@@ -0,0 +1,327 @@
+import { HostSuspension } from "./host-suspension.js";
+import { HarnessError, isHarnessError } from "@nylorun/core/define";
+import { isToolError } from "@nylorun/core/define";
+import { createId } from "../utils/ids.js";
+import { copyJson } from "@nylorun/core/define";
+import { createSessionStateBag } from "./initial-state.js";
+import { toolResult } from "./tool-result.js";
+import { isWaitSignal, WaitSignal } from "./waits.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" || call.status === "active");
+    const redelivering = plan.calls.some((call) => call.status === "active");
+    if (pending.length) {
+        invocation.state = {
+            ...invocation.state,
+            plan: {
+                ...plan,
+                calls: plan.calls.map((call) => call.status === "pending" || call.status === "active"
+                    ? { ...call, status: "active" }
+                    : call),
+            },
+        };
+        await record();
+        signal.throwIfAborted();
+        const sessionBag = invocation.sessionBag;
+        const stateApi = createSessionStateBag(sessionBag);
+        const settled = await settleDispatch(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();
+                if (definition.approval && !call.resume) {
+                    const decision = await definition.approval(call.args);
+                    const prompt = typeof decision === "string"
+                        ? decision
+                        : decision === true
+                            ? `Approve ${call.toolName}?`
+                            : undefined;
+                    if (prompt) {
+                        return copyJson({
+                            ...call,
+                            status: "interaction",
+                            interaction: {
+                                kind: "approval",
+                                prompt,
+                                id: createId("interaction"),
+                            },
+                            interactionPhase: "before",
+                        });
+                    }
+                }
+                const stepMemos = new Map();
+                if (call.token && typeof call.token === "object" && !Array.isArray(call.token)) {
+                    const memos = call.token.steps;
+                    if (memos)
+                        for (const [key, value] of Object.entries(memos))
+                            stepMemos.set(key, value);
+                }
+                const raw = 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,
+                    idempotencyKey: call.callId,
+                    ...(redelivering || call.status === "active" ? { redelivery: true } : {}),
+                    state: stateApi,
+                    session: { id: invocation.state.executionId },
+                    progress(message, data) {
+                        observe({
+                            type: "tool.progress",
+                            ...eventIds,
+                            attributes: {
+                                message,
+                                ...(data === undefined ? {} : { data }),
+                            },
+                        });
+                    },
+                    async ask(prompt, opts) {
+                        if (call.resume?.kind === "response")
+                            return call.resume.value;
+                        throw new WaitSignal({
+                            kind: "interaction-required",
+                            interaction: {
+                                kind: "response",
+                                prompt,
+                                ...(opts ? { metadata: opts } : {}),
+                            },
+                            wait: { kind: "ask", waitId: createId("wait") },
+                            token: { steps: Object.fromEntries(stepMemos) },
+                        });
+                    },
+                    async approve(prompt) {
+                        if (call.resume?.kind === "approval")
+                            return Boolean(call.resume.approved);
+                        throw new WaitSignal({
+                            kind: "interaction-required",
+                            interaction: { kind: "approval", prompt },
+                            wait: { kind: "approve", waitId: createId("wait") },
+                            token: { steps: Object.fromEntries(stepMemos) },
+                        });
+                    },
+                    async sleep(duration) {
+                        throw new WaitSignal({
+                            kind: "deferred",
+                            wait: { kind: "sleep", waitId: createId("wait") },
+                            token: { steps: Object.fromEntries(stepMemos), duration },
+                        });
+                    },
+                    async waitFor(event, opts) {
+                        throw new WaitSignal({
+                            kind: "deferred",
+                            wait: { kind: "waitFor", waitId: createId("wait"), name: event },
+                            token: { steps: Object.fromEntries(stepMemos), event, ...(opts ?? {}) },
+                        });
+                    },
+                    async step(name, fn) {
+                        if (stepMemos.has(name))
+                            return stepMemos.get(name);
+                        const value = await fn();
+                        stepMemos.set(name, value);
+                        return value;
+                    },
+                    ...(call.resume ? { resume: call.resume } : {}),
+                });
+                outcome = normalizeOutcome(raw);
+                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) {
+                if (cause instanceof HostSuspension)
+                    throw cause;
+                if (isWaitSignal(cause)) {
+                    if (cause.outcome.kind === "interaction-required") {
+                        return copyJson({
+                            ...call,
+                            status: "interaction",
+                            interaction: {
+                                ...cause.outcome.interaction,
+                                id: createId("interaction"),
+                            },
+                            interactionPhase: "execute",
+                            wait: cause.outcome.wait,
+                            ...(cause.outcome.token === undefined ? {} : { token: cause.outcome.token }),
+                        });
+                    }
+                    observe({
+                        type: "tool.deferred",
+                        ...eventIds,
+                        attributes: cause.outcome.token === undefined ? {} : { token: cause.outcome.token },
+                    });
+                    return copyJson({
+                        ...call,
+                        status: "deferred",
+                        wait: cause.outcome.wait,
+                        ...(cause.outcome.token === undefined ? {} : { token: cause.outcome.token }),
+                    });
+                }
+                if (isToolError(cause)) {
+                    const result = {
+                        callId: call.callId,
+                        toolName: call.toolName,
+                        kind: "failed",
+                        code: cause.code,
+                        message: cause.message,
+                    };
+                    observe({
+                        type: "tool.completed",
+                        ...eventIds,
+                        outcome: result.kind,
+                        attributes: result,
+                    });
+                    return copyJson({ ...call, status: "settled", result });
+                }
+                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();
+}
+function normalizeOutcome(raw) {
+    if (raw && typeof raw === "object" && "kind" in raw) {
+        const kind = raw.kind;
+        if (kind === "completed" ||
+            kind === "denied" ||
+            kind === "failed" ||
+            kind === "interaction-required" ||
+            kind === "deferred")
+            return raw;
+    }
+    return { kind: "completed", output: raw };
+}
+// Persist all parallel action intents before handing control back to a durable host.
+async function settleDispatch(promises) {
+    const results = await Promise.allSettled(promises);
+    const failure = results.find((r) => r.status === "rejected");
+    if (failure)
+        throw failure.reason;
+    return results.map((r) => r.value);
+}

package/dist/loop/host-suspension.d.ts

@@ -0,0 +1,6 @@
+/** Control transfer to a durable host, never a model/tool failure. */
+export declare class HostSuspension extends Error {
+    readonly effectId: string;
+    readonly status: "pending" | "uncertain";
+    constructor(effectId: string, status: "pending" | "uncertain");
+}

package/dist/loop/host-suspension.js

@@ -0,0 +1,10 @@
+/** Control transfer to a durable host, never a model/tool failure. */
+export class HostSuspension extends Error {
+    effectId;
+    status;
+    constructor(effectId, status) {
+        super(`Host suspended at ${effectId}`);
+        this.effectId = effectId;
+        this.status = status;
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { ExecutionState } from "../types/execution.js";
+import type { JsonObject, JsonValue } from "@nylorun/core/define";
+export declare function initializeExecutionState(agent: AgentDefinition, options?: {
+    readonly executionId?: string;
+    readonly state?: JsonObject;
+}): ExecutionState;
+/** Mutable session-memory bag backed by Invocation / ExecutionState.state. */
+export declare function createSessionStateBag(bag: Record<string, JsonValue>): {
+    get(key: string): JsonValue | undefined;
+    set(key: string, value: JsonValue): void;
+    entries(): Readonly<Record<string, JsonValue>>;
+};

package/dist/loop/initial-state.js

@@ -0,0 +1,30 @@
+import { copyJson } from "@nylorun/core/define";
+import { createId } from "../utils/ids.js";
+export function initializeExecutionState(agent, options = {}) {
+    return copyJson({
+        version: 1,
+        agentId: agent.id,
+        manifestHash: agent.hash,
+        executionId: options.executionId ?? createId("execution"),
+        revision: 0,
+        turnCount: 0,
+        transcript: [],
+        status: "ready",
+        state: options.state ?? {},
+        ...(agent.output ? { outputContract: agent.output.schema.jsonSchema } : {}),
+    });
+}
+/** Mutable session-memory bag backed by Invocation / ExecutionState.state. */
+export function createSessionStateBag(bag) {
+    return {
+        get(key) {
+            return bag[key];
+        },
+        set(key, value) {
+            bag[key] = value;
+        },
+        entries() {
+            return { ...bag };
+        },
+    };
+}

package/dist/loop/invocation.d.ts

@@ -0,0 +1,24 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { BoundToolDefinition } from "@nylorun/core/define";
+import type { ExecutionState, RunOptions } from "../types/execution.js";
+import type { ObserveEvent } from "@nylorun/core/define";
+import type { JsonValue } from "@nylorun/core/define";
+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;
+    /** Mutable durable session memory for this invocation. */
+    sessionBag: Record<string, JsonValue>;
+    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/loop/invocation.js

@@ -0,0 +1,37 @@
+import { HarnessError } from "@nylorun/core/define";
+import { copyJson } from "@nylorun/core/define";
+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,
+        sessionBag: { ...(input.state.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,
+            state: { ...invocation.sessionBag },
+            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 → loop/model}/adapters.d.ts

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

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

@@ -1,6 +1,7 @@
-import { HarnessError } from "../errors.js";
-import { copyJsonObject } from "../utils/immutable.js";
+import { HarnessError } from "@nylorun/core/define";
+import { copyJsonObject } from "@nylorun/core/define";
 import { preparedModel } from "./prepared.js";
+export { preparedModel };
 /** Translate a Harness call to the OpenAI Chat Completions request shape. */
 export function toChatCompletions(call) {
     const messages = withoutProviderReasoning(call.prompt).map((item) => {

package/dist/{model → loop/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 "@nylorun/core/define";
+import type { ModelCandidate, ModelDirective, ModelOutputBlock } from "@nylorun/core/define";
 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 → loop/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 "@nylorun/core/define";
+import { assertJson, copyJson, copyJsonObject } from "@nylorun/core/define";
 const FINISH_REASONS = new Set([
     "stop",
     "length",

package/dist/{model → loop/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 "@nylorun/core/define";
+import type { JsonValue } from "@nylorun/core/define";
 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 → loop/model}/project.d.ts

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

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

@@ -1,4 +1,4 @@
-import { copyJson } from "../utils/immutable.js";
+import { copyJson, freezeGraph } from "@nylorun/core/define";
 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/loop/observe.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutionEvent } from "../types/execution.js";
+import type { ObserveEvent, Observer } from "@nylorun/core/define";
+import type { JsonValue } from "@nylorun/core/define";
+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/loop/observe.js

@@ -0,0 +1,53 @@
+import { copyJson } from "@nylorun/core/define";
+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/loop/options.d.ts

@@ -0,0 +1,11 @@
+import type { AgentDefinition } from "../definition/agent-definition.js";
+import type { BoundToolDefinition } from "@nylorun/core/define";
+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>;
+    readonly redelivery: boolean;
+};