@noetaris/harness 0.1.0 → 0.2.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
@@ -117,72 +413,137 @@ 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>;
 };
+/**
+ * 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.
      */
@@ -191,29 +552,183 @@ interface Agent {
      * Cross-process entry point for responding to a pending interrupt.
      * Returns a RunHandle synchronously; the execution promise performs the resume.
      */
-    resume(response: unknown, sessionId: string, interruptId: string): RunHandle;
+    resume(response: unknown, sessionId: string, interruptId: string, options?: {
+        events?: {
+            onStoreError?: (error: unknown, phase: 'load' | 'persist' | 'claim') => void;
+        };
+    }): 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.
+ */
+interface ObserverAware {
+    /**
+     * Receive the run's observer.  The harness calls this once per `agent.run()`
+     * invocation before execution begins.
+     */
+    bindObserver(observer: Observer): 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 Harness, type Lease, NoInterruptError, type Observer, type ObserverAware, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RunContext, type RuntimeMarker, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type StateFromSchema, type StepContext, StoreLoadError, type StoredRun, type StoredRunMetadata, composeObservers, createAgent, createHarness, field, isRequiredMarker, isRuntimeMarker, required, runtime };