@nylorun/harness 0.5.0-beta.1

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

@@ -0,0 +1,55 @@
+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";
+export type ToolPlanProgress = {
+    readonly kind: "completed";
+    readonly results: readonly ToolResult[];
+} | {
+    readonly kind: "interaction-required";
+    readonly interaction: RequiredInteraction;
+};
+export interface ToolPlanRunContext {
+    readonly adapters: AdapterRegistry;
+    readonly signal: AbortSignal;
+    readonly observe: ObserveEmit;
+    readonly ids: {
+        readonly sessionId: string;
+        readonly turnId: string;
+        readonly stepId: string;
+    };
+}
+/** Owns the mutable progress of one sealed tool plan across interaction resumes. */
+export declare class ToolPlanRunner {
+    private readonly plan;
+    private readonly results;
+    private readonly resumes;
+    private phase;
+    private index;
+    private readonly pending;
+    private executeStarted;
+    private resumeExecute?;
+    constructor(plan: InternalToolPlan);
+    get interactionId(): string | undefined;
+    get interactionKind(): RequiredInteraction["kind"] | undefined;
+    get interactionCallId(): string | undefined;
+    get interactionToolName(): string | undefined;
+    get interactionPhase(): PlanPhase | undefined;
+    cancelledResults(reason: string): readonly ToolResult[];
+    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 resultsInOrder;
+    private throwIfAborted;
+}
+export {};

package/dist/turn/plan-runner.js

@@ -0,0 +1,370 @@
+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. */
+export class ToolPlanRunner {
+    plan;
+    results;
+    resumes = new Map();
+    phase = "interaction";
+    index = 0;
+    pending = [];
+    executeStarted = false;
+    resumeExecute;
+    constructor(plan) {
+        this.plan = plan;
+        this.results = new Map(plan.immediateResults.map((item) => [item.callId, item]));
+    }
+    get interactionId() {
+        return this.pending[0]?.interaction.id;
+    }
+    get interactionKind() {
+        return this.pending[0]?.interaction.kind;
+    }
+    get interactionCallId() {
+        const pending = this.pending[0];
+        if (!pending)
+            return undefined;
+        return this.plan.executable[pending.index]?.call.callId;
+    }
+    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;
+    }
+    cancelledResults(reason) {
+        return this.resultsInOrder("tool.cancelled", reason);
+    }
+    async run(context, resume) {
+        this.acceptResume(resume);
+        while (true) {
+            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];
+            if (this.results.has(entry.call.callId)) {
+                this.index += 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;
+            }
+            this.index += 1;
+        }
+    }
+    acceptResume(resume) {
+        const pending = this.pending.shift();
+        if (!pending)
+            return;
+        if (!resume)
+            throw new HarnessError("interaction.missing-resume", "A pending tool plan requires a correlated interaction input");
+        const value = resumeValue(resume, pending);
+        const entry = this.plan.executable[pending.index];
+        if (value.kind === "approval" && value.approved === false) {
+            this.results.set(entry.call.callId, Object.freeze({
+                callId: entry.call.callId,
+                toolName: entry.call.toolName,
+                kind: "denied",
+                reason: "Approval rejected",
+            }));
+            this.index += 1;
+            return;
+        }
+        if (pending.phase === "interaction") {
+            this.resumes.set(entry.call.callId, value);
+            this.index += 1;
+            return;
+        }
+        this.resumes.set(`${pending.phase}:${entry.call.callId}`, value);
+        if (pending.phase === "execute")
+            this.resumeExecute = entry;
+    }
+    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);
+        }
+        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;
+        }
+        context.observe({
+            type: "adapter.preflight.started",
+            turnId: context.ids.turnId,
+            stepId: context.ids.stepId,
+            adapterId: adapter.id,
+            toolName: entry.call.toolName,
+            callId: entry.call.callId,
+            invocationId: entry.invocationId,
+            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",
+                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) {
+            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,
+                    callId: entry.call.callId,
+                    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),
+                });
+                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",
+                    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)),
+                });
+                return undefined;
+            });
+        }
+        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),
+            });
+        }
+        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();
+    }
+    enqueueInteraction(pending) {
+        const position = this.pending.findIndex((item) => item.index > pending.index);
+        if (position === -1)
+            this.pending.push(pending);
+        else
+            this.pending.splice(position, 0, pending);
+    }
+    interactionRequired() {
+        const pending = this.pending[0];
+        if (!pending)
+            throw new HarnessError("interaction.invalid", "Missing pending interaction");
+        return { kind: "interaction-required", interaction: pending.interaction };
+    }
+    orderedResults() {
+        return this.resultsInOrder("tool.missing-result", "Tool call did not produce a 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,
+            })));
+    }
+    throwIfAborted(signal) {
+        if (signal.aborted)
+            throw signal.reason;
+    }
+}
+function interactionBarrier(phase, index, outcome) {
+    return {
+        phase,
+        index,
+        interaction: normalizeInteraction(outcome.interaction),
+        ...(outcome.token === undefined ? {} : { token: copyJson(outcome.token) }),
+    };
+}
+function normalizeInteraction(value) {
+    if (!value || typeof value !== "object")
+        throw new HarnessError("interaction.invalid", "Interaction must be an object");
+    if (value.kind !== "approval" && value.kind !== "response")
+        throw new HarnessError("interaction.invalid", "Interaction kind must be approval or response");
+    if (typeof value.prompt !== "string")
+        throw new HarnessError("interaction.invalid", "Interaction prompt must be a string");
+    if (value.id !== undefined && (typeof value.id !== "string" || !value.id))
+        throw new HarnessError("interaction.invalid", "Interaction id must be a non-empty string");
+    return Object.freeze({
+        id: value.id ?? createId("interaction"),
+        kind: value.kind,
+        prompt: value.prompt,
+        ...(value.metadata === undefined
+            ? {}
+            : { metadata: copyJsonObject(value.metadata, "interaction metadata") }),
+    });
+}
+function resumeValue(event, pending) {
+    if (event.kind === "approve")
+        return Object.freeze({
+            interactionId: event.interactionId,
+            kind: "approval",
+            approved: event.approved,
+            ...(pending.token === undefined ? {} : { token: pending.token }),
+        });
+    if (event.kind === "respond")
+        return Object.freeze({
+            interactionId: event.interactionId,
+            kind: "response",
+            value: event.value,
+            ...(pending.token === undefined ? {} : { token: pending.token }),
+        });
+    throw new HarnessError("interaction.uncorrelated-resume", "Only correlated interaction input can resume a plan");
+}
+function resultFrom(entry, outcome) {
+    const base = { callId: entry.call.callId, toolName: entry.call.toolName };
+    switch (outcome.kind) {
+        case "completed":
+            return Object.freeze({ ...base, kind: "completed", output: copyJson(outcome.output) });
+        case "denied":
+            if (typeof outcome.reason !== "string")
+                throw new HarnessError("tool.invalid-tool-result", "Tool denial reason must be a string");
+            return Object.freeze({ ...base, kind: "denied", reason: outcome.reason });
+        case "failed":
+            if (typeof outcome.code !== "string" || typeof outcome.message !== "string")
+                throw new HarnessError("tool.invalid-tool-result", "Tool failure code and message must be strings");
+            return Object.freeze({
+                ...base,
+                kind: "failed",
+                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 {};
+    return {
+        ...(result.code === undefined ? {} : { code: result.code }),
+        attributes: copyJson(result),
+    };
+}
+function failed(entry, code, error) {
+    return Object.freeze({
+        callId: entry.call.callId,
+        toolName: entry.call.toolName,
+        kind: "failed",
+        code,
+        message: error instanceof Error ? error.message : String(error),
+    });
+}

package/dist/turn/runner.d.ts

@@ -0,0 +1,53 @@
+import type { InputEvent, SessionEvent, 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";
+export interface PendingTurn {
+    readonly plan: ToolPlanRunner;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly stepNumber: number;
+}
+export type TurnProgress = {
+    readonly kind: "final";
+    readonly state: SessionSnapshot;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly output: string;
+} | {
+    readonly kind: "interaction-required";
+    readonly state: SessionSnapshot;
+    readonly pending: PendingTurn;
+    readonly interaction: RequiredInteraction;
+} | {
+    readonly kind: "tripwire";
+    readonly state: SessionSnapshot;
+    readonly turnId: string;
+    readonly stepId?: string;
+    readonly tripwire: Tripwire;
+};
+export interface TurnRunContext {
+    readonly signal: AbortSignal;
+    readonly observe: ObserveEmit;
+    readonly assertCurrent: () => void;
+    readonly onPlanActive: (pending: PendingTurn | undefined) => void;
+    readonly onState: (state: SessionSnapshot) => void;
+    readonly onConversation: (event: SessionEvent) => void;
+    readonly claimInterrupts: (turnId: string) => readonly InputEvent[];
+}
+/** Advances one Turn until it finalizes, trips a policy, or pauses for an interaction. */
+export declare class TurnRunner {
+    private readonly agent;
+    private readonly sessionId;
+    private readonly session;
+    constructor(agent: LoopAgent, sessionId: string, session: Readonly<{
+        readonly userId?: string;
+        readonly context?: JsonObject;
+    }>);
+    start(state: SessionSnapshot, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
+    resume(state: SessionSnapshot, pending: PendingTurn, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
+    private advance;
+    private runPlan;
+}

package/dist/turn/runner.js

@@ -0,0 +1,128 @@
+import { beginTurn, commitCandidate, commitFinal, commitInput, commitToolResults, } from "../session/state.js";
+import { runStep } from "../step/run.js";
+import { createId } from "../utils/ids.js";
+import { copyJson } from "../utils/immutable.js";
+import { ToolPlanRunner } from "./plan-runner.js";
+/** Advances one Turn until it finalizes, trips a policy, or pauses for an interaction. */
+export class TurnRunner {
+    agent;
+    sessionId;
+    session;
+    constructor(agent, sessionId, session) {
+        this.agent = agent;
+        this.sessionId = sessionId;
+        this.session = session;
+    }
+    async start(state, event, context) {
+        const turnId = createId("turn");
+        const started = beginTurn(state, turnId, event);
+        context.onState(started);
+        context.onConversation({ type: "input", event, turnId });
+        return this.advance(started, turnId, 1, [event], [], context);
+    }
+    async resume(state, pending, event, context) {
+        context.onConversation({ type: "input", event, turnId: pending.turnId });
+        const progress = await this.runPlan(pending, context, event);
+        if (progress.kind === "interaction-required")
+            return { kind: "interaction-required", state, pending, interaction: progress.interaction };
+        const afterTools = commitToolResults(state, pending.turnId, pending.stepId, progress.results);
+        context.onState(afterTools);
+        const claimed = claimAndRecord(afterTools, pending.turnId, context);
+        return this.advance(claimed.state, pending.turnId, pending.stepNumber + 1, claimed.arrivals, progress.results, context);
+    }
+    async advance(initialState, turnId, firstStep, arrivals, initialResults, context) {
+        let state = initialState;
+        let stepArrivals = arrivals;
+        let toolResults = initialResults;
+        for (let stepNumber = firstStep;; stepNumber += 1) {
+            const stepId = createId("step");
+            const run = await runStep({
+                agent: this.agent,
+                observe: context.observe,
+                state,
+                sessionId: this.sessionId,
+                turnId,
+                stepId,
+                turnNumber: state.turnCount,
+                stepNumber,
+                arrivals: stepArrivals,
+                toolResults,
+                signal: context.signal,
+                session: this.session,
+            });
+            context.assertCurrent();
+            if (run.candidate) {
+                state = commitCandidate(state, turnId, stepId, run.candidate);
+                context.onState(state);
+                context.onConversation({ type: "candidate", turnId, stepId, candidate: run.candidate });
+            }
+            if (run.output.kind === "tripwire")
+                return { kind: "tripwire", state, turnId, stepId, tripwire: run.output.tripwire };
+            if (run.output.kind === "final")
+                return {
+                    kind: "final",
+                    state: commitFinal(state, turnId, stepId, run.output.output),
+                    turnId,
+                    stepId,
+                    output: run.output.output,
+                };
+            const plan = run.output.plan;
+            context.observe(() => ({
+                type: "tool.sealed",
+                turnId,
+                stepId,
+                attributes: {
+                    executable: Object.freeze(plan.executable.map((entry) => Object.freeze({
+                        callId: entry.call.callId,
+                        toolName: entry.call.toolName,
+                        args: copyJson(entry.call.args),
+                        executeWith: entry.call.executeWith,
+                        invocationId: entry.invocationId,
+                        ...(entry.preflight === undefined ? {} : { preflight: entry.preflight }),
+                        ...(entry.interaction === undefined
+                            ? {}
+                            : { interaction: copyJson(entry.interaction) }),
+                    }))),
+                    immediate: copyJson(plan.immediateResults),
+                },
+            }));
+            const pending = {
+                plan: new ToolPlanRunner(run.output.plan),
+                turnId,
+                stepId,
+                stepNumber,
+            };
+            const progress = await this.runPlan(pending, context);
+            if (progress.kind === "interaction-required")
+                return { kind: "interaction-required", state, pending, interaction: progress.interaction };
+            state = commitToolResults(state, turnId, stepId, progress.results);
+            context.onState(state);
+            const claimed = claimAndRecord(state, turnId, context);
+            state = claimed.state;
+            stepArrivals = claimed.arrivals;
+            toolResults = progress.results;
+        }
+    }
+    async runPlan(pending, context, resume) {
+        context.onPlanActive(pending);
+        const progress = await pending.plan.run({
+            adapters: this.agent.adapters,
+            signal: context.signal,
+            observe: context.observe,
+            ids: { sessionId: this.sessionId, turnId: pending.turnId, stepId: pending.stepId },
+        }, resume);
+        context.assertCurrent();
+        context.onPlanActive(undefined);
+        return progress;
+    }
+}
+function claimAndRecord(state, turnId, context) {
+    const arrivals = context.claimInterrupts(turnId);
+    if (arrivals.length === 0)
+        return { state, arrivals };
+    let next = state;
+    for (const event of arrivals)
+        next = commitInput(next, turnId, event);
+    context.onState(next);
+    return { state: next, arrivals };
+}

package/dist/types/manifest.d.ts

@@ -0,0 +1,22 @@
+import type { BoundMiddleware } from "./middleware.js";
+import type { ModelDirective } from "./model.js";
+import type { BuildDiagnostic } from "./shared.js";
+export interface AgentManifest {
+    readonly middleware: readonly {
+        readonly id: string;
+    }[];
+    readonly model?: ModelDirective;
+    readonly adapters: readonly {
+        readonly id: string;
+        readonly maxConcurrentCalls?: number;
+    }[];
+}
+export type BuildResult<Agent> = {
+    readonly ok: true;
+    readonly agent: Agent;
+    readonly manifest: AgentManifest;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly BuildDiagnostic[];
+};
+export type { BoundMiddleware };

package/dist/types/manifest.js

@@ -0,0 +1 @@
+export {};