@nylorun/harness 0.5.0-beta.1

package/dist/session/input-queue.js

@@ -0,0 +1,78 @@
+import { copyJson, copyJsonObject } from "../utils/immutable.js";
+import { SubmissionStream } from "./submission-stream.js";
+export function isInteractionReply(event) {
+    return event.kind === "approve" || event.kind === "respond";
+}
+export function snapshotInput(event) {
+    switch (event.kind) {
+        case "user-message":
+        case "interrupt":
+            return Object.freeze({
+                kind: event.kind,
+                text: event.text,
+                ...(event.metadata ? { metadata: copyJsonObject(event.metadata, "input metadata") } : {}),
+            });
+        case "approve":
+            return Object.freeze({ ...event });
+        case "respond":
+            return Object.freeze({ ...event, value: copyJson(event.value) });
+    }
+}
+/** Serializes ordinary input while allowing a matching interaction reply to resume immediately. */
+export class InputQueue {
+    values = [];
+    get size() {
+        return this.values.length;
+    }
+    add(input, priority = false) {
+        if (priority)
+            this.values.unshift(input);
+        else
+            this.values.push(input);
+    }
+    take(waitingForInteraction) {
+        const next = this.values[0];
+        if (!next || (waitingForInteraction && !isInteractionReply(next.event)))
+            return undefined;
+        return this.values.shift();
+    }
+    takeInterrupts() {
+        const claimed = [];
+        for (let index = 0; index < this.values.length;) {
+            const item = this.values[index];
+            if (item.event.kind !== "interrupt") {
+                index += 1;
+                continue;
+            }
+            this.values.splice(index, 1);
+            if (!item.cancelled)
+                claimed.push(item);
+        }
+        return claimed;
+    }
+    remove(input) {
+        const index = this.values.indexOf(input);
+        if (index < 0)
+            return false;
+        this.values.splice(index, 1);
+        return true;
+    }
+    drain() {
+        return this.values.splice(0);
+    }
+}
+/** Binds one caller-provided signal to its queue entry and always removes the listener at completion. */
+export function watchInputAbort(input, handlers) {
+    const signal = input.options?.signal;
+    if (!signal)
+        return;
+    const onAbort = () => {
+        input.cancelled = true;
+        if (handlers.isActive())
+            handlers.abortActive(signal.reason);
+        else
+            handlers.cancelQueued();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    input.stream.onFinish(() => signal.removeEventListener("abort", onAbort));
+}

package/dist/session/scheduler.d.ts

@@ -0,0 +1,48 @@
+import type { InputEvent, InputOptions, SessionSnapshot } from "../types/session.js";
+import type { Observer } from "../types/shared.js";
+import { SessionEventLog } from "./event-log.js";
+import { SubmissionStream } from "./submission-stream.js";
+import { type LoopAgent } from "../build/agent.js";
+/** Coordinates one active turn at a time; TurnRunner owns the turn's internal state machine. */
+export declare class SessionScheduler {
+    readonly id: string;
+    readonly events: SessionEventLog;
+    private snapshotValue;
+    private readonly queue;
+    private readonly sessionController;
+    private activeController?;
+    private activeSubmission?;
+    private activeWork?;
+    private pending?;
+    private inFlightPlan?;
+    private running;
+    private stopped;
+    private generation;
+    private stopPromise?;
+    private readonly observers;
+    private readonly turns;
+    constructor(id: string, agent: LoopAgent, session: Readonly<{
+        readonly userId?: string;
+        readonly context?: import("../types/shared.js").JsonObject;
+    }>);
+    get snapshot(): SessionSnapshot;
+    observe(listener: Observer): () => void;
+    submit(event: InputEvent, options?: InputOptions): SubmissionStream;
+    stop(reason?: string): Promise<void>;
+    private enqueueReply;
+    private enqueueOrdinaryInput;
+    private watchAbort;
+    private reject;
+    private finishCancelled;
+    private finishStopped;
+    private publish;
+    private pump;
+    private run;
+    private resumeTurn;
+    private applyTurnOutcome;
+    private beginStop;
+    private emitObserve;
+    private commitCancelledPlan;
+    private claimInterrupts;
+    private assertCurrent;
+}

package/dist/session/scheduler.js

@@ -0,0 +1,352 @@
+import { HarnessError } from "../errors.js";
+import { createId } from "../utils/ids.js";
+import { createObserverRegistry } from "../utils/observe.js";
+import { InputQueue, isInteractionReply, snapshotInput, watchInputAbort, } from "./input-queue.js";
+import { SessionEventLog } from "./event-log.js";
+import { SubmissionStream } from "./submission-stream.js";
+import { commitToolResults, initialState, withStatus } from "./state.js";
+import {} from "../build/agent.js";
+import { TurnRunner } from "../turn/runner.js";
+/** Coordinates one active turn at a time; TurnRunner owns the turn's internal state machine. */
+export class SessionScheduler {
+    id;
+    events = new SessionEventLog();
+    snapshotValue;
+    queue = new InputQueue();
+    sessionController = new AbortController();
+    activeController;
+    activeSubmission;
+    activeWork;
+    pending;
+    inFlightPlan;
+    running = false;
+    stopped = false;
+    generation = 0;
+    stopPromise;
+    observers = createObserverRegistry();
+    turns;
+    constructor(id, agent, session) {
+        this.id = id;
+        this.snapshotValue = initialState(id);
+        this.turns = new TurnRunner(agent, id, session);
+    }
+    get snapshot() {
+        return this.snapshotValue;
+    }
+    observe(listener) {
+        if (this.stopped)
+            return () => undefined;
+        return this.observers.observe(listener);
+    }
+    submit(event, options) {
+        const stream = new SubmissionStream(createId("input"));
+        const submission = {
+            event: snapshotInput(event),
+            options,
+            stream,
+            cancelled: false,
+        };
+        if (this.stopped)
+            return this.finishStopped(stream);
+        if (options?.signal?.aborted)
+            return this.finishCancelled(stream, cancellationMessage(options.signal));
+        if (isInteractionReply(event)) {
+            if (!this.enqueueReply(submission, event))
+                return stream;
+        }
+        else
+            this.enqueueOrdinaryInput(submission);
+        this.watchAbort(submission);
+        this.emitObserve({
+            type: "input.received",
+            inputId: stream.inputId,
+            kind: event.kind,
+        });
+        this.pump();
+        return stream;
+    }
+    stop(reason = "Session stopped") {
+        if (this.stopPromise)
+            return this.stopPromise;
+        this.beginStop(reason);
+        const activeWork = this.activeWork;
+        this.stopPromise = (async () => {
+            if (activeWork)
+                await activeWork;
+        })();
+        return this.stopPromise;
+    }
+    enqueueReply(submission, reply) {
+        if (!this.pending) {
+            this.reject(submission.stream, "No interaction is pending");
+            return false;
+        }
+        const expected = this.pending.plan.interactionId;
+        if (expected !== reply.interactionId) {
+            this.reject(submission.stream, "Interaction id does not match the pending interaction");
+            return false;
+        }
+        if ((this.pending.plan.interactionKind === "approval") !== (reply.kind === "approve")) {
+            this.reject(submission.stream, "Interaction input kind does not match");
+            return false;
+        }
+        this.queue.add(submission, true);
+        return true;
+    }
+    enqueueOrdinaryInput(submission) {
+        if (this.running || this.pending || this.queue.size) {
+            this.publish(submission.stream, {
+                type: "input.queued",
+                inputId: submission.stream.inputId,
+            });
+            this.emitObserve({
+                type: "input.queued",
+                inputId: submission.stream.inputId,
+            });
+        }
+        this.queue.add(submission);
+    }
+    watchAbort(submission) {
+        watchInputAbort(submission, {
+            isActive: () => this.activeSubmission === submission,
+            abortActive: (reason) => this.activeController?.abort(reason),
+            cancelQueued: () => {
+                const signal = submission.options?.signal;
+                if (signal && this.queue.remove(submission))
+                    this.finishCancelled(submission.stream, cancellationMessage(signal));
+            },
+        });
+    }
+    reject(stream, reason) {
+        this.publish(stream, { type: "input.rejected", inputId: stream.inputId, reason });
+        this.emitObserve({
+            type: "input.rejected",
+            inputId: stream.inputId,
+            reason,
+        });
+        stream.finish("rejected");
+        return stream;
+    }
+    finishCancelled(stream, reason) {
+        this.publish(stream, { type: "input.cancelled", inputId: stream.inputId, reason });
+        this.emitObserve({
+            type: "input.cancelled",
+            inputId: stream.inputId,
+            reason,
+        });
+        stream.finish("cancelled");
+        return stream;
+    }
+    finishStopped(stream) {
+        this.publish(stream, { type: "session.stopped", sessionId: this.id });
+        stream.finish("stopped");
+        return stream;
+    }
+    publish(stream, event) {
+        stream.emit(event);
+        this.events.emit(event);
+    }
+    pump() {
+        if (this.running || this.stopped)
+            return;
+        const next = this.queue.take(Boolean(this.pending));
+        if (!next)
+            return;
+        if (next.cancelled) {
+            this.pump();
+            return;
+        }
+        // This Scheduler is the sole serializing point: only one turn can mutate a Session at once.
+        this.running = true;
+        this.activeSubmission = next;
+        this.activeController = new AbortController();
+        const generation = ++this.generation;
+        const signal = AbortSignal.any([
+            this.sessionController.signal,
+            this.activeController.signal,
+            ...(next.options?.signal ? [next.options.signal] : []),
+        ]);
+        const work = this.run(next, signal, generation).finally(() => {
+            this.running = false;
+            this.activeSubmission = undefined;
+            this.activeController = undefined;
+            if (this.activeWork === work)
+                this.activeWork = undefined;
+            if (!this.stopped && !this.pending)
+                this.snapshotValue = withStatus(this.snapshotValue, "idle");
+            this.pump();
+        });
+        this.activeWork = work;
+        void work;
+    }
+    async run(submission, signal, generation) {
+        try {
+            const context = {
+                signal,
+                observe: ((event) => this.emitObserve(() => withInputId(typeof event === "function" ? event() : event, submission.stream.inputId))),
+                assertCurrent: () => this.assertCurrent(generation, signal),
+                onPlanActive: (plan) => {
+                    this.inFlightPlan = plan;
+                },
+                onState: (state) => {
+                    this.snapshotValue = state;
+                },
+                onConversation: (event) => this.publish(submission.stream, event),
+                claimInterrupts: (turnId) => this.claimInterrupts(turnId),
+            };
+            const outcome = this.pending
+                ? await this.resumeTurn(submission, context)
+                : await this.turns.start(this.snapshotValue, submission.event, context);
+            this.applyTurnOutcome(submission.stream, outcome);
+        }
+        catch (error) {
+            if (this.inFlightPlan) {
+                this.commitCancelledPlan(this.inFlightPlan, message(error));
+                this.inFlightPlan = undefined;
+            }
+            if (this.stopped)
+                this.finishStopped(submission.stream);
+            else {
+                if (!this.pending)
+                    this.snapshotValue = withStatus(this.snapshotValue, "idle");
+                this.finishCancelled(submission.stream, message(error));
+            }
+        }
+    }
+    async resumeTurn(submission, context) {
+        const pending = this.pending;
+        this.pending = undefined;
+        this.snapshotValue = withStatus(this.snapshotValue, "running");
+        return this.turns.resume(this.snapshotValue, pending, submission.event, context);
+    }
+    applyTurnOutcome(stream, outcome) {
+        switch (outcome.kind) {
+            case "final":
+                this.snapshotValue = withStatus(outcome.state, "idle");
+                this.publish(stream, { type: "final", output: outcome.output, turnId: outcome.turnId });
+                this.emitObserve({
+                    type: "turn.completed",
+                    turnId: outcome.turnId,
+                    stepId: outcome.stepId,
+                    inputId: stream.inputId,
+                    attributes: { output: outcome.output },
+                });
+                stream.finish("completed");
+                return;
+            case "interaction-required":
+                this.pending = outcome.pending;
+                this.snapshotValue = withStatus(outcome.state, "waiting", outcome.interaction);
+                this.emitObserve({
+                    type: "interaction.required",
+                    turnId: outcome.pending.turnId,
+                    stepId: outcome.pending.stepId,
+                    inputId: stream.inputId,
+                    interactionId: outcome.interaction.id,
+                    kind: outcome.interaction.kind,
+                    ...(outcome.pending.plan.interactionCallId === undefined
+                        ? {}
+                        : { callId: outcome.pending.plan.interactionCallId }),
+                    ...(outcome.pending.plan.interactionToolName === undefined
+                        ? {}
+                        : { toolName: outcome.pending.plan.interactionToolName }),
+                    ...(outcome.pending.plan.interactionPhase === undefined
+                        ? {}
+                        : { phase: outcome.pending.plan.interactionPhase }),
+                    attributes: {
+                        prompt: outcome.interaction.prompt,
+                        ...(outcome.interaction.metadata === undefined
+                            ? {}
+                            : { metadata: outcome.interaction.metadata }),
+                    },
+                });
+                this.publish(stream, {
+                    type: "interaction.required",
+                    interaction: outcome.interaction,
+                    turnId: outcome.pending.turnId,
+                });
+                stream.finish("waiting");
+                return;
+            case "tripwire":
+                this.snapshotValue = outcome.state;
+                this.publish(stream, {
+                    type: "tripwire",
+                    tripwire: outcome.tripwire,
+                    turnId: outcome.turnId,
+                });
+                this.emitObserve({
+                    type: "tripwire",
+                    turnId: outcome.turnId,
+                    inputId: stream.inputId,
+                    ...(outcome.stepId ? { stepId: outcome.stepId } : {}),
+                    code: outcome.tripwire.code,
+                    scope: outcome.tripwire.scope ?? "step",
+                    attributes: { message: outcome.tripwire.message },
+                });
+                if (outcome.tripwire.scope === "session")
+                    this.beginStop("Session policy tripwire");
+                else
+                    this.snapshotValue = withStatus(this.snapshotValue, "idle");
+                stream.finish("completed");
+        }
+    }
+    beginStop(reason) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.generation += 1;
+        this.sessionController.abort(new HarnessError("session.stale-result", reason));
+        this.activeController?.abort(new HarnessError("session.stale-result", reason));
+        if (this.pending)
+            this.commitCancelledPlan(this.pending, reason);
+        this.pending = undefined;
+        this.snapshotValue = withStatus(this.snapshotValue, "stopped");
+        this.events.emit({ type: "session.stopped", sessionId: this.id });
+        this.events.finish();
+        this.emitObserve({ type: "session.stopped", reason });
+        this.observers.clear();
+        for (const item of this.queue.drain())
+            this.finishStopped(item.stream);
+    }
+    emitObserve(event) {
+        this.observers.emit(event);
+    }
+    commitCancelledPlan(pending, reason) {
+        this.snapshotValue = commitToolResults(this.snapshotValue, pending.turnId, pending.stepId, pending.plan.cancelledResults(reason));
+    }
+    claimInterrupts(turnId) {
+        const claimed = this.queue.takeInterrupts();
+        const events = [];
+        for (const item of claimed) {
+            const conversation = Object.freeze({
+                type: "input",
+                event: item.event,
+                turnId,
+            });
+            this.events.emit(conversation);
+            this.activeSubmission?.stream.emit(conversation);
+            item.stream.emit(conversation);
+            item.stream.finish("completed");
+            events.push(item.event);
+        }
+        return Object.freeze(events);
+    }
+    assertCurrent(generation, signal) {
+        // An abort-ignoring adapter may resolve late; its state must never re-enter this Session.
+        if (this.stopped || generation !== this.generation || signal.aborted)
+            throw (signal.reason ??
+                new HarnessError("session.stale-result", "Stale Session result quarantined"));
+    }
+}
+function withInputId(event, inputId) {
+    return "turnId" in event ? { ...event, inputId } : event;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function cancellationMessage(signal) {
+    return signal.reason instanceof Error
+        ? signal.reason.message
+        : signal.reason
+            ? String(signal.reason)
+            : "Input cancelled";
+}

package/dist/session/session.d.ts

@@ -0,0 +1,14 @@
+import type { InputHandle, InputOptions, MessageInput, Session, SessionEvent, SessionOptions, SessionSnapshot, SessionInput } from "../types/session.js";
+import type { Observer } from "../types/shared.js";
+import type { LoopAgent } from "../build/agent.js";
+export declare class LiveSession implements Session {
+    readonly id: string;
+    private readonly scheduler;
+    constructor(id: string, agent: LoopAgent, options: SessionOptions);
+    get state(): SessionSnapshot;
+    input(event: SessionInput, options?: InputOptions): InputHandle;
+    interrupt(event: MessageInput, options?: InputOptions): InputHandle;
+    stream(): AsyncIterable<SessionEvent>;
+    observe(listener: Observer): () => void;
+    stop(reason?: string): Promise<void>;
+}

package/dist/session/session.js

@@ -0,0 +1,55 @@
+import { SessionScheduler } from "./scheduler.js";
+import { copyJsonObject } from "../utils/immutable.js";
+export class LiveSession {
+    id;
+    scheduler;
+    constructor(id, agent, options) {
+        this.id = id;
+        const session = Object.freeze({
+            ...(options.userId ? { userId: options.userId } : {}),
+            ...(options.context ? { context: copyJsonObject(options.context, "session context") } : {}),
+        });
+        this.scheduler = new SessionScheduler(id, agent, session);
+    }
+    get state() {
+        return this.scheduler.snapshot;
+    }
+    input(event, options) {
+        return this.scheduler.submit(normalizeInput(event), options);
+    }
+    interrupt(event, options) {
+        return this.scheduler.submit(normalizeMessage("interrupt", event), options);
+    }
+    stream() {
+        return this.scheduler.events;
+    }
+    observe(listener) {
+        return this.scheduler.observe(listener);
+    }
+    stop(reason) {
+        return this.scheduler.stop(reason);
+    }
+}
+function isInteractionReply(value) {
+    return (typeof value === "object" &&
+        "kind" in value &&
+        (value.kind === "approve" || value.kind === "respond"));
+}
+function normalizeMessage(kind, value) {
+    if (typeof value === "string")
+        return { kind, text: value };
+    return {
+        kind,
+        text: value.text,
+        ...(value.metadata === undefined
+            ? {}
+            : { metadata: copyJsonObject(value.metadata, "input metadata") }),
+    };
+}
+function normalizeInput(input) {
+    if (typeof input === "string")
+        return { kind: "user-message", text: input };
+    if (isInteractionReply(input))
+        return input;
+    return normalizeMessage("user-message", input);
+}

package/dist/session/state.d.ts

@@ -0,0 +1,10 @@
+import type { InputEvent, SessionSnapshot } 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 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;
+export declare const commitToolResults: (state: SessionSnapshot, turnId: string, stepId: string, results: readonly ToolResult[]) => SessionSnapshot;
+export declare const commitFinal: (state: SessionSnapshot, turnId: string, stepId: string, output: string) => SessionSnapshot;

package/dist/session/state.js

@@ -0,0 +1,36 @@
+export function initialState(id) {
+    return Object.freeze({ id, status: "idle", turnCount: 0, transcript: Object.freeze([]) });
+}
+export function withStatus(state, status, pendingInteraction) {
+    return Object.freeze({
+        id: state.id,
+        status,
+        turnCount: state.turnCount,
+        transcript: state.transcript,
+        ...(pendingInteraction ? { pendingInteraction } : {}),
+    });
+}
+export function beginTurn(state, turnId, event) {
+    const transcript = event
+        ? [
+            ...state.transcript,
+            Object.freeze({ kind: "input", turnId, event: Object.freeze({ ...event }) }),
+        ]
+        : [...state.transcript];
+    return Object.freeze({
+        id: state.id,
+        status: "running",
+        turnCount: state.turnCount + (event ? 1 : 0),
+        transcript: Object.freeze(transcript),
+    });
+}
+function append(state, entry) {
+    return Object.freeze({
+        ...state,
+        transcript: Object.freeze([...state.transcript, Object.freeze(entry)]),
+    });
+}
+export const commitInput = (state, turnId, event) => append(state, { kind: "input", turnId, event: Object.freeze({ ...event }) });
+export const commitCandidate = (state, turnId, stepId, candidate) => append(state, { kind: "candidate", turnId, stepId, candidate });
+export const commitToolResults = (state, turnId, stepId, results) => append(state, { kind: "tool-results", turnId, stepId, results: Object.freeze([...results]) });
+export const commitFinal = (state, turnId, stepId, output) => append(state, { kind: "final", turnId, stepId, output });

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

@@ -0,0 +1,13 @@
+import type { InputCompletion, InputHandle, SessionEvent } from "../types/session.js";
+export declare class SubmissionStream implements InputHandle {
+    readonly inputId: string;
+    readonly completed: Promise<InputCompletion>;
+    private resolveCompletion;
+    private readonly events;
+    private readonly cleanups;
+    private done;
+    constructor(inputId: string);
+    emit(event: SessionEvent): void;
+    finish(status: InputCompletion["status"]): void;
+    onFinish(cleanup: () => void): void;
+}

package/dist/session/submission-stream.js

@@ -0,0 +1,36 @@
+export class SubmissionStream {
+    inputId;
+    completed;
+    resolveCompletion;
+    events = [];
+    cleanups = [];
+    done = false;
+    constructor(inputId) {
+        this.inputId = inputId;
+        this.completed = new Promise((resolve) => {
+            this.resolveCompletion = resolve;
+        });
+    }
+    emit(event) {
+        if (!this.done)
+            this.events.push(event);
+    }
+    finish(status) {
+        if (this.done)
+            return;
+        this.done = true;
+        while (this.cleanups.length)
+            this.cleanups.pop()();
+        this.resolveCompletion(Object.freeze({
+            inputId: this.inputId,
+            status,
+            events: Object.freeze([...this.events]),
+        }));
+    }
+    onFinish(cleanup) {
+        if (this.done)
+            cleanup();
+        else
+            this.cleanups.push(cleanup);
+    }
+}

package/dist/step/canonicalize.d.ts

@@ -0,0 +1,21 @@
+import type { ModelCandidate, ModelOutputBlock, ModelToolCall } from "../types/model.js";
+import type { JsonObject } from "../types/shared.js";
+export interface CanonicalCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: JsonObject;
+    readonly missingId: boolean;
+    readonly duplicateId?: string;
+}
+export declare function canonicalizeCalls(calls: readonly {
+    readonly id?: string;
+    readonly name?: string;
+    readonly args: JsonObject;
+}[]): readonly CanonicalCall[];
+export declare function callsFromCanonical(calls: readonly CanonicalCall[]): readonly ModelToolCall[];
+export declare function canonicalizeOutput(output: readonly ModelOutputBlock[]): {
+    readonly output: readonly ModelOutputBlock[];
+    readonly calls: readonly CanonicalCall[];
+};
+export declare function candidateFromCanonical(candidate: ModelCandidate, output: readonly ModelOutputBlock[]): ModelCandidate;
+export declare function identityKey(name: string, args: unknown): string;