@noetaris/harness 0.10.0 → 0.12.0

package/README.md

@@ -140,6 +140,53 @@ h.store({
 
 The framework injects `ctx.sessionId` automatically on every run — no declaration in `Ctx` needed.
 
+### Turns and `requestId`
+
+With a session store, a session is a conversation thread. Each `agent.run()` on it is one
+**turn** (a request). A turn may span several runs — `run()`, then a `resume()` for each
+interrupt — and every run of a turn is saved with the turn's `requestId`.
+
+```ts
+// one turn per user message, on one thread
+await agent.run({ messages: [msg1] }, { sessionId: 'chat-1', requestId: 'msg-1' })
+await agent.run({ messages: [msg2] }, { sessionId: 'chat-1', requestId: 'msg-2' })
+```
+
+A new turn continues from the state the last turn left: each input field is merged with its
+`reduce` (or replaced when it has none), and the run starts again from the entry step.
+`$error`, `$interrupt` and `$interruptResponses` start fresh for each new turn.
+
+`requestId` is optional. It is the turn's idempotency key: a call with a `requestId` the
+session already ran does **not** run it again. What `agent.run(input, { sessionId, requestId })`
+does depends on the session's latest run:
+
+| Latest run | No `requestId`, or a new one | The latest run's `requestId` (a retry) |
+|---|---|---|
+| none | runs from the entry step | – |
+| completed | a new turn | returns its outcome, runs nothing |
+| paused on an interrupt | resolves `$error` with `SessionPendingInterruptError` | returns its outcome (`signal: '$interrupt'`), runs nothing |
+| paused by a stop or an unhandled error | merges the input and continues from where it paused | continues from where it paused, **without** merging the input again |
+
+A retry of an earlier request (not the latest) is found with the store's optional
+`findRequest` and its outcome is returned; it never runs again, since later turns have
+moved on from it. A store without `findRequest` only recognises the latest run's
+`requestId`, so a late retry of an earlier request runs as a new turn.
+
+Notes:
+- A retry returns the request's **current** outcome, not its first response: if the turn
+  paused and was then resumed to completion, the retry returns the completed outcome. A
+  retry that returns `signal: '$interrupt'` can be resumed from its handle.
+- A returned (not re-run) outcome fires no observer events and saves nothing; its
+  `handle.runId` has no stored run and no trace.
+- Without a `requestId`, every call is a new turn. For a session that serves one request,
+  pass `requestId: sessionId` to get "run once, then return the result".
+- Duplicate calls at the same time are safe only with a store that supports claims: the
+  second call resolves `$error` with `SessionBusyError` and its retry then returns the
+  outcome. Without claims, both calls may run.
+- Without a session store, `requestId` is ignored.
+- `sessionId` and `requestId` must be non-empty strings when given; otherwise `agent.run()`
+  throws `InvalidRunResourceError`.
+
 ### Interrupts
 
 A run can be stopped or resumed:
@@ -252,14 +299,99 @@ h.loop(l =>
 If a fork fails fast while a sub agent is paused, that sub agent's own session stays
 paused in its store — clean it up or reuse it the next time the step runs.
 
+### Debugging a run
+
+`agent.debug(initialState, resources)` starts a run held before its first step and returns a
+`DebugSession`. Each command runs part of the run and resolves with the next **stop**: where the
+run is held, the step that just settled, and a copy of the state. It takes the same arguments as
+`agent.run()` and drives the whole run chain — an interrupt is answered inside the session.
+
+```typescript
+const dbg = agent.debug({}, { sessionId: 's1' })
+
+let stop = await dbg.current          // held before the first step: kind 'step', reason 'start'
+stop = await dbg.next()               // run one step; stop.last is the step that settled
+if (stop.kind === 'step') console.log(stop.last?.name, stop.last?.update?.values)
+
+dbg.setBreakpoint('review', (state) => (state.score as number) < 0.5)
+stop = await dbg.continue()           // runs until a breakpoint, an interrupt or the end
+
+if (stop.kind === 'step') dbg.setState({ score: 0.9 })        // edit state before 'review' runs
+stop = await dbg.continue()
+if (stop.kind === 'interrupt') stop = await dbg.answer(true)  // resume; held before the re-run
+
+stop = await dbg.continue()           // { kind: 'end', outcome: { state, signal } }
+```
+
+The session is local to this process. While it lasts, `run()`, `resume()` and `debug()` on its
+session throw `SessionInDebugError` here; see [LIMITATIONS.md](./LIMITATIONS.md) for other processes.
+
+**Stops** (`DebugStop`):
+
+| `kind` | Fields | When |
+|---|---|---|
+| `step` | `reason`, `next` (the step about to run), `last` (the step that just settled: `name`, `outcome`, `update`, `signal`, `next`, `error`, `before`), `state`, `frame` | held at a step boundary. `reason` is `start`, `step`, `breakpoint`, `resume` (after `answer`), `fork-entry` or `branch-end` |
+| `interrupt` | `interruptId`, `prompt`, `pending` (every interrupt the run waits on), `last`, `state`, `frame` | a step called `ctx.interrupt()` |
+| `end` | `outcome` (`{ state, signal }`), `last` | the run completed, paused on an error, or was stopped |
+
+`state`, `last.before` and `last.update` are `Snapshot`s: `{ values, shared }`. Each top-level key
+is copied with `structuredClone`; a key that can't be cloned (a function, say) keeps its reference
+and is listed in `shared`.
+
+**Commands** (`DebugSession`):
+
+| Command | Does |
+|---|---|
+| `current` | promise of the latest stop (the start stop at first) |
+| `next()` | run exactly one step (a fork counts as one step) |
+| `continue()` | run until a breakpoint hits, an interrupt, or the end |
+| `setBreakpoint(step, when?)`, `clearBreakpoint(step)`, `breakpoints` | stop before `step` when `when(state)` is truthy (always without `when`); one breakpoint per step |
+| `setState(patch)` | while held at a `step` stop: overwrite keys before the next step (no reducers; values are copied; `$` keys are refused). Observers get event `debug.setState` with `{ patch }` |
+| `answer(response, interruptId?)` | at an `interrupt` stop: resume through the normal resume path and hold before the resumed step |
+| `stop()` | end the session at any time; resolves with the `end` stop. At an interrupt stop the interrupt stays pending as saved |
+| `done` | promise of the last run's outcome, as `await handle` gives it |
+
+One command at a time: a second `next()`, `continue()` or `answer()` while one runs rejects with
+`DebugCommandError` (`reason: 'busy'`). Other reasons: `not-held`, `not-a-fork`, `reserved-key`,
+`ended`.
+
+While the run is held, the session renews its claim on the session store (when the store supports
+claims), so the lease doesn't expire during a pause. Aborting the `signal` resource ends the
+session in any state; so does `stop()`. Step durations leave out the time held.
+
+#### Fork branches
+
+`next()` steps over a fork. To step inside it, call `stepInto()` when the next step is a fork:
+every branch starts and is held at its first step, and the first branch is focused. Branches are
+**frames**, named by their branch path (`[]` is the top level).
+
+```typescript
+stop = await dbg.stepInto()           // { frame: ['x'], reason: 'fork-entry', next: 'sx' }
+dbg.frames                            // [{ frame: [], status: 'in-fork' }, { frame: ['x'], status: 'held' }, …]
+stop = dbg.focus(['y'])               // switch to another held branch
+dbg.setState({ note: 'edited in y' }) // counts as written by branch y, so the join keeps it
+stop = await dbg.continueAll()        // release every branch; resolves with the first stop any frame makes
+```
+
+`next()` and `continue()` drive only the focused frame; other branches wait. When the driven frame
+ends, focus moves to the next held frame (`reason: 'branch-end'`, with `ended`). Breakpoints hit in
+any frame. If a branch fails and the fork fails fast, held siblings are released and end.
+
 ### Observers
 
 An `Observer` receives telemetry hooks for a run. Pass it as `observer` in the resources
-of `agent.run()` or `agent.resume()`. Combine several with `composeObservers([a, b])`;
+of `agent.run()` or `agent.resume()`, or once for every run of an agent in
+`createAgent(id, h, slots, { observer })`. Combine several with `composeObservers([a, b])`;
 a hook that throws is reported to `onObserverError` (or `console.error`) and never stops
 the run. The observer that LLM adapters call is isolated the same way, so an observer that
 throws on an adapter event never fails a step. Every hook is optional.
 
+An agent's observer serves `agent.run()`, `handle.resume()` and `agent.resume()`. A per-call
+`observer` is composed on top of it, never replacing it: the agent's hooks fire first, its `wrap` is
+outermost, and on a shared `carry` key the per-call value wins. Passing the agent's own observer per
+call uses it once. Hook errors go to the per-call `onObserverError`, else the agent's
+`onObserverError` option, else `console.error`.
+
 | Hook | Fires |
 |---|---|
 | `onRunStart(ctx)` | once when a run starts |
@@ -331,9 +463,13 @@ Some runs continue an earlier one. Their `RunContext` says which, so an observer
 |---|---|
 | the next run on a session that paused — on an interrupt, a stop, or an unhandled error — whether started by `agent.resume()`, `run.resume()` (with or without a store), or `agent.run()` on that session | `resumedFrom: { runId, carrier? }` — the run that paused |
 | the first run of a session created by `SessionStore.branch()` | `branchedFrom: { sessionId, runId, carrier? }` — the run it was branched from, in the source session |
+| a new turn on a session whose last run completed (see [Turns and `requestId`](#turns-and-requestid)) | `continuedFrom: { runId, carrier? }` — the previous turn's last run |
+
+A run has at most one of the three, only on its top-level context (never on a fork branch's). A
+call that returns a request's outcome without running has none: it has no run.
 
-A run has at most one of the two, only on its top-level context (never on a fork branch's), and a
-session that already completed runs nothing, so it has neither.
+Every context of a turn's runs (fork branches included) also carries `requestId` when the turn
+has one.
 
 `carrier` is what the earlier run's observer returned from `carry(ctx)`: core calls `carry` once,
 right after `onRunStart`, keeps its string values, and saves them as `StoredRun.carrier` (or on the
@@ -411,14 +547,14 @@ The harness never trusts a wrapper. `fn` always runs exactly once, and the calle
 | Export | Description |
 |---|---|
 | `createHarness<Ctx>()(schema)` | Creates a harness. Fixes `Ctx`, infers `State` from schema. |
-| `createAgent(id, h, slots, options?)` | Assigns the agent an ID and fills `required()` slots. `options` (`AgentOptions`) takes `instanceId`, `stores` (for `required()` store slots) and `claimOptions` (this agent's default claim TTL; per-call `claimOptions` wins, then `HARNESS_CLAIM_TTL_MS`, then 30 000 ms). Returns an `Agent`. |
+| `createAgent(id, h, slots, options?)` | Assigns the agent an ID and fills `required()` slots. `options` (`AgentOptions`) takes `instanceId`, `stores` (for `required()` store slots), `claimOptions` (this agent's default claim TTL; per-call `claimOptions` wins, then `HARNESS_CLAIM_TTL_MS`, then 30 000 ms), `observer` (for every run of the agent; see [Observers](#observers)) and `onObserverError` (the default sink for hook errors). Returns an `Agent`. |
 | `field<T>(opts)` | Declares a state field with a default and optional reduce function. |
 | `required()` | Marks a provider slot as required at `createAgent()`. |
 | `runtime()` | Marks a provider slot as required at `agent.run()`. |
 | `composeObservers([a, b], onObserverError?)` | Merges multiple `Observer` instances into one fan-out observer; a throwing observer is isolated and reported to `onObserverError`. |
-| `SessionStore` | Interface for session persistence backends. |
-| `StoredRun` | Type for a persisted run snapshot. Includes `agentId`, `runId`, `sessionId`, `phase`, state, and optionally `carrier` (the run's `carry` result) and `branchedFrom` (on a branch seed). |
-| `RunRef` | `{ runId, carrier? }` — points at an earlier run; used by `RunContext.resumedFrom` and `branchedFrom` (which adds `sessionId`). |
+| `SessionStore` | Interface for session persistence backends. Optional extensions: `loadHistory`, `branch`, `claim` / `release` / `extendClaim`, and `findRequest` (the newest run of a request, for retries of earlier requests). |
+| `StoredRun` | Type for a persisted run snapshot. Includes `agentId`, `runId`, `sessionId`, `phase`, state, and optionally `requestId` (the run's turn), `carrier` (the run's `carry` result) and `branchedFrom` (on a branch seed). |
+| `RunRef` | `{ runId, carrier? }` — points at an earlier run; used by `RunContext.resumedFrom`, `continuedFrom` and `branchedFrom` (which adds `sessionId`). |
 | `RunCarrier` | `Readonly<Record<string, string>>` — the opaque map an observer's `carry` returns. |
 | `Observer` | Interface for telemetry hooks on run and step lifecycle events (see [Observers](#observers)). |
 | `StepSettledEvent` | Payload of `Observer.onStepSettled` — outcome, duration, update, signal, next, error, interrupt, fork. |
@@ -426,12 +562,22 @@ The harness never trusts a wrapper. `fn` always runs exactly once, and the calle
 | `ObserverAware` | Interface for provider objects that want per-step telemetry: the harness calls `withTelemetry(telemetry)` once per step and installs the returned view on `ctx`. |
 | `TelemetryContext` | What `withTelemetry` receives: `observer` (the run's observer, fault-isolated), `stepContext`, and `within(type, payload, fn)` bound to that step. |
 | `WrapScope` | What `Observer.wrap` is asked to enclose: `{ kind: 'step' }` or `{ kind: 'event', type, payload }`. |
-| `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`, `runId`, `parentRunId?`, `instanceId?`, `branchPath?`, `resumedFrom?`, `branchedFrom?` (see [Linking runs](#linking-runs)). |
+| `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`, `runId`, `parentRunId?`, `instanceId?`, `branchPath?`, `resumedFrom?`, `branchedFrom?`, `continuedFrom?`, `requestId?` (see [Linking runs](#linking-runs)). |
 | `StepContext` | Context passed to step-level observer hooks — `agentId`, `sessionId`, `runId`, `stepName`, `branchPath?`. |
+| `InvalidRunResourceError` | Thrown by `agent.run()` when `sessionId` or `requestId` is given but is not a non-empty string; `key` and `value` name it. |
 | `NoInterruptError` | Thrown when `resume()` is called but the session is not paused on a matching interrupt. |
 | `SessionInFlightError` | Thrown when a session is already running. |
-| `SessionPendingInterruptError` | Thrown when a session is paused on a pending interrupt — use `agent.resume()` instead of `agent.run()`. |
+| `SessionPendingInterruptError` | `agent.run()` on a session paused on a pending interrupt — use `agent.resume()` instead. With a session store, the run resolves with `signal: '$error'` and this error in `state.$error`; without one, `agent.run()` throws it. |
 | `StoreLoadError` | Thrown when the session store fails to load state. |
+| `InvalidAgentOptionError` | Thrown by `createAgent()` when `observer` is not an object or `onObserverError` is not a function; `key` and `value` name it. |
+| `InvalidClaimOptionsError` | Thrown by `createAgent()` when `claimOptions.ttlMs` is not a finite number greater than 0. |
+| `DebugSession` | Returned by `agent.debug()`: a run driven step by step (see [Debugging a run](#debugging-a-run)). |
+| `DebugStop` | Where a debug session stopped: `step`, `interrupt` or `end`. |
+| `SettledStep`, `Snapshot` | The step that just settled at a stop, and a per-key copy of a state or update. |
+| `DebugFrame`, `EndedFrame`, `PendingInterrupt` | A fork branch held by a debug session, a frame that ended, an interrupt the run waits on. |
+| `DebugBreakpoint` | `{ step, when? }`. |
+| `DebugCommandError` | A debug command that can't run now; `reason` is `busy`, `not-held`, `not-a-fork`, `reserved-key` or `ended`. |
+| `SessionInDebugError` | `run()`, `resume()` or `debug()` on a session that is being debugged in this process. |
 
 ## Design Principles
 
@@ -456,6 +602,8 @@ See [LIMITATIONS.md](LIMITATIONS.md) for known limitations.
 - [`@noetaris/harness-openai`](https://github.com/noetaris-lab/harness-openai) — OpenAI adapter
 - [`@noetaris/harness-google`](https://github.com/noetaris-lab/harness-google) — Google Gemini adapter
 - [`@noetaris/harness-otel`](https://github.com/noetaris-lab/harness-otel) — OpenTelemetry observer bridge
+- [`@noetaris/harness-recorder`](https://github.com/noetaris-lab/harness-recorder) — records runs step by step and plays a finished session back
+- [`@noetaris/harness-testing`](https://github.com/noetaris-lab/harness-testing) — `runStep`, `runRoute`, `MockObserver` for tests
 - [`@noetaris/harness-otel-genai`](https://github.com/noetaris-lab/harness-otel-genai) — GenAI semantic-conventions extension for the bridge
 
 ## License

package/dist/index.d.ts

@@ -133,7 +133,8 @@ interface RunContext {
     /**
      * The run this one continues: the run that paused the session (on an interrupt, a stop or
      * an unhandled error), with the carrier its observer produced. Present on a resumed
-     * top-level run only — never on a fork branch's context, never together with `branchedFrom`.
+     * top-level run only — never on a fork branch's context, never together with `branchedFrom` or
+     * `continuedFrom`.
      */
     readonly resumedFrom?: RunRef;
     /**
@@ -143,6 +144,18 @@ interface RunContext {
     readonly branchedFrom?: RunRef & {
         readonly sessionId: string;
     };
+    /**
+     * The previous turn's run, when this run starts a new turn on a session whose last run
+     * completed. Present on the top-level run only — never together with `resumedFrom` or
+     * `branchedFrom`.
+     */
+    readonly continuedFrom?: RunRef;
+    /**
+     * The request (turn) this run belongs to — the `requestId` passed to `agent.run()`, kept by
+     * every resume of that turn. Present on every context of the run, fork branches included.
+     * Absent for keyless turns and when the agent has no session store.
+     */
+    readonly requestId?: string;
 }
 /**
  * Identifies the agent, session, and current step for step-level observer callbacks.
@@ -321,7 +334,7 @@ interface Observer {
      * Called once per top-level run, right after `onRunStart` (never for a fork branch). Return
      * an opaque string map that lets a later run refer back to this one — e.g. the run's trace
      * context. Core saves it on the run's record and hands it back as `RunContext.resumedFrom.carrier`
-     * (or `branchedFrom.carrier`) to the run that continues or branches from it. Return
+     * (or `branchedFrom.carrier`, `continuedFrom.carrier`) to the run that continues or branches from it. Return
      * `undefined` for nothing. Only string values are kept; a throw is reported via
      * `onObserverError` (hook name `'carry'`) and counts as `undefined`.
      */
@@ -537,7 +550,7 @@ interface SessionStore {
      * no `step`, both states equal to the source run's `finalState`, and `branchedFrom` set to the
      * source session, `runId` and the source run's `carrier` (when it has one). When the source is
      * itself such a seed, copy its `branchedFrom` instead (or leave it out if it has none): a seed's
-     * own `runId` never ran. The seed has no `carrier` of its own.
+     * own `runId` never ran. The seed has no `carrier` and no `requestId` of its own.
      *
      * @throws {@link BranchNotFoundError} when `runId` is not found in history.
      */
@@ -574,6 +587,16 @@ interface SessionStore {
      * Optional — omit if your store does not support claim/release.
      */
     extendClaim?(lease: Lease, options: ClaimOptions): Promise<Lease>;
+    /**
+     * The newest run of the session whose `requestId` equals `requestId`, or `null` when there is none.
+     *
+     * Core calls it only from `agent.run()` with a `requestId` that the latest run does not carry,
+     * so a late retry of an earlier request is replayed instead of run again. Without it, core
+     * dedupes against the latest run only.
+     *
+     * Optional — omit if your store keeps no history.
+     */
+    findRequest?(agentId: string, sessionId: string, requestId: string): Promise<StoredRun | null>;
 }
 /**
  * Serializable snapshot of a single agent run, written to the store after
@@ -620,6 +643,12 @@ interface StoredRun {
     readonly branchedFrom?: RunRef & {
         readonly sessionId: string;
     };
+    /**
+     * The request (turn) this run belongs to: the `requestId` passed to `agent.run()`, inherited by
+     * every resume of that turn. Absent for keyless turns, branch seeds and runs saved before this
+     * field was added.
+     */
+    readonly requestId?: string;
 }
 /**
  * Discriminated union returned by {@link Agent.status} describing the lifecycle
@@ -648,13 +677,13 @@ 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;
 };
 /** One outstanding `ctx.interrupt()` call awaiting a response. See {@link SessionPhase}. */
-interface PendingInterrupt {
+interface PendingInterrupt$1 {
     readonly interruptId: string;
     readonly prompt: unknown;
     /**
@@ -1032,6 +1061,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 {
     /**
@@ -1051,12 +1243,33 @@ 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;
 }
 interface Agent {
     /** The agent's unique identifier, as provided to createAgent(). */
     readonly id: string;
     /**
-     * Start a new run. Returns a RunHandle synchronously before execution begins.
+     * Start a run. Returns a RunHandle synchronously before execution begins.
+     *
+     * Reserved `resources` keys that shape the session:
+     * - `sessionId?: string` — the conversation thread; a random UUID when absent
+     * - `requestId?: string` — this turn and its idempotency key. With a session store, a call whose
+     *   `requestId` the session already ran returns that request's current outcome without running
+     *   it again; without one, every call is a new turn. Ignored when the agent has no session store
+     *
+     * Both must be non-empty strings when given; otherwise `run` throws `InvalidRunResourceError`.
      */
     run(initialState: Record<string, unknown>, resources: Record<string, unknown>): RunHandle;
     /**
@@ -1064,7 +1277,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)
@@ -1073,11 +1287,43 @@ 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 {@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);
+}
+/** Thrown by {@link createAgent} when `agentOptions.observer` is not an object or `agentOptions.onObserverError` is not a function. */
+declare class InvalidAgentOptionError extends Error {
+    /** The option that was rejected. */
+    readonly key: 'observer' | 'onObserverError';
+    /** The rejected value, as given. */
+    readonly value: unknown;
+    constructor(key: 'observer' | 'onObserverError', value: unknown);
+}
+/** Thrown by `agent.run()` when `sessionId` or `requestId` is given but is not a non-empty string. */
+declare class InvalidRunResourceError extends Error {
+    /** The resource key that was rejected. */
+    readonly key: 'sessionId' | 'requestId';
+    /** The rejected value, as given. */
+    readonly value: unknown;
+    constructor(key: 'sessionId' | 'requestId', value: unknown);
+}
 /**
  * Instantiate an agent from a fully-configured {@link Harness}.
  *
@@ -1104,17 +1350,6 @@ interface Agent {
  */
 declare function createAgent<Ctx, State, Req extends keyof Ctx, Run extends keyof Ctx>(id: string, h: Harness<Ctx, State, Req, Run>, slots: Pick<Ctx, Req>, agentOptions?: AgentOptions): Agent;
 
-/**
- * Thrown by {@link RunHandle.resume} or {@link Agent.resume} when the session
- * is not currently paused on a matching interrupt.
- *
- * Common causes: the run has not yet settled, the session does not exist,
- * or the supplied `interruptId` does not match the pending interrupt.
- */
-declare class NoInterruptError extends Error {
-    constructor();
-}
-
 /**
  * Thrown by {@link Agent.run} or {@link Agent.resume} when the given session
  * is already executing a run in the same process.
@@ -1126,6 +1361,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.
@@ -1174,4 +1420,15 @@ declare class LeaseExpiredError extends Error {
     constructor(sessionId: string);
 }
 
-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, 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 };
+/**
+ * Thrown by {@link RunHandle.resume} or {@link Agent.resume} when the session
+ * is not currently paused on a matching interrupt.
+ *
+ * Common causes: the run has not yet settled, the session does not exist,
+ * or the supplied `interruptId` does not match the pending interrupt.
+ */
+declare class NoInterruptError extends Error {
+    constructor();
+}
+
+export { type Agent, type AgentOptions, type BranchCursor, type BranchDef, 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, 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 };