@nylorun/harness 0.12.0-beta → 0.15.0-beta

package/dist/loop/step/runtime.d.ts

@@ -0,0 +1,40 @@
+import type { ToolRegistry } from "../../definition/registry.js";
+import type { AgentDefinition } from "../../definition/agent-definition.js";
+import type { ModelAdapter } from "@nylorun/core/define";
+import type { InputEvent, TranscriptEntry } from "@nylorun/core/define";
+import type { ToolResult } from "@nylorun/core/define";
+import type { BoundMiddleware } from "@nylorun/core/define";
+import type { JsonValue } from "@nylorun/core/define";
+/** Compiled definition pieces plus the per-run model adapter for one step. */
+export interface StepRuntime {
+    readonly middleware: readonly BoundMiddleware[];
+    readonly invoke: ModelAdapter;
+    readonly registry: ToolRegistry;
+    /** Full definition for before/after dynamics (optional for middleware-only agents). */
+    readonly definition?: AgentDefinition;
+    /** Mutable session memory bag shared with tools. */
+    sessionState?: Record<string, JsonValue>;
+    /** Called after Patch/Decision applied so the host can record. */
+    recordAfterDynamics?: () => Promise<void>;
+}
+export interface StepInput {
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    /** One-based position of this turn within the execution. */
+    readonly turnNumber: number;
+    /** One-based position of this Model Step within the Turn. */
+    readonly stepNumber: number;
+    readonly info?: unknown;
+    readonly arrivals: readonly InputEvent[];
+    readonly toolResults: readonly ToolResult[];
+    readonly transcript: readonly TranscriptEntry[];
+}
+/** Internal view consumed by a single model step. */
+export interface ExecutionSnapshot {
+    readonly id: string;
+    readonly status: "running";
+    readonly turnCount: number;
+    readonly revision: number;
+    readonly transcript: readonly TranscriptEntry[];
+}

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

@@ -1,9 +1,17 @@
-import type { ModelCandidate } from "../types/model.js";
-import type { Tripwire } from "../types/shared.js";
-import type { BoundToolDefinition, RequiredInteraction, SealedToolCall, ToolOwner, ToolResult } from "../types/tool.js";
+import type { BoundToolDefinition } from "@nylorun/core/define";
+import type { ModelCandidate } from "@nylorun/core/define";
+import type { JsonValue, Tripwire } from "@nylorun/core/define";
+import type { RequiredInteraction, ToolOwner, ToolResult } from "@nylorun/core/define";
 import type { StepContext } from "./step-context.js";
-import type { TurnOutputContract } from "../session/output-contract.js";
+import type { TurnOutputContract } from "@nylorun/core/define";
+export interface SealedToolCall {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly args: JsonValue;
+}
 export interface ExecutablePlanEntry {
+    readonly definition: BoundToolDefinition;
+    readonly rawArgs: JsonValue;
     readonly call: SealedToolCall;
     readonly invocationId: string;
     readonly owner: ToolOwner;
@@ -25,10 +33,7 @@ export type SealedStepOutput = {
     readonly tripwire: Tripwire;
 } | {
     readonly kind: "final";
-    readonly output: import("../types/shared.js").JsonValue;
-} | {
-    readonly kind: "deferred-model";
-    readonly active: import("../types/session.js").ActiveModelExecutionRecord;
+    readonly output: JsonValue;
 } | {
     readonly kind: "tools";
     readonly plan: InternalToolPlan;

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

@@ -1,7 +1,7 @@
 import { textFromOutput } from "../model/normalize.js";
-import { createId } from "../utils/ids.js";
-import { HarnessError, isHarnessError } from "../errors.js";
-import { assertJson, copyJson } from "../utils/immutable.js";
+import { createId } from "../../utils/ids.js";
+import { HarnessError, isHarnessError } from "@nylorun/core/define";
+import { assertJson, copyJson } from "@nylorun/core/define";
 const failed = (callId, toolName, code, message, details) => Object.freeze({
     kind: "failed",
     callId,
@@ -14,8 +14,6 @@ const failed = (callId, toolName, code, message, details) => Object.freeze({
 export function sealStep(context, outputContract) {
     if (context.currentTripwire)
         return Object.freeze({ kind: "tripwire", tripwire: context.currentTripwire });
-    if (context.currentModelDeferred)
-        return Object.freeze({ kind: "deferred-model", active: context.currentModelDeferred });
     const calls = context.canonicalCalls();
     if (!calls.length) {
         if (outputContract)
@@ -45,7 +43,9 @@ function sealStructuredOutput(context, contract) {
         return invalidOutput("Structured terminal output must contain exactly one JSON block and no text blocks");
     const validation = contract.schema.validate(json[0].value);
     if (!validation.ok)
-        return invalidOutput(`Structured terminal output failed validation: ${validation.issues.map(renderIssue).join("; ")}`);
+        return invalidOutput(`Structured terminal output failed validation: ${validation.issues
+            .map(renderIssue)
+            .join("; ")}`);
     try {
         assertJson(validation.value, "structured terminal output");
         return Object.freeze({ kind: "final", output: copyJson(validation.value) });
@@ -113,6 +113,8 @@ function sealCall(context, catalog, candidate) {
         order,
         canonical,
         executable: Object.freeze({
+            definition: tool,
+            rawArgs: copyJson(candidate.args),
             call: Object.freeze({
                 callId: candidate.id,
                 toolName: candidate.name,

package/dist/{step → loop/step}/slot-assembly.d.ts

@@ -1,4 +1,4 @@
-import { type HarnessErrorCode } from "../errors.js";
+import { type HarnessErrorCode } from "@nylorun/core/define";
 export interface SlotOwner {
     readonly middlewareId: string;
     readonly middlewareOrder: number;
@@ -11,9 +11,9 @@ export interface SlotDeclaration<Value> {
     readonly reason?: string;
 }
 /**
- * Shared per-step slot store. It has no session lifetime: declarations are discarded with the
- * draft that owns this instance. Configuration and context supply their typed values and snapshot
- * them after this assembler has applied ownership, replacement, and canonical ordering.
+ * Shared per-step slot store. Declarations are discarded with the draft that owns this instance.
+ * Configuration and context supply their typed values and snapshot them after this assembler has
+ * applied ownership, replacement, and canonical ordering.
  */
 export declare class SlotDraft<Value> {
     #private;

package/dist/{step → loop/step}/slot-assembly.js

@@ -1,8 +1,8 @@
-import { HarnessError } from "../errors.js";
+import { HarnessError } from "@nylorun/core/define";
 /**
- * Shared per-step slot store. It has no session lifetime: declarations are discarded with the
- * draft that owns this instance. Configuration and context supply their typed values and snapshot
- * them after this assembler has applied ownership, replacement, and canonical ordering.
+ * Shared per-step slot store. Declarations are discarded with the draft that owns this instance.
+ * Configuration and context supply their typed values and snapshot them after this assembler has
+ * applied ownership, replacement, and canonical ordering.
  */
 export class SlotDraft {
     #slots = new Map();

package/dist/{step → loop/step}/step-context.d.ts

@@ -1,35 +1,34 @@
-import type { ContextSnapshot, ModelCandidate, ModelDirective, ModelConfigurationSnapshot } from "../types/model.js";
-import type { StepInput, StepRequest, StepResponse } from "../types/middleware.js";
-import type { Tripwire } from "../types/shared.js";
-import type { ActiveModelExecutionRecord } from "../types/session.js";
-import type { ObserveEmit } from "../utils/observe.js";
-import type { BoundToolDefinition, Interaction } from "../types/tool.js";
+import type { BoundToolDefinition } from "@nylorun/core/define";
+import type { StepInput } from "./runtime.js";
+import type { InternalModelConfigurationSnapshot } from "./describe.js";
+import type { ContextSnapshot, ModelCandidate, ModelDirective } from "@nylorun/core/define";
+import type { StepRequest, StepResponse } from "@nylorun/core/define";
+import type { Tripwire } from "@nylorun/core/define";
+import type { ObserveEmit } from "../observe.js";
+import type { Interaction } from "@nylorun/core/define";
 import { type CanonicalCall } from "./canonicalize.js";
 import { ContextDraft } from "./context-draft.js";
 import { ModelConfigurationDraft } from "./model-configuration.js";
-import type { CapabilityStateRegistry } from "../session/capability-state.js";
 export declare function isBrandedResponse(value: unknown): value is StepResponse;
 /** Mutable Step state. Middleware receives leased request views and one branded response. */
 export declare class StepContext {
     #private;
     readonly input: Readonly<StepInput>;
-    constructor(input: Readonly<StepInput>, observe: ObserveEmit, configuration: ModelConfigurationDraft, context: ContextDraft, states?: CapabilityStateRegistry);
+    constructor(input: Readonly<StepInput>, observe: ObserveEmit, configuration: ModelConfigurationDraft, context: ContextDraft);
     get currentTripwire(): Tripwire | undefined;
     get currentCandidate(): Readonly<ModelCandidate> | undefined;
-    get currentModelDeferred(): ActiveModelExecutionRecord | undefined;
     get selectedDirective(): ModelDirective | undefined;
     get instructions(): readonly string[];
     contextSnapshot(): ContextSnapshot;
     get offeredTools(): readonly BoundToolDefinition[];
     get catalogByName(): ReadonlyMap<string, BoundToolDefinition>;
-    configurationSnapshot(): ModelConfigurationSnapshot;
-    sealConfiguration(snapshot: ModelConfigurationSnapshot): void;
+    configurationSnapshot(): InternalModelConfigurationSnapshot;
+    sealConfiguration(snapshot: InternalModelConfigurationSnapshot): void;
     sealContext(snapshot: ContextSnapshot): void;
     denialFor(callId: string): string | undefined;
     interactionFor(callId: string): Interaction | undefined;
     canonicalCalls(): readonly CanonicalCall[];
     mintFromModel(candidate: Readonly<ModelCandidate>): StepResponse;
-    deferModel(active: ActiveModelExecutionRecord): StepResponse;
     tripwire(error: Tripwire): StepResponse;
     seal(): void;
     requestFacade(middlewareId: string, middlewareOrder: number): {

package/dist/{step → loop/step}/step-context.js

@@ -1,4 +1,5 @@
-import { HarnessError, isHarnessError } from "../errors.js";
+import { HarnessError, isHarnessError } from "@nylorun/core/define";
+import { freezeGraph } from "@nylorun/core/define";
 import { callsFromCanonical, candidateFromCanonical, canonicalizeOutput, identityKey, } from "./canonicalize.js";
 import { normalizeCandidate } from "../model/normalize.js";
 import { ContextDraft } from "./context-draft.js";
@@ -13,24 +14,21 @@ export class StepContext {
     #observe;
     #context;
     #configuration;
-    #states;
     #denials = new Map();
     #interactions = new Map();
     #identities = new Map();
     #canonical = Object.freeze([]);
     #candidate;
     #tripwire;
-    #modelDeferred;
     #response;
     #sealed = false;
     #configurationSnapshot;
     #contextSnapshot;
-    constructor(input, observe, configuration, context, states) {
+    constructor(input, observe, configuration, context) {
         this.input = input;
         this.#observe = observe;
         this.#configuration = configuration;
         this.#context = context;
-        this.#states = states;
     }
     get currentTripwire() {
         return this.#tripwire;
@@ -38,9 +36,6 @@ export class StepContext {
     get currentCandidate() {
         return this.#candidate;
     }
-    get currentModelDeferred() {
-        return this.#modelDeferred;
-    }
     get selectedDirective() {
         return this.configurationSnapshot().model;
     }
@@ -83,10 +78,6 @@ export class StepContext {
             this.#identities.set(call.id, identityKey(call.name, call.args));
         return this.#ensureResponse();
     }
-    deferModel(active) {
-        this.#modelDeferred = active;
-        return this.#ensureResponse();
-    }
     tripwire(error) {
         this.#tripwire ??= Object.freeze({ ...error });
         return this.#ensureResponse();
@@ -138,10 +129,10 @@ export class StepContext {
             }
         });
         const request = {
-            sessionId: this.input.sessionId,
+            executionId: this.input.executionId,
             turnId: this.input.turnId,
             stepId: this.input.stepId,
-            session: this.input.session,
+            info: this.input.info,
             turnNumber: this.input.turnNumber,
             stepNumber: this.input.stepNumber,
             arrivals: this.input.arrivals,
@@ -171,11 +162,6 @@ export class StepContext {
                 return minted;
             },
         };
-        if (this.#states?.has(middlewareId))
-            Object.defineProperty(request, "state", {
-                enumerable: true,
-                get: () => this.#states.get(middlewareId),
-            });
         const value = Object.freeze(request);
         return Object.freeze({
             value,
@@ -253,11 +239,3 @@ function pickSidecar(key, replacement, normalized, current) {
     const value = source?.[key];
     return value === undefined ? {} : { [key]: value };
 }
-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/tool-result.d.ts

@@ -0,0 +1,4 @@
+import type { BoundToolDefinition } from "@nylorun/core/define";
+import type { SavedToolCall } from "../types/execution.js";
+import type { ToolOutcome, ToolResult } from "@nylorun/core/define";
+export declare function toolResult(call: SavedToolCall, definition: BoundToolDefinition, outcome: ToolOutcome): ToolResult;

package/dist/loop/tool-result.js

@@ -0,0 +1,30 @@
+import { HarnessError } from "@nylorun/core/define";
+import { copyJson } from "@nylorun/core/define";
+export function toolResult(call, definition, outcome) {
+    const identity = { callId: call.callId, toolName: call.toolName };
+    if (outcome.kind === "completed") {
+        const checked = definition.outputSchema?.validate(outcome.output);
+        if (checked && !checked.ok)
+            return {
+                ...identity,
+                kind: "failed",
+                code: "tool.invalid-output",
+                message: checked.issues.map((issue) => issue.message).join("; "),
+                details: { phase: "output", issues: checked.issues },
+            };
+        return copyJson({
+            ...identity,
+            kind: "completed",
+            output: checked?.ok ? checked.value : outcome.output,
+        });
+    }
+    if (outcome.kind === "failed" &&
+        typeof outcome.code === "string" &&
+        typeof outcome.message === "string")
+        return copyJson({ ...identity, kind: "failed", code: outcome.code, message: outcome.message });
+    if (outcome.kind === "denied" && typeof outcome.reason !== "string")
+        throw new HarnessError("tool.invalid-tool-result", "Tool denial reason must be a string");
+    if (outcome.kind === "denied" && typeof outcome.reason === "string")
+        return copyJson({ ...identity, kind: "denied", reason: outcome.reason });
+    throw new HarnessError("tool.invalid-tool-result", "Expected a completed, failed, or denied tool result");
+}

package/dist/loop/transcript.d.ts

@@ -0,0 +1,2 @@
+import type { TranscriptEntry } from "@nylorun/core/define";
+export declare function validateTranscript(value: readonly TranscriptEntry[]): readonly TranscriptEntry[];

package/dist/{session/seed.js → loop/transcript.js}

@@ -1,39 +1,20 @@
-import { HarnessError } from "../errors.js";
-import { normalizeCandidate } from "../model/normalize.js";
-import { assertJson, copyJson, copyJsonObject } from "../utils/immutable.js";
-export function normalizeSessionSeed(seed) {
+import { HarnessError } from "@nylorun/core/define";
+import { normalizeCandidate } from "./model/normalize.js";
+import { assertJson, copyJson, copyJsonObject } from "@nylorun/core/define";
+export function validateTranscript(value) {
     try {
-        return normalizeSeed(seed);
+        if (!Array.isArray(value))
+            fail("Transcript must be an array");
+        return Object.freeze(value.map((entry, index) => entryAt(entry, index)));
     }
     catch (cause) {
-        if (cause instanceof HarnessError && cause.code === "session.invalid-seed")
+        if (cause instanceof HarnessError && cause.code === "execution.invalid-state")
             throw cause;
-        throw new HarnessError("session.invalid-seed", "Session seed contains invalid typed JSON", {
+        throw new HarnessError("execution.invalid-state", "Transcript contains invalid typed JSON", {
             cause,
         });
     }
 }
-function normalizeSeed(seed) {
-    if (!seed || typeof seed !== "object")
-        fail("Session seed must be an object");
-    if (!Array.isArray(seed.transcript))
-        fail("Session seed transcript must be an array");
-    optionalString(seed.id, "Session seed id");
-    optionalString(seed.userId, "Session seed userId");
-    const turnCount = count(seed.turnCount, "turnCount");
-    const revision = count(seed.revision, "revision");
-    const transcript = Object.freeze(seed.transcript.map((entry, index) => entryAt(entry, index)));
-    return Object.freeze({
-        ...(seed.id === undefined ? {} : { id: seed.id }),
-        ...(seed.userId === undefined ? {} : { userId: seed.userId }),
-        ...(seed.context === undefined
-            ? {}
-            : { context: copyJsonObject(seed.context, "session seed context") }),
-        turnCount,
-        revision,
-        transcript,
-    });
-}
 function entryAt(value, index) {
     if (!value || typeof value !== "object")
         fail(`Transcript entry ${index} must be an object`);
@@ -61,7 +42,7 @@ function entryAt(value, index) {
                 });
             }
             catch (cause) {
-                throw new HarnessError("session.invalid-seed", `Invalid candidate at transcript ${index}`, {
+                throw new HarnessError("execution.invalid-state", `Invalid candidate at transcript ${index}`, {
                     cause,
                 });
             }
@@ -273,21 +254,10 @@ function exactKeys(value, allowed, label) {
         if (!allowed.includes(key))
             fail(`${label} has unknown field '${key}'`);
 }
-function count(value, label) {
-    if (value === undefined)
-        return 0;
-    if (!Number.isSafeInteger(value) || value < 0)
-        fail(`Session seed ${label} must be a non-negative safe integer`);
-    return value;
-}
-function optionalString(value, label) {
-    if (value !== undefined)
-        requiredString(value, label);
-}
 function requiredString(value, label) {
     if (typeof value !== "string" || value.length === 0)
         fail(`${label} must be a non-empty string`);
 }
 function fail(message) {
-    throw new HarnessError("session.invalid-seed", message);
+    throw new HarnessError("execution.invalid-state", message);
 }

package/dist/loop/waits.d.ts

@@ -0,0 +1,50 @@
+import type { JsonObject, JsonValue } from "@nylorun/core/define";
+/** Internal signal thrown by durable wait helpers; caught by the tool dispatcher. */
+export declare class WaitSignal {
+    readonly outcome: {
+        readonly kind: "interaction-required";
+        readonly interaction: {
+            readonly kind: "approval" | "response";
+            readonly prompt: string;
+            readonly metadata?: JsonObject;
+        };
+        readonly token?: JsonValue;
+        readonly wait: {
+            readonly kind: "ask" | "approve" | "sleep" | "waitFor";
+            readonly waitId: string;
+            readonly name?: string;
+        };
+    } | {
+        readonly kind: "deferred";
+        readonly token?: JsonValue;
+        readonly wait: {
+            readonly kind: "ask" | "approve" | "sleep" | "waitFor";
+            readonly waitId: string;
+            readonly name?: string;
+        };
+    };
+    readonly name = "WaitSignal";
+    constructor(outcome: {
+        readonly kind: "interaction-required";
+        readonly interaction: {
+            readonly kind: "approval" | "response";
+            readonly prompt: string;
+            readonly metadata?: JsonObject;
+        };
+        readonly token?: JsonValue;
+        readonly wait: {
+            readonly kind: "ask" | "approve" | "sleep" | "waitFor";
+            readonly waitId: string;
+            readonly name?: string;
+        };
+    } | {
+        readonly kind: "deferred";
+        readonly token?: JsonValue;
+        readonly wait: {
+            readonly kind: "ask" | "approve" | "sleep" | "waitFor";
+            readonly waitId: string;
+            readonly name?: string;
+        };
+    });
+}
+export declare function isWaitSignal(value: unknown): value is WaitSignal;

package/dist/loop/waits.js

@@ -0,0 +1,11 @@
+/** Internal signal thrown by durable wait helpers; caught by the tool dispatcher. */
+export class WaitSignal {
+    outcome;
+    name = "WaitSignal";
+    constructor(outcome) {
+        this.outcome = outcome;
+    }
+}
+export function isWaitSignal(value) {
+    return value instanceof WaitSignal;
+}

package/dist/run/durable.d.ts

@@ -0,0 +1,71 @@
+import type { AgentManifest } from "@nylorun/core/define";
+import type { ExecutionInput, ExecutionState, RunResult } from "../types/execution.js";
+import type { JsonObject } from "@nylorun/core/define";
+import type { ActionOutcome } from "@nylorun/core/contracts";
+import { ENGINE_VERSION } from "../compatibility.js";
+/** Private persistence contract for hosts; this is not a session wire type. */
+export interface DurableCheckpoint {
+    readonly version: 1;
+    readonly engineVersion: typeof ENGINE_VERSION;
+    readonly manifestHash: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    /** Increment for each human/event continuation, not for an action result. */
+    readonly segment: number;
+    readonly input: ExecutionInput;
+    readonly state?: ExecutionState;
+    readonly info?: JsonObject;
+}
+export interface HostEffect {
+    readonly effectId: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly agentId: string;
+    readonly manifestHash: string;
+    readonly kind: "model" | "tool" | "beforeModelCall" | "afterModelCall";
+    readonly capabilityId?: string;
+    readonly toolName?: string;
+    readonly input: unknown;
+    readonly context: Record<string, unknown>;
+}
+export type EffectResolution = {
+    readonly status: "completed";
+    readonly outcome: ActionOutcome;
+} | {
+    readonly status: "pending" | "uncertain";
+};
+export interface DurableHost {
+    /** Atomically load-or-create by effectId; validate identical request on replay.
+     * Return recorded outcomes. Record intent BEFORE invoking a provider or exposing
+     * customer work. Uncertain effects must never be automatically executed again.
+     */
+    resolveEffect(effect: HostEffect): Promise<EffectResolution>;
+}
+export type DurableResult = {
+    readonly status: "waiting" | "uncertain";
+    readonly checkpoint: DurableCheckpoint;
+    readonly effectIds: readonly string[];
+} | {
+    readonly status: "completed" | "paused" | "cancelled" | "failed";
+    readonly checkpoint: DurableCheckpoint;
+    readonly result: RunResult<unknown>;
+};
+export declare function createDurableCheckpoint(input: {
+    manifest: AgentManifest;
+    sessionId: string;
+    turnId: string;
+    input: ExecutionInput;
+    state?: ExecutionState;
+    info?: JsonObject;
+    segment?: number;
+}): DurableCheckpoint;
+/** Deterministic reconstruction uses individually journaled effects, never a replayable whole loop.
+ * A suspended checkpoint is the immutable segment start plus the host's durable effect journal.
+ * Returning waiting releases all execution stacks; no process-local continuation survives.
+ */
+export declare function runDurable(options: {
+    manifest: AgentManifest;
+    checkpoint: DurableCheckpoint;
+    host: DurableHost;
+    signal?: AbortSignal;
+}): Promise<DurableResult>;