@noetaris/harness 0.4.0 → 0.6.0

package/README.md

@@ -156,6 +156,157 @@ const resumed = run.resume(response, interruptId)
 const resumed = agent.resume(response, sessionId, interruptId)
 ```
 
+**Resume replays the interrupted step from the top.** On resume, the step that called
+`ctx.interrupt()` runs again from its first line; each `ctx.interrupt()` call it reaches
+returns the stored response instead of pausing. State updates from the paused attempt are
+not kept — a step's update is applied only when `run` returns. So any side effect a step
+performs *before* `ctx.interrupt()` (an HTTP call, a DB write, a sub agent run) happens
+again on resume. Making that safe is up to the step: guard the side effect so a replay
+skips or reuses it.
+
+**Inside a fork, only paused branches replay.** When a fork pauses, each branch is saved
+separately. On resume, a branch that already finished is not run again — its saved state
+goes straight to the join. Every branch that is still paused runs again from its paused
+step, even if the response you sent was for a different branch; a branch with no response
+yet reaches its `ctx.interrupt()` again and re-pauses. The session stays paused until
+every pending interrupt (see `agent.status(sessionId).pendingInterrupts`) is answered.
+If any branch fails, the fork fails fast: the other branches are aborted and paused
+branches are dropped. The same happens when a branch throws a graph-definition error
+(for example a signal with no matching `.on()`): the other branches are aborted, and the
+run rejects with that error only after they have stopped.
+
+**Stopping a fork.** `stop()` while a fork runs stops each branch at its next step
+boundary. What happens next depends on whether any branch is waiting on an interrupt:
+
+| At the stop | Run settles with | To continue |
+|---|---|---|
+| No branch is waiting on an interrupt | `signal: null` — a plain stop; `agent.status()` shows `paused` with no pending interrupts | `agent.run()` on the same session continues the fork: finished branches are not run again, stopped branches continue from where they stopped. `resume()` throws `NoInterruptError`. |
+| At least one branch (at any depth) is waiting on an interrupt | `signal: '$interrupt'` | `resume()` answers it and re-runs every paused branch, including the ones that were only stopped |
+
+Input passed to the `agent.run()` that continues a stopped fork is merged into the main
+state only. The branches that continue keep their own saved state and do not see it; it
+is visible from the join onward.
+
+#### Calling sub agents from a step
+
+A sub agent is just another agent with its own session. When it pauses, its `run()`
+resolves with `signal: '$interrupt'` — it does not throw — so the calling step must pass
+the interrupt up with `ctx.interrupt()` and, after resume, call the sub agent's
+`resume()`. Because the step replays, the call must be idempotent. Checking the sub
+agent's session phase is enough:
+
+```ts
+async function callSubAgent(agent: Agent, sessionId: string, input: object, ctx: any) {
+  const status = await agent.status(sessionId)
+  if (status.phase === 'completed') return loadResult(sessionId)   // your own lookup — don't run again
+  let outcome
+  if (status.phase === 'paused') {
+    const pending = status.pendingInterrupts[0]!
+    const answer = await ctx.interrupt(pending.prompt, `${sessionId}:${pending.interruptId}`)
+    outcome = await agent.resume(answer, sessionId, pending.interruptId)
+  } else {
+    outcome = await agent.run(input, { sessionId })
+  }
+  if (outcome.signal === '$interrupt') {
+    const { interruptId, prompt } = outcome.state.$interrupt
+    await ctx.interrupt(prompt, `${sessionId}:${interruptId}`)             // pauses the main agent
+  }
+  return outcome.state
+}
+```
+
+Use a stable sub agent `sessionId` (for example derived from the main `sessionId`) so a
+replay finds the same session. To run several sub agents in parallel, put each in its own
+fork branch rather than `Promise.all` in one step: then, when one pauses, the finished ones
+are not run again on resume.
+
+```ts
+h.loop(l =>
+  l.start()
+   .fork('research')
+   .branch('web', b => b.start()
+     .step('callWeb', {
+       run: async (s, ctx) => ({ web: await callSubAgent(webAgent, `${ctx.sessionId}:web`, {}, ctx) }),
+       route: () => 'done',
+     })
+     .on('done').end())                       // inside a branch, .end() ends the branch
+   .branch('docs', b => b.start()
+     .step('callDocs', {
+       run: async (s, ctx) => ({ docs: await callSubAgent(docsAgent, `${ctx.sessionId}:docs`, {}, ctx) }),
+       route: () => 'done',
+     })
+     .on('done').end())
+   .join('merge', { run: mergeResults, route: () => 'done' })
+   .on('done').end()
+)
+```
+
+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.
+
+### 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])`;
+a hook that throws is reported to `onObserverError` (or `console.error`) and never stops
+the run. Every hook is optional.
+
+| Hook | Fires |
+|---|---|
+| `onRunStart(ctx)` | once when a run starts |
+| `onRunEnd(ctx, { signal, durationMs })` | once when a run settles (`$stopped` for a stop) |
+| `onStepStart(ctx)` | before each step |
+| `onStepEnd(ctx, { durationMs })` | after a step's `run` succeeds, before its `route` |
+| `onStepError(ctx, { error, durationMs })` | when a step's `run` throws |
+| `onInterrupt(ctx, { prompt, interruptId })` | when a step calls `ctx.interrupt()` |
+| `onEvent(ctx, type, payload)` | on `ctx.emit()` and adapter events such as `llm.response` |
+| `onStepSettled(ctx, event)` | once per step, when its outcome and destination are final |
+
+**`onStepSettled`** is the one hook that tells you, for every step, how it ended and
+where the run goes next. It fires exactly once for each `onStepStart`, on every path:
+
+```
+onStepStart → onStepEnd | onStepError | onInterrupt → onStepSettled → onRunEnd
+```
+
+It also fires for a fork node and for each step inside a branch (`ctx.branchPath` names the
+branch). A graph-definition error (`UnknownSignalError`, `NoNextStepError`,
+`MissingReducerError`) settles with `next.kind === 'throw'` before the run rejects. It does
+not fire when a run stops before starting a step, or for a finished branch that a resume
+skips.
+
+| `event` field | Meaning |
+|---|---|
+| `outcome` | `'ok'`, `'error'`, `'interrupt'`, or `'stopped'` (a fork whose branches were stopped) |
+| `durationMs` | from `onStepStart` until the destination is known — includes `route` |
+| `update` | what `run` returned, present only when it was applied to state. The raw object — copy it if you keep it |
+| `signal` | what `route` returned, when it was called |
+| `next` | `{ kind: 'step', name }`, `{ kind: 'end' }`, `{ kind: 'pause' }`, or `{ kind: 'throw' }` |
+| `error` | present when `outcome` is `'error'` |
+| `interrupt` | `{ interruptId, prompt }`, when a plain step paused on an interrupt |
+| `fork` | on a fork node that ended done or paused: `{ branches: [{ name, status, touchedKeys }] }` |
+
+```ts
+const logger: Observer = {
+  onStepSettled(ctx, e) {
+    const next = e.next.kind === 'step' ? `→ ${e.next.name}` : e.next.kind
+    console.log(`${ctx.stepName}: ${e.outcome} ${next}`, e.signal ? `(signal ${e.signal})` : '')
+  },
+}
+
+const h = createHarness()({ total: field({ default: () => 0 }) }).loop(l =>
+  l.start()
+   .step('fetch', { run: async () => ({ total: 3 }) })
+   .step('decide', { route: s => (s.total > 0 ? 'done' : 'empty') })
+   .on('done').end()
+   .on('empty').end()
+)
+
+await createAgent('demo', h, {}).run({}, { observer: logger })
+// fetch: ok → decide
+// decide: ok end (signal done)
+```
+
 ## API
 
 | Export | Description |
@@ -165,10 +316,12 @@ const resumed = agent.resume(response, sessionId, interruptId)
 | `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(...observers)` | Merges multiple `Observer` instances into one fan-out observer. |
+| `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`, and state. |
-| `Observer` | Interface for telemetry hooks on run and step lifecycle events. |
+| `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. |
+| `StepSettledNext` | Where the run goes after a step settles: `step`, `end`, `pause`, or `throw`. |
 | `ObserverAware` | Interface for provider objects that accept an `Observer` binding via `bindObserver()`. |
 | `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`. |
 | `StepContext` | Context passed to step-level observer hooks — `agentId`, `sessionId`, `stepName`. |
@@ -190,6 +343,8 @@ const resumed = agent.resume(response, sessionId, interruptId)
 - ESM only (`"type": "module"`)
 - Zero runtime dependencies
 
+See [LIMITATIONS.md](LIMITATIONS.md) for known limitations.
+
 ## Related Packages
 
 - [`@noetaris/harness-store`](https://github.com/noetaris-lab/harness-store) — session store implementations (`InMemorySessionStore`, `LocalFileSessionStore`, etc.)

package/dist/index.d.ts

@@ -145,6 +145,62 @@ interface StepContext {
      */
     readonly branchPath?: readonly string[];
 }
+/**
+ * Where execution goes after a step settles.
+ *
+ * - `step` — the next step to run (a route target, `.next()`, the implicit next step, the
+ *   `l.onError()` fallback, or the join after a fork).
+ * - `end` — the loop ended via `.end()` (inside a fork branch: the branch ended).
+ * - `pause` — the run paused (interrupt, stop, or an unhandled error) and can be continued later.
+ * - `throw` — a graph-definition error (`UnknownSignalError`, `NoNextStepError`,
+ *   `MissingReducerError`) is about to reject the run.
+ */
+type StepSettledNext = {
+    readonly kind: 'step';
+    readonly name: string;
+} | {
+    readonly kind: 'end';
+} | {
+    readonly kind: 'pause';
+} | {
+    readonly kind: 'throw';
+};
+/**
+ * Payload of {@link Observer.onStepSettled}: everything known about one step once its
+ * outcome and destination are final. Optional keys are omitted, never set to `undefined`.
+ */
+interface StepSettledEvent {
+    /** `'stopped'` only occurs on fork nodes whose branches were stopped without an interrupt. */
+    readonly outcome: 'ok' | 'error' | 'interrupt' | 'stopped';
+    /** From `onStepStart` until the destination is known — includes `route()`. */
+    readonly durationMs: number;
+    /**
+     * The value `run()` returned, present iff it was applied to state. The raw reference,
+     * unfiltered — it may be aliased into state, so copy it before the next step if you keep it.
+     */
+    readonly update?: Record<string, unknown>;
+    /** Present iff `route()` was called and returned a signal. */
+    readonly signal?: string;
+    readonly next: StepSettledNext;
+    /** Present iff `outcome` is `'error'`. */
+    readonly error?: Error;
+    /** Present iff `outcome` is `'interrupt'` on a plain (non-fork) step. */
+    readonly interrupt?: {
+        readonly interruptId: string;
+        readonly prompt: unknown;
+    };
+    /**
+     * Fork nodes only, when every branch ended done or paused (not when the fork failed):
+     * each branch in declaration order.
+     */
+    readonly fork?: {
+        readonly branches: readonly {
+            readonly name: string;
+            readonly status: 'done' | 'paused';
+            readonly touchedKeys: readonly string[];
+        }[];
+    };
+}
 /**
  * Observability hook interface.  All methods are optional — implement only
  * the hooks you need.
@@ -193,40 +249,47 @@ interface Observer {
      * by LLM adapters (e.g. `'llm.response'`).
      */
     onEvent?: (ctx: StepContext, type: string, payload: unknown) => void;
+    /**
+     * Called exactly once per step, on every path, once the step's outcome and destination
+     * are final: after `onStepEnd` / `onStepError` / `onInterrupt` (when that hook fires on the
+     * path) and before `onRunEnd`. Also fires for fork nodes and for steps inside fork branches
+     * (with `ctx.branchPath`). Not fired when a run stops before starting a step.
+     */
+    onStepSettled?: (ctx: StepContext, event: StepSettledEvent) => void;
 }
 /**
- * Implemented by resources (e.g. LLM adapters) that accept an {@link Observer}
- * at run time.  The harness calls `bindObserver` on every slot value that
- * implements this interface before the first step runs.
+ * The telemetry a resource needs to attribute an `invoke()` call to the correct
+ * run and step: the run's {@link Observer} and the current {@link StepContext}.
  *
- * Optionally, the harness calls `setStepContext` at the start of each step for
- * every slot that exposes it.  Adapters use this to attribute per-step telemetry
- * (e.g. `observer.onEvent`) to the correct step without manual calls from step code.
+ * The harness passes this per call rather than storing it on the resource instance,
+ * so concurrently-running fork branches that share one instance never race on it —
+ * each call carries its own context by value.
+ */
+interface TelemetryContext {
+    readonly observer: Observer;
+    readonly stepContext: StepContext;
+}
+/**
+ * Implemented by resources (e.g. LLM adapters) that emit per-step telemetry.
+ *
+ * The harness calls {@link ObserverAware.withTelemetry} at the start of each step for every
+ * slot that exposes it, and installs the returned value as that slot on the step's `ctx`.
+ * Step code then calls the returned view (e.g. `ctx.llm.invoke(...)`) with no telemetry
+ * arguments, and the view forwards the {@link TelemetryContext} into the call it wraps — so
+ * telemetry travels *with the call* rather than living in mutable instance state.
+ *
+ * The return is typed `unknown` because core exports no LLM-domain type; a concrete adapter
+ * narrows it (e.g. to its `LLM` view). The harness treats the returned value as an opaque
+ * slot, exactly as it treats every provided slot.
  */
 interface ObserverAware {
     /**
-     * Receive the run's observer.  The harness calls this once per `agent.run()`
-     * invocation before execution begins.
-     */
-    bindObserver(observer: Observer): void;
-    /**
-     * Receive the current step context.  The harness calls this at the start of
-     * each step for every slot that exposes this method, before calling `step.run`.
-     *
-     * Adapters that emit `observer.onEvent` in their `invoke()` method store the
-     * provided `StepContext` and use it as the first argument to `onEvent`, so
-     * events are attributed to the correct step automatically.
-     *
-     * **Known limitation (fork/join branches):** the store-in-a-field pattern above is safe only
-     * because exactly one step runs at a time in a non-forked run. When a fork's branches run
-     * concurrently, they typically share one `ObserverAware` slot instance (`h.provide('llm', ...)`
-     * provides it once), so concurrent branches race on that stored field and `onEvent` calls may
-     * be attributed to the wrong branch/step. This is a known v1 limitation of the built-in LLM
-     * adapters (`@noetaris/harness-anthropic`/`-openai`/`-google`/`-ollama`), not fixed for this
-     * release — a correct fix means passing `StepContext` through the call instead of storing it.
-     * Treat per-step LLM telemetry as unreliable for concurrently-running branches until then.
+     * Return a view of this resource scoped to the given telemetry. The harness installs
+     * the returned value as the resource's slot on the step's `ctx` before calling `step.run`.
+     * Called once per step (and once per step per branch), so each concurrent branch gets its
+     * own scoped view and there is no shared field to race on.
      */
-    setStepContext?(ctx: StepContext): void;
+    withTelemetry(ctx: TelemetryContext): unknown;
 }
 /**
  * Combine multiple {@link Observer} instances into one.  Each hook on the
@@ -234,10 +297,27 @@ interface ObserverAware {
  *
  * @example
  * ```ts
- * const observer = composeObservers(otelObserver, metricsObserver)
+ * const observer = composeObservers([otelObserver, metricsObserver])
  * ```
  */
-declare function composeObservers(...observers: Observer[]): Observer;
+/**
+ * Identifies which observer hook threw. Passed to an {@link ObserverErrorSink}.
+ */
+interface ObserverErrorContext {
+    /** The observer hook that threw, e.g. `'onStepStart'`, `'onRunEnd'`, `'onEvent'`. */
+    readonly hookName: string;
+}
+/**
+ * Opt-in sink for errors thrown by observer callbacks. Supplied under the
+ * `'onObserverError'` key in `agent.run()` / `agent.resume()` resources.
+ *
+ * Telemetry is a side-channel: an observer that throws must never crash a run.
+ * The harness routes every such throw here and continues. The sink is called at
+ * most once per failed hook invocation and MUST NOT rethrow into the run — if it
+ * does, the harness contains that too (see {@link safeInvoke}).
+ */
+type ObserverErrorSink = (error: unknown, ctx: ObserverErrorContext) => void;
+declare function composeObservers(observers: Observer[], onObserverError?: ObserverErrorSink): Observer;
 
 type Cursor = string | ForkCursor;
 /**
@@ -664,11 +744,10 @@ interface LoopBuilder<S, Ctx> {
      * with .branch() immediately after. The step immediately following the fork automatically
      * waits for every branch to settle (the "join") — no separate join primitive exists.
      *
-     * Known limitation: the built-in LLM adapters (`@noetaris/harness-anthropic`/`-openai`/
-     * `-google`/`-ollama`) attribute per-step telemetry via a stored-field pattern that is not
-     * safe when one adapter instance is shared across concurrently-running branches (the normal
-     * setup). See `ObserverAware.setStepContext`'s doc comment (`agent/observer.ts`) for details
-     * — not fixed for this release.
+     * Per-step telemetry is attributed correctly across concurrent branches: the harness scopes
+     * each branch's slots per step via {@link ObserverAware.withTelemetry}, so telemetry travels
+     * with the call rather than through shared instance state. See `ObserverAware`'s doc comment
+     * (`agent/observer.ts`).
      */
     fork(name: string): LoopBuilder<S, Ctx>;
     /**
@@ -967,4 +1046,4 @@ declare class LeaseExpiredError extends Error {
     constructor(sessionId: string);
 }
 
-export { type Agent, 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, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TransitionTarget, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };
+export { type Agent, 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 RunContext, type RunFn, 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, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };