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

package/dist/session/capability-state.js

@@ -0,0 +1,67 @@
+import { HarnessError } from "../errors.js";
+/** Owns declared, process-local state for exactly one Session. */
+export class CapabilityStateRegistry {
+    session;
+    observe;
+    #entries = new Map();
+    #controller = new AbortController();
+    #shutdown;
+    constructor(middleware, session, observe) {
+        this.session = session;
+        this.observe = observe;
+        for (const middlewareEntry of middleware) {
+            if (middlewareEntry.state)
+                this.#entries.set(middlewareEntry.id, {
+                    id: middlewareEntry.id,
+                    state: middlewareEntry.state,
+                });
+        }
+    }
+    has(id) {
+        return this.#entries.has(id);
+    }
+    get(id) {
+        const entry = this.#entries.get(id);
+        if (!entry)
+            return Promise.reject(new HarnessError("capability.state.undeclared", `Capability '${id}' did not declare session state`));
+        if (!entry.promise) {
+            entry.promise = Promise.resolve()
+                .then(() => entry.state.create(this.session, this.#controller.signal))
+                .then((value) => {
+                entry.value = value;
+                entry.created = true;
+                return value;
+            }, (cause) => {
+                throw new HarnessError("capability.state.create-failed", `Capability '${id}' failed to create session state`, { cause });
+            });
+        }
+        return entry.promise;
+    }
+    abort(reason) {
+        this.#controller.abort(reason);
+    }
+    shutdown(reason) {
+        if (this.#shutdown)
+            return this.#shutdown;
+        this.abort(reason);
+        this.#shutdown = (async () => {
+            const created = [...this.#entries.values()].filter((entry) => entry.promise);
+            await Promise.allSettled(created.map((entry) => entry.promise));
+            for (const entry of [...created].reverse()) {
+                if (!entry.created || !entry.state.dispose)
+                    continue;
+                try {
+                    await entry.state.dispose(entry.value);
+                }
+                catch (error) {
+                    this.observe({
+                        type: "capability.state.dispose.failed",
+                        capabilityId: entry.id,
+                        attributes: { message: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+            }
+        })();
+        return this.#shutdown;
+    }
+}

package/dist/session/input-queue.d.ts

@@ -1,11 +1,19 @@
 import type { InputEvent, InputOptions } from "../types/session.js";
 import { SubmissionStream } from "./submission-stream.js";
+export type WorkEvent = InputEvent | {
+    readonly kind: "continue";
+};
 export interface QueuedInput {
-    readonly event: InputEvent;
+    readonly event: WorkEvent;
     readonly options?: InputOptions;
     readonly stream: SubmissionStream;
     cancelled: boolean;
 }
+export type QueuedInterrupt = Omit<QueuedInput, "event"> & {
+    readonly event: Extract<InputEvent, {
+        kind: "interrupt";
+    }>;
+};
 export interface QueueAbortHandlers {
     readonly isActive: () => boolean;
     readonly abortActive: (reason: unknown) => void;
@@ -15,13 +23,14 @@ export declare function isInteractionReply(event: InputEvent): event is Extract<
     kind: "approve" | "respond";
 }>;
 export declare function snapshotInput(event: InputEvent): InputEvent;
+export declare function snapshotWork(event: WorkEvent): WorkEvent;
 /** Serializes ordinary input while allowing a matching interaction reply to resume immediately. */
 export declare class InputQueue {
     private readonly values;
     get size(): number;
     add(input: QueuedInput, priority?: boolean): void;
     take(waitingForInteraction: boolean): QueuedInput | undefined;
-    takeInterrupts(): QueuedInput[];
+    takeInterrupts(): QueuedInterrupt[];
     remove(input: QueuedInput): boolean;
     drain(): readonly QueuedInput[];
 }

package/dist/session/input-queue.js

@@ -18,6 +18,9 @@ export function snapshotInput(event) {
             return Object.freeze({ ...event, value: copyJson(event.value) });
     }
 }
+export function snapshotWork(event) {
+    return event.kind === "continue" ? Object.freeze({ kind: "continue" }) : snapshotInput(event);
+}
 /** Serializes ordinary input while allowing a matching interaction reply to resume immediately. */
 export class InputQueue {
     values = [];
@@ -32,7 +35,8 @@ export class InputQueue {
     }
     take(waitingForInteraction) {
         const next = this.values[0];
-        if (!next || (waitingForInteraction && !isInteractionReply(next.event)))
+        if (!next ||
+            (waitingForInteraction && (next.event.kind === "continue" || !isInteractionReply(next.event))))
             return undefined;
         return this.values.shift();
     }

package/dist/session/record.d.ts

@@ -0,0 +1,11 @@
+import type { ActiveExecutionRecord, SessionRecord, SessionSnapshot } from "../types/session.js";
+import type { JsonObject } from "../types/shared.js";
+export declare function sessionRecord(input: {
+    readonly state: SessionSnapshot;
+    readonly transition: SessionRecord["transition"];
+    readonly session: Readonly<{
+        readonly userId?: string;
+        readonly context?: JsonObject;
+    }>;
+    readonly active?: ActiveExecutionRecord;
+}): SessionRecord;

package/dist/session/record.js

@@ -0,0 +1,26 @@
+import { copyJson } from "../utils/immutable.js";
+export function sessionRecord(input) {
+    const value = {
+        version: 1,
+        revision: input.state.revision,
+        transition: input.transition,
+        session: {
+            id: input.state.id,
+            ...(input.session.userId === undefined ? {} : { userId: input.session.userId }),
+            ...(input.session.context === undefined ? {} : { context: copyJson(input.session.context) }),
+            turnCount: input.state.turnCount,
+            status: input.state.status,
+        },
+        transcript: copyJson(input.state.transcript),
+        ...(input.active === undefined ? {} : { active: copyJson(input.active) }),
+    };
+    return deepFreeze(value);
+}
+function deepFreeze(value, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    return Object.freeze(value);
+}

package/dist/session/scheduler.d.ts

@@ -1,8 +1,9 @@
-import type { InputEvent, InputOptions, SessionSnapshot } from "../types/session.js";
+import type { InputEvent, InputOptions, SessionRecorder, 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";
+import type { NormalizedSessionSeed } from "./seed.js";
 /** Coordinates one active turn at a time; TurnRunner owns the turn's internal state machine. */
 export declare class SessionScheduler {
     readonly id: string;
@@ -16,18 +17,29 @@ export declare class SessionScheduler {
     private pending?;
     private inFlightPlan?;
     private running;
+    private stopping;
     private stopped;
+    private suspended;
     private generation;
     private stopPromise?;
+    private recordFailure?;
     private readonly observers;
     private readonly turns;
+    private readonly states;
     constructor(id: string, agent: LoopAgent, session: Readonly<{
         readonly userId?: string;
         readonly context?: import("../types/shared.js").JsonObject;
-    }>);
+    }>, options?: {
+        readonly seed?: NormalizedSessionSeed;
+        readonly recorder?: SessionRecorder;
+    });
+    private readonly session;
+    private readonly recorder?;
     get snapshot(): SessionSnapshot;
     observe(listener: Observer): () => void;
     submit(event: InputEvent, options?: InputOptions): SubmissionStream;
+    continue(options?: InputOptions): SubmissionStream;
+    private submitWork;
     stop(reason?: string): Promise<void>;
     private enqueueReply;
     private enqueueOrdinaryInput;
@@ -40,9 +52,11 @@ export declare class SessionScheduler {
     private run;
     private resumeTurn;
     private applyTurnOutcome;
-    private beginStop;
     private emitObserve;
     private commitCancelledPlan;
     private claimInterrupts;
+    private commit;
+    private assertRecordable;
+    private failRecording;
     private assertCurrent;
 }

package/dist/session/scheduler.js

@@ -1,12 +1,14 @@
 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 { InputQueue, isInteractionReply, snapshotWork, 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 { commitInput, commitToolResults, initialState, withStatus } from "./state.js";
 import {} from "../build/agent.js";
 import { TurnRunner } from "../turn/runner.js";
+import { sessionRecord } from "./record.js";
+import { CapabilityStateRegistry } from "./capability-state.js";
 /** Coordinates one active turn at a time; TurnRunner owns the turn's internal state machine. */
 export class SessionScheduler {
     id;
@@ -20,16 +22,38 @@ export class SessionScheduler {
     pending;
     inFlightPlan;
     running = false;
+    stopping = false;
     stopped = false;
+    suspended = false;
     generation = 0;
     stopPromise;
+    recordFailure;
     observers = createObserverRegistry();
     turns;
-    constructor(id, agent, session) {
+    states;
+    constructor(id, agent, session, options = {}) {
         this.id = id;
-        this.snapshotValue = initialState(id);
+        this.snapshotValue = initialState(id, options.seed);
         this.turns = new TurnRunner(agent, id, session);
+        this.session = session;
+        this.recorder = options.recorder;
+        this.states = new CapabilityStateRegistry(agent.middleware, Object.freeze({ id, ...session }), (event) => this.emitObserve(event));
+        if (options.seed) {
+            const event = Object.freeze({
+                type: "session.seeded",
+                revision: options.seed.revision,
+                transcriptEntries: options.seed.transcript.length,
+            });
+            // Construction precedes public observer registration. Defer this live-only fact
+            // by one microtask so callers can subscribe immediately after run({ seed }).
+            queueMicrotask(() => {
+                if (!this.stopped)
+                    this.emitObserve(event);
+            });
+        }
     }
+    session;
+    recorder;
     get snapshot() {
         return this.snapshotValue;
     }
@@ -39,9 +63,15 @@ export class SessionScheduler {
         return this.observers.observe(listener);
     }
     submit(event, options) {
+        return this.submitWork(event, options);
+    }
+    continue(options) {
+        return this.submitWork({ kind: "continue" }, options);
+    }
+    submitWork(event, options) {
         const stream = new SubmissionStream(createId("input"));
         const submission = {
-            event: snapshotInput(event),
+            event: snapshotWork(event),
             options,
             stream,
             cancelled: false,
@@ -50,7 +80,7 @@ export class SessionScheduler {
             return this.finishStopped(stream);
         if (options?.signal?.aborted)
             return this.finishCancelled(stream, cancellationMessage(options.signal));
-        if (isInteractionReply(event)) {
+        if (event.kind !== "continue" && isInteractionReply(event)) {
             if (!this.enqueueReply(submission, event))
                 return stream;
         }
@@ -68,11 +98,39 @@ export class SessionScheduler {
     stop(reason = "Session stopped") {
         if (this.stopPromise)
             return this.stopPromise;
-        this.beginStop(reason);
+        this.stopping = true;
+        this.generation += 1;
+        const stopError = new HarnessError("session.stale-result", reason);
+        this.sessionController.abort(stopError);
+        this.activeController?.abort(stopError);
+        this.states.abort(stopError);
         const activeWork = this.activeWork;
+        const activeStream = this.activeSubmission?.stream;
+        const pending = this.pending;
+        this.pending = undefined;
         this.stopPromise = (async () => {
             if (activeWork)
                 await activeWork;
+            if (pending && !this.recordFailure)
+                await this.commitCancelledPlan(pending, reason);
+            const stopped = await this.commit(withStatus(this.snapshotValue, "stopped"), "stopped");
+            this.snapshotValue = stopped;
+            this.stopped = true;
+            this.stopping = false;
+            const event = { type: "session.stopped", sessionId: this.id };
+            this.events.emit(event);
+            this.events.finish();
+            if (activeStream) {
+                activeStream.emit(event);
+                activeStream.finish("stopped");
+            }
+            for (const item of this.queue.drain()) {
+                item.stream.emit(event);
+                item.stream.finish("stopped");
+            }
+            this.emitObserve({ type: "session.stopped", reason });
+            await this.states.shutdown(stopError);
+            this.observers.clear();
         })();
         return this.stopPromise;
     }
@@ -147,7 +205,7 @@ export class SessionScheduler {
         this.events.emit(event);
     }
     pump() {
-        if (this.running || this.stopped)
+        if (this.running || this.stopping || this.stopped || this.suspended)
             return;
         const next = this.queue.take(Boolean(this.pending));
         if (!next)
@@ -172,8 +230,6 @@ export class SessionScheduler {
             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;
@@ -183,27 +239,40 @@ export class SessionScheduler {
         try {
             const context = {
                 signal,
+                states: this.states,
                 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;
-                },
+                commit: (state, transition, active) => this.commit(state, transition, active).then((committed) => {
+                    if (transition === "model-requested" && submission.event.kind === "continue")
+                        this.emitObserve({ type: "session.continued", inputId: submission.stream.inputId });
+                    return committed;
+                }),
                 onConversation: (event) => this.publish(submission.stream, event),
-                claimInterrupts: (turnId) => this.claimInterrupts(turnId),
+                claimInterrupts: (state, turnId) => this.claimInterrupts(state, turnId),
             };
             const outcome = this.pending
                 ? await this.resumeTurn(submission, context)
-                : await this.turns.start(this.snapshotValue, submission.event, context);
+                : submission.event.kind === "continue"
+                    ? await this.turns.continue(this.snapshotValue, 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));
+            if (this.inFlightPlan && !this.recordFailure) {
+                try {
+                    await this.commitCancelledPlan(this.inFlightPlan, message(error));
+                }
+                catch {
+                    if (this.recordFailure)
+                        return;
+                }
                 this.inFlightPlan = undefined;
             }
+            if (this.recordFailure || this.stopping)
+                return;
             if (this.stopped)
                 this.finishStopped(submission.stream);
             else {
@@ -216,13 +285,14 @@ export class SessionScheduler {
     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);
+        if (submission.event.kind === "continue")
+            throw new HarnessError("interaction.uncorrelated-resume", "Continue cannot answer an interaction");
+        return this.turns.resume(withStatus(this.snapshotValue, "running"), pending, submission.event, context);
     }
     applyTurnOutcome(stream, outcome) {
         switch (outcome.kind) {
             case "final":
-                this.snapshotValue = withStatus(outcome.state, "idle");
+                this.snapshotValue = outcome.state;
                 this.publish(stream, { type: "final", output: outcome.output, turnId: outcome.turnId });
                 this.emitObserve({
                     type: "turn.completed",
@@ -235,7 +305,7 @@ export class SessionScheduler {
                 return;
             case "interaction-required":
                 this.pending = outcome.pending;
-                this.snapshotValue = withStatus(outcome.state, "waiting", outcome.interaction);
+                this.snapshotValue = outcome.state;
                 this.emitObserve({
                     type: "interaction.required",
                     turnId: outcome.pending.turnId,
@@ -249,9 +319,7 @@ export class SessionScheduler {
                     ...(outcome.pending.plan.interactionToolName === undefined
                         ? {}
                         : { toolName: outcome.pending.plan.interactionToolName }),
-                    ...(outcome.pending.plan.interactionPhase === undefined
-                        ? {}
-                        : { phase: outcome.pending.plan.interactionPhase }),
+                    phase: "interaction",
                     attributes: {
                         prompt: outcome.interaction.prompt,
                         ...(outcome.interaction.metadata === undefined
@@ -266,6 +334,25 @@ export class SessionScheduler {
                 });
                 stream.finish("waiting");
                 return;
+            case "deferred":
+                this.suspended = true;
+                this.snapshotValue = outcome.state;
+                if (outcome.active.kind === "model")
+                    this.emitObserve({
+                        type: "model.deferred",
+                        turnId: outcome.turnId,
+                        stepId: outcome.stepId,
+                        inputId: stream.inputId,
+                        invocationId: outcome.active.invocationId,
+                        attributes: outcome.active.token === undefined ? {} : { token: outcome.active.token },
+                    });
+                this.publish(stream, {
+                    type: "execution.deferred",
+                    active: outcome.active,
+                    turnId: outcome.turnId,
+                });
+                stream.finish("waiting");
+                return;
             case "tripwire":
                 this.snapshotValue = outcome.state;
                 this.publish(stream, {
@@ -283,40 +370,24 @@ export class SessionScheduler {
                     attributes: { message: outcome.tripwire.message },
                 });
                 if (outcome.tripwire.scope === "session")
-                    this.beginStop("Session policy tripwire");
+                    void this.stop("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));
+    async commitCancelledPlan(pending, reason) {
+        this.snapshotValue = await this.commit(commitToolResults(this.snapshotValue, pending.turnId, pending.stepId, pending.plan.cancelledResults(reason)), "tool-results");
     }
-    claimInterrupts(turnId) {
+    async claimInterrupts(state, turnId) {
         const claimed = this.queue.takeInterrupts();
         const events = [];
+        let nextState = state;
         for (const item of claimed) {
+            nextState = await this.commit(commitInput(nextState, turnId, item.event), "input");
             const conversation = Object.freeze({
                 type: "input",
                 event: item.event,
@@ -328,10 +399,72 @@ export class SessionScheduler {
             item.stream.finish("completed");
             events.push(item.event);
         }
-        return Object.freeze(events);
+        return Object.freeze({ state: nextState, arrivals: Object.freeze(events) });
+    }
+    async commit(state, transition, active) {
+        this.assertRecordable();
+        const revision = this.snapshotValue.revision + 1;
+        const { active: _oldActive, ...rest } = state;
+        const next = Object.freeze({
+            ...rest,
+            revision,
+            ...(state.pendingInteraction === undefined
+                ? {}
+                : { pendingInteraction: state.pendingInteraction }),
+            ...(active === undefined ? {} : { active }),
+        });
+        if (this.recorder) {
+            const value = sessionRecord({ state: next, transition, session: this.session, active });
+            try {
+                await this.recorder.record(value);
+            }
+            catch (cause) {
+                const error = new HarnessError("session.record-failed", "Session recorder failed", {
+                    cause,
+                });
+                this.failRecording(error);
+                throw error;
+            }
+        }
+        this.snapshotValue = next;
+        return next;
+    }
+    assertRecordable() {
+        if (this.recordFailure)
+            throw this.recordFailure;
+        if (this.stopped && !this.stopping)
+            throw new HarnessError("session.stale-result", "Stopped Session cannot record state");
+    }
+    failRecording(error) {
+        if (this.recordFailure)
+            return;
+        this.recordFailure = error;
+        this.stopping = false;
+        this.stopped = true;
+        this.generation += 1;
+        this.sessionController.abort(error);
+        this.activeController?.abort(error);
+        void this.states.shutdown(error);
+        this.pending = undefined;
+        this.inFlightPlan = undefined;
+        this.snapshotValue = withStatus(this.snapshotValue, "stopped");
+        this.emitObserve({
+            type: "session.record.failed",
+            code: error.code,
+            attributes: { message: error.message },
+        });
+        const event = { type: "session.stopped", sessionId: this.id };
+        this.events.emit(event);
+        this.events.finish();
+        this.activeSubmission?.stream.emit(event);
+        this.activeSubmission?.stream.fail(error);
+        for (const item of this.queue.drain()) {
+            item.stream.emit(event);
+            item.stream.finish("stopped");
+        }
     }
     assertCurrent(generation, signal) {
-        // An abort-ignoring adapter may resolve late; its state must never re-enter this Session.
+        // An abort-ignoring model or tool may resolve late; it 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"));

package/dist/session/seed.d.ts

@@ -0,0 +1,10 @@
+import type { SessionSeed, TranscriptEntry } from "../types/session.js";
+export interface NormalizedSessionSeed {
+    readonly id?: string;
+    readonly userId?: string;
+    readonly context?: import("../types/shared.js").JsonObject;
+    readonly turnCount: number;
+    readonly revision: number;
+    readonly transcript: readonly TranscriptEntry[];
+}
+export declare function normalizeSessionSeed(seed: SessionSeed): NormalizedSessionSeed;