@noetaris/harness 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -339,6 +339,22 @@ interface Observer {
      * `onObserverError` (hook name `'carry'`) and counts as `undefined`.
      */
     carry?: (ctx: RunContext) => Record<string, string> | undefined;
+    /**
+     * Called after a checkpoint was saved (`checkpoint: 'step'`): the session can now continue
+     * from `event.step` if this instance dies. Not called when a checkpoint was skipped or failed —
+     * those go to `onStoreError` with phase `'checkpoint'` (or `'claim'` when the run lost the
+     * session). Top-level runs only.
+     */
+    onCheckpoint?: (ctx: RunContext, event: CheckpointEvent) => void;
+}
+/** What {@link Observer.onCheckpoint} gets. */
+interface CheckpointEvent {
+    /** The step the session continues from. */
+    readonly step: string;
+    /** The version of the saved row. */
+    readonly version: number;
+    /** Time spent on the checkpoint: snapshot, save and lease extension. */
+    readonly durationMs: number;
 }
 /**
  * The telemetry a resource needs to attribute an `invoke()` call to the correct
@@ -485,6 +501,24 @@ interface Lease {
      */
     readonly token: unknown;
 }
+/**
+ * `'step'`: save the session after every finished top-level step, so a run whose instance dies
+ * continues from its last finished step. `'off'`: save only when a run settles.
+ */
+type CheckpointMode = 'off' | 'step';
+/** Options passed to {@link SessionStore.save}. */
+interface SaveOptions {
+    /**
+     * The lease the caller holds on the session. When given, a store that supports claims
+     * must check — atomically with the version check — that the session's current claim is
+     * the one this lease was issued for (by the store's own claim identity, e.g. the nonce in
+     * `lease.token`; never by comparing times). If it is not, write nothing and throw an
+     * `Error` whose `name` is `'LeaseLostError'`, whatever the version: this check takes
+     * precedence over the version check, because the framework treats a version conflict on a
+     * run's last save as a failed write and carries on.
+     */
+    readonly lease?: Lease;
+}
 /**
  * Operational metadata written by the framework into every {@link StoredRun}.
  *
@@ -534,8 +568,15 @@ interface SessionStore {
      *   record and `run.version === 0`), the write succeeds.
      * - Otherwise, another writer committed a newer version concurrently — the
      *   implementation must throw `ConcurrentModificationError`.
+     *
+     * The framework passes `options.lease` on every save it makes while holding a claim, and
+     * no `options` otherwise. A store that supports claims fences the write with it (see
+     * {@link SaveOptions.lease}), so an instance whose lease was taken over cannot overwrite
+     * the new owner's progress; the framework stops that run with `LeaseExpiredError`. A store
+     * without claims, or one that ignores `options`, keeps the version check only and gives no
+     * protection against such a stale owner.
      */
-    save(agentId: string, sessionId: string, run: StoredRun): Promise<void>;
+    save(agentId: string, sessionId: string, run: StoredRun, options?: SaveOptions): Promise<void>;
     /**
      * Return the full ordered run history for a session, oldest first.
      * Optional — omit if your store does not support history.
@@ -543,7 +584,8 @@ interface SessionStore {
     loadHistory?(agentId: string, sessionId: string): Promise<StoredRun[]>;
     /**
      * Fork the session at the state captured by `runId`, returning a new session ID
-     * whose initial state equals the forked run's `finalState`.
+     * whose initial state equals the forked run's `finalState`. When a run has several records,
+     * use its last one.
      * Optional — omit if your store does not support branching.
      *
      * Save the new session's version-0 record as a seed the next run continues: `phase: 'paused'`,
@@ -610,6 +652,9 @@ interface SessionStore {
  *   existed is still a valid `Cursor`, so old rows load and resume unchanged.
  * - `phase: 'completed'` — the loop exited normally; `signal` holds the exit
  *   signal (or is absent when the loop ended without emitting a signal).
+ * - `phase: 'running'` — a checkpoint, written after a finished step when checkpoints are on
+ *   (`checkpoint: 'step'`); `step` is the step to run next, always a plain step name, and there
+ *   is no `signal`. The run has not settled since: it is still running, or its instance died.
  */
 interface StoredRun {
     readonly agentId: string;
@@ -618,7 +663,7 @@ interface StoredRun {
     readonly version: number;
     readonly startedAt: string;
     readonly settledAt: string;
-    readonly phase: 'paused' | 'completed';
+    readonly phase: 'paused' | 'completed' | 'running';
     readonly initialState: Record<string, unknown>;
     readonly finalState: Record<string, unknown>;
     readonly signal?: string;
@@ -661,6 +706,9 @@ interface StoredRun {
  *   step that issued the interrupt. When the run paused inside a fork, `step` is
  *   the fork's own name (not the richer per-branch detail — see `pendingInterrupts`).
  * - `'completed'` — the last run exited the loop; `signal` is the exit signal.
+ * - `'running'` — the last run saved a checkpoint and has not settled since: it is still
+ *   running, or its instance died. Running the session again continues it from `step`
+ *   (another instance gets `SessionBusyError` while the owner's claim is alive).
  */
 type SessionPhase = {
     readonly phase: 'fresh';
@@ -677,13 +725,21 @@ type SessionPhase = {
      * caller discover and resolve each one — via `Agent.resume(response, sessionId, id)` —
      * independently; the session stays `'paused'` until every entry is resolved.
      */
-    readonly pendingInterrupts: readonly PendingInterrupt[];
+    readonly pendingInterrupts: readonly PendingInterrupt$1[];
 } | {
     readonly phase: 'completed';
     readonly signal?: string;
+} | {
+    readonly phase: 'running';
+    /** The step the session continues from. */
+    readonly step: string;
+    /** The `instanceId` of the instance that saved the checkpoint, when it had one. */
+    readonly instanceId?: string;
+    /** When the checkpoint was saved (ISO 8601). */
+    readonly checkpointedAt: string;
 };
 /** One outstanding `ctx.interrupt()` call awaiting a response. See {@link SessionPhase}. */
-interface PendingInterrupt {
+interface PendingInterrupt$1 {
     readonly interruptId: string;
     readonly prompt: unknown;
     /**
@@ -1061,6 +1117,169 @@ interface RunHandle extends PromiseLike<RunOutcome> {
     readonly currentStep: string | null;
 }
 
+/**
+ * A copy of a state (or update) object taken when a debug stop was made. Each top-level key is
+ * copied with `structuredClone`; a key whose value can't be cloned (a function, for example) keeps
+ * its reference and is listed in `shared`, so its value may have changed since.
+ */
+interface Snapshot {
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly shared: readonly string[];
+}
+/** A step that has settled, as a debug stop reports it: what `onStepSettled` knows, plus state. */
+interface SettledStep {
+    readonly name: string;
+    readonly outcome: StepSettledEvent['outcome'];
+    /** The step's return value, copied; absent when it did not return one (see {@link StepSettledEvent}). */
+    readonly update?: Snapshot;
+    readonly signal?: string;
+    readonly next: StepSettledNext;
+    readonly error?: Error;
+    /** The state just before this step ran. The state after it is the stop's own `state` (or `outcome.state`). */
+    readonly before: Snapshot;
+    readonly durationMs: number;
+    readonly fork?: StepSettledEvent['fork'];
+}
+/** A branch frame that ended, as a `branch-end` stop reports it. */
+interface EndedFrame {
+    readonly frame: readonly string[];
+    readonly outcome: 'done' | 'interrupt' | 'error' | 'stopped';
+    readonly last?: SettledStep;
+}
+/** An interrupt the paused run is waiting on, and the frame that raised it. */
+interface PendingInterrupt {
+    readonly interruptId: string;
+    readonly prompt: unknown;
+    readonly frame: readonly string[];
+}
+/**
+ * Where a debug session stopped. `frame` is the frame the stop belongs to: `[]` for the top-level run,
+ * the branch path for a fork branch.
+ * - `step`: held at a step boundary of `frame`, before `next` runs. `last` is the step that just settled
+ *   in that frame (absent on its first stop). `reason` says why it stopped here; `branch-end` means the
+ *   frame the command was driving ended (see `ended`) and focus moved here.
+ * - `interrupt`: the run paused on `ctx.interrupt()`; `pending` lists every interrupt it waits on
+ *   (depth-first, declaration order), the first one also in `interruptId` / `prompt` / `frame`.
+ *   Answer with {@link DebugSession.answer}.
+ * - `end`: the session is over — the run completed, paused on an error, or was stopped.
+ */
+type DebugStop = {
+    readonly kind: 'step';
+    readonly frame: readonly string[];
+    readonly reason: 'start' | 'step' | 'breakpoint' | 'resume' | 'fork-entry' | 'branch-end';
+    readonly runId: string;
+    readonly next: string;
+    readonly last?: SettledStep;
+    readonly state: Snapshot;
+    /** What a breakpoint condition threw, when that is why the session stopped here. */
+    readonly conditionError?: unknown;
+    /** With `reason: 'branch-end'`: the frame that ended. */
+    readonly ended?: EndedFrame;
+} | {
+    readonly kind: 'interrupt';
+    readonly frame: readonly string[];
+    readonly runId: string;
+    readonly last: SettledStep;
+    readonly interruptId: string;
+    readonly prompt: unknown;
+    readonly pending: readonly PendingInterrupt[];
+    readonly state: Snapshot;
+} | {
+    readonly kind: 'end';
+    readonly runId: string;
+    readonly last?: SettledStep;
+    readonly outcome: RunOutcome;
+};
+/** A frame of a debug session, as {@link DebugSession.frames} lists it. */
+interface DebugFrame {
+    readonly frame: readonly string[];
+    /** `in-fork`: waiting for a fork it started to join. `ended`: a branch that has finished (listed until the join). */
+    readonly status: 'held' | 'running' | 'in-fork' | 'ended';
+    /** The step it is held before, when `held`. */
+    readonly next?: string;
+}
+/** A breakpoint: stop before `step` runs, when `when` (if given) returns a truthy value. */
+interface DebugBreakpoint {
+    readonly step: string;
+    /** Gets the live state of the frame about to run the step, not a copy: it must not change it. */
+    readonly when?: (state: Readonly<Record<string, unknown>>) => unknown;
+}
+/** Thrown (or rejected) by a {@link DebugSession} command that can't run in the session's current state. */
+declare class DebugCommandError extends Error {
+    /**
+     * - `busy`: another command is still running
+     * - `not-held`: the focused frame is not held at a step stop (or, for `answer`, the session is not at
+     *   an interrupt stop; for `focus`, the frame is not held)
+     * - `not-a-fork`: `stepInto` where the next step is not a fork node
+     * - `reserved-key`: `setState` was given a framework key (`$…`)
+     * - `ended`: the session is over
+     */
+    readonly reason: 'busy' | 'not-held' | 'not-a-fork' | 'reserved-key' | 'ended';
+    /** The command that was refused. */
+    readonly command: string;
+    constructor(reason: DebugCommandError['reason'], command: string, detail?: string);
+}
+/**
+ * A run of an agent driven step by step, returned by `agent.debug()`. The session starts held before
+ * the first step; each command returns the next stop. It spans the whole run chain: a run that pauses
+ * on an interrupt is answered with {@link answer} and stepping continues in the resumed run.
+ *
+ * Fork branches are frames. Stepping into a fork ({@link stepInto}) holds every branch at its first
+ * step; only the focused frame runs, the others wait until focused or released with
+ * {@link continueAll}. When the frame a command drives ends, focus moves to the next held frame.
+ *
+ * One command at a time: `next()`, `continue()`, `stepInto()`, `continueAll()` and `answer()` reject
+ * with a `busy` {@link DebugCommandError} while another is running. `stop()` is valid at any time.
+ *
+ * While a frame is held, the session renews the run's claim (if the store can extend claims). Call
+ * `stop()`, or abort the `signal` resource, to end a session you no longer drive: a held session
+ * otherwise keeps the session fenced in this process.
+ */
+interface DebugSession {
+    readonly sessionId: string;
+    /** The id of the current run; changes when an interrupt is answered. */
+    readonly runId: string;
+    /**
+     * The focused frame's latest stop. At first, the start stop (`reason: 'start'`, `next` = the entry
+     * step). While no frame is held, a promise of the next stop.
+     */
+    readonly current: Promise<DebugStop>;
+    /** The final outcome of the last run, as `await handle` would give it. */
+    readonly done: Promise<RunOutcome>;
+    readonly breakpoints: ReadonlyArray<DebugBreakpoint>;
+    /** The frames of the current run, depth-first in declaration order. */
+    readonly frames: ReadonlyArray<DebugFrame>;
+    /** Focus a held frame; returns its current stop. */
+    focus(frame: readonly string[]): DebugStop;
+    /** Run exactly one step of the focused frame (a whole fork, stepping over it). Ignores breakpoints at its own boundary. */
+    next(): Promise<DebugStop>;
+    /** At a fork: start every branch and hold each at its first step; focus the first branch. */
+    stepInto(): Promise<DebugStop>;
+    /** Run the focused frame until a breakpoint hits or the frame ends; other frames stay held. */
+    continue(): Promise<DebugStop>;
+    /** Release every held frame; resolves with the first stop any frame makes. */
+    continueAll(): Promise<DebugStop>;
+    /** At an `interrupt` stop: answer it (by default the stop's own interrupt) and hold before the resumed run's first step. */
+    answer(response: unknown, interruptId?: string): Promise<DebugStop>;
+    /**
+     * While the focused frame is held at a `step` stop: set state keys of that frame, overwriting them as
+     * given (no reducers). Values are copied. In a branch the keys count as written by the branch, so the
+     * join keeps them (a key also written by a sibling then needs a reducer, as for any write). Reported to
+     * the observer as event `debug.setState` with `{ patch }` before the frame's next step.
+     */
+    setState(patch: Record<string, unknown>): Snapshot;
+    /** Stop before `step` when `when` returns a truthy value (always, without `when`). Replaces that step's breakpoint. */
+    setBreakpoint(step: string, when?: DebugBreakpoint['when']): void;
+    clearBreakpoint(step: string): void;
+    /**
+     * End the session. Held frames end (stopped) where they are; running steps are stopped like
+     * `handle.stop()` and their frames end at the next boundary. At an interrupt stop: the session ends
+     * and the interrupt stays pending as saved. Resolves with the `end` stop — the same one a pending
+     * command resolves with, and again on every later call.
+     */
+    stop(): Promise<DebugStop>;
+}
+
 /** Options passed to createAgent(). */
 interface AgentOptions {
     /**
@@ -1080,6 +1299,26 @@ interface AgentOptions {
      * `ttlMs` must be a finite number greater than 0; otherwise `createAgent` throws `InvalidClaimOptionsError`.
      */
     readonly claimOptions?: ClaimOptions;
+    /**
+     * Observer for every run of this agent: `agent.run()`, `handle.resume()` and `agent.resume()`.
+     * A per-call `observer` is composed on top of it (this one first: its hooks fire first, its `wrap`
+     * is outermost, and on a shared `carry` key the per-call value wins); it never replaces it. The
+     * same object passed per call is used once. One object serves every run, concurrent runs included.
+     * Must be an object; otherwise `createAgent` throws `InvalidAgentOptionError`.
+     */
+    readonly observer?: Observer;
+    /**
+     * Default sink for observer-hook errors, used when a call passes no `onObserverError`.
+     * Must be a function; otherwise `createAgent` throws `InvalidAgentOptionError`.
+     */
+    readonly onObserverError?: ObserverErrorSink;
+    /**
+     * Save the session after every finished top-level step, so a run whose instance dies continues
+     * from its last finished step instead of re-running the turn: `'step'`. `'off'` (the default)
+     * saves only when a run settles. Ignored without a session store. A per-call `checkpoint`
+     * resource overrides it. Any other value makes `createAgent` throw `InvalidAgentOptionError`.
+     */
+    readonly checkpoint?: CheckpointMode;
 }
 interface Agent {
     /** The agent's unique identifier, as provided to createAgent(). */
@@ -1101,7 +1340,8 @@ interface Agent {
      * Returns a RunHandle synchronously; the execution promise performs the resume.
      *
      * The optional fourth argument `resources` accepts:
-     * - `observer?: Observer` — structured telemetry for the resumed run (see Observability)
+     * - `observer?: Observer` — structured telemetry for the resumed run, composed on top of `AgentOptions.observer` (see Observability)
+     * - `onObserverError?: ObserverErrorSink` — sink for observer-hook errors; falls back to `AgentOptions.onObserverError`
      * - `parentRunId?: string` — the caller's run id, as for `run()`; set on this resumed run's
      *   `RunContext` only (a later `handle.resume()` on the returned handle does not inherit it)
      * - `events?.onStoreError?` — raw store-error callback (unchanged from prior shape)
@@ -1110,18 +1350,53 @@ interface Agent {
      *   on the returned handle reuses it
      */
     resume(response: unknown, sessionId: string, interruptId: string, resources?: Record<string, unknown>): RunHandle;
+    /**
+     * Start a run held before its first step, to drive it step by step. Takes the same `initialState`
+     * and `resources` as {@link run} and returns a {@link DebugSession}, whose `current` resolves to
+     * the start stop. While the session lasts, `run()`, `resume()` and `debug()` on its session throw
+     * `SessionInDebugError` (in this process only). The `signal` resource, when given, ends the session
+     * when aborted, in any state.
+     *
+     * Step durations exclude the time held; a run's duration (`onRunEnd`) includes it.
+     */
+    debug(initialState: Record<string, unknown>, resources: Record<string, unknown>): DebugSession;
     /**
      * Query the session store for the current phase of a session.
      */
     status(sessionId: string): Promise<SessionPhase>;
 }
-/** Thrown by `agent.run()` when `sessionId` or `requestId` is given but is not a non-empty string. */
+/** Thrown by {@link createAgent} when `agentOptions.claimOptions.ttlMs` is not a finite number greater than 0. */
+declare class InvalidClaimOptionsError extends Error {
+    /** The rejected `ttlMs` value, as given. */
+    readonly ttlMs: unknown;
+    constructor(ttlMs: unknown);
+}
+declare const AGENT_OPTION_EXPECTED: {
+    readonly observer: "an object";
+    readonly onObserverError: "a function";
+    readonly checkpoint: "'off' or 'step'";
+};
+/**
+ * Thrown by {@link createAgent} when `agentOptions.observer` is not an object, `agentOptions.onObserverError`
+ * is not a function, or `agentOptions.checkpoint` is not `'off'` or `'step'`.
+ */
+declare class InvalidAgentOptionError extends Error {
+    /** The option that was rejected. */
+    readonly key: keyof typeof AGENT_OPTION_EXPECTED;
+    /** The rejected value, as given. */
+    readonly value: unknown;
+    constructor(key: keyof typeof AGENT_OPTION_EXPECTED, value: unknown);
+}
+/**
+ * Thrown by `agent.run()` when `sessionId` or `requestId` is given but is not a non-empty string, and by
+ * `agent.run()`, `agent.debug()` and `agent.resume()` when `checkpoint` is given but is not `'off'` or `'step'`.
+ */
 declare class InvalidRunResourceError extends Error {
     /** The resource key that was rejected. */
-    readonly key: 'sessionId' | 'requestId';
+    readonly key: 'sessionId' | 'requestId' | 'checkpoint';
     /** The rejected value, as given. */
     readonly value: unknown;
-    constructor(key: 'sessionId' | 'requestId', value: unknown);
+    constructor(key: 'sessionId' | 'requestId' | 'checkpoint', value: unknown);
 }
 /**
  * Instantiate an agent from a fully-configured {@link Harness}.
@@ -1160,6 +1435,17 @@ declare class SessionInFlightError extends Error {
     readonly sessionId: string;
     constructor(sessionId: string);
 }
+/**
+ * Thrown by {@link Agent.run}, {@link Agent.resume} or {@link Agent.debug} when the given session is
+ * being debugged by a debug session of the same agent instance. The fence is in-process only.
+ *
+ * Stop the debug session (`stop()`) or let it end before running the session normally.
+ */
+declare class SessionInDebugError extends Error {
+    /** The session being debugged. */
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
 /**
  * Thrown by {@link Agent.run} when the session is paused on an unanswered
  * interrupt.  Call {@link Agent.resume} (or `handle.resume()`) instead.
@@ -1205,7 +1491,13 @@ declare class SessionBusyError extends Error {
 declare class LeaseExpiredError extends Error {
     /** The session whose lease expired. */
     readonly sessionId: string;
-    constructor(sessionId: string);
+    /**
+     * The store's error when the store rejected a save: its `LeaseLostError` (the session's
+     * claim is no longer this run's lease), or, on a checkpoint, its `ConcurrentModificationError`
+     * (another writer saved first). Absent when the expiry was seen on the local clock.
+     */
+    readonly cause?: unknown;
+    constructor(sessionId: string, cause?: unknown);
 }
 
 /**
@@ -1219,4 +1511,4 @@ declare class NoInterruptError extends Error {
     constructor();
 }
 
-export { type Agent, type AgentOptions, type BranchCursor, type BranchDef, type ClaimOptions, type Cursor, type DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, InvalidRunResourceError, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunCarrier, type RunContext, type RunFn, type RunRef, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepSettledEvent, type StepSettledNext, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, type WrapScope, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };
+export { type Agent, type AgentOptions, type BranchCursor, type BranchDef, type CheckpointEvent, type CheckpointMode, type ClaimOptions, type Cursor, type DebugBreakpoint, DebugCommandError, type DebugFrame, type DebugSession, type DebugStop, type DeepWithMarkers, type EndedFrame, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, InvalidAgentOptionError, InvalidClaimOptionsError, InvalidRunResourceError, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, type PendingInterrupt, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunCarrier, type RunContext, type RunFn, type RunRef, type RuntimeMarker, type SaveOptions, SessionBusyError, SessionInDebugError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SettledStep, type SignalTransition, type Snapshot, type StateFromSchema, type StepContext, type StepDef, type StepSettledEvent, type StepSettledNext, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, type WrapScope, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };