@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/agents-C0Ji9ldU.d.cts

@@ -0,0 +1,629 @@
+import { NodeInput, ReactiveMapBundle } from '@graphrefly/pure-ts/extra';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+import { c as LLMResponse, j as ToolCall, L as LLMAdapter, k as ToolDefinition, i as TokenUsage } from './types-BB5Lw-pB.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
+import { C as ChatStreamGraph, o as ToolRegistryGraph, q as ToolResult, d as MemoryTiersBundle, h as MemoryWithTiersGraph, m as RetrievalQuery, R as RetrievalEntry, e as MemoryTiersOptions } from './memory-composers-BryDrRBX.cjs';
+import { D as DistillBundle, E as Extraction } from './distill-De6Rnn15.cjs';
+import { VectorIndexGraph, KnowledgeGraph } from './utils/memory/index.cjs';
+
+/**
+ * Reactive agent loop — autonomous multi-turn LLM agent with tool execution.
+ */
+type AgentLoopStatus = "idle" | "thinking" | "acting" | "done" | "error";
+
+type AgentLoopOptions = {
+    graph?: GraphOptions;
+    adapter: LLMAdapter;
+    tools?: readonly ToolDefinition[];
+    systemPrompt?: string;
+    maxTurns?: number;
+    stopWhen?: (response: LLMResponse) => boolean;
+    onToolCall?: (call: ToolCall) => void;
+    maxMessages?: number;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Reactive tool-call splice (COMPOSITION-GUIDE §31 "interception is security").
+     * When set, the raw `toolCalls` node is piped through this transform before
+     * reaching the executor. The transform is a pure reactive composition —
+     * `(calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>` — so the
+     * gate is visible in `describe()` / `explain()` as a real edge (no hidden
+     * imperative wraps; §24).
+     *
+     * Typical uses:
+     * - **Filter / block** — `derived([calls, policy], ([raw, p]) => raw.filter(p))`
+     * - **Throttle / debounce** — `throttle(calls, windowMs)`
+     * - **Human-in-the-loop approval** — pipe through a `gate` controller so
+     *   calls wait for human approval before reaching the executor.
+     *
+     * The public `agent.toolCalls` node surfaces the POST-intercept stream, so
+     * audit / telemetry consumers see what the executor actually runs. The raw
+     * pre-intercept stream is not exposed — tests that need it should run
+     * without `interceptToolCalls` set (the identity case).
+     */
+    interceptToolCalls?: (calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>;
+};
+/**
+ * Reactive agent loop.
+ *
+ * The loop is a reactive state machine wired entirely from graph primitives:
+ * `chat.messages` + `tools.schemas` + gating state feed a `promptInput`
+ * derived; `switchMap` turns non-null inputs into an LLM invocation via
+ * `fromAny(adapter.invoke(...))`. The LLM response drives chat writes and
+ * status transitions via effects. Tool calls flow through a reactive
+ * executor (`retrySource` + `rescue`) that retries once on error and
+ * surfaces terminal errors as JSON-shaped `ToolResult` payloads for the
+ * LLM to react to.
+ *
+ * **No imperative control flow inside the reactive layer** (spec §5.8-5.12):
+ * no `while` loops, no manual `await adapter.invoke`, no polling.
+ * `agent.run()` is a thin `awaitSettled` bridge so callers can still `await`
+ * the loop if they want a Promise.
+ *
+ * Public surface:
+ * - `chat` / `tools` — subgraphs (imperative `append` at boundary, reactive `executeReactive` for tool invocation)
+ * - `status` / `turn` / `aborted` — state nodes with explicit initials
+ * - `lastResponse` / `toolCalls` / `toolResults` — reactive outputs (SENTINEL until first emission; callers use `awaitSettled` / `subscribe`)
+ * - `run(userMessage?, signal?)` — optional user append + Promise bridge
+ * - `abort()` — imperative abort shim; flips `aborted` state
+ *
+ * **Lifecycle: single-mount.** `AgentLoopGraph` instances expect to be
+ * constructed once and used until `destroy()`. The internal closure mirrors
+ * (`latestTurn` / `latestAborted` / `latestStatus`) are wired by
+ * subscribe-and-capture at construction time; their `addDisposer`-registered
+ * subscriptions are torn down on subgraph unmount or `destroy()`. After
+ * teardown the mirrors freeze at their last value, so re-using a destroyed
+ * instance — calling `run()` again, or remounting under a new parent —
+ * would silently feed stale mirror data into reactive fn bodies. If you
+ * need to "reset" an agent, build a fresh `AgentLoopGraph` instance instead
+ * of recycling.
+ */
+declare class AgentLoopGraph extends Graph {
+    readonly chat: ChatStreamGraph;
+    readonly tools: ToolRegistryGraph;
+    /** Current agent status. `initial: "idle"` — always has a real value. */
+    readonly status: Node<AgentLoopStatus>;
+    /** Turn count (completed LLM invocations this run). `initial: 0`. */
+    readonly turn: Node<number>;
+    /** Aborted flag; flipped by `abort()` or external `AbortSignal`. `initial: false`. */
+    readonly aborted: Node<boolean>;
+    /**
+     * Most recent LLM response. State-backed mirror driven by the response
+     * effect. **Stays SENTINEL** (`cache === undefined`, no DATA emitted)
+     * until the first real response — bridge subscribers see no spurious
+     * push-on-subscribe DATA. After a real response, holds the latest
+     * `LLMResponse`. Reset between `run()` calls via `[[INVALIDATE]]` (clears
+     * cache back to SENTINEL) so a second run with a pre-aborted signal
+     * cannot leak the prior run's response. Bridge with
+     * `awaitSettled(lastResponse)` for the first DATA as a Promise; consumers
+     * inside reactive fns gate on `ctx.prevData[i] === undefined`.
+     */
+    readonly lastResponse: Node<LLMResponse>;
+    /** Tool-call batch emitted by the most recent LLM response. SENTINEL. */
+    readonly toolCalls: Node<readonly ToolCall[]>;
+    /** Tool-result batch (one entry per call) after reactive execution. SENTINEL. */
+    readonly toolResults: Node<readonly ToolResult[]>;
+    private readonly _terminalResult;
+    private readonly _disposeRunWiring;
+    /** Guards against overlapping `run()` calls. */
+    private _running;
+    /**
+     * Abort controller for the currently-running `adapter.invoke`. Minted per
+     * switchMap project; aborted when the reactive `aborted` node flips true
+     * OR when the caller's external `AbortSignal` fires. Threaded into
+     * `adapter.invoke({ signal })` AND `fromAny(promise, { signal })`, so the
+     * reactive layer sees ERROR when the wire call is cancelled.
+     */
+    private _currentAbortController;
+    constructor(name: string, opts: AgentLoopOptions);
+    /**
+     * Bridge to `Promise<LLMResponse>` over the reactive pipeline.
+     *
+     * - If `userMessage` is provided, appends it as a user message and
+     *   transitions status to `"thinking"` to kick the loop.
+     * - If `signal` is provided, binds it to the reactive `aborted` node
+     *   AND threads into `adapter.invoke({ signal })` so the wire call can
+     *   cancel mid-flight. The reactive `aborted` state + effect 3 guarantee
+     *   that even an adapter that ignores `signal` will stop emitting into
+     *   the agent graph.
+     * - Resolves when `status === "done"` with the final LLM response.
+     *   Rejects with `AbortError` when the abort signal fires pre-response.
+     *   Rejects with the stage error when `status === "error"`.
+     *
+     * **Concurrency:** `run()` refuses to overlap with a pending call on the
+     * same agent. Attempting to call `run()` while a previous `run()` is
+     * still in-flight throws a `RangeError` immediately. Stale-resolution
+     * safety is provided by `awaitSettled({skipCurrent: true})`, which
+     * ignores the cached initial DATA from any previous run and resolves
+     * only on a fresh post-subscribe emission of `_terminalResult`.
+     */
+    run(userMessage?: string, signal?: AbortSignal): Promise<LLMResponse | null>;
+    /**
+     * Flip the reactive `aborted` state. Equivalent to setting an external
+     * `AbortSignal` — the pipeline observes and transitions to `"done"`.
+     */
+    abort(): void;
+    destroy(): void;
+}
+declare function agentLoop(name: string, opts: AgentLoopOptions): AgentLoopGraph;
+
+type AgentMemoryOptions<TMem = unknown> = {
+    graph?: GraphOptions;
+    /** LLM adapter for extraction and consolidation. */
+    adapter?: LLMAdapter;
+    /** System prompt for the extractor LLM. */
+    extractPrompt?: string;
+    /** Custom extractFn (overrides adapter + extractPrompt). */
+    extractFn?: (raw: unknown, existing: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
+    /** System prompt for the consolidation LLM. */
+    consolidatePrompt?: string;
+    /** Custom consolidateFn (overrides adapter + consolidatePrompt). */
+    consolidateFn?: (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
+    /** Reactive trigger for consolidation (caller supplies e.g. `fromTimer`). */
+    consolidateTrigger?: NodeInput<unknown>;
+    /** Score function for budget packing (required). */
+    score: (mem: TMem, context: unknown) => number;
+    /** Cost function for budget packing (required). */
+    cost: (mem: TMem) => number;
+    /** Token budget for compact view (default 2000). */
+    budget?: number;
+    /** Context node for scoring. */
+    context?: NodeInput<unknown>;
+    /** Admission filter (default: admit all). */
+    admissionFilter?: (candidate: unknown) => boolean;
+    /** Vector index dimensions (> 0 enables vector index for retrieval). */
+    vectorDimensions?: number;
+    /**
+     * B12: optional accessor for an entry's hierarchical context breadcrumb
+     * (e.g. `["projects", "auth", "tokens"]`). When supplied alongside
+     * `contextWeight > 0`, retrieval applies a score boost for entries whose
+     * context shares a prefix with the query's `context`. Entries without
+     * a breadcrumb are scored flatly.
+     */
+    contextOf?: (mem: TMem) => readonly string[] | undefined;
+    /**
+     * B12: hierarchical context boost multiplier. Score is scaled by
+     * `(1 + contextWeight * sharedDepth / queryDepth)` when both the query
+     * and entry supply a `context`. Default: 0.
+     */
+    contextWeight?: number;
+    /** Extract embedding vector from a memory entry (enables vector index). */
+    embedFn?: (mem: TMem) => readonly number[] | undefined;
+    /** Enable knowledge graph for entity/relation tracking. */
+    enableKnowledgeGraph?: boolean;
+    /** Extract entities and relations from a memory entry. */
+    entityFn?: (key: string, mem: TMem) => {
+        entities?: Array<{
+            id: string;
+            value: unknown;
+        }>;
+        relations?: Array<{
+            from: string;
+            to: string;
+            relation: string;
+            weight?: number;
+        }>;
+    } | undefined;
+    /** 3-tier storage configuration. Omit to use single-tier (existing behavior). */
+    tiers?: MemoryTiersOptions<TMem>;
+    /** Retrieval pipeline configuration. Requires vector index or knowledge graph. */
+    retrieval?: {
+        /** Max candidates from vector search (default 20). */
+        topK?: number;
+        /** KG expansion depth in hops (default 1). */
+        graphDepth?: number;
+    };
+    /** Periodic reflection/consolidation configuration. */
+    reflection?: {
+        /** Interval in ms between consolidation runs (default 300_000 = 5 min). */
+        interval?: number;
+        /** Enable/disable periodic reflection (default true when consolidateFn is available). */
+        enabled?: boolean;
+    };
+};
+/**
+ * Pre-wired agentic memory graph. Sugar over `distill` plus the
+ * `memoryWithVectors` / `memoryWithKG` / `memoryWithTiers` / `memoryRetrieval`
+ * composers. Power users who want a subset of capabilities can call those
+ * composers directly; this class bundles them into one ergonomic Graph subclass.
+ *
+ * Mounts:
+ * - `tiers/*`     — present when `opts.tiers` configured (replaces the
+ *                   default distill bundle).
+ * - `vectors/*`   — present when `opts.vectorDimensions > 0 && opts.embedFn`.
+ * - `knowledge/*` — present when `opts.enableKnowledgeGraph`.
+ * - `retrieval/*` — present when vectors or kg configured.
+ *
+ * When `opts.tiers` is omitted, `store` / `compact` / `size` are added as
+ * top-level nodes on this graph (visible in `describe()` / `explain()`).
+ */
+declare class AgentMemoryGraph<TMem = unknown> extends Graph {
+    readonly distillBundle: DistillBundle<TMem>;
+    readonly compact: Node<Array<{
+        key: string;
+        value: TMem;
+        score: number;
+    }>>;
+    readonly size: Node<number>;
+    /** Vector index bundle (null if not enabled). */
+    readonly vectors: VectorIndexGraph<TMem> | null;
+    /** Knowledge graph (null if not enabled). */
+    readonly kg: KnowledgeGraph<unknown, string> | null;
+    /** Memory tiers bundle (null if not configured). */
+    readonly memoryTiers: MemoryTiersBundle<TMem> | null;
+    /**
+     * The mounted `MemoryWithTiersGraph` subgraph (null when `opts.tiers` was
+     * omitted). Surfaces the inner graph for `describe()` / `explain()` walks
+     * and for callers that need direct access to the tiers subgraph (e.g.
+     * to register additional disposers or attach storage). Companion to
+     * `memoryTiers`, which carries only the bundle's reactive surface (B5e).
+     */
+    readonly tiers: MemoryWithTiersGraph<unknown, TMem> | null;
+    /**
+     * Reactive consumer API. Given a reactive `RetrievalQuery | null` source,
+     * returns a `Node` emitting the packed retrieval results. Composable with
+     * graph topology — subscribe it, chain it into `promptNode`, or switchMap
+     * over a user-input node.
+     *
+     * Each call mounts its own per-input subgraph at
+     * `retrieval::retrieve_${id}` (via `MemoryRetrievalGraph`); concurrent
+     * calls don't share state mirrors. One-shot consumers wrap with
+     * `awaitSettled(retrieveReactive(query))`.
+     *
+     * Null when no retrieval pipeline is configured.
+     *
+     * **QA F-9 (2026-04-30):** the prior `retrieval` / `retrievalTrace`
+     * shared state-node mirrors have been dropped. Use `retrieveReactive`
+     * for per-call reactive results; one-shot trace consumers should
+     * subscribe to the projection's upstream `result` derived directly
+     * via `view.target.resolve("retrieval::retrieve_${id}::result")`.
+     */
+    readonly retrieveReactive: ((queryInput: NodeInput<RetrievalQuery | null>) => Node<ReadonlyArray<RetrievalEntry<TMem>>>) | null;
+    constructor(name: string, source: NodeInput<unknown>, opts: AgentMemoryOptions<TMem>);
+}
+/**
+ * Pre-wired agentic memory graph. Sugar over `distill` plus the
+ * `memoryWithVectors` / `memoryWithKG` / `memoryWithTiers` / `memoryRetrieval`
+ * composers. Power users who want a subset of capabilities can call those
+ * composers directly; this factory bundles them into one ergonomic call.
+ *
+ * Returns an {@link AgentMemoryGraph} subclass instance — `instanceof
+ * AgentMemoryGraph` narrows in callers (e.g. Phase 13.G `agent(spec)`).
+ */
+declare function agentMemory<TMem = unknown>(name: string, source: NodeInput<unknown>, opts: AgentMemoryOptions<TMem>): AgentMemoryGraph<TMem>;
+
+/**
+ * Phase 13.G — `AgentBundle<TIn, TOut>` interface + `class AgentGraph extends Graph`.
+ *
+ * Source: `archive/docs/SESSION-multi-agent-gap-analysis.md` G1 lock B.
+ *
+ * Composes the existing substrate (`agentLoop`, `toolRegistry`,
+ * `agentMemory`) into a typed inbox/outbox subgraph that other parts of a
+ * multi-agent system can wire to. Sibling preset `agent()` (in
+ * `./agents.ts`) is the ergonomic factory; this file is the contract.
+ *
+ * **Cross-cut #1 lock (no `agent.run()`):** caller-side runtime entry is
+ * `bundle.in.emit(input)` + `awaitSettled(bundle.out)`. The legacy
+ * `agentLoop.run()` is still available on `bundle.graph.loop` for
+ * single-shot Promise-bridge use cases, but `agent()` does NOT expose a
+ * `run()` method on the bundle.
+ *
+ * **Memory partition default:** private memory per agent (each `agent(...)`
+ * call creates its own `AgentMemoryGraph` if none passed). Pass an explicit
+ * shared instance for §29 handoff context-transfer.
+ */
+
+/**
+ * Lifecycle status of an {@link AgentGraph}.
+ *
+ * - `idle` — no input has been received since construction or last reset.
+ * - `running` — inputs are flowing through the underlying agentLoop
+ *   (collapses the loop's `thinking` + `acting` substates so consumers
+ *   don't have to model the tool-call inner loop).
+ * - `verifying` — verifier subgraph is in flight (reserved; lights up when
+ *   the verifier slot is added in a future wave per G7 recipe).
+ * - `done` — the most recent input has settled with a verified response.
+ * - `error` — the loop or verifier produced a terminal error.
+ *
+ * **Note (Phase 13.G, 2026-05-01):** v1 of `agent()` has no built-in
+ * verifier slot — `verifying` is reserved but never produced. When a
+ * verifier consumer surfaces, this enum widens (non-breaking type
+ * widening; existing consumers see the same `idle | running | done | error`
+ * subset).
+ */
+type AgentStatus = "idle" | "running" | "verifying" | "done" | "error";
+/**
+ * Aggregated cost for an agent's run, surfaced as a `Node<CostState>` on
+ * the bundle. **Wraps the canonical {@link TokenUsage}** so consumers get
+ * the full provider-disaggregated token classes (cache-read /
+ * cache-write-5m / cache-write-1h / audio / image / video / tool-use /
+ * reasoning / prediction-accepted / prediction-rejected / extensions /
+ * auxiliary non-token costs / raw escape-hatch) without losing fidelity
+ * for downstream pricing. USD conversion is a downstream `derived` over
+ * `usage`.
+ *
+ * - `usage` — accumulated {@link TokenUsage} across all turns of the
+ *   current input.
+ * - `turns` — number of completed agentLoop iterations (LLM invocations).
+ *
+ * **Counter scope:** resets to {@link ZERO_COST} on each new `bundle.in`
+ * emit (per-input cost rather than per-agent-lifetime). Sum across multiple
+ * inputs by snapshotting `cost` at `done` and accumulating externally —
+ * a per-lifetime cost is a downstream `scan` over this.
+ *
+ * **Helpers.** Use `sumInputTokens(usage)` / `sumOutputTokens(usage)` from
+ * `@graphrefly/graphrefly-ts` to flatten to scalars when the caller wants
+ * a single number.
+ */
+interface CostState {
+    readonly usage: TokenUsage;
+    readonly turns: number;
+}
+/** Empty cost. Used as the initial value and the per-input reset baseline. */
+declare const ZERO_COST: CostState;
+/**
+ * Accumulates two {@link TokenUsage} snapshots. All field classes are
+ * summed; optional fields propagate as `undefined` when absent from both
+ * sides, otherwise treated as 0 for the missing side. `auxiliary` and
+ * `extensions` merge by key. `raw` is dropped — it's a per-call escape
+ * hatch, not summable.
+ *
+ * @category extra
+ */
+declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/**
+ * Spec for {@link agent} (in `./agents.ts`). Required fields are minimal —
+ * `name` and `adapter` cover the common case where the input is a string
+ * and the output is the raw `LLMResponse`. Optional fields shape the
+ * agent's behavior:
+ *
+ * - **Mappers** (`inMapper` / `outMapper`) translate between caller-typed
+ *   `TIn` / `TOut` and the loop's internal `string` / `LLMResponse`. Default
+ *   identity mappers are wired automatically when `TIn` extends `string`
+ *   and `TOut` extends `LLMResponse`.
+ * - **`tools`** is a reactive `NodeInput<readonly ToolDefinition[]>` —
+ *   `agent()` subscribes and reconciles the underlying `toolRegistry`'s
+ *   registrations on each emit. Static-array form is also accepted.
+ * - **`memory`** is an explicit `AgentMemoryGraph` instance for shared
+ *   memory across agents (§29 handoff context transfer). Default: private
+ *   memory per agent (each `agent()` call mints its own).
+ * - **`maxIterations`** caps the underlying agentLoop's tool-call inner
+ *   loop. Default 10 (matches `agentLoop`).
+ * - **Verifier slot** is intentionally not in v1 — G7 reframe locks it as
+ *   a caller-composed recipe. When a real consumer surfaces, a
+ *   `verifier?: (out: Node<TOut>) => NodeInput<VerifierResult>` field
+ *   lands here additively.
+ */
+interface AgentSpec<TIn, TOut> {
+    /** Local mount name when wired to a parent graph. Required. */
+    readonly name: string;
+    /** LLM adapter for the underlying agentLoop. Required. */
+    readonly adapter: LLMAdapter;
+    /** Optional system prompt. Static today; reactive widening pending. */
+    readonly systemPrompt?: string;
+    /**
+     * Optional reactive tool list. When a Node, the agent subscribes and
+     * reconciles the underlying `toolRegistry` registrations on each emit
+     * (additions registered, removals unregistered). When a static array,
+     * tools are registered once at construction.
+     */
+    readonly tools?: Node<readonly ToolDefinition[]> | readonly ToolDefinition[];
+    /**
+     * Optional shared memory. Default: private (agent mints its own
+     * `AgentMemoryGraph` if needed; not yet wired into the loop's chat —
+     * that wiring is a separate follow-up). Pass an explicit instance to
+     * share memory across agents for §29 handoff context transfer.
+     */
+    readonly memory?: AgentMemoryGraph<unknown>;
+    /**
+     * Maps caller-typed input → string for the underlying chat. Defaults to
+     * identity when `TIn extends string`; required otherwise.
+     */
+    readonly inMapper?: (input: TIn) => string;
+    /**
+     * Maps the agentLoop's `LLMResponse` → caller-typed output. Defaults to
+     * identity when `TOut extends LLMResponse`; required otherwise.
+     */
+    readonly outMapper?: (response: LLMResponse) => TOut;
+    /** Caps tool-call inner-loop iterations. Default 10. */
+    readonly maxIterations?: number;
+    /** Escape hatch for non-core fields. Surfaced in `describe()` via meta. */
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Public contract for an agent — typed inbox/outbox + lifecycle / cost
+ * observables + the underlying graph for inspection / mounting.
+ *
+ * **Reactive entry:** caller writes to `in` (e.g. `bundle.in.emit(input)`).
+ * The agent reactively kicks the underlying loop and produces `out`.
+ *
+ * **Reactive exit:** caller reads `out` via `subscribe` (continuous) or
+ * `awaitSettled(out)` (single-shot). Both `in` and `out` stay SENTINEL
+ * (`cache === undefined`) until the first real emission — no `null`
+ * push-on-subscribe trap (per `feedback_use_prevdata_for_sentinel`).
+ *
+ * **Cross-graph wiring:** the bundle's `graph` is mountable under any
+ * parent via `parent.mount(name, bundle.graph)`. After mount, the bundle's
+ * Nodes are reachable through both the bundle reference (direct) and via
+ * `parent.node("<name>::out")` etc. (qualified path).
+ */
+interface AgentBundle<TIn, TOut> {
+    readonly in: Node<TIn>;
+    readonly out: Node<TOut>;
+    readonly status: Node<AgentStatus>;
+    readonly cost: Node<CostState>;
+    readonly graph: AgentGraph<TIn, TOut>;
+}
+/**
+ * Graph subclass implementing {@link AgentBundle}. Mounts an inner
+ * {@link AgentLoopGraph} at `loop/`; `in` / `out` / `status` / `cost`
+ * surface the bundle contract as top-level nodes.
+ *
+ * Construction is internal — use the {@link agent} factory in
+ * `./agents.ts` for normal use. Direct `new AgentGraph(name, spec)` is
+ * supported for callers that want full control over mount order.
+ *
+ * **Topology:**
+ * ```
+ * <name>
+ * ├── loop                  (AgentLoopGraph subgraph)
+ * │   ├── chat
+ * │   ├── tools
+ * │   ├── status / turn / aborted / lastResponse / ...
+ * ├── in                    (Node<TIn>, SENTINEL until first emit)
+ * ├── out                   (Node<TOut>, SENTINEL until first response)
+ * ├── status                (Node<AgentStatus>, mirror of loop.status)
+ * └── cost                  (Node<CostState>)
+ * ```
+ *
+ * **Lifecycle:**
+ * - On `in` emit: `inMapper` projects to `string`; appended to
+ *   `loop.chat`; loop status reset (`turn=0`, `aborted=false`,
+ *   `status="thinking"`); per-input cost counters reset to zero.
+ * - On `loop.lastResponse` emit: cost rolls forward; `out` emits
+ *   `outMapper(response)`.
+ * - On `loop.status="done"`: agent's status emits `"done"`.
+ * - On `loop.status="error"` (or any ERROR propagation): agent's status
+ *   emits `"error"`.
+ */
+declare class AgentGraph<TIn, TOut> extends Graph {
+    /** The agent's typed inbox. Writable; `in.emit(value)` kicks the loop. */
+    readonly in: Node<TIn>;
+    /** The agent's typed outbox. SENTINEL until first response. */
+    readonly out: Node<TOut>;
+    /** Lifecycle status (translated from the underlying loop's substates). */
+    readonly status: Node<AgentStatus>;
+    /** Cumulative cost for the current / most-recent input. */
+    readonly cost: Node<CostState>;
+    /** The underlying agentLoop — exposed for inspection / advanced wiring. */
+    readonly loop: AgentLoopGraph;
+    /** Optional shared memory subgraph (mounted at `memory/` if provided). */
+    readonly memory: AgentMemoryGraph<unknown> | null;
+    constructor(spec: AgentSpec<TIn, TOut>, opts?: GraphOptions);
+}
+
+/**
+ * Phase 13.H — `agent(spec)` preset + `presetRegistry` sugar.
+ *
+ * Source: `archive/docs/SESSION-multi-agent-gap-analysis.md` G1 + G2.
+ *
+ * `agent()` is the ergonomic factory — given a parent Graph and an
+ * `AgentSpec`, mints an `AgentGraph`, mounts it under the parent at
+ * `spec.name`, and returns the `AgentBundle` contract.
+ *
+ * `presetRegistry()` is thin sugar over `reactiveMap` — a typed reactive
+ * map of `<id, preset>`. Pairs with `materialize` (Phase 13.C) for
+ * dynamic preset selection: callers store specs / factories / configs in
+ * the registry and `materialize` mounts the matching one based on a
+ * routing key.
+ *
+ * **Cross-cut #1 lock:** no `agent.run()` imperative sugar — caller-side
+ * runtime is `bundle.in.emit(input)` + `awaitSettled(bundle.out)`.
+ */
+
+/**
+ * Mints an {@link AgentGraph} from `spec`, mounts it under `parent` at
+ * `spec.name`, and returns the {@link AgentBundle} contract.
+ *
+ * **Default type parameters.** When called without explicit type params,
+ * `TIn` defaults to `string` and `TOut` to `LLMResponse` — the common
+ * case where the caller writes a user message and reads the raw response.
+ * Custom types require both `inMapper` and `outMapper` in the spec; the
+ * default mappers throw at runtime if `TIn` / `TOut` aren't string /
+ * LLMResponse.
+ *
+ * **Memory partition default.** Each `agent()` call mints its own
+ * `AgentMemoryGraph` if `spec.memory` is omitted (private memory; the
+ * common case). Pass an explicit shared instance — e.g.
+ * `agent(parent, { ..., memory: sharedMemory })` for two agents — to
+ * implement §29 handoff context transfer.
+ *
+ * **Reactive entry / exit:**
+ * - `bundle.in.emit(input)` kicks the loop reactively (no imperative
+ *   `.run()` per cross-cut #1 lock).
+ * - `awaitSettled(bundle.out, { skipCurrent: true })` resolves on the
+ *   first response after the kick. `skipCurrent` matters for the second
+ *   call onward — `out` caches the prior response.
+ *
+ * **Mounting.** The factory mounts under `parent.mount(spec.name, ...)`.
+ * The slot name must be free on `parent` at construction time. To keep
+ * the agent unmounted, construct `new AgentGraph(spec)` directly.
+ *
+ * @example
+ * ```ts
+ * import { agent, awaitSettled, Graph } from "@graphrefly/graphrefly-ts";
+ *
+ * const parent = new Graph("parent");
+ * const a = agent(parent, {
+ *   name: "researcher",
+ *   adapter: openaiAdapter,
+ *   systemPrompt: "Research the user's question carefully.",
+ * });
+ * a.in.emit("What's the capital of France?");
+ * const resp = await awaitSettled(a.out, { skipCurrent: true });
+ * ```
+ *
+ * @category patterns
+ */
+declare function agent<TIn = string, TOut = LLMResponse>(parent: Graph, spec: AgentSpec<TIn, TOut>): AgentBundle<TIn, TOut>;
+/**
+ * The bundle returned by {@link presetRegistry}. Wraps a `reactiveMap`
+ * with imperative `put` / `remove` shortcuts and exposes the underlying
+ * `registry` for direct reactive consumption (`.entries` is a
+ * `Node<ReadonlyMap<string, TPreset>>`).
+ *
+ * Use the `registry.entries` Node directly with {@link materialize} (Phase
+ * 13.C) — pass it as the `factories` argument when `TPreset` is itself
+ * a `() => Graph` factory thunk, or transform via `derived` when
+ * `TPreset` is a richer spec type that needs a `spec → factory` adapter.
+ */
+interface PresetRegistryBundle<TPreset> {
+    /**
+     * The underlying reactive map. `registry.entries` is the
+     * `Node<ReadonlyMap<string, TPreset>>` — pass directly to
+     * {@link materialize} when preset shape matches the factories arg.
+     */
+    readonly registry: ReactiveMapBundle<string, TPreset>;
+    /** Imperative add / replace. Always emits a fresh snapshot. */
+    put(id: string, preset: TPreset): void;
+    /** Imperative remove. Returns `true` if the id was present. */
+    remove(id: string): boolean;
+}
+/**
+ * Thin sugar over `reactiveMap` — a typed registry of `<id, preset>` for
+ * agent / strategy / persona / skill catalogs.
+ *
+ * **Generic over preset shape.** `TPreset` is open — could be an
+ * {@link AgentSpec}, a `() => Graph` factory thunk, a static config
+ * object, or anything else. Decoupled from `agent()` so the same primitive
+ * powers harnessLoop strategy registries, pipelineGraph stage catalogs,
+ * etc.
+ *
+ * **Composes with `materialize`.** When `TPreset` is a `() => Graph`
+ * factory, pass `registry.entries` directly to
+ * {@link materialize} as the `factories` argument. When `TPreset` is a
+ * spec, transform via `derived` to build a `Map<id, () => Graph>` adapter:
+ *
+ * ```ts
+ * const presets = presetRegistry<AgentSpec<string, LLMResponse>>();
+ * presets.put("researcher", { name: "researcher", adapter, systemPrompt: "..." });
+ *
+ * // Adapter: spec → factory.
+ * const factories = derived(
+ *   [presets.registry.entries],
+ *   ([m]) => new Map(
+ *     [...m].map(([id, spec]) => [id, () => new AgentGraph(spec)]),
+ *   ),
+ * );
+ * const slot = materialize(activeKey, factories, parent);
+ * ```
+ *
+ * @param initial - Optional initial entries.
+ * @returns {@link PresetRegistryBundle}.
+ *
+ * @category patterns
+ */
+declare function presetRegistry<TPreset>(initial?: ReadonlyMap<string, TPreset>): PresetRegistryBundle<TPreset>;
+
+export { type AgentBundle as A, type CostState as C, type PresetRegistryBundle as P, ZERO_COST as Z, AgentGraph as a, AgentLoopGraph as b, type AgentLoopOptions as c, type AgentLoopStatus as d, AgentMemoryGraph as e, type AgentMemoryOptions as f, type AgentSpec as g, type AgentStatus as h, addUsage as i, agent as j, agentLoop as k, agentMemory as l, presetRegistry as p };