@nylorun/harness 0.5.0-beta.1 → 0.8.0-beta.1

package/dist/session/state.d.ts

@@ -1,8 +1,13 @@
-import type { InputEvent, SessionSnapshot } from "../types/session.js";
+import type { ActiveExecutionRecord, InputEvent, SessionSnapshot, TranscriptEntry } from "../types/session.js";
 import type { ModelCandidate } from "../types/model.js";
 import type { RequiredInteraction, ToolResult } from "../types/tool.js";
-export declare function initialState(id: string): SessionSnapshot;
-export declare function withStatus(state: SessionSnapshot, status: SessionSnapshot["status"], pendingInteraction?: RequiredInteraction): SessionSnapshot;
+export declare function initialState(id: string, input?: {
+    readonly turnCount?: number;
+    readonly revision?: number;
+    readonly transcript?: readonly TranscriptEntry[];
+}): SessionSnapshot;
+export declare function withStatus(state: SessionSnapshot, status: SessionSnapshot["status"], pendingInteraction?: RequiredInteraction, active?: ActiveExecutionRecord): SessionSnapshot;
+export declare function withRevision(state: SessionSnapshot, revision: number): SessionSnapshot;
 export declare function beginTurn(state: SessionSnapshot, turnId: string, event?: InputEvent): SessionSnapshot;
 export declare const commitInput: (state: SessionSnapshot, turnId: string, event: InputEvent) => SessionSnapshot;
 export declare const commitCandidate: (state: SessionSnapshot, turnId: string, stepId: string, candidate: ModelCandidate) => SessionSnapshot;

package/dist/session/state.js

@@ -1,15 +1,26 @@
-export function initialState(id) {
-    return Object.freeze({ id, status: "idle", turnCount: 0, transcript: Object.freeze([]) });
+export function initialState(id, input = {}) {
+    return Object.freeze({
+        id,
+        status: "idle",
+        turnCount: input.turnCount ?? 0,
+        revision: input.revision ?? 0,
+        transcript: Object.freeze([...(input.transcript ?? [])]),
+    });
 }
-export function withStatus(state, status, pendingInteraction) {
+export function withStatus(state, status, pendingInteraction, active) {
     return Object.freeze({
         id: state.id,
         status,
         turnCount: state.turnCount,
+        revision: state.revision,
         transcript: state.transcript,
         ...(pendingInteraction ? { pendingInteraction } : {}),
+        ...(active ? { active } : {}),
     });
 }
+export function withRevision(state, revision) {
+    return Object.freeze({ ...state, revision });
+}
 export function beginTurn(state, turnId, event) {
     const transcript = event
         ? [
@@ -20,7 +31,8 @@ export function beginTurn(state, turnId, event) {
     return Object.freeze({
         id: state.id,
         status: "running",
-        turnCount: state.turnCount + (event ? 1 : 0),
+        turnCount: state.turnCount + 1,
+        revision: state.revision,
         transcript: Object.freeze(transcript),
     });
 }

package/dist/session/submission-stream.d.ts

@@ -3,11 +3,13 @@ export declare class SubmissionStream implements InputHandle {
     readonly inputId: string;
     readonly completed: Promise<InputCompletion>;
     private resolveCompletion;
+    private rejectCompletion;
     private readonly events;
     private readonly cleanups;
     private done;
     constructor(inputId: string);
     emit(event: SessionEvent): void;
     finish(status: InputCompletion["status"]): void;
+    fail(error: unknown): void;
     onFinish(cleanup: () => void): void;
 }

package/dist/session/submission-stream.js

@@ -2,13 +2,15 @@ export class SubmissionStream {
     inputId;
     completed;
     resolveCompletion;
+    rejectCompletion;
     events = [];
     cleanups = [];
     done = false;
     constructor(inputId) {
         this.inputId = inputId;
-        this.completed = new Promise((resolve) => {
+        this.completed = new Promise((resolve, reject) => {
             this.resolveCompletion = resolve;
+            this.rejectCompletion = reject;
         });
     }
     emit(event) {
@@ -27,6 +29,14 @@ export class SubmissionStream {
             events: Object.freeze([...this.events]),
         }));
     }
+    fail(error) {
+        if (this.done)
+            return;
+        this.done = true;
+        while (this.cleanups.length)
+            this.cleanups.pop()();
+        this.rejectCompletion(error);
+    }
     onFinish(cleanup) {
         if (this.done)
             cleanup();

package/dist/step/model-configuration.d.ts

@@ -1,11 +1,9 @@
 import type { ModelConfigurationMutationOptions, ModelConfigurationSnapshot, ModelDirective } from "../types/model.js";
 import type { ToolDefinition } from "../types/tool.js";
-import type { AdapterRegistry } from "../build/adapters.js";
 /** Per-step, middleware-owned model configuration draft. It never persists past the call. */
 export declare class ModelConfigurationDraft {
     #private;
-    private readonly adapters;
-    constructor(adapters: AdapterRegistry, directive?: ModelDirective);
+    constructor(directive?: ModelDirective);
     setInstructions(middlewareId: string, middlewareOrder: number, slot: string, items: readonly string[], options?: ModelConfigurationMutationOptions): void;
     setTools(middlewareId: string, middlewareOrder: number, slot: string, tools: readonly ToolDefinition[], options?: ModelConfigurationMutationOptions): void;
     select(middlewareId: string, middlewareOrder: number, directive: ModelDirective, options?: Omit<ModelConfigurationMutationOptions, "order">): void;

package/dist/step/model-configuration.js

@@ -6,12 +6,10 @@ import { copyJson } from "../utils/immutable.js";
 import { checkedReason, slotOwner, SlotDraft } from "./slot-assembly.js";
 /** Per-step, middleware-owned model configuration draft. It never persists past the call. */
 export class ModelConfigurationDraft {
-    adapters;
     #instructions = new SlotDraft();
     #tools = new SlotDraft();
     #model;
-    constructor(adapters, directive) {
-        this.adapters = adapters;
+    constructor(directive) {
         if (directive !== undefined)
             this.#model = Object.freeze({ directive: checkedDirective(directive) });
     }
@@ -38,7 +36,7 @@ export class ModelConfigurationDraft {
             middlewareId,
             middlewareOrder,
             slot,
-            value: Object.freeze(tools.map((tool) => bindTool(tool, this.adapters))),
+            value: Object.freeze(tools.map((tool) => bindTool(tool, { middlewareId, slot }))),
             order: options?.order,
             reason: options?.reason,
             invalidSlot: "configuration.invalid-slot",

package/dist/step/project.js

@@ -81,8 +81,10 @@ function projectToolResult(result) {
 }
 function toolResultPayload(result) {
     if (result.kind === "completed")
-        return result.output ?? null;
-    return { kind: result.kind, reason: result.reason ?? result.message ?? result.code ?? "failed" };
+        return result.output;
+    if (result.kind === "denied")
+        return { kind: result.kind, reason: result.reason };
+    return { kind: result.kind, code: result.code, message: result.message };
 }
 function textPart(text) {
     return Object.freeze({ type: "text", text });

package/dist/step/run.d.ts

@@ -1,12 +1,15 @@
 import type { ModelCandidate } from "../types/model.js";
-import type { InputEvent, SessionSnapshot } from "../types/session.js";
+import type { ActiveModelExecutionRecord, InputEvent, SessionSnapshot } from "../types/session.js";
 import type { LoopAgent } from "../build/agent.js";
 import type { ObserveEmit } from "../utils/observe.js";
 import { type SealedStepOutput } from "./seal.js";
+import type { CapabilityStateRegistry } from "../session/capability-state.js";
 export interface StepRunResult {
     readonly stepId: string;
+    readonly state: SessionSnapshot;
     readonly candidate?: ModelCandidate;
     readonly output: SealedStepOutput;
+    readonly requestedModelId?: string;
 }
 export declare function runStep(input: {
     agent: LoopAgent;
@@ -24,4 +27,6 @@ export declare function runStep(input: {
         readonly userId?: string;
         readonly context?: import("../types/shared.js").JsonObject;
     }>;
+    states: CapabilityStateRegistry;
+    recordModelRequested(state: SessionSnapshot, active: ActiveModelExecutionRecord): Promise<SessionSnapshot>;
 }): Promise<StepRunResult>;

package/dist/step/run.js

@@ -8,7 +8,10 @@ import { projectModelCall } from "./project.js";
 import { resolveModelRequest } from "./resolve.js";
 import { sealStep } from "./seal.js";
 import { ModelConfigurationDraft } from "./model-configuration.js";
+import { createId } from "../utils/ids.js";
 export async function runStep(input) {
+    let state = input.state;
+    let requestedModelId;
     const stepInput = Object.freeze({
         sessionId: input.sessionId,
         turnId: input.turnId,
@@ -20,9 +23,9 @@ export async function runStep(input) {
         toolResults: Object.freeze([...input.toolResults]),
         transcript: Object.freeze([...input.state.transcript]),
     });
-    const configuration = new ModelConfigurationDraft(input.agent.adapters, input.agent.directive);
+    const configuration = new ModelConfigurationDraft();
     const runtimeContext = new ContextDraft(input.session.context);
-    const context = new StepContext(stepInput, input.observe, configuration, runtimeContext);
+    const context = new StepContext(stepInput, input.observe, configuration, runtimeContext, input.states);
     input.observe(() => ({
         type: "step.started",
         turnId: input.turnId,
@@ -50,7 +53,17 @@ export async function runStep(input) {
             arrivals: input.arrivals,
             toolResults: input.toolResults,
         });
+        requestedModelId = request.model?.id;
         const call = projectModelCall(request);
+        const invocationId = createId("invocation");
+        const active = Object.freeze({
+            kind: "model",
+            turnId: input.turnId,
+            stepId: input.stepId,
+            invocationId,
+            call,
+        });
+        state = await input.recordModelRequested(state, active);
         input.observe(() => ({
             type: "model.requested",
             turnId: input.turnId,
@@ -63,22 +76,22 @@ export async function runStep(input) {
             }),
         }));
         try {
-            const minted = context.mintFromModel(normalizeCandidate(await input.agent.invoke(call, {
+            const outcome = await input.agent.invoke(call, {
                 request,
+                invocationId,
                 signal: input.signal,
-            })));
+            });
             if (input.signal.aborted)
                 throw input.signal.reason;
+            if (isDeferred(outcome))
+                return context.deferModel(Object.freeze({
+                    ...active,
+                    ...(outcome.token === undefined ? {} : { token: copyJson(outcome.token) }),
+                }));
+            const minted = context.mintFromModel(normalizeCandidate(outcome));
             const candidate = context.currentCandidate;
             if (!candidate)
                 throw new HarnessError("model.candidate-missing", "Model candidate missing after mint");
-            input.observe(() => ({
-                type: "model.completed",
-                turnId: input.turnId,
-                stepId: input.stepId,
-                ...(request.model?.id === undefined ? {} : { requestedModelId: request.model.id }),
-                attributes: candidate,
-            }));
             return minted;
         }
         catch (error) {
@@ -92,7 +105,16 @@ export async function runStep(input) {
     }, input.observe);
     const output = sealStep(context);
     const candidate = output.kind === "tools" ? output.plan.candidate : context.currentCandidate;
-    return Object.freeze({ stepId: input.stepId, ...(candidate ? { candidate } : {}), output });
+    return Object.freeze({
+        stepId: input.stepId,
+        state,
+        ...(candidate ? { candidate } : {}),
+        ...(requestedModelId === undefined ? {} : { requestedModelId }),
+        output,
+    });
+}
+function isDeferred(value) {
+    return (typeof value === "object" && value !== null && "kind" in value && value.kind === "deferred");
 }
 function snapshotStepStart(input) {
     const session = Object.freeze({
@@ -121,7 +143,7 @@ function snapshotTools(tools) {
     return Object.freeze(tools.map((tool) => Object.freeze({
         name: tool.name,
         ...(tool.description === undefined ? {} : { description: tool.description }),
-        executeWith: tool.executeWith,
+        owner: tool.owner,
         parameters: Object.freeze({ jsonSchema: copyJson(tool.parameters.jsonSchema) }),
     })));
 }

package/dist/step/seal.d.ts

@@ -1,12 +1,13 @@
 import type { ModelCandidate } from "../types/model.js";
 import type { Tripwire } from "../types/shared.js";
-import type { RequiredInteraction, SealedToolCall, ToolResult } from "../types/tool.js";
+import type { BoundToolDefinition, RequiredInteraction, SealedToolCall, ToolOwner, ToolResult } from "../types/tool.js";
 import type { StepContext } from "./step-context.js";
 export interface ExecutablePlanEntry {
     readonly call: SealedToolCall;
     readonly invocationId: string;
+    readonly owner: ToolOwner;
+    readonly execute: BoundToolDefinition["execute"];
     readonly interaction?: RequiredInteraction;
-    readonly preflight?: "sandbox" | "validation";
 }
 export interface InternalToolPlan {
     readonly candidate: ModelCandidate;
@@ -23,6 +24,9 @@ export type SealedStepOutput = {
 } | {
     readonly kind: "final";
     readonly output: string;
+} | {
+    readonly kind: "deferred-model";
+    readonly active: import("../types/session.js").ActiveModelExecutionRecord;
 } | {
     readonly kind: "tools";
     readonly plan: InternalToolPlan;

package/dist/step/seal.js

@@ -7,6 +7,8 @@ const failed = (callId, toolName, code, message) => Object.freeze({ kind: "faile
 export function sealStep(context) {
     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)
         return Object.freeze({
@@ -75,7 +77,6 @@ function sealCall(context, catalog, candidate) {
     const interaction = requested
         ? Object.freeze({ ...requested, id: requested.id ?? createId("interaction") })
         : undefined;
-    const preflight = context.preflightFor(candidate.id);
     return {
         order,
         canonical,
@@ -84,11 +85,11 @@ function sealCall(context, catalog, candidate) {
                 callId: candidate.id,
                 toolName: candidate.name,
                 args,
-                executeWith: tool.executeWith,
             }),
             invocationId: createId("invocation"),
+            owner: tool.owner,
+            execute: tool.execute,
             ...(interaction ? { interaction } : {}),
-            ...(preflight ? { preflight } : {}),
         }),
     };
 }

package/dist/step/step-context.d.ts

@@ -1,19 +1,22 @@
 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 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);
+    constructor(input: Readonly<StepInput>, observe: ObserveEmit, configuration: ModelConfigurationDraft, context: ContextDraft, states?: CapabilityStateRegistry);
     get currentTripwire(): Tripwire | undefined;
     get currentCandidate(): Readonly<ModelCandidate> | undefined;
+    get currentModelDeferred(): ActiveModelExecutionRecord | undefined;
     get selectedDirective(): ModelDirective | undefined;
     get instructions(): readonly string[];
     contextSnapshot(): ContextSnapshot;
@@ -24,9 +27,9 @@ export declare class StepContext {
     sealContext(snapshot: ContextSnapshot): void;
     denialFor(callId: string): string | undefined;
     interactionFor(callId: string): Interaction | undefined;
-    preflightFor(callId: string): "sandbox" | "validation" | 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/step-context.js

@@ -13,22 +13,24 @@ export class StepContext {
     #observe;
     #context;
     #configuration;
+    #states;
     #denials = new Map();
     #interactions = new Map();
-    #preflights = new Map();
     #identities = new Map();
     #canonical = Object.freeze([]);
     #candidate;
     #tripwire;
+    #modelDeferred;
     #response;
     #sealed = false;
     #configurationSnapshot;
     #contextSnapshot;
-    constructor(input, observe, configuration, context) {
+    constructor(input, observe, configuration, context, states) {
         this.input = input;
         this.#observe = observe;
         this.#configuration = configuration;
         this.#context = context;
+        this.#states = states;
     }
     get currentTripwire() {
         return this.#tripwire;
@@ -36,6 +38,9 @@ export class StepContext {
     get currentCandidate() {
         return this.#candidate;
     }
+    get currentModelDeferred() {
+        return this.#modelDeferred;
+    }
     get selectedDirective() {
         return this.configurationSnapshot().model;
     }
@@ -66,9 +71,6 @@ export class StepContext {
     interactionFor(callId) {
         return this.#interactions.get(callId);
     }
-    preflightFor(callId) {
-        return this.#preflights.get(callId);
-    }
     canonicalCalls() {
         return this.#canonical;
     }
@@ -81,6 +83,10 @@ 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();
@@ -131,7 +137,7 @@ export class StepContext {
                 });
             }
         });
-        const value = Object.freeze({
+        const request = {
             sessionId: this.input.sessionId,
             turnId: this.input.turnId,
             stepId: this.input.stepId,
@@ -164,7 +170,13 @@ 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,
             revokeMutators: () => {
@@ -187,10 +199,6 @@ export class StepContext {
                 if (!this.#interactions.has(callId))
                     this.#interactions.set(callId, freezeGraph({ ...interaction }));
             },
-            requirePreflight: (callId, kind) => {
-                if (!this.#preflights.has(callId))
-                    this.#preflights.set(callId, kind);
-            },
             tripwire: (error) => {
                 this.#tripwire ??= Object.freeze({ ...error });
                 return value;

package/dist/turn/plan-runner.d.ts

@@ -1,18 +1,30 @@
-import type { AdapterRegistry } from "../build/adapters.js";
 import type { ObserveEmit } from "../utils/observe.js";
 import type { InputEvent } from "../types/session.js";
-import type { RequiredInteraction, ToolResult } from "../types/tool.js";
-import type { InternalToolPlan } from "../step/seal.js";
-type PlanPhase = "interaction" | "preflight" | "execute";
+import type { ActiveInteractionExecutionRecord, ActiveToolsExecutionRecord } from "../types/session.js";
+import type { RequiredInteraction, ToolExecutionResume, ToolResult } from "../types/tool.js";
+import type { JsonValue } from "../types/shared.js";
+import type { CapabilityStateRegistry } from "../session/capability-state.js";
+import type { ExecutablePlanEntry, InternalToolPlan } from "../step/seal.js";
+export interface DeferredToolCall {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly args: JsonValue;
+    readonly invocationId: string;
+    readonly owner: ExecutablePlanEntry["owner"];
+    readonly token?: JsonValue;
+}
 export type ToolPlanProgress = {
     readonly kind: "completed";
     readonly results: readonly ToolResult[];
 } | {
     readonly kind: "interaction-required";
     readonly interaction: RequiredInteraction;
+} | {
+    readonly kind: "deferred";
+    readonly settled: readonly ToolResult[];
+    readonly deferred: readonly DeferredToolCall[];
 };
 export interface ToolPlanRunContext {
-    readonly adapters: AdapterRegistry;
     readonly signal: AbortSignal;
     readonly observe: ObserveEmit;
     readonly ids: {
@@ -20,15 +32,17 @@ export interface ToolPlanRunContext {
         readonly turnId: string;
         readonly stepId: string;
     };
+    readonly states?: CapabilityStateRegistry;
 }
-/** Owns the mutable progress of one sealed tool plan across interaction resumes. */
+/** Owns one sealed plan's deterministic interaction and concurrent execution progress. */
 export declare class ToolPlanRunner {
     private readonly plan;
     private readonly results;
+    private readonly deferred;
     private readonly resumes;
-    private phase;
-    private index;
     private readonly pending;
+    private readonly settlementEvents;
+    private interactionIndex;
     private executeStarted;
     private resumeExecute?;
     constructor(plan: InternalToolPlan);
@@ -36,20 +50,21 @@ export declare class ToolPlanRunner {
     get interactionKind(): RequiredInteraction["kind"] | undefined;
     get interactionCallId(): string | undefined;
     get interactionToolName(): string | undefined;
-    get interactionPhase(): PlanPhase | undefined;
     cancelledResults(reason: string): readonly ToolResult[];
+    /** Publishes settlement facts only after their authoritative state was recorded. */
+    publishSettlements(observe: ObserveEmit): void;
+    activeToolsRecord(turnId: string, stepId: string): ActiveToolsExecutionRecord;
+    activeInteractionRecord(turnId: string, stepId: string, resume?: ToolExecutionResume): ActiveInteractionExecutionRecord;
+    interactionResume(event: InputEvent): ToolExecutionResume;
     run(context: ToolPlanRunContext, resume?: InputEvent): Promise<ToolPlanProgress>;
     private acceptResume;
-    private runExecute;
-    private preflight;
     private executeBatch;
     private execute;
     private takeResume;
-    private requireInteraction;
     private enqueueInteraction;
     private interactionRequired;
     private orderedResults;
+    private orderedSettledResults;
     private resultsInOrder;
     private throwIfAborted;
 }
-export {};