@warble/claude-agent-sdk 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,1143 @@
+import { Query, Options, CanUseTool, HookCallbackMatcher, NonNullableUsage, ModelUsage, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * Dispatch-time error — the TS analogue of the Rust back-end's `DispatchError`.
+ *
+ * Every loud-fail in this back-end (unknown IR version, unsupported enum "wall-hit", capability
+ * `fail`, undefined tier) throws a `DispatchError`; the CLI turns it into a non-zero exit + message.
+ */
+declare class DispatchError extends Error {
+    constructor(message: string);
+}
+
+/** The deliberately small host-facing contract for provider-owned model discovery. */
+declare const MODEL_CATALOG_VERSION: 1;
+interface ModelCatalogModel {
+    model: string;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+    reasoningEfforts?: Array<{
+        value: string;
+        displayName: string;
+        description?: string;
+    }>;
+}
+type ModelCatalogUnavailableCode = "not_authenticated" | "runtime_unavailable" | "timeout" | "protocol_error";
+type ModelCatalogResult = {
+    version: typeof MODEL_CATALOG_VERSION;
+    status: "ready";
+    provider: "claude";
+    models: ModelCatalogModel[];
+} | {
+    version: typeof MODEL_CATALOG_VERSION;
+    status: "unavailable";
+    provider: "claude";
+    code: ModelCatalogUnavailableCode;
+    retryable: boolean;
+};
+type QueryFactory = (params: {
+    prompt: AsyncIterable<unknown>;
+    options: {
+        cwd: string;
+        tools: string[];
+        mcpServers: [];
+        settingSources: [];
+        abortController: AbortController;
+    };
+}) => Query;
+interface DiscoverClaudeModelsOptions {
+    cwd?: string;
+    timeoutMs?: number;
+    /** Test seam; production always uses the installed Agent SDK query factory. */
+    queryFactory?: QueryFactory;
+}
+/**
+ * Ask the authenticated Agent SDK for its model picker data without yielding a user message.
+ * The Query object still owns a subprocess/session, so every exit path interrupts, aborts, and
+ * returns its iterator before exposing the narrow catalog result.
+ */
+declare function discoverClaudeModels(options?: DiscoverClaudeModelsOptions): Promise<ModelCatalogResult>;
+
+/** `realization_kind` — how a component is realized. */
+type RealizationKind = "skill" | "tool" | "gated-tool";
+/** Component family. */
+type ComponentType = "analytical" | "assertive" | "mutating" | "constitutive" | "orchestrating";
+/** `trigger.kind`. */
+type TriggerKind = "one_shot" | "scheduled" | "event";
+/** `effect.outcome.kind`. */
+type OutcomeKind = "none" | "assertion" | "mutation" | "dispatch";
+declare const REALIZATION_KINDS: readonly RealizationKind[];
+declare const COMPONENT_TYPES: readonly ComponentType[];
+declare const TRIGGER_KINDS: readonly TriggerKind[];
+declare const OUTCOME_KINDS: readonly OutcomeKind[];
+interface ContextBinding {
+    project: string;
+    binding_mode: string;
+    /**
+     * Fine-grained resolved binding (IR v0.3): metrics/dimensions/grains + lineage summary the
+     * front-end learned from the bound semantic layer. Carried through and tolerated; this back-end
+     * does not yet consume it (it drives off the coarse project path).
+     */
+    resolved?: unknown;
+}
+/**
+ * The IR's profile-level `config` block. Empty since IR `0.6` removed `tier_policy` (an inert
+ * field no back-end read); kept as a type so future profile-level config is an additive change.
+ */
+type IrConfig = Record<string, never>;
+/**
+ * A per-step LLM call. `tier` is an **open string** (standard core: `strong`/`cheap`; custom names
+ * allowed) resolved to a concrete model at dispatch by the model config. The v0.2 named I/O contract
+ * (`consumes`/`produces`) + per-step `prompt` make a step realizable in isolation; an in-loop runtime
+ * like this one carries context itself and does not need them for single-session delegation.
+ */
+interface LlmCall {
+    name: string;
+    tier: string;
+    consumes: string[];
+    produces: string | null;
+    prompt: string;
+    conditional: boolean;
+    /**
+     * The closed-vocabulary guard deciding whether a `conditional` step runs (IR v0.3+; see
+     * `docs/spec/ir-schema.md`). Realized by the hybrid-staged executor (`run.ts`, `conditional.ts`):
+     * an `on_failure` guard whose target is the adjacent producing step folds that step into a bounded
+     * repair turn; every other guard shape is a deterministic run/skip decision. The single/sdk-split
+     * paths ride the SDK's own in-loop `query()`, where Claude judges the condition emergently from the
+     * prompt text instead.
+     */
+    when: WhenGuard | null;
+}
+/**
+ * A closed-vocabulary guard on a conditional `llm_call`: `guard` is one of `on_failure` /
+ * `on_flag` / `on_missing`, `target` is the guard-specific argument. See `docs/spec/ir-schema.md`.
+ */
+interface WhenGuard {
+    guard: string;
+    target: string;
+}
+interface Guardrail {
+    name: string;
+    locked: boolean;
+    scope: string | null;
+    threshold?: unknown;
+}
+/** A context precondition a component requires to hold before it runs (e.g. `has_metric`). */
+interface Precondition {
+    predicate: string;
+    args?: Record<string, unknown>;
+}
+/**
+ * A component parameter, either bound at dispatch time (`bind`, with an optional `default`) or
+ * sourced from context (`source`). Exactly one of `bind`/`source` is expected per the schema.
+ */
+interface ParamSpec {
+    name: string;
+    bind?: string;
+    source?: string;
+    default?: unknown;
+}
+/** An authored evaluation spec: which eval template to run and which metrics it scores. */
+interface EvalSpec {
+    template_ref: string;
+    metrics: string[];
+}
+interface Trigger {
+    kind: TriggerKind;
+}
+/** A typed render block: a type plus its field-name → field-type schema (echoed verbatim). */
+interface RenderBlock {
+    type: string;
+    fields: Record<string, string>;
+}
+interface Outcome {
+    kind: OutcomeKind;
+    verdict_type?: string;
+    emits?: string[];
+    target?: string;
+    change_type?: string;
+    routable_scope?: unknown;
+}
+interface Effect {
+    render_blocks: RenderBlock[];
+    outcome: Outcome;
+}
+/** One evaluated `context_precondition` and its outcome (IR v0.3: structured, was a string list). */
+interface PreconditionCheck {
+    predicate: string;
+    outcome: string;
+}
+interface PreconditionResult {
+    status: string;
+    checks: PreconditionCheck[];
+}
+interface ComponentNode {
+    id: string;
+    verb: string;
+    type: ComponentType;
+    realization_kind: RealizationKind;
+    context_binding: ContextBinding;
+    precondition_result: PreconditionResult;
+    prompt_fragment: string;
+    llm_calls: LlmCall[];
+    guardrails: Guardrail[];
+    trigger: Trigger;
+    required_capabilities: string[];
+    borrowed_actions: string[];
+    eval_ref: string;
+    effect: Effect;
+    context_requirements: string[];
+    context_precondition: Precondition[];
+    params: ParamSpec[];
+    eval: EvalSpec | null;
+    /** Optional free-form framing shared by every step of this component (see `docs/spec/ir-schema.md`). */
+    brief?: string;
+}
+interface WarbleIr {
+    warble_ir_version: string;
+    profile: string;
+    context_binding: ContextBinding;
+    config: IrConfig;
+    components: ComponentNode[];
+}
+/**
+ * IR versions this back-end understands. Older versions (0.1, 0.2) are no longer accepted now that
+ * the front-end only emits 0.3 — see the compatibility matrix in `docs/spec/ir-schema.md`. An
+ * unrecognized version is a loud-fail rather than a silent best-effort read.
+ */
+declare const SUPPORTED_IR_VERSIONS: readonly string[];
+/**
+ * Parse + validate a Warble IR JSON document. Throws a {@link DispatchError} (loud-fail) on an
+ * unsupported version, a missing/mistyped load-bearing field, or an out-of-vocabulary enum value.
+ */
+declare function parseIr(json: string): WarbleIr;
+/** Distinct tier names across a node's `llm_calls`, order-preserving. */
+declare function distinctTiers(calls: readonly LlmCall[]): string[];
+
+/**
+ * Target capability profiles — the declarative side of the capability model
+ * (`docs/spec/capability-model.md`), owned by THIS back-end in TypeScript.
+ *
+ * A runtime target is `engine × mode`. This back-end declares one target, `claude-agent-sdk:local`:
+ * the local `@anthropic-ai/claude-agent-sdk` `query()` loop (subscription login, compute on the
+ * user's machine). The shared thing across back-ends is the IR + the capability-model
+ * *semantics* (native / realize-via / degrade / fail, criticality, provided_by); the profile *data*
+ * is target-specific and each back-end writes its own. So this file is the TS sibling of
+ * the Rust file target's `targets.rs`, not a shared table.
+ *
+ * How `local` differs from the Rust file target's `claude-code:headless` (the point of the second
+ * back-end):
+ *   - `llm:per_step_tier`        native (in-loop per-call model)   ← headless: realize-via(subagents)
+ *   - `structured_output_capture` native (message stream)          ← headless: native(stream-json)
+ *   - `render_contract`          realize-via(warble-render)         ← headless: realize-via(html-file)
+ * The rest match headless, including the safety-critical loud-fails (human_approval, blast_radius).
+ */
+/** One of the four resolution outcomes a capability can take on a target. */
+type CapabilityOutcome = "native" | "realize-via" | "degrade" | "fail";
+/** Who supplies a resolved capability. */
+type ProvidedBy = "runtime" | "warble" | "none";
+/**
+ * safety-critical capabilities must never silently degrade — unsupported means the resolution pass
+ * aborts. required/best-effort may degrade with a warning recorded in the report.
+ */
+type Criticality = "safety-critical" | "required" | "best-effort";
+interface CapabilityEntry {
+    outcome: CapabilityOutcome;
+    via: string | null;
+    provided_by: ProvidedBy;
+    criticality: Criticality;
+    note: string | null;
+}
+type CapabilityProfile = Record<string, CapabilityEntry>;
+/** The one target this back-end declares (engine × mode). */
+type TargetId = "claude-agent-sdk:local";
+declare const DEFAULT_TARGET: TargetId;
+declare function isKnownTarget(value: string): value is TargetId;
+declare function knownTargetNames(): readonly string[];
+/** Capability profile for `claude-agent-sdk:local`. */
+declare function localProfile(): CapabilityProfile;
+/** Resolve a target id to its capability profile, or `null` if unknown. */
+declare function profileFor(targetId: string): CapabilityProfile | null;
+
+interface ResolvedCapability {
+    capability: string;
+    outcome: CapabilityOutcome;
+    provided_by: ProvidedBy;
+    criticality: Criticality;
+    note?: string;
+}
+type ResolutionReport = ResolvedCapability[];
+/** Union of declared + implied required capabilities, de-duplicated, order-preserving. */
+declare function collectRequiredCapabilities(node: ComponentNode): string[];
+declare function resolveCapabilities(node: ComponentNode, targetId: string, profile: CapabilityProfile): ResolutionReport;
+/**
+ * Resolve one node's required capabilities against `targetId`, erroring on any `fail` outcome
+ * (no silent degradation). Callers must not dispatch when this throws.
+ */
+declare function resolveNodeCapabilities(node: ComponentNode, targetId: string): ResolutionReport;
+/**
+ * Read-only inspection counterpart to `resolveNodeCapabilities`. It returns
+ * the same report, including a failed entry, but does not legalize execution.
+ * Only display-only callers may use this; dispatch/emit/chat retain the loud
+ * failure above.
+ */
+declare function inspectNodeCapabilities(node: ComponentNode, targetId: string): ResolutionReport;
+
+/**
+ * Which provider serves a tier's model — an **open string**, opaque to warble (mirrors how the IR
+ * treats `tier`; see `docs/spec/binding-spec.md`). Two well-known values get behavior baked into
+ * `TierBinding` parsing below (`ANTHROPIC_PROVIDER`, the default; `OPENAI_COMPAT_PROVIDER`, which
+ * requires `endpoint`), but warble does **not** validate this field against a fixed provider list —
+ * any other string is a valid, warble-unrecognized provider that passes through unchanged.
+ * Rejecting a genuinely unsupported provider is the consuming harness/back-end's job (its
+ * per-provider adapter registry), never warble's — warble stays opaque pass-through.
+ */
+type Provider = string;
+/**
+ * A tier's full runtime binding: which `provider` serves it, at what `endpoint` (OpenAI-compat only),
+ * running which `model`. The shorthand YAML form `tier: <model>` is `{ provider: 'anthropic',
+ * endpoint: null, model }` — so existing configs (and every all-cloud path) are byte-for-byte
+ * unchanged. Per-step provider routing reads `provider`/`endpoint`; `require()` reads `model`.
+ */
+interface TierBinding {
+    provider: Provider;
+    endpoint: string | null;
+    model: string;
+}
+/**
+ * An ordered tier→binding map. Declaration order is priority: earlier tiers are "stronger" — used to
+ * pick the single model when a multi-tier component collapses to one call.
+ */
+declare class ModelConfig {
+    /** `[tier name, binding]` in declaration order (earliest = strongest). */
+    private readonly tiers;
+    private constructor();
+    /** The Agent SDK defaults, matching the file target: strong→opus, cheap→haiku, orchestrator→sonnet. */
+    static default(): ModelConfig;
+    /**
+     * Build from the inline `--strong/--cheap/--orchestrator` flags. Inline flags are always
+     * Anthropic-provider aliases — provider/endpoint routing is `--models-config` only, so a non-alias
+     * inline flag still loud-fails on the SDK split path (unchanged behavior).
+     */
+    static fromFlags(strong: string, cheap: string, orchestrator: string): ModelConfig;
+    /**
+     * Parse a `--models-config` YAML document — the same shape the file target accepts. A tier value is
+     * EITHER a bare model-alias string (Anthropic shorthand) OR a `{ provider, endpoint?, model }` map:
+     *
+     * ```yaml
+     * tiers:
+     *   strong: opus                          # shorthand ⇒ provider: anthropic
+     *   cheap:                                # structured binding (docs/spec/capability-model.md §7.2)
+     *     provider: openai_compat
+     *     endpoint: http://localhost:11434/v1
+     *     model: qwen2.5
+     *   orchestrator: sonnet                  # reserved: the per-step-tier driver
+     * ```
+     */
+    static fromYaml(text: string): ModelConfig;
+    private bindingFor;
+    /** Priority rank of a tier (declaration order); unknown tiers rank last. */
+    private rank;
+    private tierNames;
+    /** The model a tier maps to, or a loud-fail naming the undefined tier. */
+    require(tier: string): string;
+    /**
+     * The full `{provider, endpoint, model}` binding a tier maps to (see docs/spec/capability-model.md
+     * §7.2), or a loud-fail.
+     * The per-step provider router (route.ts) reads this to send a step cloud-vs-local.
+     */
+    binding(tier: string): TierBinding;
+    /** The model for the reserved `orchestrator` tier, or a loud-fail if a config omitted it. */
+    orchestrator(): string;
+    /** The model for a single collapsed call: the strongest (lowest-rank) tier among the calls. */
+    collapsedModel(calls: readonly LlmCall[]): string;
+    /** Validate every step tier in the IR maps to a model (front-loaded so dispatch is infallible). */
+    validate(ir: WarbleIr): void;
+}
+
+/**
+ * Per-step provider routing — the hybrid-LLM core (see docs/spec/capability-model.md §7.2).
+ *
+ * The IR only knows *tiers*; the `--models-config` binding (models.ts) resolves each tier to a
+ * `{ provider, endpoint, model }`. When every step's provider is `anthropic`, the existing single
+ * `query()` loop (options.ts: single / sdk-split path) realizes the component and this module changes
+ * nothing. When ANY step binds to a non-Anthropic provider (e.g. ollama over OpenAI-compat), that step
+ * CANNOT ride the SDK `agents[].model` mechanism — that field is a restricted `sonnet|opus|haiku|inherit`
+ * alias union and loud-fails on anything else (SDK-NOTES.md #1). So the back-end must drive the steps
+ * itself: run each step as an isolated invocation on its own provider and marshal state between them via
+ * the IR's `consumes`/`produces` contract. That staged executor is the "hybrid-staged" mode.
+ *
+ * This module is PURE (no SDK, no network): it resolves the per-step bindings, decides the routing
+ * mode, and builds the marshaling messages. The actual per-step execution (a `query()` for cloud
+ * steps, an OpenAI-compat call for local steps) lives in run.ts. Keeping the decision pure is what
+ * lets the whole hybrid contract be unit-tested offline, with no ollama and no Claude subscription.
+ *
+ * Invariant (spike D2): none of this is in the IR, the components, or the profile — hybrid is entirely
+ * a layer-3 binding + back-end realization concern. The same compiled IR runs all-cloud or hybrid; only
+ * the injected `--models-config` differs.
+ */
+
+/** A step with its tier resolved to a concrete `{provider, endpoint, model}` binding + its IO contract. */
+interface StagedStep {
+    name: string;
+    tier: string;
+    provider: Provider;
+    endpoint: string | null;
+    model: string;
+    consumes: string[];
+    produces: string | null;
+    prompt: string;
+    conditional: boolean;
+    /** The closed-vocabulary guard deciding run/skip/repair for a `conditional` step; `null` when
+     *  `conditional` is false. Realized by run.ts's staged executor (see conditional.ts). */
+    when: WhenGuard | null;
+}
+/**
+ * How a component's steps are realized:
+ *  - `single`        — one tier (or a tier collapse), one Anthropic `query()`. Existing path.
+ *  - `sdk-split`     — >1 Anthropic tier, per-step subagents in one `query()` via `agents`. Existing path.
+ *  - `hybrid-staged` — ≥1 non-Anthropic provider; the back-end drives steps itself, one isolated
+ *                      invocation per step, marshaling `produces`→`consumes`.
+ */
+type RoutingMode = "single" | "sdk-split" | "hybrid-staged";
+interface RoutingPlan {
+    mode: RoutingMode;
+    /** Per-step resolved bindings (order = IR order). */
+    steps: StagedStep[];
+    /** Distinct providers across the steps, order-preserving. */
+    providers: Provider[];
+}
+/** Resolve every `llm_call`'s tier to a concrete binding, preserving IR order. Pure. */
+declare function resolveStagedSteps(node: ComponentNode, models: ModelConfig): StagedStep[];
+/** Distinct providers across resolved steps, order-preserving. */
+declare function distinctProviders(steps: readonly StagedStep[]): Provider[];
+/** True when any step binds to a non-Anthropic provider — the trigger for the hybrid-staged path. */
+declare function usesLocalProvider(steps: readonly StagedStep[]): boolean;
+/**
+ * Decide the routing mode for a component under a binding. `anthropicSplit` is the existing
+ * per-step-tier split decision (owned by options.ts, passed in to keep a single source of truth):
+ * it only applies when every provider is Anthropic.
+ */
+declare function planProviderRouting(node: ComponentNode, models: ModelConfig, anthropicSplit: boolean): RoutingPlan;
+/** A chat message for an isolated per-step invocation (both providers speak this shape). */
+interface StepMessage {
+    role: "system" | "user";
+    content: string;
+}
+/**
+ * Build the messages for one staged step: the step's own prompt as the system message, and the user
+ * message = the question plus each consumed slot's value marshaled in by name (the `produces`→`consumes`
+ * hand-off). This is the same isolated-invocation contract the IR already carries for the file target's
+ * subagents (ir.ts `consumes`/`produces`), generalized here across providers.
+ */
+declare function buildStepMessages(step: StagedStep, question: string, slots: Readonly<Record<string, string>>): StepMessage[];
+
+/**
+ * Minimal OpenAI-compatible chat client for the hybrid-staged path (see docs/spec/capability-model.md §7.2).
+ *
+ * A local step (provider `openai_compat`, e.g. ollama's `http://localhost:11434/v1`) is executed by
+ * calling `POST {endpoint}/chat/completions` directly — NOT through the Claude SDK, whose `agents[].model`
+ * is a restricted alias union that loud-fails on a local model id (SDK-NOTES.md #1). ollama speaks the
+ * OpenAI Chat Completions shape, not the Anthropic Messages shape, so this is a distinct, deliberately
+ * tiny client — no streaming, no tools, no retries. It is the "third provider-aware back-end" embryo:
+ * enough to prove a per-step local model can be marshaled into a cloud run, not a production LLM client.
+ *
+ * Live-gated: exercised only when an ollama (or other OpenAI-compat) endpoint is reachable. The request
+ * SHAPING is unit-tested via {@link buildChatRequest} with no network.
+ */
+
+interface ChatRequest {
+    model: string;
+    messages: StepMessage[];
+    stream: false;
+    /** Deterministic-leaning default; a local step is a bounded transform, not open-ended generation. */
+    temperature: number;
+}
+/** Build the JSON body for an OpenAI-compatible `/chat/completions` call. Pure (no network). */
+declare function buildChatRequest(model: string, messages: StepMessage[]): ChatRequest;
+/** Extract the assistant text from an OpenAI-compatible completion response. Pure. */
+declare function extractCompletionText(body: unknown): string;
+interface CallLocalOptions {
+    endpoint: string;
+    model: string;
+    messages: StepMessage[];
+    /** Optional bearer token (ollama ignores it; other OpenAI-compat servers may require it). */
+    apiKey?: string;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Call an OpenAI-compatible chat endpoint and return the assistant text. Live-gated (needs a reachable
+ * endpoint); the request/response shaping is covered by {@link buildChatRequest} /
+ * {@link extractCompletionText} tests, and a stubbed `fetchImpl` can drive this end-to-end offline.
+ */
+declare function callOpenAiCompat(opts: CallLocalOptions): Promise<string>;
+
+/**
+ * IR enum → `query({options})` mapping — the core of this back-end, the TS analogue of the
+ * file target's `emit.rs`. Keyed on the **three orthogonal IR enums** (`realization_kind`,
+ * `effect.outcome.kind`, `trigger.kind`), never on a component's id/verb: adding another component
+ * of an existing type changes 0 lines here. Enum values this target does not yet
+ * realize fail loudly ("wall-hit"), mirroring `emit.rs::unsupported`.
+ *
+ * This module is pure/data: it builds the serializable `query()` options + a metadata report. The
+ * live callbacks — `canUseTool` runtime enforcement — are attached by `run.ts` from `guardrails.ts`,
+ * so the mapping stays testable offline.
+ */
+
+type RenderFlavor = "programmatic" | "prompt";
+declare const DEFAULT_RENDER_FLAVOR: RenderFlavor;
+declare function parseRenderFlavor(value: string): RenderFlavor;
+/** Bash rule patterns denied outright (defense in depth; canUseTool is the semantic gate). */
+declare const DESTRUCTIVE_BASH_DENY: string[];
+/**
+ * Per-step-tier split: a component whose steps span >1 tier. Realized in-loop via SDK `agents`.
+ * Realization-independent (see `resolve.ts::impliedCapabilities`) — driven purely by IR shape
+ * (>1 distinct step tier), never by `realization_kind` nor by whether the component happens to
+ * also *declare* `llm:per_step_tier` itself: that declaration is shape-implied, not authored, so
+ * requiring it redundantly would reintroduce the same silent-collapse failure for a tool/gated-tool
+ * component that never bothered to self-declare a capability the compiler already derives for it.
+ */
+declare function shouldSplitPerStepTier(node: ComponentNode): boolean;
+type GateKind = "realize" | "degrade" | "none";
+/**
+ * How a RUNTIME render failure (`warble render` exiting non-zero, after the gate already resolved to
+ * `realize`) should be handled — distinct from `GateKind`'s `"degrade"`, which is a DESIGN-TIME
+ * capability degrade (no artifact-write surface at all, so no render is even attempted). Derived from
+ * the resolved `render_contract` capability's criticality: `best-effort` → `"degrade"` (fall back to
+ * the agent's own text, per the capability model's "best-effort may degrade" rule); `required` /
+ * `safety-critical` → `"fail"` (never silently degrade).
+ */
+type GateFailureMode = "degrade" | "fail";
+interface RenderGate {
+    kind: GateKind;
+    scope: string | null;
+    flavor: RenderFlavor | null;
+    /** Only meaningful when `kind === "realize"` (a runtime render call actually happens). Optional so
+     *  the facet stays additive: a consumer that doesn't know about it sees `undefined` and must default
+     *  to today's hard-fail behavior, never assume degrade. */
+    onFailure?: GateFailureMode;
+}
+interface ToolPlan {
+    /** Base built-in tool set made available to the agent (`tools` option). */
+    tools: string[];
+    /** Auto-allowed without a permission check. */
+    allowedTools: string[];
+    /** Hard-removed (defense in depth). */
+    disallowedTools: string[];
+}
+interface DispatchMeta {
+    verb: string;
+    target: string;
+    readOnly: boolean;
+    split: boolean;
+    render: RenderGate;
+    /** True when the outcome is an `assertion`: the final message is a verdict envelope (status block). */
+    assertion: boolean;
+    /** True when the outcome is a `mutation`: the final message is a diff/apply envelope (gated). */
+    mutation: boolean;
+    model: string;
+    /** Subagent tier→model, present only on the split path. */
+    subagentModels: Record<string, string>;
+    tierCollapseNote: string | null;
+    /** How the steps are realized (hybrid-LLM spike): single | sdk-split | hybrid-staged. */
+    mode: RoutingMode;
+    /** Distinct providers across the steps (order-preserving). `["anthropic"]` on the existing paths. */
+    providers: Provider[];
+    /** Per-step resolved bindings — populated on the `hybrid-staged` path (empty otherwise), so run.ts
+     *  can drive each step on its own provider and marshal `produces`→`consumes`. */
+    stagedSteps: StagedStep[];
+    /** The project root a `setup_execution` component may write into (genbi-setup's onboarding
+     *  flavor), or `null` for every other component. Threaded to `makeReadOnlyGuard` so Bash broadens
+     *  beyond `wren` and Write/Edit are scoped to this root, instead of denied outright. `null` on the
+     *  hybrid-staged path (out of scope — see buildHybridStagedPlan). */
+    setupScope: string | null;
+}
+interface DispatchPlan {
+    /** The user question (assembled prompt for `query()`). */
+    prompt: string;
+    /** Serializable `query()` options (canUseTool is attached later by run.ts). */
+    options: Options;
+    meta: DispatchMeta;
+}
+interface BuildConfig {
+    target: string;
+    flavor: RenderFlavor;
+    models: ModelConfig;
+    question: string;
+    /** Absolute path to the bound wren project (resolved by the CLI). */
+    cwd: string;
+    maxTurns?: number;
+}
+/**
+ * Build the `query({options})` for one resolved IR node. Loud-fails on any unsupported enum value
+ * before producing anything (wall-hit), mirroring `emit.rs`.
+ */
+declare function buildDispatchPlan(node: ComponentNode, report: ResolutionReport, cfg: BuildConfig): DispatchPlan;
+
+/**
+ * Warble's own, consumer-agnostic chat-event vocabulary — the NDJSON records `chat --stream-json`
+ * (cli.ts) emits to stdout, one JSON object per line, as a turn runs. This module owns the mapping
+ * FROM the Agent SDK's `SDKMessage` stream TO this vocabulary; it knows nothing about any particular
+ * consumer's own event types — a consumer maps `WarbleChatEvent` to whatever shape it needs on its own
+ * side (out of scope here).
+ *
+ * Step bracketing: rather than trying to derive nested Task-subagent step boundaries from
+ * `parent_tool_use_id` transitions (fragile — a subagent's tool calls interleave with the driver's,
+ * and the SDK gives no explicit "subagent started/finished" message), `ChatEventMapper` emits a
+ * SINGLE enclosing `step_start` (id = the dispatched verb) on the first message that produces a tool
+ * call, and a matching `step_finish` when the caller reports the turn is done (`finish()`). Every
+ * `tool_call`/`tool_result` the turn produces is grouped under that one step. Simple and correct beats
+ * clever-but-fragile here — a consumer that wants finer-grained nesting can still use each event's
+ * `parent`/`depth` fields (populated from `parent_tool_use_id`) to distinguish driver-turn tool calls
+ * from subagent-turn tool calls within the single step.
+ *
+ * The mapper does NOT emit `answer` — that line is assembled by the CLI from the turn's final text
+ * once the whole message stream has been consumed (see cli.ts's `runChatCmd`).
+ */
+type WarbleChatEvent = {
+    readonly t: "step_start";
+    readonly id: string;
+    readonly name: string;
+    readonly parent: string | null;
+    readonly depth: number;
+} | {
+    readonly t: "step_finish";
+    readonly id: string;
+    readonly ok: boolean;
+    readonly detail?: string;
+} | {
+    readonly t: "tool_call";
+    readonly id: string;
+    readonly name: string;
+    readonly input?: unknown;
+    readonly parent: string | null;
+    readonly depth: number;
+} | {
+    readonly t: "tool_result";
+    readonly id: string;
+    readonly ok: boolean;
+    readonly summary?: string;
+    readonly error?: string;
+} | {
+    readonly t: "answer";
+    readonly text: string;
+} | {
+    /**
+     * The turn's SDK session id (multi-turn resume anchor, `run.ts`'s `RunResult.sessionId`),
+     * emitted once per turn by `chat --stream-json` (cli.ts) — on success AND on a failed turn
+     * (e.g. `error_max_turns`), since a caller resuming after a failure needs the session id of
+     * the conversation that failed, not just of a successfully completed one. `id` is null only
+     * if the SDK's result message never carried a session id at all.
+     */
+    readonly t: "session";
+    readonly id: string | null;
+};
+
+/** A blocked tool call, recorded so the trace/report can prove enforcement actually fired. */
+interface Denial {
+    tool: string;
+    reason: string;
+    command?: string;
+}
+interface GuardConfig {
+    readOnly: boolean;
+    /** Absolute artifact-write scope dir (prompt flavor); null keeps the agent fully read-only. */
+    writeScope: string | null;
+    /** The session cwd (bound wren project), used to resolve relative write paths. */
+    cwd: string;
+    /**
+     * +Mutating: when set, Write/Edit calls are the gated apply of a mutating component's diff, not a
+     * plain artifact write. The actual approval decision is borrowed from the SDK embedder's own
+     * `canUseTool` wrapper / approval channel — this guard cannot grant an apply on its own, so it
+     * always denies fail-closed and records why (a target with no approval channel is the honest edge,
+     * not a bug to route around).
+     */
+    mutation?: {
+        mustDryRun: boolean;
+        approvalRequired: boolean;
+        /**
+         * +Constitutive: the THIRD enforcement point, `context_write_authz` — a path-scoped gate distinct
+         * from `writeScope` (render artifact writes) and the plain mutation approval gate (data writes).
+         * When set, a Write/Edit outside this scope is denied with a SCOPE-VIOLATION reason (never even
+         * reaches the approval question); a write inside the scope still denies fail-closed, but with an
+         * APPROVAL reason — same fail-closed philosophy as the unscoped mutation branch below. The two
+         * reasons are distinguishable so callers/tests can tell which gate fired. Unset keeps the existing
+         * unscoped mutation behavior unchanged.
+         */
+        contextScope?: string;
+    };
+    /**
+     * +Setup (genbi-setup, the 5th enforcement point: `setup_execution`): the onboarding flavor. When
+     * set, Bash is broadened beyond `wren` (connector CLIs like `dlt` are permitted too — still subject
+     * to the DESTRUCTIVE/REDIRECTION/dotenv-read denylist, checked first and never relaxed), and
+     * Write/Edit are scoped to this project root rather than denied outright, and Read is denied for a
+     * dotenv-shaped path (see DOTENV_READER_COMMANDS/DOTENV_PATH below). Distinct from `writeScope`
+     * (render artifacts) and the `mutation` gates (a pre-existing MDL's diff/apply lifecycle): setup has
+     * no pre-bound context to gate reads against and no diff to approve — it is scaffolding a NEW
+     * project. `undefined`/`null` leaves every other component's behavior unchanged.
+     */
+    setupScope?: string | null;
+}
+/**
+ * Build the `canUseTool` gate for a component, plus the `PreToolUse` hooks needed to actually enforce
+ * the +Setup dotenv-read gap's Read side (see `makeSetupReadDenyHook`'s comment — `canUseTool` alone
+ * does not reach in-cwd Read in the real SDK). Both share the same `denials` array so the trace sees
+ * every enforcement point that fired, however it fired. Callers MUST wire `hooks` into the `query()`
+ * `Options.hooks.PreToolUse` for every invocation this guard's `canUseTool` is passed to — passing one
+ * without the other leaves the Read side unenforced for +Setup. `hooks` is `[]` for every non-setup
+ * component (readOnly/writeScope/mutation/context_write_authz), so wiring it unconditionally is safe
+ * and does not change behavior for those paths.
+ *
+ * Fail-closed: anything not explicitly permitted by `canUseTool` is denied with guidance.
+ */
+declare function makeReadOnlyGuard(cfg: GuardConfig): {
+    canUseTool: CanUseTool;
+    denials: Denial[];
+    hooks: HookCallbackMatcher[];
+};
+
+/** One assistant turn's usage. `parent_tool_use_id` distinguishes driver turns from subagent turns. */
+interface StepUsage {
+    model: string;
+    parent_tool_use_id: string | null;
+    usage: unknown;
+}
+interface Trace {
+    target: string;
+    verb: string;
+    model: string;
+    split: boolean;
+    run: {
+        total_cost_usd: number;
+        duration_ms: number;
+        duration_api_ms: number;
+        num_turns: number;
+    } | null;
+    usage: NonNullableUsage | null;
+    /** Per-model usage — and since each tier maps to a distinct model, this is per-tier cost. */
+    modelUsage: Record<string, ModelUsage>;
+    /** Per assistant turn (per-step granularity the headless file target can't produce). */
+    steps: StepUsage[];
+    denials: Denial[];
+}
+/** Pure: fold the captured message stream + guardrail denials into a trace. */
+declare function aggregateTrace(messages: readonly SDKMessage[], meta: {
+    target: string;
+    verb: string;
+    model: string;
+    split: boolean;
+}, denials: Denial[]): Trace;
+interface RunResult {
+    finalText: string;
+    trace: Trace;
+    htmlPath: string | null;
+    denials: Denial[];
+    /** The SDK's session id for this run, if the result carried one (multi-turn resume anchor). */
+    sessionId: string | null;
+    /** Set when a best-effort `render_contract` failed at runtime (`warble render` exited non-zero)
+     *  and the turn degraded instead of hard-failing (`render.onFailure === "degrade"`): `htmlPath`
+     *  stays `null`, `finalText` is still the agent's answer, and this carries why the render was
+     *  skipped. `null` on every run that never hit a render failure — a required/safety-critical
+     *  render failure still throws (`DispatchError`/`DispatchSessionError`) and never reaches here. */
+    renderDegraded: {
+        reason: string;
+    } | null;
+}
+interface RunConfig {
+    outDir: string;
+    warbleBin: string;
+    /** Optional dashboard title passed through to `warble render`. */
+    title?: string;
+    /** Resume a prior turn's session (multi-turn continuity, session.ts). Mutually exclusive in practice
+     *  with a fresh turn — omit for turn 1. */
+    resume?: string;
+    /** Opt-in streaming sink (`chat --stream-json`, cli.ts): called once per `WarbleChatEvent` as the
+     *  message stream is consumed, not batched after the fact. Only wired on the main (single/split) SDK
+     *  loop below — the hybrid-staged executor passes through with no events. */
+    onEvent?: (event: WarbleChatEvent) => void;
+}
+/**
+ * A dispatch failure that still carries the SDK's session id, when the result message had one —
+ * e.g. `error_max_turns`: the run failed, but the conversation itself is still resumable. A caller
+ * that wants to continue the SAME session with more turns (rather than re-dispatching a fresh
+ * prompt) needs this id; a plain `DispatchError` would discard it. `sessionId` is null only when
+ * the SDK never produced a result message at all (no session to resume).
+ */
+declare class DispatchSessionError extends DispatchError {
+    readonly sessionId: string | null;
+    constructor(message: string, sessionId: string | null);
+}
+/**
+ * Run a dispatch plan against the live Agent SDK, then render + trace. Writes `result.txt`,
+ * `trace.json`, and (programmatic realize flavor) `dashboard.html` into `outDir`.
+ */
+declare function runDispatch(plan: DispatchPlan, cfg: RunConfig): Promise<RunResult>;
+
+/**
+ * The orchestrator's system prompt — PROVIDER-AGNOSTIC. Lists the steps in order by name and the
+ * produces→consumes marshaling; it never says which step is local vs cloud (that is the handler's job,
+ * from the binding). So the same prompt shape is emitted whether the binding is all-cloud or hybrid.
+ */
+declare function buildToolDriverPrompt(steps: readonly StagedStep[]): string;
+/**
+ * Run the hybrid-tool path: one orchestrator query() + a `dispatch_step` tool that routes each step to
+ * its bound provider. Mirrors {@link runHybridStaged}'s outputs (result.txt / trace.json / RunResult).
+ */
+declare function runHybridTool(plan: DispatchPlan, cfg: RunConfig): Promise<RunResult>;
+
+interface RenderResult {
+    outPath: string;
+    /** stderr from `warble render` (it logs "wrote … (N block(s))"). */
+    log: string;
+}
+/**
+ * Write the captured agent output to a temp file and shell out to `warble render`. `warble render`
+ * tolerates the model fencing/prose-wrapping the envelope and unwraps a `--output-format json`
+ * result object (see the Rust `parseEnvelope`), so we pass the raw final text through unchanged.
+ */
+declare function renderEnvelope(finalText: string, outPath: string, opts: {
+    warbleBin: string;
+    title?: string;
+}): RenderResult;
+
+/**
+ * A minimal structured snapshot of what a turn resolved — filters/dimensions/measures/grain — used
+ * only to thread context into the NEXT turn's prompt. Nothing here is inferred by this module: a
+ * caller who has parsed it out of the agent's own answer (or a render envelope) supplies it via
+ * `ChatSession.ask(question, { intent })`. Sessions with no supplied intent simply skip distillation.
+ */
+interface ResolvedIntent {
+    filters: string[];
+    dimensions: string[];
+    measures: string[];
+    grain?: string;
+}
+/**
+ * Merge the prior turn's resolved intent with a new follow-up question into a distilled context
+ * string, PREPENDED to the question as guidance for the agent — this never decides routing or
+ * overrides the agent's own resolution, it only reduces the odds it drops context a human speaker
+ * would have kept implicit ("break it down by region" after "completed orders" should still mean
+ * completed orders, broken down by region).
+ *
+ * Merge policy (heuristic, intentionally simple for G1):
+ *   - filters: carried forward unless the new question signals its own filter override (`where`,
+ *     `only`, `excluding`, `filtered to`, `instead of`).
+ *   - dimensions: swapped to whatever the new question names after "by"/"group by"; otherwise carried.
+ *   - measures / grain: always carried (no override heuristic yet — every question in G1 keeps the
+ *     same metric family; multi-metric follow-ups are out of scope).
+ */
+declare function distillFollowup(prevIntent: ResolvedIntent, newQuestion: string): string;
+type ClarifyOutcome = {
+    kind: "clarify";
+    question: string;
+} | {
+    kind: "answer";
+};
+/** Below this confidence, clarify rather than guess (a clarifying question is cheaper than a
+ *  wasted expensive call). Confidence itself is supplied by the caller — parsed from whatever signal
+ *  the agent/router gave (an eval score, a router's own stated confidence, etc.); this function only
+ *  encodes the threshold policy, it doesn't compute confidence. */
+declare const DEFAULT_CLARIFY_THRESHOLD = 0.55;
+declare function decideClarify(question: string, confidence: number, threshold?: number): ClarifyOutcome;
+interface Turn {
+    question: string;
+    /** The prompt actually sent to `query()` for this turn (post-distillation). */
+    prompt: string;
+    /** The turn's resolved intent, if the caller supplied one for carry-forward; null if not tracked. */
+    intent: ResolvedIntent | null;
+    /** The SDK's session id for this turn's run (resume anchor for the next turn), if any. */
+    sessionId: string | null;
+    finalText: string;
+}
+interface SessionState {
+    turns: readonly Turn[];
+}
+declare function createSessionState(): SessionState;
+/** The resume anchor for the NEXT turn: the most recent turn's `session_id`, or null on turn 1. */
+declare function lastSessionId(state: SessionState): string | null;
+/** The most recently resolved intent to carry forward, or null if none was ever supplied. */
+declare function lastResolvedIntent(state: SessionState): ResolvedIntent | null;
+/** Pure append — returns a new state, does not mutate. */
+declare function appendTurn(state: SessionState, turn: Turn): SessionState;
+/** Build the next turn's prompt: turn 1 = the raw question; turn N = distilled context + question. */
+declare function buildTurnPrompt(state: SessionState, question: string): string;
+interface TurnResult {
+    finalText: string;
+    sessionId: string | null;
+    trace: Trace;
+    /** The actual (post-distillation) prompt sent for this turn. */
+    prompt: string;
+}
+interface AskOptions {
+    /** Supply this turn's resolved intent so it can be carried forward into the NEXT turn's prompt. */
+    intent?: ResolvedIntent;
+    /** Opt-in streaming sink for this turn, forwarded straight to `runDispatch` (`chat --stream-json`). */
+    onEvent?: (event: WarbleChatEvent) => void;
+}
+/**
+ * A multi-turn chat session over ONE prepared component's `DispatchPlan`. Each `ask()` resumes the
+ * prior turn's SDK session (`resume: session_id`) so the agent keeps the real conversation history;
+ * `distillFollowup` layers a structured hint on top for callers tracking resolved intent explicitly.
+ * All branching policy (distillation, clarify) lives in the pure functions above — this class is just
+ * plumbing over `runDispatch`.
+ */
+declare class ChatSession {
+    private readonly plan;
+    private readonly runCfg;
+    /**
+     * Seeds the FIRST `ask()` call's resume anchor with a session id captured by an earlier
+     * process (e.g. `warble-agent-sdk chat --resume <id>`, cli.ts) — lets a NEW `ChatSession`
+     * instance resume a conversation it did not itself start. Ignored once any real turn has been
+     * asked in THIS instance: `lastSessionId(this.state)` then takes over, exactly as before.
+     */
+    private readonly initialResumeSessionId?;
+    private state;
+    constructor(plan: DispatchPlan, runCfg: RunConfig, 
+    /**
+     * Seeds the FIRST `ask()` call's resume anchor with a session id captured by an earlier
+     * process (e.g. `warble-agent-sdk chat --resume <id>`, cli.ts) — lets a NEW `ChatSession`
+     * instance resume a conversation it did not itself start. Ignored once any real turn has been
+     * asked in THIS instance: `lastSessionId(this.state)` then takes over, exactly as before.
+     */
+    initialResumeSessionId?: string | undefined);
+    getState(): SessionState;
+    ask(question: string, opts?: AskOptions): Promise<TurnResult>;
+}
+declare function createChatSession(plan: DispatchPlan, runCfg: RunConfig, initialResumeSessionId?: string): ChatSession;
+
+interface DispatchInput {
+    /** A parsed IR or a raw JSON string. */
+    ir: WarbleIr | string;
+    /** The data question to answer (the `query()` prompt). Optional for prepare-only (dry-run/emit). */
+    question?: string;
+    target?: string;
+    flavor?: RenderFlavor;
+    models?: ModelConfig;
+    maxTurns?: number;
+    /** Explicit bound-project cwd (absolute or cwd-relative). Overrides `irPath`-based resolution. */
+    project?: string;
+    /** Resolve each node's relative `context_binding.project` against this IR file's directory. */
+    irPath?: string;
+    /**
+     * Scope preparation to exactly this component id: only its capabilities are resolved and only
+     * its plan is built — every *other* component in the IR is left untouched, so its
+     * `required_capabilities` never enter this dispatch's preflight. Use this for `chat`, which
+     * only ever runs one component per process.
+     *
+     * Omit (the default) to prepare every component in the IR — the shape `manifest`, `emit`, and
+     * the whole-profile `dispatch` subcommand need, since each of those actually reads or runs
+     * every component and must know every component's resolution, not just one's.
+     *
+     * This narrows *which* component's requirements gate a given `prepareDispatch` call — it does
+     * not change what happens when a gated capability is unmet (still a loud throw, same message,
+     * same named capability; see `resolveNodeCapabilities`). A component that can itself invoke
+     * another IR component at runtime would need that callee's requirements folded in here too, but
+     * no such reachability exists yet: `borrowed_actions` names external runtime actions (notify,
+     * ticket, …), never another component, and the one mechanism shaped for it — `orchestrating` /
+     * `effect.outcome.kind: "dispatch"` with `routable_scope` — is parsed but not consumed by any
+     * back-end (`docs/spec/authoring.md` marks `orchestrating` "scaffolded", not realized). If that
+     * ever lands, this scoping must fold in the callee's requirements too.
+     */
+    componentId?: string;
+}
+interface PreparedComponent {
+    id: string;
+    node: ComponentNode;
+    report: ResolutionReport;
+    plan: DispatchPlan;
+}
+interface PreparedDispatch {
+    target: string;
+    components: PreparedComponent[];
+}
+/** Stable redacted status for a component the configured target cannot run. */
+declare const UNAVAILABLE_COMPONENT_REASON = "component is unavailable on the configured runtime";
+interface UnavailableDisplayComponent {
+    id: string;
+    node: ComponentNode;
+    availability: {
+        status: "unavailable";
+        reason: typeof UNAVAILABLE_COMPONENT_REASON;
+    };
+}
+type DisplayComponent = PreparedComponent | UnavailableDisplayComponent;
+interface PreparedDisplayManifest {
+    target: string;
+    components: DisplayComponent[];
+}
+/**
+ * Resolve a node's bound wren project to an absolute cwd. Relative `context_binding.project` paths
+ * resolve against the IR file's directory (`irPath`) when given, else the current working directory;
+ * an explicit `project` always wins.
+ */
+declare function resolveProjectCwd(node: ComponentNode, opts: {
+    project?: string;
+    irPath?: string;
+}): string;
+/**
+ * Parse + resolve + build every requested component's `query({options})`, without calling the SDK.
+ *
+ * By default this prepares every component in the IR. Pass `input.componentId` to scope
+ * preparation — and therefore capability resolution — to exactly that one component; every other
+ * component's `required_capabilities` are never consulted, so a component that isn't being
+ * dispatched can't wall-hit a dispatch it has nothing to do with. See {@link DispatchInput.componentId}.
+ */
+declare function prepareDispatch(input: DispatchInput): PreparedDispatch;
+/**
+ * Prepare a display-only whole-profile manifest. Unsupported components are
+ * represented by a closed unavailable marker; no executable plan is built
+ * for them. This must never be used by emit, dispatch, or chat.
+ */
+declare function prepareDisplayManifest(input: Omit<DispatchInput, "componentId" | "question">): PreparedDisplayManifest;
+interface DispatchRunConfig {
+    outDir: string;
+    warbleBin?: string;
+    title?: string;
+}
+interface ComponentOutcome {
+    id: string;
+    report: ResolutionReport;
+    plan: DispatchPlan;
+    result: RunResult;
+}
+interface DispatchOutcome {
+    target: string;
+    components: ComponentOutcome[];
+}
+/**
+ * Prepare then RUN each component against the live Agent SDK loop. Requires `input.question`.
+ * Writes each run's artifacts under `runCfg.outDir` (see {@link runDispatch}).
+ */
+declare function dispatch(input: DispatchInput, runCfg: DispatchRunConfig): Promise<DispatchOutcome>;
+
+/**
+ * Codegen (`emit`) — freeze a prepared dispatch into an importable TS agent module.
+ *
+ * The IR→options mapping is resolved at emit time and the resulting `query({options})` is written as
+ * source, plus a thin `run()` per component. Analogue of the file target emitting `.md` — here it is
+ * `.ts` a user drops into their own codebase. Two modes:
+ *   - **thin (default)** — imports the runtime helpers (guardrail / trace / render) from
+ *     `@warble/claude-agent-sdk`; small and always in sync with the library.
+ *   - **standalone** — inlines a minimal read-only guard + trace + render shell, so the only imports
+ *     are `@anthropic-ai/claude-agent-sdk` and Node built-ins (the `warble` *binary* is still used
+ *     for render — that is the renderer-reuse contract, not a TS dependency).
+ */
+
+interface EmitOptions {
+    standalone?: boolean;
+}
+/**
+ * Emit a TS agent module (as source text) for a prepared dispatch. Each component becomes an exported
+ * async `run()` function that drives the SDK loop with the resolved, frozen options.
+ */
+declare function emitAgentModule(prepared: PreparedDispatch, opts?: EmitOptions): string;
+
+/**
+ * The `claude-agent-sdk:local` display manifest — a stable, structural snapshot of a resolved
+ * profile (agents / steps / tiers / capabilities / guardrails) for THIS target, so a consumer can
+ * source a "what will run" display from whichever back-end actually runs, instead of always
+ * reading the vercel bundle target's output even when this back-end is the one dispatching.
+ *
+ * Field-for-field port of the vercel bundle target's assembly (`dispatcher/vercel/src/{bundle,
+ * guardrails,schema,classify,emit}.rs`), driven off the same parsed IR + `ResolutionReport` this
+ * back-end already produces via `prepareDispatch` — no shelling out to the Rust binary, and no
+ * shared code between the two ports (each is a small, pure derivation from the same IR seam, kept
+ * independently portable per language).
+ */
+
+interface CompatibilityPolicy {
+    min_ir_version: string;
+    max_ir_version: string;
+}
+interface WhenGuardOut {
+    guard: string;
+    target: string;
+}
+/**
+ * How a conditional step is realized — mirrors the vercel bundle's `StepRealization` (serde
+ * `tag = "kind"`, `snake_case`). `fallback` is omitted (never emitted): the IR has no field
+ * declaring one today, matching the Rust port's `skip_serializing_if` behavior.
+ */
+type StepRealization = {
+    kind: "independent";
+} | {
+    kind: "repair_fold";
+    fold_into: string;
+    max_attempts: number;
+    fallback?: string;
+} | {
+    kind: "guarded_skip";
+};
+interface StepManifest {
+    name: string;
+    tier: string;
+    consumes: string[];
+    produces?: string;
+    prompt: string;
+    when?: WhenGuardOut;
+    realization: StepRealization;
+}
+interface ToolRef {
+    name: string;
+    source: string;
+}
+interface GuardrailManifest {
+    enforcement: string;
+    locked: boolean;
+    scope?: string;
+    threshold?: unknown;
+}
+interface AvailableAgentManifest {
+    id: string;
+    verb: string;
+    component_type: ComponentNode["type"];
+    realization_kind: ComponentNode["realization_kind"];
+    trigger: ComponentNode["trigger"]["kind"];
+    outcome: ComponentNode["effect"]["outcome"]["kind"];
+    steps: StepManifest[];
+    guardrails: Record<string, GuardrailManifest>;
+    tools: ToolRef[];
+    output_schema: unknown;
+    capabilities: ResolutionReport;
+    brief?: string;
+}
+/** A display-only declaration of a component that remains unavailable to this target. */
+interface UnavailableAgentManifest {
+    id: string;
+    verb: string;
+    component_type: ComponentNode["type"];
+    realization_kind: ComponentNode["realization_kind"];
+    trigger: ComponentNode["trigger"]["kind"];
+    outcome: ComponentNode["effect"]["outcome"]["kind"];
+    /** Fixed empty surfaces: this record can never be treated as an execution plan. */
+    steps: [];
+    guardrails: Record<string, never>;
+    tools: [];
+    output_schema: Record<string, never>;
+    capabilities: [];
+    availability: {
+        status: "unavailable";
+        reason: string;
+    };
+}
+type AgentManifest = AvailableAgentManifest | UnavailableAgentManifest;
+interface Manifest {
+    manifest_version: string;
+    compat: CompatibilityPolicy;
+    profile: string;
+    target: string;
+    agents: AgentManifest[];
+}
+/** Port of `emit.rs::build_agent_bundle`, minus the tool-map parameter (this back-end's is fixed,
+ * see `LOCAL_TOOL_MAP`). */
+declare function buildAgentManifest(component: PreparedComponent): AvailableAgentManifest;
+/** Never derives a plan, tool, or capability grant for an unavailable component. */
+declare function buildUnavailableAgentManifest(component: UnavailableDisplayComponent): UnavailableAgentManifest;
+/** Build the full display manifest for a `prepareDispatch` result. `raw` is the same IR the
+ * dispatch was prepared from — re-parsed here (a second, cheap, pure parse) just to read
+ * `profile`, which `PreparedDispatch` does not itself carry. */
+declare function buildManifest(prepared: PreparedDispatch | PreparedDisplayManifest, raw: string): Manifest;
+
+export { type AgentManifest, type AskOptions, type AvailableAgentManifest, type BuildConfig, COMPONENT_TYPES, type CallLocalOptions, type CapabilityEntry, type CapabilityOutcome, type CapabilityProfile, type ChatRequest, ChatSession, type ClarifyOutcome, type CompatibilityPolicy, type ComponentNode, type ComponentOutcome, type ComponentType, type ContextBinding, type Criticality, DEFAULT_CLARIFY_THRESHOLD, DEFAULT_RENDER_FLAVOR, DEFAULT_TARGET, DESTRUCTIVE_BASH_DENY, type Denial, type DiscoverClaudeModelsOptions, DispatchError, type DispatchInput, type DispatchMeta, type DispatchOutcome, type DispatchPlan, type DispatchRunConfig, DispatchSessionError, type DisplayComponent, type Effect, type EmitOptions, type GateFailureMode, type GateKind, type GuardConfig, type Guardrail, type GuardrailManifest, type IrConfig, type LlmCall, MODEL_CATALOG_VERSION, type Manifest, type ModelCatalogModel, type ModelCatalogResult, type ModelCatalogUnavailableCode, ModelConfig, OUTCOME_KINDS, type Outcome, type OutcomeKind, type PreconditionResult, type PreparedComponent, type PreparedDispatch, type PreparedDisplayManifest, type ProvidedBy, type Provider, REALIZATION_KINDS, type RealizationKind, type RenderBlock, type RenderFlavor, type RenderGate, type RenderResult, type ResolutionReport, type ResolvedCapability, type ResolvedIntent, type RoutingMode, type RoutingPlan, type RunConfig, type RunResult, SUPPORTED_IR_VERSIONS, type SessionState, type StagedStep, type StepManifest, type StepMessage, type StepRealization, type StepUsage, TRIGGER_KINDS, type TargetId, type TierBinding, type ToolPlan, type ToolRef, type Trace, type Trigger, type TriggerKind, type Turn, type TurnResult, UNAVAILABLE_COMPONENT_REASON, type UnavailableAgentManifest, type UnavailableDisplayComponent, type WarbleIr, type WhenGuardOut, aggregateTrace, appendTurn, buildAgentManifest, buildChatRequest, buildDispatchPlan, buildManifest, buildStepMessages, buildToolDriverPrompt, buildTurnPrompt, buildUnavailableAgentManifest, callOpenAiCompat, collectRequiredCapabilities, createChatSession, createSessionState, decideClarify, discoverClaudeModels, dispatch, distillFollowup, distinctProviders, distinctTiers, emitAgentModule, extractCompletionText, inspectNodeCapabilities, isKnownTarget, knownTargetNames, lastResolvedIntent, lastSessionId, localProfile, makeReadOnlyGuard, parseIr, parseRenderFlavor, planProviderRouting, prepareDispatch, prepareDisplayManifest, profileFor, renderEnvelope, resolveCapabilities, resolveNodeCapabilities, resolveProjectCwd, resolveStagedSteps, runDispatch, runHybridTool, shouldSplitPerStepTier, usesLocalProvider };