@noetaris/harness 0.5.0 → 0.7.0

package/README.md

@@ -156,6 +156,226 @@ 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. 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.
+
+| Hook | Fires |
+|---|---|
+| `onRunStart(ctx)` | once when a run starts |
+| `onRunEnd(ctx, { signal, durationMs })` | once when a run settles — completed, stopped (`$stopped`), paused, or rejected by a thrown error (`$error`) |
+| `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 |
+| `wrap(ctx, scope, fn)` | around a step's `run`, and around calls made with `ctx.within` |
+
+Step hooks receive a `StepContext`: `agentId`, `sessionId`, `runId`, `stepName` and, inside a
+fork branch, `branchPath`. `runId` is the same value as `RunContext.runId`. Steps inside a branch
+carry the top-level run's id, and a resumed run has a new one.
+
+**`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; `onRunEnd`
+then fires with `'$error'` and the run rejects with the same error. 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)
+```
+
+### Running code inside a span
+
+Hooks are notifications: they return before the step runs, so they cannot make a span the
+active context for the code inside it. `wrap` is the one hook that encloses work.
+
+```ts
+const timing: Observer = {
+  async wrap(ctx, scope, fn) {
+    const label = scope.kind === 'step' ? ctx.stepName : `${ctx.stepName}/${scope.type}`
+    console.log(`enter ${label}`)
+    try {
+      return await fn()
+    } finally {
+      console.log(`exit ${label}`)
+    }
+  },
+}
+
+const h = createHarness()({ done: field({ default: () => false }) }).loop(l =>
+  l.start()
+   .step('work', {
+     run: async (_s, ctx) => {
+       await ctx.within('tool.call', { toolCallId: 't1' }, async () => { /* call the tool */ })
+       return { done: true }
+     },
+     route: () => 'done',
+   })
+   .on('done').end()
+)
+
+await createAgent('demo', h, {}).run({}, { observer: timing })
+// enter work
+// enter work/tool.call
+// exit work/tool.call
+// exit work
+```
+
+- `scope` is `{ kind: 'step' }` for a step's `run`, or `{ kind: 'event', type, payload }` for code
+  that asks for a scope with `ctx.within(type, payload, fn)`. `type` is the name of the event you
+  emit for that call (for example `'tool.call'`) and `payload` carries its id (`{ toolCallId }`).
+- `ctx.within` only runs `fn` when no observer has `wrap`. For tool calls, `runTool` from
+  [`@noetaris/harness-types`](https://github.com/noetaris-lab/harness-types) emits the tool events
+  and calls `ctx.within` for you.
+- Only a step's `run` is wrapped. `route` runs after the wrap has exited, and a fork node is not
+  wrapped; each step inside a branch is wrapped with its own `ctx.branchPath`.
+- With `composeObservers([a, b])`, `a` is the outer scope.
+- LLM adapters use the same primitive: the `TelemetryContext` an `ObserverAware` slot receives from
+  `withTelemetry` carries a `within` bound to the current step.
+
+The harness never trusts a wrapper. `fn` always runs exactly once, and the caller always gets
+`fn`'s own result:
+
+| The wrapper... | What happens |
+|---|---|
+| throws before calling `fn` | the error goes to `onObserverError`; `fn` runs without the scope |
+| never calls `fn` | `fn` runs without the scope |
+| calls `fn` twice | `fn` runs once |
+| returns another value, or swallows `fn`'s error | ignored; the caller gets `fn`'s result or error |
+| does not await `fn` | the harness still waits for `fn` |
+| throws after `fn` settled | reported to `onObserverError`, unless it is `fn`'s own error passed through |
+| never settles | the step never finishes — a wrapper must settle |
+
 ## API
 
 | Export | Description |
@@ -165,13 +385,17 @@ 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. |
-| `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`. |
+| `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 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?`. |
+| `StepContext` | Context passed to step-level observer hooks — `agentId`, `sessionId`, `runId`, `stepName`, `branchPath?`. |
 | `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()`. |

package/dist/index.d.ts

@@ -137,6 +137,13 @@ interface RunContext {
 interface StepContext {
     readonly agentId: string;
     readonly sessionId: string;
+    /**
+     * The runId of the run this step belongs to — the same value as `RunContext.runId`. Steps
+     * inside fork branches carry the top-level run's id (tell branches apart with `branchPath`).
+     * A resumed run has a new id. Empty string only when the loop is driven without a runId
+     * (direct `runLoop` use), as for `RunContext.runId`.
+     */
+    readonly runId: string;
     readonly stepName: string;
     /**
      * Branch-name path (outermost to innermost), present only when this step runs inside a
@@ -145,6 +152,77 @@ 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[];
+        }[];
+    };
+}
+/**
+ * What {@link Observer.wrap} is asked to enclose.
+ *
+ * - `step` — one step's `run()`. Hooks (`onStepStart`, `onStepEnd`, …) and `route()` run outside it.
+ * - `event` — a call inside a step that an event already opened, named by that event's `type`
+ *   (e.g. `'tool.call'`, `'llm.request'`), with a `payload` carrying the id the event used
+ *   (e.g. `{ toolCallId }`, `{ callId }`). Requested via `ctx.within()` or `TelemetryContext.within()`.
+ */
+type WrapScope = {
+    readonly kind: 'step';
+} | {
+    readonly kind: 'event';
+    readonly type: string;
+    readonly payload: unknown;
+};
 /**
  * Observability hook interface.  All methods are optional — implement only
  * the hooks you need.
@@ -167,7 +245,11 @@ interface StepContext {
 interface Observer {
     /** Called once when a run begins, before the first step executes. */
     onRunStart?: (ctx: RunContext) => void;
-    /** Called once when a run settles (completed or stopped). */
+    /**
+     * Called once when a run settles — completed, stopped, paused, or rejected by a thrown error
+     * (a graph-definition error or a throwing callback). On a rejection `signal` is `'$error'` and
+     * the run rejects right after, with the original error.
+     */
     onRunEnd?: (ctx: RunContext, event: {
         signal: string;
         durationMs: number;
@@ -193,6 +275,28 @@ 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;
+    /**
+     * Run `fn` inside this observer's scope — e.g. make a span the active context so code in
+     * `fn` (auto-instrumented clients, sub agents) nests under it. The only hook that encloses
+     * work rather than being notified about it.
+     *
+     * Call `fn` at most once and return its promise. The harness never trusts the wrapper:
+     * `fn` always runs exactly once, and the caller always gets `fn`'s own result. A wrapper
+     * that throws before calling `fn` is reported via `onObserverError` (hook name `'wrap'`) and
+     * `fn` runs unwrapped; one that never calls `fn` just loses its scope; one that swallows or
+     * replaces `fn`'s result is ignored. A wrapper error after `fn` was called is reported too,
+     * unless it is `fn`'s own rejection passed through.
+     *
+     * Not guarded: a wrapper that never settles hangs the step it encloses.
+     */
+    wrap?: <T>(ctx: StepContext, scope: WrapScope, fn: () => Promise<T>) => Promise<T>;
 }
 /**
  * The telemetry a resource needs to attribute an `invoke()` call to the correct
@@ -203,8 +307,18 @@ interface Observer {
  * each call carries its own context by value.
  */
 interface TelemetryContext {
+    /**
+     * The run's observer, fault-isolated: a hook that throws is reported via `onObserverError`
+     * and never reaches the caller. Not the object passed to `agent.run()` itself.
+     */
     readonly observer: Observer;
     readonly stepContext: StepContext;
+    /**
+     * Run `fn` inside the observer's scope for the event `type` (e.g. `'llm.request'`), whose
+     * `payload` carries that event's id (e.g. `{ callId }`). Bound to this step. A passthrough
+     * when the observer has no `wrap`; wrapper faults are isolated as for {@link Observer.wrap}.
+     */
+    within<T>(type: string, payload: unknown, fn: () => Promise<T>): Promise<T>;
 }
 /**
  * Implemented by resources (e.g. LLM adapters) that emit per-step telemetry.
@@ -550,6 +664,12 @@ type RunFn<S, Ctx> = (state: StepState<S>, ctx: Ctx & {
     readonly signal: AbortSignal;
     readonly interrupt: (prompt: unknown, id?: string) => Promise<unknown>;
     readonly emit: (name: string, payload?: unknown) => void;
+    /**
+     * Run `fn` inside the observer's scope for an event this step already emitted — `type` is
+     * that event's name (e.g. `'tool.call'`), `payload` carries its id (e.g. `{ toolCallId }`).
+     * Returns `fn`'s own result. A passthrough when no observer implements `wrap`.
+     */
+    readonly within: <T>(type: string, payload: unknown, fn: () => Promise<T>) => Promise<T>;
     readonly keepAlive: KeepAliveFn;
 }) => Promise<Partial<Omit<S, '$error' | '$interrupt'>>> | Partial<Omit<S, '$error' | '$interrupt'>>;
 /**
@@ -983,4 +1103,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, 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 StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, 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, type WrapScope, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };