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

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 {};

package/dist/turn/plan-runner.js

@@ -1,14 +1,15 @@
 import { HarnessError, isHarnessError } from "../errors.js";
 import { createId } from "../utils/ids.js";
 import { copyJson, copyJsonObject } from "../utils/immutable.js";
-/** Owns the mutable progress of one sealed tool plan across interaction resumes. */
+/** Owns one sealed plan's deterministic interaction and concurrent execution progress. */
 export class ToolPlanRunner {
     plan;
     results;
+    deferred = new Map();
     resumes = new Map();
-    phase = "interaction";
-    index = 0;
     pending = [];
+    settlementEvents = [];
+    interactionIndex = 0;
     executeStarted = false;
     resumeExecute;
     constructor(plan) {
@@ -23,65 +24,104 @@ export class ToolPlanRunner {
     }
     get interactionCallId() {
         const pending = this.pending[0];
-        if (!pending)
-            return undefined;
-        return this.plan.executable[pending.index]?.call.callId;
+        return pending ? this.plan.executable[pending.index]?.call.callId : undefined;
     }
     get interactionToolName() {
         const pending = this.pending[0];
-        if (!pending)
-            return undefined;
-        return this.plan.executable[pending.index]?.call.toolName;
-    }
-    get interactionPhase() {
-        return this.pending[0]?.phase;
+        return pending ? this.plan.executable[pending.index]?.call.toolName : undefined;
     }
     cancelledResults(reason) {
         return this.resultsInOrder("tool.cancelled", reason);
     }
+    /** Publishes settlement facts only after their authoritative state was recorded. */
+    publishSettlements(observe) {
+        for (const event of this.settlementEvents.splice(0))
+            observe(event);
+    }
+    activeToolsRecord(turnId, stepId) {
+        return Object.freeze({
+            kind: "tools",
+            turnId,
+            stepId,
+            calls: Object.freeze(this.plan.executable.map((entry) => {
+                const result = this.results.get(entry.call.callId);
+                const deferred = this.deferred.get(entry.call.callId);
+                return Object.freeze({
+                    callId: entry.call.callId,
+                    toolName: entry.call.toolName,
+                    args: copyJson(entry.call.args),
+                    invocationId: entry.invocationId,
+                    owner: entry.owner,
+                    status: result
+                        ? "settled"
+                        : deferred
+                            ? "deferred"
+                            : "pending",
+                    ...(result ? { result } : {}),
+                    ...(deferred?.token === undefined ? {} : { token: deferred.token }),
+                });
+            })),
+        });
+    }
+    activeInteractionRecord(turnId, stepId, resume) {
+        const pending = this.pending[0];
+        const entry = pending ? this.plan.executable[pending.index] : undefined;
+        if (!pending || !entry)
+            throw new HarnessError("interaction.invalid", "Missing pending interaction state");
+        return Object.freeze({
+            kind: "interaction",
+            turnId,
+            stepId,
+            callId: entry.call.callId,
+            toolName: entry.call.toolName,
+            interaction: pending.interaction,
+            ...(pending.token === undefined ? {} : { token: pending.token }),
+            ...(resume === undefined ? {} : { resume }),
+            tools: this.activeToolsRecord(turnId, stepId),
+        });
+    }
+    interactionResume(event) {
+        const pending = this.pending[0];
+        if (!pending)
+            throw new HarnessError("interaction.invalid", "Missing pending interaction state");
+        return resumeValue(event, pending);
+    }
     async run(context, resume) {
         this.acceptResume(resume);
-        while (true) {
+        while (this.interactionIndex < this.plan.executable.length) {
             this.throwIfAborted(context.signal);
-            if (this.phase === "execute")
-                return this.runExecute(context);
-            if (this.index >= this.plan.executable.length) {
-                if (this.phase === "interaction") {
-                    this.phase = "preflight";
-                    this.index = 0;
-                    continue;
-                }
-                if (this.phase === "preflight") {
-                    this.phase = "execute";
-                    this.index = 0;
-                    continue;
-                }
-                return { kind: "completed", results: this.orderedResults() };
-            }
-            const entry = this.plan.executable[this.index];
+            const entry = this.plan.executable[this.interactionIndex];
             if (this.results.has(entry.call.callId)) {
-                this.index += 1;
+                this.interactionIndex += 1;
                 continue;
             }
-            if (this.phase === "interaction") {
-                if (!entry.interaction) {
-                    this.index += 1;
-                    continue;
-                }
-                return this.requireInteraction({
-                    phase: this.phase,
-                    index: this.index,
-                    interaction: entry.interaction,
-                });
-            }
-            const adapter = context.adapters.require(entry.call.executeWith);
-            if (this.phase === "preflight") {
-                const progress = await this.preflight(entry, adapter, context);
-                if (progress)
-                    return progress;
+            if (entry.interaction) {
+                this.enqueueInteraction({ index: this.interactionIndex, interaction: entry.interaction });
+                return this.interactionRequired();
             }
-            this.index += 1;
+            this.interactionIndex += 1;
         }
+        if (this.resumeExecute) {
+            const entry = this.resumeExecute;
+            this.resumeExecute = undefined;
+            await this.executeBatch([entry], context);
+        }
+        else if (!this.executeStarted) {
+            this.executeStarted = true;
+            await this.executeBatch(this.plan.executable.filter((entry) => !this.results.has(entry.call.callId)), context);
+        }
+        if (this.pending.length)
+            return this.interactionRequired();
+        if (this.deferred.size)
+            return {
+                kind: "deferred",
+                settled: this.orderedSettledResults(),
+                deferred: Object.freeze(this.plan.executable.flatMap((entry) => {
+                    const value = this.deferred.get(entry.call.callId);
+                    return value ? [value] : [];
+                })),
+            };
+        return { kind: "completed", results: this.orderedResults() };
     }
     acceptResume(resume) {
         const pending = this.pending.shift();
@@ -98,162 +138,100 @@ export class ToolPlanRunner {
                 kind: "denied",
                 reason: "Approval rejected",
             }));
-            this.index += 1;
-            return;
-        }
-        if (pending.phase === "interaction") {
-            this.resumes.set(entry.call.callId, value);
-            this.index += 1;
+            this.interactionIndex = Math.max(this.interactionIndex, pending.index + 1);
             return;
         }
-        this.resumes.set(`${pending.phase}:${entry.call.callId}`, value);
-        if (pending.phase === "execute")
+        this.resumes.set(entry.call.callId, value);
+        if (this.executeStarted)
             this.resumeExecute = entry;
+        else
+            this.interactionIndex = Math.max(this.interactionIndex, pending.index + 1);
     }
-    async runExecute(context) {
-        if (this.resumeExecute) {
-            const entry = this.resumeExecute;
-            this.resumeExecute = undefined;
-            await this.executeBatch([entry], context);
-        }
-        else if (!this.executeStarted) {
-            this.executeStarted = true;
-            await this.executeBatch(this.plan.executable.filter((entry) => !this.results.has(entry.call.callId)), context);
+    async executeBatch(entries, context) {
+        const settled = await Promise.allSettled(entries.map((entry) => this.execute(entry, context)));
+        if (context.signal.aborted)
+            throw context.signal.reason;
+        for (const outcome of settled) {
+            if (outcome.status === "rejected")
+                throw outcome.reason;
+            if (outcome.value)
+                this.enqueueInteraction(outcome.value);
         }
-        return this.pending.length
-            ? this.interactionRequired()
-            : { kind: "completed", results: this.orderedResults() };
     }
-    async preflight(entry, adapter, context) {
-        if (!entry.preflight)
-            return undefined;
-        if (!adapter.preflight) {
-            this.results.set(entry.call.callId, failed(entry, "tool.preflight-missing", `Adapter '${entry.call.executeWith}' does not implement preflight`));
-            return undefined;
-        }
+    async execute(entry, context) {
         context.observe({
-            type: "adapter.preflight.started",
+            type: "tool.started",
+            sessionId: context.ids.sessionId,
             turnId: context.ids.turnId,
             stepId: context.ids.stepId,
-            adapterId: adapter.id,
             toolName: entry.call.toolName,
             callId: entry.call.callId,
             invocationId: entry.invocationId,
+            middlewareId: entry.owner.middlewareId,
+            slot: entry.owner.slot,
             attributes: { args: copyJson(entry.call.args) },
         });
         try {
-            const outcome = await adapter.preflight(entry.call, {
-                kind: entry.preflight,
-                invocationId: entry.invocationId,
-                signal: context.signal,
-                resume: this.takeResume("preflight", entry.call.callId),
-            });
-            this.throwIfAborted(context.signal);
-            if (outcome.kind === "interaction-required")
-                return this.requireInteraction(interactionBarrier(this.phase, this.index, outcome));
-            if (outcome.kind !== "completed")
-                this.results.set(entry.call.callId, resultFrom(entry, outcome));
-            context.observe({
-                type: "adapter.preflight.completed",
+            const toolContext = {
+                sessionId: context.ids.sessionId,
                 turnId: context.ids.turnId,
                 stepId: context.ids.stepId,
-                adapterId: adapter.id,
-                toolName: entry.call.toolName,
                 callId: entry.call.callId,
-                outcome: outcome.kind,
-                ...adapterCompleted(this.results.get(entry.call.callId)),
-            });
-        }
-        catch (error) {
+                invocationId: entry.invocationId,
+                signal: context.signal,
+                resume: this.takeResume(entry.call.callId),
+            };
+            if (context.states?.has(entry.owner.middlewareId))
+                Object.defineProperty(toolContext, "state", {
+                    enumerable: true,
+                    get: () => context.states.get(entry.owner.middlewareId),
+                });
+            const outcome = await entry.execute(entry.call.args, Object.freeze(toolContext));
             this.throwIfAborted(context.signal);
-            const result = failed(entry, isHarnessError(error) ? error.code : "tool.preflight-failed", error);
-            this.results.set(entry.call.callId, result);
-            context.observe({
-                type: "adapter.preflight.completed",
-                turnId: context.ids.turnId,
-                stepId: context.ids.stepId,
-                adapterId: adapter.id,
-                toolName: entry.call.toolName,
-                callId: entry.call.callId,
-                outcome: "failed",
-                ...adapterCompleted(result),
-            });
-        }
-        return undefined;
-    }
-    async executeBatch(entries, context) {
-        const settled = await Promise.allSettled(entries.map((entry) => this.execute(entry, context)));
-        if (context.signal.aborted)
-            throw context.signal.reason;
-        for (const outcome of settled) {
-            if (outcome.status === "rejected")
-                throw outcome.reason;
-            if (outcome.value)
-                this.enqueueInteraction(outcome.value);
-        }
-    }
-    async execute(entry, context) {
-        const adapter = context.adapters.require(entry.call.executeWith);
-        try {
-            return await context.adapters.execute(adapter.id, context.signal, async () => {
-                context.observe({
-                    type: "adapter.started",
-                    turnId: context.ids.turnId,
-                    stepId: context.ids.stepId,
-                    adapterId: adapter.id,
-                    toolName: entry.call.toolName,
+            if (!outcome || typeof outcome !== "object" || typeof outcome.kind !== "string")
+                throw new HarnessError("tool.invalid-tool-result", "Tool returned an invalid outcome");
+            if (outcome.kind === "interaction-required")
+                return interactionBarrier(this.plan.executable.indexOf(entry), outcome);
+            if (outcome.kind === "deferred") {
+                const value = Object.freeze({
                     callId: entry.call.callId,
+                    toolName: entry.call.toolName,
+                    args: copyJson(entry.call.args),
                     invocationId: entry.invocationId,
-                    attributes: { args: copyJson(entry.call.args) },
-                });
-                const outcome = await adapter.execute(entry.call, {
-                    invocationId: entry.invocationId,
-                    signal: context.signal,
-                    resume: this.takeResume("execute", entry.call.callId),
+                    owner: entry.owner,
+                    ...(outcome.token === undefined ? {} : { token: copyJson(outcome.token) }),
                 });
-                this.throwIfAborted(context.signal);
-                if (outcome.kind === "interaction-required")
-                    return interactionBarrier("execute", this.plan.executable.indexOf(entry), outcome);
-                this.results.set(entry.call.callId, resultFrom(entry, outcome));
-                context.observe({
-                    type: "adapter.completed",
+                this.deferred.set(entry.call.callId, value);
+                this.settlementEvents.push({
+                    type: "tool.deferred",
+                    sessionId: context.ids.sessionId,
                     turnId: context.ids.turnId,
                     stepId: context.ids.stepId,
-                    adapterId: adapter.id,
                     toolName: entry.call.toolName,
                     callId: entry.call.callId,
-                    outcome: outcome.kind,
-                    ...adapterCompleted(this.results.get(entry.call.callId)),
+                    invocationId: entry.invocationId,
+                    middlewareId: entry.owner.middlewareId,
+                    slot: entry.owner.slot,
+                    attributes: outcome.token === undefined ? {} : { token: copyJson(outcome.token) },
                 });
                 return undefined;
-            });
+            }
+            const result = resultFrom(entry, outcome);
+            this.results.set(entry.call.callId, result);
+            this.settlementEvents.push(completedEvent(entry, context, result));
         }
         catch (error) {
             this.throwIfAborted(context.signal);
             const result = failed(entry, isHarnessError(error) ? error.code : "tool.execution-failed", error);
             this.results.set(entry.call.callId, result);
-            context.observe({
-                type: "adapter.completed",
-                turnId: context.ids.turnId,
-                stepId: context.ids.stepId,
-                adapterId: adapter.id,
-                toolName: entry.call.toolName,
-                callId: entry.call.callId,
-                outcome: "failed",
-                ...adapterCompleted(result),
-            });
+            this.settlementEvents.push(completedEvent(entry, context, result));
         }
         return undefined;
     }
-    takeResume(phase, callId) {
-        const phased = `${phase}:${callId}`;
-        const resume = this.resumes.get(phased) ?? this.resumes.get(callId);
-        this.resumes.delete(phased);
-        return resume;
-    }
-    requireInteraction(pending) {
-        this.enqueueInteraction(pending);
-        return this.interactionRequired();
+    takeResume(callId) {
+        const value = this.resumes.get(callId);
+        this.resumes.delete(callId);
+        return value;
     }
     enqueueInteraction(pending) {
         const position = this.pending.findIndex((item) => item.index > pending.index);
@@ -271,24 +249,23 @@ export class ToolPlanRunner {
     orderedResults() {
         return this.resultsInOrder("tool.missing-result", "Tool call did not produce a result");
     }
+    orderedSettledResults() {
+        return Object.freeze(this.plan.order.flatMap(({ callId }) => {
+            const result = this.results.get(callId);
+            return result ? [result] : [];
+        }));
+    }
     resultsInOrder(code, message) {
         return Object.freeze(this.plan.order.map(({ callId, toolName }) => this.results.get(callId) ??
-            Object.freeze({
-                callId,
-                toolName,
-                kind: "failed",
-                code,
-                message,
-            })));
+            Object.freeze({ kind: "failed", callId, toolName, code, message })));
     }
     throwIfAborted(signal) {
         if (signal.aborted)
             throw signal.reason;
     }
 }
-function interactionBarrier(phase, index, outcome) {
+function interactionBarrier(index, outcome) {
     return {
-        phase,
         index,
         interaction: normalizeInteraction(outcome.interaction),
         ...(outcome.token === undefined ? {} : { token: copyJson(outcome.token) }),
@@ -347,15 +324,21 @@ function resultFrom(entry, outcome) {
                 code: outcome.code,
                 message: outcome.message,
             });
-        default:
-            throw new HarnessError("adapter.invalid-outcome", "Tool adapter returned an invalid outcome");
     }
 }
-function adapterCompleted(result) {
-    if (!result)
-        return {};
+function completedEvent(entry, context, result) {
     return {
-        ...(result.code === undefined ? {} : { code: result.code }),
+        type: "tool.completed",
+        sessionId: context.ids.sessionId,
+        turnId: context.ids.turnId,
+        stepId: context.ids.stepId,
+        toolName: entry.call.toolName,
+        callId: entry.call.callId,
+        invocationId: entry.invocationId,
+        middlewareId: entry.owner.middlewareId,
+        slot: entry.owner.slot,
+        outcome: result.kind,
+        ...(result.kind === "failed" ? { code: result.code } : {}),
         attributes: copyJson(result),
     };
 }