@noetaris/harness 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,9 +1,27 @@
 declare const _fieldType: unique symbol;
+/**
+ * Descriptor for a single state field, produced by {@link field}.
+ *
+ * - `default` — factory called once on session start to populate the field when no
+ *   initial value is supplied.
+ * - `reduce` — merge function invoked on resume: `reduce(storedValue, incomingValue)`.
+ *   When absent, incoming values overwrite stored ones on resume.
+ */
 type FieldDefinition<T> = {
     readonly [_fieldType]: T;
     readonly default?: () => T;
     readonly reduce?: (current: T, update: T) => T;
 };
+/**
+ * Derives the concrete state record type from a schema object whose values are
+ * {@link FieldDefinition} descriptors.
+ *
+ * @example
+ * ```ts
+ * const schema = { count: field<number>({ default: () => 0 }) }
+ * type State = StateFromSchema<typeof schema> // { count: number }
+ * ```
+ */
 type StateFromSchema<S> = {
     [K in keyof S]: S[K] extends FieldDefinition<infer T> ? T : never;
 };
@@ -11,25 +29,296 @@ type FieldOptions<T> = {
     default?: () => T;
     reduce?: (current: T, update: T) => T;
 };
+/**
+ * Declare a typed state field with an optional default factory and optional
+ * reduce function.
+ *
+ * @param options.default - Factory called once at session start.
+ * @param options.reduce - Merge function for resume: `(stored, incoming) => merged`.
+ *
+ * @example
+ * ```ts
+ * const schema = {
+ *   messages: field<string[]>({ default: () => [], reduce: (a, b) => [...a, ...b] }),
+ * }
+ * ```
+ */
 declare function field<T>(options?: FieldOptions<T>): FieldDefinition<T>;
 
+/** @internal Discriminant tag for {@link RequiredMarker}. */
 declare const REQUIRED_TAG: "__noetaris_required__";
+/** @internal Discriminant tag for {@link RuntimeMarker}. */
 declare const RUNTIME_TAG: "__noetaris_runtime__";
+/**
+ * Sentinel returned by {@link required} to mark a context slot that **must** be
+ * supplied at `createAgent()` time (not at `agent.run()` time).
+ */
 type RequiredMarker = {
     readonly _tag: typeof REQUIRED_TAG;
 };
+/**
+ * Sentinel returned by {@link runtime} to mark a context slot that **must** be
+ * supplied at `agent.run()` time (not at `createAgent()` time).
+ */
 type RuntimeMarker = {
     readonly _tag: typeof RUNTIME_TAG;
 };
+/**
+ * Recursive variant of `T` that allows any nested position to also be a
+ * {@link RequiredMarker} or {@link RuntimeMarker}.  Used as the `value`
+ * parameter type on {@link Harness.provide}.
+ */
 type DeepWithMarkers<T> = T extends (...args: any[]) => any ? T | RequiredMarker | RuntimeMarker : T extends object ? {
     [K in keyof T]: DeepWithMarkers<T[K]> | RequiredMarker | RuntimeMarker;
 } | RequiredMarker | RuntimeMarker : T | RequiredMarker | RuntimeMarker;
+/**
+ * Return a {@link RequiredMarker} sentinel that instructs the harness to
+ * require this slot at `createAgent()` time.
+ *
+ * @example
+ * ```ts
+ * h.provide('llm', required())
+ * ```
+ */
 declare function required(): RequiredMarker;
+/**
+ * Return a {@link RuntimeMarker} sentinel that instructs the harness to
+ * require this slot at `agent.run()` time instead of `createAgent()` time.
+ *
+ * @example
+ * ```ts
+ * h.provide('signal', runtime())
+ * ```
+ */
 declare function runtime(): RuntimeMarker;
+/**
+ * Type guard — returns `true` when `value` is a {@link RequiredMarker}.
+ */
 declare function isRequiredMarker(value: unknown): value is RequiredMarker;
+/**
+ * Type guard — returns `true` when `value` is a {@link RuntimeMarker}.
+ */
 declare function isRuntimeMarker(value: unknown): value is RuntimeMarker;
 
-/** Framework fields injected into every step function's state argument. */
+/**
+ * Options passed to {@link SessionStore.claim}.
+ *
+ * `ttlMs` is the initial lease duration in milliseconds. The claim expires
+ * if not renewed within this window — enabling crash recovery by other instances.
+ */
+interface ClaimOptions {
+    /** Lease duration in milliseconds. Must be a positive integer. */
+    readonly ttlMs: number;
+}
+/**
+ * A successfully acquired distributed lease on a session.
+ *
+ * Returned by {@link SessionStore.claim} when no other instance holds the
+ * session. The framework holds this object for the duration of the run and
+ * passes it to {@link SessionStore.release} and {@link SessionStore.extendClaim}.
+ */
+interface Lease {
+    /**
+     * Wall-clock expiry timestamp (milliseconds since epoch).
+     * The framework checks `Date.now() >= lease.expiresAt` at each step boundary
+     * to detect TTL expiry without contacting the store.
+     */
+    readonly expiresAt: number;
+    /**
+     * The `agentId` this lease was issued for.
+     * Stored in the claim record for stuck-lease diagnosis.
+     */
+    readonly agentId: string;
+    /**
+     * The `sessionId` this lease covers.
+     */
+    readonly sessionId: string;
+    /**
+     * The `instanceId` of the holder, if provided to `createAgent()`.
+     * Written into the store's claim record for operational diagnostics.
+     * Absent when `instanceId` was not configured.
+     */
+    readonly instanceId?: string;
+    /**
+     * Store-implementation-specific token — e.g. a Redis key name, a lock token,
+     * or a database row ID. Opaque to the framework; passed back unmodified on
+     * `release` and `extendClaim` calls so the store can locate the record.
+     */
+    readonly token: unknown;
+}
+/**
+ * Operational metadata written by the framework into every {@link StoredRun}.
+ *
+ * The framework writes only `instanceId`. All other fields are reserved for
+ * domain-specific operational annotations (tenantId, region, requestId, etc.).
+ */
+interface StoredRunMetadata {
+    /** The `instanceId` of the instance that produced this run. Absent when not configured. */
+    instanceId?: string;
+    /** Open extension point — domain-specific fields. */
+    [key: string]: unknown;
+}
+/**
+ * Persistence contract for agent sessions.
+ *
+ * Implementations must be safe to call concurrently for **different** sessions;
+ * concurrent calls for the **same** session are prevented by the harness concurrency guards.
+ *
+ * `loadHistory` and `branch` are optional extensions:
+ * - `loadHistory` — full run history for a session (used by branching and debugging tools).
+ * - `branch` — fork a session at a specific past run, returning a new session ID.
+ */
+interface SessionStore {
+    /**
+     * Load the most recent {@link StoredRun} for the given session, or `null` if
+     * the session has never been saved.
+     */
+    load(agentId: string, sessionId: string): Promise<StoredRun | null>;
+    /**
+     * Persist a run record as a conditional write.
+     *
+     * Implementations must compare `run.version` against the version of the
+     * currently stored record before writing:
+     * - If the stored version equals `run.version - 1` (or there is no stored
+     *   record and `run.version === 0`), the write succeeds.
+     * - Otherwise, another writer committed a newer version concurrently — the
+     *   implementation must throw `ConcurrentModificationError`.
+     */
+    save(agentId: string, sessionId: string, run: StoredRun): Promise<void>;
+    /**
+     * Return the full ordered run history for a session, oldest first.
+     * Optional — omit if your store does not support history.
+     */
+    loadHistory?(agentId: string, sessionId: string): Promise<StoredRun[]>;
+    /**
+     * Fork the session at the state captured by `runId`, returning a new session ID
+     * whose initial state equals the forked run's `finalState`.
+     * Optional — omit if your store does not support branching.
+     *
+     * @throws {@link BranchNotFoundError} when `runId` is not found in history.
+     */
+    branch?(agentId: string, sessionId: string, runId: string): Promise<string>;
+    /**
+     * Attempt to acquire a distributed claim on the session before starting a run.
+     *
+     * - Returns a {@link Lease} when the claim is acquired.
+     * - Returns `null` when another instance already holds the claim — the framework
+     *   throws {@link SessionBusyError} immediately without starting any LLM work.
+     *
+     * Optional — stores that do not support distributed locking omit this method.
+     * The framework checks for its presence before calling it.
+     */
+    claim?(agentId: string, sessionId: string, options: ClaimOptions): Promise<Lease | null>;
+    /**
+     * Release a held claim after the run settles.
+     *
+     * Called by the framework after `save()` completes (or after an error that
+     * prevents saving). Stores may use this to remove the lock record immediately
+     * rather than waiting for TTL expiry.
+     *
+     * Optional — omit if your store does not support claim/release.
+     */
+    release?(lease: Lease): Promise<void>;
+    /**
+     * Extend the TTL of an active claim.
+     *
+     * Called by `ctx.keepAlive()` (both one-shot and background interval modes).
+     * The store must update `expiresAt` on the claim record; the new expiry is
+     * `Date.now() + options.ttlMs`. The returned `Lease` object carries the updated
+     * `expiresAt`; the framework replaces its held reference with the returned value.
+     *
+     * Optional — omit if your store does not support claim/release.
+     */
+    extendClaim?(lease: Lease, options: ClaimOptions): Promise<Lease>;
+}
+/**
+ * Serializable snapshot of a single agent run, written to the store after
+ * every run settles (either `'paused'` on an interrupt or `'completed'`).
+ *
+ * - `phase: 'paused'` — the run paused on an interrupt; `step` is the step that
+ *   issued the interrupt and `signal` is `'$interrupt'`.
+ * - `phase: 'completed'` — the loop exited normally; `signal` holds the exit
+ *   signal (or is absent when the loop ended without emitting a signal).
+ */
+interface StoredRun {
+    readonly agentId: string;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly version: number;
+    readonly startedAt: string;
+    readonly settledAt: string;
+    readonly phase: 'paused' | 'completed';
+    readonly initialState: Record<string, unknown>;
+    readonly finalState: Record<string, unknown>;
+    readonly signal?: string;
+    readonly step?: string;
+    /**
+     * Operational metadata written by the framework.
+     *
+     * The framework writes `instanceId` when configured; all other fields are
+     * domain-defined. Absent for runs produced before this field was added.
+     */
+    readonly metadata?: StoredRunMetadata;
+}
+/**
+ * Discriminated union returned by {@link Agent.status} describing the lifecycle
+ * phase of a session.
+ *
+ * - `'fresh'` — no run has been stored yet.
+ * - `'in-flight'` — a run is currently executing (in-process guard only; not
+ *   detectable cross-process from the store alone).
+ * - `'paused'` — the last run settled on an interrupt; `step` identifies the
+ *   step that issued the interrupt.
+ * - `'completed'` — the last run exited the loop; `signal` is the exit signal.
+ */
+type SessionPhase = {
+    readonly phase: 'fresh';
+} | {
+    readonly phase: 'in-flight';
+    readonly step: null;
+} | {
+    readonly phase: 'paused';
+    readonly signal?: string;
+    readonly step: string;
+} | {
+    readonly phase: 'completed';
+    readonly signal?: string;
+};
+
+/**
+ * Options for background renewal mode.
+ */
+interface KeepAliveOptions {
+    /**
+     * Renewal interval in milliseconds. A background timer calls
+     * `store.extendClaim()` at this cadence.
+     * Must be less than the original claim `ttlMs` to ensure renewal
+     * reaches the store before expiry.
+     */
+    readonly every: number;
+}
+/**
+ * The stop function returned by `ctx.keepAlive({ every })`.
+ * Always call this in a `finally` block to cancel the background timer.
+ */
+type StopFn = () => void;
+/**
+ * The `ctx.keepAlive` function type injected into the step ctx.
+ *
+ * - Called with no arguments: one-shot TTL extension. Returns a Promise.
+ * - Called with `{ every: ms }`: starts a background interval renewal timer.
+ *   Returns a `StopFn` synchronously.
+ */
+type KeepAliveFn = ((() => Promise<void>) & ((options: KeepAliveOptions) => StopFn));
+
+/**
+ * Framework-managed fields injected into every step function's `state` argument.
+ *
+ * - `$error` — the `Error` thrown by the previous step, or `null` if no error occurred.
+ *   Only populated on the error path; non-error-aware steps never see a non-null value here.
+ * - `$interrupt` — set while a step is awaiting a resume response.  The `response` field
+ *   is populated after {@link Agent.resume} is called.
+ */
 interface FrameworkState {
     readonly $error: Error | null;
     readonly $interrupt: {
@@ -38,7 +327,10 @@ interface FrameworkState {
         readonly response?: unknown;
     } | null;
 }
-/** The full state type visible inside step functions: user state + framework fields. */
+/**
+ * The complete state type visible inside {@link RunFn} step functions:
+ * the user-defined state `S` merged with {@link FrameworkState}.
+ */
 type StepState<S> = S & FrameworkState;
 /**
  * State transformer. Receives the full step state and ctx; returns a partial update
@@ -46,9 +338,13 @@ type StepState<S> = S & FrameworkState;
  * May be async.
  */
 type RunFn<S, Ctx> = (state: StepState<S>, ctx: Ctx & {
+    readonly agentId: string;
     readonly sessionId: string;
+    readonly runId: string;
+    readonly signal: AbortSignal;
     readonly interrupt: (prompt: unknown, id?: string) => Promise<unknown>;
     readonly emit: (name: string, payload?: unknown) => void;
+    readonly keepAlive: KeepAliveFn;
 }) => Promise<Partial<Omit<S, '$error' | '$interrupt'>>> | Partial<Omit<S, '$error' | '$interrupt'>>;
 /**
  * Pure signal emitter. Receives step state without $error — the route is not called on the error
@@ -80,6 +376,54 @@ type StepOptions<S, Ctx> = {
     run?: RunFn<S, Ctx>;
     route?: RouteFn<S>;
 };
+/**
+ * Where a signal transition routes to.
+ * 'step' — routes to the named step.
+ * 'end'  — exits the loop; run resolves with the emitted signal.
+ */
+type TransitionTarget = {
+    readonly kind: 'step';
+    readonly name: string;
+} | {
+    readonly kind: 'end';
+};
+/** A single `.on(signal).to(step)` or `.on(signal).end()` declaration. */
+interface SignalTransition {
+    readonly signal: string;
+    readonly target: TransitionTarget;
+}
+/**
+ * Compiled step definition stored in LoopDefinition.
+ * run and route are stored as-is (user functions — validated structurally, not semantically).
+ * transitions: all .on() declarations attached to this step.
+ * next: explicit .next(name) target, or undefined if none declared.
+ * errorAware: true when the step was declared with optin: '$error' — the executor calls route
+ *   on the error path when this is true.
+ */
+interface StepDef {
+    readonly name: string;
+    readonly run: RunFn<unknown, unknown> | undefined;
+    readonly route: RouteFn<unknown> | undefined;
+    readonly transitions: readonly SignalTransition[];
+    readonly next: string | undefined;
+    readonly errorAware: boolean;
+}
+/**
+ * Complete loop topology captured from the builder lambda.
+ * Immutable snapshot — produced once, consumed by LoopValidator and (later) F6.
+ *
+ * startCalled: true if l.start() was invoked at least once.
+ * entryStep: name of the first .step() declared after .start() was called; undefined if .start()
+ *   was never called or no step was declared after it.
+ * steps: all declared steps in declaration order.
+ * onError: the fallback step name from l.onError(), or undefined if not set.
+ */
+interface LoopDefinition {
+    readonly startCalled: boolean;
+    readonly entryStep: string | undefined;
+    readonly steps: readonly StepDef[];
+    readonly onError: string | undefined;
+}
 /**
  * Fluent chain returned by .on(signal). Caller must call either .to(step) or .end()
  * to complete the transition declaration.
@@ -117,72 +461,149 @@ interface LoopBuilder<S, Ctx> {
     onError(step: string): LoopBuilder<S, Ctx>;
 }
 
+/**
+ * Immutable builder that accumulates context-slot declarations, store bindings,
+ * and the loop definition for an agent.  Produced by {@link createHarness} and
+ * consumed by {@link createAgent}.
+ *
+ * The four type parameters track what has been declared so far:
+ * - `Ctx` — the full context shape expected by step functions.
+ * - `State` — the state record shape derived from the schema passed to `createHarness()`.
+ * - `Req` — keys declared as {@link required} (must be supplied to `createAgent`).
+ * - `Run` — keys declared as {@link runtime} (must be supplied to `agent.run()`).
+ *
+ * Each call returns a **new** `Harness` instance; the original is unchanged.
+ *
+ * @example
+ * ```ts
+ * const h = createHarness<Ctx>()(schema)
+ *   .provide('llm', required())
+ *   .provide('model', 'claude-3-5-haiku-20241022')
+ *   .store({ session: new InMemorySessionStore() })
+ *   .loop(l => {
+ *     l.start().step('run', { run, route }).on('done').end()
+ *   })
+ * ```
+ */
 type Harness<Ctx, State, Req extends keyof Ctx = never, Run extends keyof Ctx = never> = {
+    /**
+     * Declare a context slot.
+     *
+     * - Pass {@link required} to require the value at `createAgent()` time.
+     * - Pass {@link runtime} to require the value at `agent.run()` time.
+     * - Pass any concrete value (or a deep object mixing in markers) to bind it now.
+     */
     provide<K extends keyof Ctx>(key: K, value: RequiredMarker): Harness<Ctx, State, Req | K, Run>;
     provide<K extends keyof Ctx>(key: K, value: RuntimeMarker): Harness<Ctx, State, Req, Run | K>;
     provide<K extends keyof Ctx>(key: K, value: DeepWithMarkers<Ctx[K]>): Harness<Ctx, State, Req, Run>;
+    /**
+     * Bind session store(s).  Pass `{ session: myStore }` to enable persistence and
+     * interrupt/resume across processes.
+     */
     store(stores: DeepWithMarkers<{
         session?: unknown;
     } & Record<string, unknown>>): Harness<Ctx, State, Req, Run>;
+    /**
+     * Define the execution loop using the {@link LoopBuilder} DSL.
+     *
+     * @param builder - Callback that receives a `LoopBuilder` and uses it to
+     *   declare steps, transitions, and the entry point.
+     */
     loop(builder: (l: LoopBuilder<State, Ctx>) => void): Harness<Ctx, State, Req, Run>;
+    /**
+     * Return the frozen {@link LoopDefinition} captured when {@link loop} was called.
+     *
+     * @throws {LoopNotDefinedError} if `h.loop()` has not been called on this harness instance.
+     */
+    definition(): LoopDefinition;
 };
+/**
+ * Thrown by {@link Harness.definition} when `h.loop()` has not been called yet.
+ */
+declare class LoopNotDefinedError extends Error {
+    constructor();
+}
+/**
+ * Create a harness builder for the given context type.
+ *
+ * Call the returned function (optionally with a state schema) to get the
+ * {@link Harness} builder on which you chain `.provide()`, `.store()`, and `.loop()`.
+ *
+ * @example
+ * ```ts
+ * interface Ctx { llm: LLM; model: string }
+ * const schema = { messages: field<string[]>({ default: () => [] }) }
+ *
+ * const h = createHarness<Ctx>()(schema)
+ * ```
+ */
 declare function createHarness<Ctx = any>(): <S extends object = {}>(// any: allows createHarness() without an explicit Ctx type parameter
 stateSchema?: S) => Harness<Ctx, StateFromSchema<S>>;
 
-interface SessionStore {
-    load(sessionId: string): Promise<StoredRun | null>;
-    save(sessionId: string, run: StoredRun): Promise<void>;
-    loadHistory?(sessionId: string): Promise<StoredRun[]>;
-    branch?(sessionId: string, runId: string): Promise<string>;
-}
-interface StoredRun {
-    readonly runId: string;
-    readonly sessionId: string;
-    readonly startedAt: string;
-    readonly settledAt: string;
-    readonly phase: 'paused' | 'completed';
-    readonly initialState: Record<string, unknown>;
-    readonly finalState: Record<string, unknown>;
-    readonly signal?: string;
-    readonly step?: string;
-}
-type SessionPhase = {
-    readonly phase: 'fresh';
-} | {
-    readonly phase: 'in-flight';
-    readonly step: null;
-} | {
-    readonly phase: 'paused';
-    readonly signal?: string;
-    readonly step: string;
-} | {
-    readonly phase: 'completed';
-    readonly signal?: string;
-};
-
+/**
+ * The resolved value of a {@link RunHandle} promise: the final state and the
+ * signal that caused the loop to exit.
+ *
+ * `signal` is `null` when the loop exited via `.end()` without an explicit signal,
+ * `'$interrupt'` when paused on an interrupt, or any custom signal string returned
+ * by a route function.
+ */
 interface RunOutcome {
     readonly state: Record<string, unknown>;
     readonly signal: string | null;
 }
+/**
+ * Handle returned synchronously by {@link Agent.run} and {@link Agent.resume}.
+ *
+ * Implements `PromiseLike<RunOutcome>` so it can be `await`-ed directly.
+ *
+ * @example
+ * ```ts
+ * const handle = agent.run({}, { llm })
+ * console.log(handle.sessionId)   // available immediately
+ * const { state, signal } = await handle
+ * ```
+ */
 interface RunHandle extends PromiseLike<RunOutcome> {
     /** Cancel the in-flight run at the next safe point between steps. Idempotent. */
     stop(): void;
     /**
-     * Provide a response to a pending ctx.interrupt() call.
-     * Returns a new RunHandle for the resumed execution.
-     * Stub in F8 — implemented in F9.
+     * Provide a response to a pending `ctx.interrupt()` call and start a new run.
+     * Returns a new {@link RunHandle} for the resumed execution.
+     *
+     * Throws {@link NoInterruptError} when the run has not settled on `signal: '$interrupt'`.
+     *
+     * @param response - The value to deliver as the interrupt response.
+     * @param interruptId - The `interruptId` from `state.$interrupt`.
      */
     resume(response: unknown, interruptId: string): RunHandle;
     /** The session identity for this run. */
     readonly sessionId: string;
+    /**
+     * Unique identifier for this specific invocation.
+     * One UUID per `agent.run()` or `agent.resume()` call.
+     */
+    readonly runId: string;
     /**
      * The name of the step currently executing in this process.
-     * null before the first step runs, after execution settles, and always when inspected cross-process.
+     * `null` before the first step runs, after execution settles, and always
+     * when inspected cross-process.
      */
     readonly currentStep: string | null;
 }
 
+/** Options passed to createAgent(). */
+interface AgentOptions {
+    /**
+     * Stable identifier for the process or replica running this agent instance.
+     * Written to `StoredRun.metadata` on every save and propagated to observers
+     * via `RunContext.instanceId`.
+     */
+    readonly instanceId?: string;
+}
 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.
      */
@@ -190,30 +611,197 @@ interface Agent {
     /**
      * Cross-process entry point for responding to a pending interrupt.
      * 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)
+     * - `events?.onStoreError?` — raw store-error callback (unchanged from prior shape)
      */
-    resume(response: unknown, sessionId: string, interruptId: string): RunHandle;
+    resume(response: unknown, sessionId: string, interruptId: string, resources?: Record<string, unknown>): RunHandle;
     /**
      * Query the session store for the current phase of a session.
      */
     status(sessionId: string): Promise<SessionPhase>;
 }
-declare function createAgent<Ctx, State, Req extends keyof Ctx, Run extends keyof Ctx>(h: Harness<Ctx, State, Req, Run>, slots: Pick<Ctx, Req>): Agent;
+/**
+ * Instantiate an agent from a fully-configured {@link Harness}.
+ *
+ * Validates that all `required()` slots are present in `slots`, that no
+ * `runtime()` slots are passed here, and that the harness has a loop defined.
+ *
+ * @param id - A stable, human-readable identifier for this agent (used as the
+ *   first argument to every store operation).
+ * @param h - The harness produced by `createHarness()...loop()`.
+ * @param slots - Values for every slot declared with `required()` in the harness.
+ * @param options - Optional agent-level options (e.g., instanceId).
+ *
+ * @throws {@link MissingLoopError} when `h.loop()` was never called.
+ * @throws {@link MissingSlotError} when a `required()` slot is absent from `slots`.
+ * @throws {@link RuntimeSlotInAgentError} when a `runtime()` slot is passed in `slots`.
+ * @throws {@link UnknownSlotError} when `slots` contains a key not declared in the harness.
+ *
+ * @example
+ * ```ts
+ * const agent = createAgent('my-agent', h, { llm: new Claude('claude-3-5-haiku-20241022') })
+ * const handle = agent.run({}, {})
+ * const { state, signal } = await handle
+ * ```
+ */
+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.
+ *
+ * Wait for the in-flight {@link RunHandle} to settle before starting a new run.
+ */
 declare class SessionInFlightError extends Error {
+    /** The session that was already in-flight. */
     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.
+ */
 declare class SessionPendingInterruptError extends Error {
+    /** The session that is awaiting an interrupt response. */
     readonly sessionId: string;
     constructor(sessionId: string);
 }
+/**
+ * Thrown by the harness when the session store's `load()` call rejects.
+ * The original error is available on the `cause` property.
+ */
 declare class StoreLoadError extends Error {
     readonly cause: unknown;
     constructor(cause: unknown);
 }
 
-export { type Agent, type DeepWithMarkers, type FieldDefinition, type Harness, NoInterruptError, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RuntimeMarker, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type StateFromSchema, StoreLoadError, type StoredRun, createAgent, createHarness, field, isRequiredMarker, isRuntimeMarker, required, runtime };
+/**
+ * Identifies the agent and session for run-level observer callbacks.
+ */
+interface RunContext {
+    readonly agentId: string;
+    readonly sessionId: string;
+    /**
+     * The UUID for this specific run invocation. Always present in RunContext
+     * passed to observer methods.
+     */
+    readonly runId: string;
+    /**
+     * Optional parent run UUID for cross-process trace correlation. Present
+     * when parentRunId was passed to agent.run() resources. Absent for top-level
+     * runs or when not provided by the caller.
+     */
+    readonly parentRunId?: string;
+    /**
+     * The physical instance ID of the agent process, if configured via
+     * `createAgent()` options. Absent when `instanceId` was not provided.
+     */
+    readonly instanceId?: string;
+}
+/**
+ * Identifies the agent, session, and current step for step-level observer callbacks.
+ */
+interface StepContext {
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly stepName: string;
+}
+/**
+ * Observability hook interface.  All methods are optional — implement only
+ * the hooks you need.
+ *
+ * Pass an `Observer` implementation in `agent.run()` resources under the key
+ * `'observer'`, or bind it to an {@link ObserverAware} slot before running.
+ *
+ * LLM adapters emit `'llm.response'` events via `onEvent` carrying an
+ * `LLMUsageEvent` payload for token tracking.
+ *
+ * @example
+ * ```ts
+ * const obs: Observer = {
+ *   onRunStart: (ctx) => console.log('run started', ctx.sessionId),
+ *   onEvent: (ctx, type, payload) => metrics.record(type, payload),
+ * }
+ * agent.run({}, { llm, observer: obs })
+ * ```
+ */
+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). */
+    onRunEnd?: (ctx: RunContext, event: {
+        signal: string;
+        durationMs: number;
+    }) => void;
+    /** Called immediately before each step's `run` function is invoked. */
+    onStepStart?: (ctx: StepContext) => void;
+    /** Called after a step completes successfully. */
+    onStepEnd?: (ctx: StepContext, event: {
+        durationMs: number;
+    }) => void;
+    /** Called when a step's `run` function throws. */
+    onStepError?: (ctx: StepContext, event: {
+        error: unknown;
+        durationMs: number;
+    }) => void;
+    /** Called when a step issues a `ctx.interrupt()`. */
+    onInterrupt?: (ctx: StepContext, event: {
+        prompt: unknown;
+        interruptId: string;
+    }) => void;
+    /**
+     * Called for arbitrary named events emitted by step code via `ctx.emit()` or
+     * by LLM adapters (e.g. `'llm.response'`).
+     */
+    onEvent?: (ctx: StepContext, type: string, payload: unknown) => 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.
+ *
+ * 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.
+ */
+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.
+     */
+    setStepContext?(ctx: StepContext): void;
+}
+/**
+ * Combine multiple {@link Observer} instances into one.  Each hook on the
+ * composite forwards to all constituent observers in order.
+ *
+ * @example
+ * ```ts
+ * const observer = composeObservers(otelObserver, metricsObserver)
+ * ```
+ */
+declare function composeObservers(...observers: Observer[]): Observer;
+
+export { type Agent, type ClaimOptions, type DeepWithMarkers, type FieldDefinition, type FrameworkState, type Harness, type Lease, type LoopDefinition, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, 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, isRequiredMarker, isRuntimeMarker, required, runtime };