@noetaris/harness 0.8.0 → 0.10.0

package/README.md

@@ -156,6 +156,14 @@ const resumed = run.resume(response, interruptId)
 const resumed = agent.resume(response, sessionId, interruptId)
 ```
 
+`agent.resume()` takes an optional fourth argument with these reserved resources (a subset of
+`run()`'s): `observer`, `onObserverError`, `events: { onStoreError }`, `parentRunId` (the caller's run id,
+for a sub agent resumed from a step), and `claimOptions`. `parentRunId` applies to that resumed run only: calling
+`resume()` again on the handle it returns keeps the other resources but not `parentRunId`, which
+is stale by then. With a store, both `agent.resume()` and `run.resume()` record the agent's
+`instanceId` in the resumed run's `metadata` and, when the store supports claims, claim the
+session for the resumed run; a `resume()` on the returned handle reuses the same claim TTL.
+
 **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
@@ -263,6 +271,7 @@ throws on an adapter event never fails a step. Every hook is optional.
 | `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` |
+| `carry(ctx)` | once per top-level run, right after `onRunStart`; returns a string map to keep on the run's record (see [Linking runs](#linking-runs)) |
 
 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
@@ -314,6 +323,27 @@ await createAgent('demo', h, {}).run({}, { observer: logger })
 // decide: ok end (signal done)
 ```
 
+### Linking runs
+
+Some runs continue an earlier one. Their `RunContext` says which, so an observer can link them:
+
+| The run is | `RunContext` field |
+|---|---|
+| 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 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.
+
+`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
+handle, for `run.resume()` without a store). It describes that run only — when the earlier run had
+no observer with `carry`, `carrier` is absent rather than taken from an older run.
+`@noetaris/harness-otel` uses this to link each run's root span to the one before it.
+`composeObservers` merges the maps its observers return (on a shared key the later observer wins);
+a `carry` that throws is reported to `onObserverError` with hook name `'carry'` and counts as
+returning nothing.
+
 ### Running code inside a span
 
 Hooks are notifications: they return before the step runs, so they cannot make a span the
@@ -381,20 +411,22 @@ 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)` | Assigns the agent an ID and fills `required()` slots. 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) and `claimOptions` (this agent's default claim TTL; per-call `claimOptions` wins, then `HARNESS_CLAIM_TTL_MS`, then 30 000 ms). 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`, and state. |
+| `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`). |
+| `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. |
 | `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?`. |
+| `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`, `runId`, `parentRunId?`, `instanceId?`, `branchPath?`, `resumedFrom?`, `branchedFrom?` (see [Linking runs](#linking-runs)). |
 | `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. |

package/dist/index.d.ts

@@ -130,6 +130,19 @@ interface RunContext {
      * from the real top-level pair. Absent for the top-level run.
      */
     readonly branchPath?: readonly string[];
+    /**
+     * 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`.
+     */
+    readonly resumedFrom?: RunRef;
+    /**
+     * The run this session was branched from (`SessionStore.branch`), in the source session.
+     * Present on the branched session's first top-level run only.
+     */
+    readonly branchedFrom?: RunRef & {
+        readonly sessionId: string;
+    };
 }
 /**
  * Identifies the agent, session, and current step for step-level observer callbacks.
@@ -304,6 +317,15 @@ interface Observer {
      * Not guarded: a wrapper that never settles hangs the step it encloses.
      */
     wrap?: <T>(ctx: StepContext, scope: WrapScope, fn: () => Promise<T>) => Promise<T>;
+    /**
+     * 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
+     * `undefined` for nothing. Only string values are kept; a throw is reported via
+     * `onObserverError` (hook name `'carry'`) and counts as `undefined`.
+     */
+    carry?: (ctx: RunContext) => Record<string, string> | undefined;
 }
 /**
  * The telemetry a resource needs to attribute an `invoke()` call to the correct
@@ -462,6 +484,18 @@ interface StoredRunMetadata {
     /** Open extension point — domain-specific fields. */
     [key: string]: unknown;
 }
+/**
+ * Opaque string map an observer's `carry` hook returns for a run (e.g. a trace
+ * context). Core stores it on the run's record and hands it back to later runs; it never
+ * reads it.
+ */
+type RunCarrier = Readonly<Record<string, string>>;
+/** Points at one earlier run, with the carrier that run's observer produced (if any). */
+interface RunRef {
+    readonly runId: string;
+    /** Absent when that run had no observer that carries, or its `carry` returned nothing. */
+    readonly carrier?: RunCarrier;
+}
 /**
  * Persistence contract for agent sessions.
  *
@@ -499,6 +533,12 @@ interface SessionStore {
      * whose initial state equals the forked run's `finalState`.
      * 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'`,
+     * 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.
+     *
      * @throws {@link BranchNotFoundError} when `runId` is not found in history.
      */
     branch?(agentId: string, sessionId: string, runId: string): Promise<string>;
@@ -567,6 +607,19 @@ interface StoredRun {
      * domain-defined. Absent for runs produced before this field was added.
      */
     readonly metadata?: StoredRunMetadata;
+    /**
+     * What the run's observer returned from `carry` (e.g. its trace context). Describes this
+     * run only. Absent when no observer carried anything.
+     */
+    readonly carrier?: RunCarrier;
+    /**
+     * Set by `SessionStore.branch` on the seed record of a branched session: the run it was
+     * branched from, in the source session. The branched session's first run reports it as
+     * `RunContext.branchedFrom`.
+     */
+    readonly branchedFrom?: RunRef & {
+        readonly sessionId: string;
+    };
 }
 /**
  * Discriminated union returned by {@link Agent.status} describing the lifecycle
@@ -992,6 +1045,12 @@ interface AgentOptions {
      * Keyed by the store key used in the harness (e.g. `{ session: myStore }`).
      */
     readonly stores?: Record<string, unknown>;
+    /**
+     * Default claim options for every run and resume of this agent, used when the call passes none.
+     * Resolution: per-call `claimOptions` → this → `HARNESS_CLAIM_TTL_MS` → 30 000 ms.
+     * `ttlMs` must be a finite number greater than 0; otherwise `createAgent` throws `InvalidClaimOptionsError`.
+     */
+    readonly claimOptions?: ClaimOptions;
 }
 interface Agent {
     /** The agent's unique identifier, as provided to createAgent(). */
@@ -1006,7 +1065,12 @@ interface Agent {
      *
      * The optional fourth argument `resources` accepts:
      * - `observer?: Observer` — structured telemetry for the resumed run (see Observability)
+     * - `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)
+     * - `claimOptions?: ClaimOptions` — claim TTL for this resume, parsed like `agent.run()`'s; falls back
+     *   to `AgentOptions.claimOptions`, then `HARNESS_CLAIM_TTL_MS`, then 30 000 ms. A later `handle.resume()`
+     *   on the returned handle reuses it
      */
     resume(response: unknown, sessionId: string, interruptId: string, resources?: Record<string, unknown>): RunHandle;
     /**
@@ -1110,4 +1174,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 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 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 };