@noetaris/harness 0.3.2 → 0.4.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

package/dist/index.d.ts

@@ -100,6 +100,172 @@ 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;
+}
+/**
+ * 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.
+     *
+     * **Known limitation (fork/join branches):** the store-in-a-field pattern above is safe only
+     * because exactly one step runs at a time in a non-forked run. When a fork's branches run
+     * concurrently, they typically share one `ObserverAware` slot instance (`h.provide('llm', ...)`
+     * provides it once), so concurrent branches race on that stored field and `onEvent` calls may
+     * be attributed to the wrong branch/step. This is a known v1 limitation of the built-in LLM
+     * adapters (`@noetaris/harness-anthropic`/`-openai`/`-google`/`-ollama`), not fixed for this
+     * release — a correct fix means passing `StepContext` through the call instead of storing it.
+     * Treat per-step LLM telemetry as unreliable for concurrently-running branches until then.
+     */
+    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;
+
+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 +402,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 +421,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 +438,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 +451,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 +597,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 +655,41 @@ 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.
+     *
+     * Known limitation: the built-in LLM adapters (`@noetaris/harness-anthropic`/`-openai`/
+     * `-google`/`-ollama`) attribute per-step telemetry via a stored-field pattern that is not
+     * safe when one adapter instance is shared across concurrently-running branches (the normal
+     * setup). See `ObserverAware.setStepContext`'s doc comment (`agent/observer.ts`) for details
+     * — not fixed for this release.
+     */
+    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 +967,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, 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, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };