@noetaris/harness 0.9.0 → 0.11.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:
@@ -157,11 +204,12 @@ 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 }`, and `parentRunId` (the caller's run id,
-for a sub agent resumed from a step). `parentRunId` applies to that resumed run only: calling
+`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`.
+`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
@@ -330,9 +378,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
@@ -410,14 +462,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)` | 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`, 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. |
@@ -425,11 +477,12 @@ 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. |
 
 ## Design Principles

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
@@ -1045,12 +1074,26 @@ 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(). */
     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;
     /**
@@ -1062,6 +1105,9 @@ interface Agent {
      * - `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;
     /**
@@ -1069,6 +1115,14 @@ interface Agent {
      */
     status(sessionId: string): Promise<SessionPhase>;
 }
+/** 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}.
  *
@@ -1095,17 +1149,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.
@@ -1165,4 +1208,15 @@ 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 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 DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, InvalidRunResourceError, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunCarrier, type RunContext, type RunFn, type RunRef, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepSettledEvent, type StepSettledNext, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, type WrapScope, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };