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

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),
     };
 }

package/dist/turn/runner.d.ts

@@ -1,9 +1,10 @@
-import type { InputEvent, SessionEvent, SessionSnapshot } from "../types/session.js";
+import type { ActiveExecutionRecord, InputEvent, SessionEvent, SessionRecord, SessionSnapshot } from "../types/session.js";
 import type { JsonObject, Tripwire } from "../types/shared.js";
 import type { RequiredInteraction } from "../types/tool.js";
 import type { LoopAgent } from "../build/agent.js";
 import type { ObserveEmit } from "../utils/observe.js";
 import { ToolPlanRunner } from "./plan-runner.js";
+import type { CapabilityStateRegistry } from "../session/capability-state.js";
 export interface PendingTurn {
     readonly plan: ToolPlanRunner;
     readonly turnId: string;
@@ -21,6 +22,12 @@ export type TurnProgress = {
     readonly state: SessionSnapshot;
     readonly pending: PendingTurn;
     readonly interaction: RequiredInteraction;
+} | {
+    readonly kind: "deferred";
+    readonly state: SessionSnapshot;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly active: ActiveExecutionRecord;
 } | {
     readonly kind: "tripwire";
     readonly state: SessionSnapshot;
@@ -30,14 +37,18 @@ export type TurnProgress = {
 };
 export interface TurnRunContext {
     readonly signal: AbortSignal;
+    readonly states: CapabilityStateRegistry;
     readonly observe: ObserveEmit;
     readonly assertCurrent: () => void;
     readonly onPlanActive: (pending: PendingTurn | undefined) => void;
-    readonly onState: (state: SessionSnapshot) => void;
+    readonly commit: (state: SessionSnapshot, transition: SessionRecord["transition"], active?: ActiveExecutionRecord) => Promise<SessionSnapshot>;
     readonly onConversation: (event: SessionEvent) => void;
-    readonly claimInterrupts: (turnId: string) => readonly InputEvent[];
+    readonly claimInterrupts: (state: SessionSnapshot, turnId: string) => Promise<{
+        readonly state: SessionSnapshot;
+        readonly arrivals: readonly InputEvent[];
+    }>;
 }
-/** Advances one Turn until it finalizes, trips a policy, or pauses for an interaction. */
+/** Advances one Turn until it finalizes, trips policy, or reaches a waiting barrier. */
 export declare class TurnRunner {
     private readonly agent;
     private readonly sessionId;
@@ -47,7 +58,10 @@ export declare class TurnRunner {
         readonly context?: JsonObject;
     }>);
     start(state: SessionSnapshot, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
+    continue(state: SessionSnapshot, context: TurnRunContext): Promise<TurnProgress>;
     resume(state: SessionSnapshot, pending: PendingTurn, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
     private advance;
+    private waitForInteraction;
+    private waitForDeferred;
     private runPlan;
 }