@noetaris/harness 0.3.2 → 0.5.0

package/README.md

@@ -124,17 +124,20 @@ h.provide('model',   runtime())           // per-run   — supplied at agent.run
 
 ### Session Store
 
-`h.store()` adds persistence. The reserved `session` key is used by the framework to save and restore state across runs; all other keys are surfaced as `ctx.store.<name>`.
+`h.store()` adds persistence. The reserved `session` key is used by the framework to save and restore state across runs.
 
 ```ts
 import { InMemorySessionStore } from '@noetaris/harness-store'
 
 h.store({
-  session:   new InMemorySessionStore(), // framework-managed lifecycle
-  knowledge: new MyKnowledgeGraph(),     // available as ctx.store.knowledge
+  session: new InMemorySessionStore(), // framework-managed lifecycle
 })
 ```
 
+> **Note:** Only the `session` key is processed today. Surfacing additional
+> store keys to steps as `ctx.store.<name>` is planned but not yet wired up —
+> non-session keys passed to `h.store()` are currently ignored.
+
 The framework injects `ctx.sessionId` automatically on every run — no declaration in `Ctx` needed.
 
 ### Interrupts
@@ -187,6 +190,8 @@ const resumed = agent.resume(response, sessionId, interruptId)
 - ESM only (`"type": "module"`)
 - Zero runtime dependencies
 
+See [LIMITATIONS.md](LIMITATIONS.md) for known limitations.
+
 ## Related Packages
 
 - [`@noetaris/harness-store`](https://github.com/noetaris-lab/harness-store) — session store implementations (`InMemorySessionStore`, `LocalFileSessionStore`, etc.)

package/dist/index.d.ts

@@ -100,6 +100,189 @@ declare function isRequiredMarker(value: unknown): value is RequiredMarker;
  */
 declare function isRuntimeMarker(value: unknown): value is RuntimeMarker;
 
+/**
+ * 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;
+    /**
+     * Branch-name path (outermost to innermost), present only when this context describes a
+     * fork branch's own nested run rather than the top-level run. A branch is implemented as
+     * its own recursive runLoop call, so it fires onRunStart/onRunEnd on the same observer as
+     * the top-level run, under the same runId — this field is what makes those distinguishable
+     * from the real top-level pair. Absent for the top-level run.
+     */
+    readonly branchPath?: readonly string[];
+}
+/**
+ * Identifies the agent, session, and current step for step-level observer callbacks.
+ */
+interface StepContext {
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly stepName: string;
+    /**
+     * Branch-name path (outermost to innermost), present only when this step runs inside a
+     * fork branch. Absent for a step at the top level of the loop (including the fork node
+     * itself, which is one atomic step from the outer run's point of view).
+     */
+    readonly branchPath?: readonly 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;
+}
+/**
+ * The telemetry a resource needs to attribute an `invoke()` call to the correct
+ * run and step: the run's {@link Observer} and the current {@link StepContext}.
+ *
+ * The harness passes this per call rather than storing it on the resource instance,
+ * so concurrently-running fork branches that share one instance never race on it —
+ * each call carries its own context by value.
+ */
+interface TelemetryContext {
+    readonly observer: Observer;
+    readonly stepContext: StepContext;
+}
+/**
+ * Implemented by resources (e.g. LLM adapters) that emit per-step telemetry.
+ *
+ * The harness calls {@link ObserverAware.withTelemetry} at the start of each step for every
+ * slot that exposes it, and installs the returned value as that slot on the step's `ctx`.
+ * Step code then calls the returned view (e.g. `ctx.llm.invoke(...)`) with no telemetry
+ * arguments, and the view forwards the {@link TelemetryContext} into the call it wraps — so
+ * telemetry travels *with the call* rather than living in mutable instance state.
+ *
+ * The return is typed `unknown` because core exports no LLM-domain type; a concrete adapter
+ * narrows it (e.g. to its `LLM` view). The harness treats the returned value as an opaque
+ * slot, exactly as it treats every provided slot.
+ */
+interface ObserverAware {
+    /**
+     * Return a view of this resource scoped to the given telemetry. The harness installs
+     * the returned value as the resource's slot on the step's `ctx` before calling `step.run`.
+     * Called once per step (and once per step per branch), so each concurrent branch gets its
+     * own scoped view and there is no shared field to race on.
+     */
+    withTelemetry(ctx: TelemetryContext): unknown;
+}
+/**
+ * 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])
+ * ```
+ */
+/**
+ * Identifies which observer hook threw. Passed to an {@link ObserverErrorSink}.
+ */
+interface ObserverErrorContext {
+    /** The observer hook that threw, e.g. `'onStepStart'`, `'onRunEnd'`, `'onEvent'`. */
+    readonly hookName: string;
+}
+/**
+ * Opt-in sink for errors thrown by observer callbacks. Supplied under the
+ * `'onObserverError'` key in `agent.run()` / `agent.resume()` resources.
+ *
+ * Telemetry is a side-channel: an observer that throws must never crash a run.
+ * The harness routes every such throw here and continues. The sink is called at
+ * most once per failed hook invocation and MUST NOT rethrow into the run — if it
+ * does, the harness contains that too (see {@link safeInvoke}).
+ */
+type ObserverErrorSink = (error: unknown, ctx: ObserverErrorContext) => void;
+declare function composeObservers(observers: Observer[], onObserverError?: ObserverErrorSink): Observer;
+
+type Cursor = string | ForkCursor;
+/**
+ * Persisted/returned shape of a paused fork. Always lists every branch of the fork, in
+ * declaration order (never completion order — see decision #8). A branch never appears
+ * with an 'errored' status: an uncaught branch error always escalates to whole-fork
+ * failure (decision #9) rather than sitting here as a persisted per-branch state.
+ */
+interface ForkCursor {
+    readonly kind: 'fork';
+    readonly fork: string;
+    readonly branches: readonly BranchCursor[];
+}
+type BranchCursor = {
+    readonly name: string;
+    readonly status: 'done';
+    readonly state: Record<string, unknown>;
+    readonly touchedKeys: readonly string[];
+} | {
+    readonly name: string;
+    readonly status: 'paused';
+    readonly state: Record<string, unknown>;
+    readonly cursor: Cursor;
+    readonly touchedKeys: readonly string[];
+};
+/** Structural type guard distinguishing a ForkCursor from a plain step-name cursor. */
+declare function isForkCursor(cursor: Cursor): cursor is ForkCursor;
+
 /**
  * Options passed to {@link SessionStore.claim}.
  *
@@ -236,7 +419,11 @@ interface SessionStore {
  * 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'`.
+ *   issued the interrupt and `signal` is `'$interrupt'`. `step` is a plain step name,
+ *   or (when the run paused inside a fork) a composite `ForkCursor` carrying every
+ *   branch's own state/cursor — see `Cursor` in `loop-executor.ts` and
+ *   HANDOVER-fork-join.md §4/Phase 5. A plain-string `step` from before fork/join
+ *   existed is still a valid `Cursor`, so old rows load and resume unchanged.
  * - `phase: 'completed'` — the loop exited normally; `signal` holds the exit
  *   signal (or is absent when the loop ended without emitting a signal).
  */
@@ -251,7 +438,7 @@ interface StoredRun {
     readonly initialState: Record<string, unknown>;
     readonly finalState: Record<string, unknown>;
     readonly signal?: string;
-    readonly step?: string;
+    readonly step?: Cursor;
     /**
      * Operational metadata written by the framework.
      *
@@ -268,7 +455,8 @@ interface StoredRun {
  * - `'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.
+ *   step that issued the interrupt. When the run paused inside a fork, `step` is
+ *   the fork's own name (not the richer per-branch detail — see `pendingInterrupts`).
  * - `'completed'` — the last run exited the loop; `signal` is the exit signal.
  */
 type SessionPhase = {
@@ -280,10 +468,28 @@ type SessionPhase = {
     readonly phase: 'paused';
     readonly signal?: string;
     readonly step: string;
+    /**
+     * Every interrupt currently awaiting a response, one per paused branch when the run
+     * paused inside a fork (a single-element array for a plain, non-forked pause). Lets a
+     * caller discover and resolve each one — via `Agent.resume(response, sessionId, id)` —
+     * independently; the session stays `'paused'` until every entry is resolved.
+     */
+    readonly pendingInterrupts: readonly PendingInterrupt[];
 } | {
     readonly phase: 'completed';
     readonly signal?: string;
 };
+/** One outstanding `ctx.interrupt()` call awaiting a response. See {@link SessionPhase}. */
+interface PendingInterrupt {
+    readonly interruptId: string;
+    readonly prompt: unknown;
+    /**
+     * The step that raised this interrupt. For a forked pause this is a `/`-joined
+     * breadcrumb (`"<fork>/<branch>/<step>"`, recursing further for nested forks) —
+     * same style as the validator's own fork/branch violation paths.
+     */
+    readonly step: string;
+}
 
 /**
  * Options for background renewal mode.
@@ -408,20 +614,47 @@ interface StepDef {
     readonly next: string | undefined;
     readonly errorAware: boolean;
 }
+/**
+ * A single `.branch(name, fn)` declaration inside a fork.
+ * definition is the branch's own, independently-captured LoopDefinition — built by running
+ * the branch's builder lambda against a fresh createLoopBuilder() instance. Inside a branch,
+ * `.end()` means "this branch is done," not "the run is done" (see LoopBuilder.branch).
+ */
+interface BranchDef {
+    readonly name: string;
+    readonly definition: LoopDefinition;
+}
+/**
+ * Compiled fork node stored in LoopDefinition.steps alongside StepDef nodes.
+ * A fork has no run/route of its own — it never emits a signal, so .on() is not supported on it.
+ * next: explicit .next(name) target for the step that runs once every branch has settled
+ *   (the "join"), or undefined to fall through to the next declared top-level node.
+ * Discriminated from StepDef structurally (see isForkDef) rather than via a tag field, so
+ * existing StepDef-only code and hand-built StepDef literals are unaffected.
+ */
+interface ForkDef {
+    readonly name: string;
+    readonly branches: readonly BranchDef[];
+    readonly next: string | undefined;
+}
+/** A top-level node in a LoopDefinition: either an ordinary step or a fork. */
+type LoopNode = StepDef | ForkDef;
+/** Structural type guard distinguishing ForkDef from StepDef within a LoopNode. */
+declare function isForkDef(node: LoopNode): node is ForkDef;
 /**
  * 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.
+ * entryStep: name of the first .step()/.fork() declared after .start() was called; undefined if
+ *   .start() was never called or no node was declared after it.
+ * steps: all declared top-level nodes (steps and forks) 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 steps: readonly LoopNode[];
     readonly onError: string | undefined;
 }
 /**
@@ -439,13 +672,40 @@ interface OnChain<S, Ctx> {
  * All methods mutate internal state and return `this` for chaining.
  */
 interface LoopBuilder<S, Ctx> {
-    /** Mark the loop as having a declared entry. The first .step() called after .start() is the entry. */
+    /** Mark the loop as having a declared entry. The first .step()/.fork() called after .start() is the entry. */
     start(): LoopBuilder<S, Ctx>;
     /** Declare a step. At least one of run or route must be set (validated later by LoopValidator). */
     step(name: string, options: StepOptions<S, Ctx>): LoopBuilder<S, Ctx>;
+    /**
+     * Declare a fork: a named node that splits execution into 2+ concurrent branches, declared
+     * with .branch() immediately after. The step immediately following the fork automatically
+     * waits for every branch to settle (the "join") — no separate join primitive exists.
+     *
+     * Per-step telemetry is attributed correctly across concurrent branches: the harness scopes
+     * each branch's slots per step via {@link ObserverAware.withTelemetry}, so telemetry travels
+     * with the call rather than through shared instance state. See `ObserverAware`'s doc comment
+     * (`agent/observer.ts`).
+     */
+    fork(name: string): LoopBuilder<S, Ctx>;
+    /**
+     * Declare one branch of the fork most recently opened with .fork(). Must be called immediately
+     * after .fork() or another .branch() on the same fork — throws otherwise.
+     * builderFn receives a fresh LoopBuilder scoped to this branch, using the same .step()/.on()/
+     * .next() vocabulary as the top level; inside it, .end() means "this branch is done," not
+     * "the run is done."
+     */
+    branch(name: string, builderFn: (b: LoopBuilder<S, Ctx>) => void): LoopBuilder<S, Ctx>;
+    /**
+     * Declare the step that runs once every branch of the preceding fork has settled.
+     * Pure alias of .step(name, options) — not enforced by the validator, just a naming
+     * convenience so the DSL reads as fork/branch/join.
+     */
+    join(name: string, options: StepOptions<S, Ctx>): LoopBuilder<S, Ctx>;
     /**
      * Begin a signal transition declaration. Must be called immediately after .step() or after
      * a previous .on().to() or .on().end() chain (attaches to the most recently declared step).
+     * Throws if the most recently declared node is a fork — a fork has no run/route to emit
+     * a signal from.
      */
     on(signal: string): OnChain<S, Ctx>;
     /**
@@ -723,120 +983,4 @@ declare class LeaseExpiredError extends Error {
     constructor(sessionId: string);
 }
 
-/**
- * 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, LeaseExpiredError, type LoopDefinition, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TransitionTarget, composeObservers, createAgent, createHarness, field, isRequiredMarker, isRuntimeMarker, required, runtime };
+export { type Agent, type BranchCursor, type BranchDef, type ClaimOptions, type Cursor, type DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };