@wrongstack/core 0.63.4 → 0.68.0

package/dist/agent-subagent-runner-DRZ9-NnR.d.ts

@@ -0,0 +1,1042 @@
+import { t as ToolRegistry, m as ProviderRegistry, f as AgentPipelines, q as ToolExecutorLike, E as ExtensionRegistry, d as AgentInit, e as AgentInput, R as RunResult, p as ToolCallPipelinePayload, u as ToolWrapper, S as SystemPromptContributor } from './index-DKUvyTvV.js';
+import { C as Container, e as Renderer, R as ReadonlyPipeline } from './system-prompt-b61lOd49.js';
+import { E as EventBus, k as EventName, L as Listener } from './events-CIplI98R.js';
+import { a as RetryPolicy, E as ErrorHandler } from './retry-policy-CG3qvH_e.js';
+import { a as Logger } from './logger-DDd5C--Z.js';
+import { T as Tracer } from './observability-BhnVLBLS.js';
+import { a as PermissionPolicy } from './permission-C1A5whY5.js';
+import { d as Context, Q as Tool, u as RunOptions, J as JSONSchema, p as Request, q as Response, c as ContentBlock, T as TextBlock, m as Provider, $ as Usage } from './context-y87Jc5ei.js';
+import { l as HookEvent, n as HookMatcher, I as InProcessHook, a as Config } from './config--86aHSln.js';
+import { W as WireFamily } from './models-registry-BcYJDKLm.js';
+
+declare class Agent {
+    readonly container: Container;
+    readonly tools: ToolRegistry;
+    readonly providers: ProviderRegistry;
+    readonly events: EventBus;
+    readonly pipelines: AgentPipelines;
+    readonly ctx: Context;
+    readonly maxIterations: number;
+    readonly executionStrategy: 'parallel' | 'sequential' | 'smart';
+    readonly perIterationOutputCapBytes: number;
+    private readonly plugins;
+    readonly toolExecutor: ToolExecutorLike;
+    readonly autoExtendLimit: boolean;
+    private readonly autonomousContinue;
+    readonly tracer: Tracer | undefined;
+    readonly extensions: ExtensionRegistry;
+    private readonly _toolHandler;
+    private readonly _responseHandler;
+    private readonly _loopHandler;
+    constructor(init: AgentInit);
+    get logger(): Logger;
+    get retry(): RetryPolicy;
+    get errorHandler(): ErrorHandler;
+    get permission(): PermissionPolicy;
+    get renderer(): Renderer | undefined;
+    disableInteractiveConfirmation(): void;
+    register(tool: Tool): void;
+    use(plugin: Plugin, api: PluginAPI): Promise<void>;
+    teardown(): Promise<void>;
+    run(userInput: AgentInput, opts?: RunOptions): Promise<RunResult>;
+}
+
+/**
+ * A slash command registered with the CLI or available to plugins.
+ * Plugins receive a view of the registry via PluginAPI.slashCommands.
+ *
+ * Commands registered by plugins use a namespaced name: `pluginName:commandName`.
+ * This prevents collisions with built-in commands and other plugins.
+ */
+interface SlashCommand {
+    /** Unique command name. For plugins: `pluginName:commandName`. */
+    name: string;
+    /** Short aliases — also prefixed automatically: `pluginName:alias`. */
+    aliases?: string[];
+    description: string;
+    /**
+     * Optional compact argument hint for interactive menus. This is not parsed
+     * by the registry; it only helps TUI/REPL surfaces show the expected shape,
+     * for example `[list|install <alias>|disable <name>]`.
+     */
+    argsHint?: string;
+    /**
+     * Optional detailed help shown by `/help <name>`. Use this for usage,
+     * arguments, examples, side-effects — anything that doesn't fit in
+     * `description`. Renders verbatim, so format with line breaks.
+     * If absent, `/help <name>` falls back to `description`.
+     */
+    help?: string;
+    /**
+     * Execute the command.
+     * @param args Everything after the command name (trimmed by dispatch).
+     * @param ctx The current agent context.
+     * @returns `{ exit: true }` to quit the REPL. `{ message }` to print and
+     * continue. `{ runText }` to send a follow-up user-role message to the
+     * model immediately (e.g. `/steer <text>` builds a STEERING preamble
+     * here and asks the TUI to run it as the next turn). The TUI prints
+     * `message` first (if any) so the user sees the slash result before
+     * the model's response starts streaming. `{ metadata }` carries
+     * structured data for the REPL/TUI to act on (e.g. SDD session state).
+     */
+    run(args: string, ctx: Context): Promise<{
+        exit?: boolean;
+        message?: string;
+        runText?: string;
+        metadata?: Record<string, unknown>;
+    } | void>;
+}
+
+interface ToolRegistryView {
+    register(t: Tool): void;
+    unregister(name: string): void;
+    /** Wrap (decorate) an existing tool. The wrapper gets the current tool and returns the decorated version. */
+    wrap(name: string, wrapper: ToolWrapper): void;
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+}
+interface ProviderFactory {
+    type: string;
+    family: WireFamily;
+    create(cfg: unknown): Provider;
+}
+interface ProviderRegistryView {
+    register(f: ProviderFactory): void;
+    create(cfg: {
+        type: string;
+    } & Record<string, unknown>): Provider;
+    list(): string[];
+}
+interface MCPRegistryView {
+    start(cfg: unknown): Promise<void>;
+    stop(name: string): Promise<void>;
+    restart(name: string): Promise<void>;
+    list(): {
+        name: string;
+        state: string;
+        toolCount: number;
+    }[];
+}
+interface SlashCommandRegistryView {
+    register(cmd: SlashCommand): void;
+    unregister(name: string): boolean;
+    get(name: string): SlashCommand | undefined;
+    list(): SlashCommand[];
+}
+/**
+ * Read-only view of the session writer. Plugins can append custom events
+ * to the JSONL session log and read the transcript path.
+ *
+ * The `append` method accepts any JSON-serializable payload — custom
+ * event types are persisted verbatim next to the built-in events.
+ */
+interface SessionWriterView {
+    readonly transcriptPath?: string;
+    append(event: Record<string, unknown> & {
+        type: string;
+        ts: string;
+    }): Promise<void>;
+}
+/**
+ * Metrics sink scoped to a plugin. The host auto-prefixes metric names
+ * with `plugin.<pluginName>.` so plugins don't need to namespace
+ * manually. Plugins call counter/histogram/gauge directly; the values
+ * flow to the host's MetricsSink (Prometheus, OTLP, or noop).
+ */
+interface MetricsSinkView {
+    counter(name: string, value?: number, labels?: Record<string, string>): void;
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+}
+interface PluginPipelines {
+    request: ReadonlyPipeline<Request>;
+    response: ReadonlyPipeline<Response>;
+    toolCall: ReadonlyPipeline<ToolCallPipelinePayload>;
+    userInput: ReadonlyPipeline<{
+        content: ContentBlock[];
+        text: string;
+        ctx: Context;
+    }>;
+    assistantOutput: ReadonlyPipeline<TextBlock>;
+    contextWindow: ReadonlyPipeline<Context>;
+    [k: string]: ReadonlyPipeline<any>;
+}
+interface PluginAPI {
+    container: Container;
+    pipelines: PluginPipelines;
+    events: EventBus;
+    tools: ToolRegistryView;
+    providers: ProviderRegistryView;
+    mcp: MCPRegistryView;
+    slashCommands: SlashCommandRegistryView;
+    /** Live session writer — plugins can append custom events here. */
+    session: SessionWriterView;
+    /** Scoped metrics sink — counters/histograms/gauges auto-namespaced under `plugin.<name>.` */
+    metrics: MetricsSinkView;
+    /** Registry for agent lifecycle extensions — hooks like beforeRun, beforeIteration, onError, etc. */
+    extensions: ExtensionRegistry;
+    /**
+     * Register a system prompt contributor. Plugins call this to inject
+     * ephemeral TextBlocks into the system prompt on every build.
+     * Returns an unregister function.
+     */
+    registerSystemPromptContributor(c: SystemPromptContributor): () => void;
+    /**
+     * Register an in-process lifecycle hook. `matcher` is a tool-name filter for
+     * `PreToolUse`/`PostToolUse` (`"Bash"`, `"edit|write"`, `"*"`) and ignored
+     * for other events. The hook can block, rewrite tool input, or inject extra
+     * context — see `HookOutcome`. Automatically removed when the plugin is
+     * uninstalled. Returns an unregister function.
+     */
+    registerHook(event: HookEvent, matcher: HookMatcher | undefined, hook: InProcessHook): () => void;
+    config: Config;
+    log: Logger;
+    /**
+     * Register a one-time event listener. The handler is automatically removed
+     * after the first emission, or when the plugin is uninstalled — whichever
+     * comes first.
+     */
+    onEvent<K extends EventName>(event: K, handler: Listener<K>): () => void;
+    /**
+     * Subscribe to all events matching a glob-style pattern.
+     * `'tool.*'` matches all tool events. `'*'` matches everything.
+     * Returns an unsubscribe function.
+     */
+    onPattern(pattern: string, handler: (event: string, payload: unknown) => void): () => void;
+    /**
+     * Emit a custom event on the agent's EventBus. Use for inter-plugin
+     * communication or to surface plugin-specific state to the host.
+     *
+     * Custom events use a `pluginName:eventName` convention to avoid
+     * collisions with built-in events (e.g. `my-plugin:cache_hit`).
+     * The payload is passed through to all subscribers.
+     */
+    emitCustom(event: string, payload: unknown): void;
+    /**
+     * Register a callback that fires when the configuration changes at
+     * runtime (e.g. via `/config` slash command or programmatic update).
+     * The handler receives the new and previous config snapshots.
+     * Returns an unsubscribe function.
+     */
+    onConfigChange(handler: (next: Readonly<Config>, prev: Readonly<Config>) => void): () => void;
+}
+/**
+ * Capability declaration — informs the host which subsystems a plugin
+ * intends to touch. Used for diagnostics and per-plugin enable/disable UX
+ * (e.g. "this plugin registers tools — disable to remove them"). Not
+ * enforced at runtime: a plugin that declares `tools: false` can still
+ * call `api.tools.register()`, but the host can flag the discrepancy.
+ */
+interface PluginCapabilities {
+    /** Will register tools via `api.tools.register()`. */
+    tools?: boolean;
+    /** Will register provider factories via `api.providers.register()`. */
+    providers?: boolean;
+    /**
+     * Pipelines the plugin hooks into. Use the standard names
+     * (`request | response | toolCall | userInput | assistantOutput | contextWindow`)
+     * or custom pipeline names exposed by other plugins.
+     */
+    pipelines?: string[];
+    /** Will register slash commands via `api.slashCommands.register()`. */
+    slashCommands?: boolean;
+    /** Will start MCP servers via `api.mcp.start()`. */
+    mcp?: boolean;
+}
+/**
+ * Structured dependency declaration. The string form (`dependsOn: ['foo']`)
+ * is shorthand for `[{ name: 'foo' }]` — both work. Use the structured form
+ * when you need a version constraint:
+ *
+ *   dependsOn: [{ name: 'wstack-auth', version: '^1.2.0' }]
+ */
+interface PluginDependency {
+    name: string;
+    /** npm-style semver range. Supports `^`, `~`, exact, and unprefixed. */
+    version?: string;
+}
+interface Plugin {
+    name: string;
+    version?: string;
+    /** One-line summary for `wstack plugins list` and error messages. */
+    description?: string;
+    /** Semver range against the kernel API version (KERNEL_API_VERSION). */
+    apiVersion: string;
+    /**
+     * Capability hints — what subsystems the plugin will register against.
+     * Optional; provided for diagnostics and UX. The loader does not enforce
+     * these, but mismatch is surfaced via logger at warn level.
+     */
+    capabilities?: PluginCapabilities;
+    /**
+     * JSON Schema for the options under `Config.plugins[<name>].options`.
+     * When present, the loader validates that section before calling `setup`
+     * and rejects the plugin with a clear error path on failure.
+     */
+    configSchema?: JSONSchema;
+    /**
+     * Mandatory plugin dependencies — loading fails if any are absent or
+     * version-incompatible. Accepts both the legacy string-array form and
+     * the structured form with version constraints.
+     */
+    dependsOn?: (string | PluginDependency)[];
+    /** Optional plugin dependencies — silently skipped if absent. */
+    optionalDeps?: (string | PluginDependency)[];
+    conflictsWith?: string[];
+    /**
+     * Default configuration values, deep-merged under the plugin's options
+     * key before `configSchema` validation. User-provided values take
+     * precedence over defaults — this is a fallback, not an override.
+     *
+     * @example
+     * defaultConfig: { ttl: 3600, maxSize: 100 }
+     */
+    defaultConfig?: Record<string, unknown>;
+    setup(api: PluginAPI): void | Promise<void>;
+    teardown?(api: PluginAPI): void | Promise<void>;
+    /**
+     * Optional health check. Called by the host (e.g. `/diag plugins` slash
+     * command or health endpoint) to surface plugin status. Return
+     * `{ ok: false, message: '...' }` when the plugin is degraded.
+     */
+    health?(): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}
+
+type BridgeMessageType = 'task' | 'result' | 'progress' | 'error' | 'heartbeat' | 'stop' | 'delegate' | 'budget_threshold';
+interface BridgeMessage<T = unknown> {
+    id: string;
+    type: BridgeMessageType;
+    from: string;
+    to?: string;
+    payload: T;
+    timestamp: number;
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+}
+interface AgentBridgeConfig {
+    agentId: string;
+    coordinatorId: string;
+    timeoutMs?: number;
+    bufferSize?: number;
+}
+interface AgentBridge {
+    readonly agentId: string;
+    readonly coordinatorId: string;
+    send(msg: BridgeMessage): Promise<void>;
+    broadcast(msg: BridgeMessage): Promise<void>;
+    subscribe(handler: (msg: BridgeMessage) => void | Promise<void>): () => void;
+    request<T>(msg: BridgeMessage, timeoutMs?: number): Promise<BridgeMessage<T>>;
+    stop(): Promise<void>;
+}
+interface BridgeTransport {
+    send(msg: BridgeMessage, to: string): Promise<void>;
+    subscribe(agentId: string, handler: (msg: BridgeMessage) => void | Promise<void>): () => void;
+    close(agentId: string): Promise<void>;
+}
+
+type BudgetKind = 'tool_calls' | 'iterations' | 'tokens' | 'timeout' | 'idle_timeout' | 'cost';
+declare class BudgetExceededError extends Error {
+    readonly kind: BudgetKind;
+    readonly limit: number;
+    readonly observed: number;
+    constructor(kind: BudgetKind, limit: number, observed: number);
+}
+interface BudgetLimits {
+    maxIterations?: number;
+    maxToolCalls?: number;
+    maxTokens?: number;
+    /** Estimated USD cost ceiling. */
+    maxCostUsd?: number;
+    /**
+     * Hard wall-clock timeout measured from `start()`. Off by default — set it
+     * explicitly only when a task must finish within an absolute window. For
+     * the everyday "don't kill an agent that's still working" guard, prefer
+     * `idleTimeoutMs`, which resets on activity.
+     */
+    timeoutMs?: number;
+    /**
+     * Idle timeout: the maximum gap (ms) between activity signals (iterations,
+     * tool calls, token usage, streamed progress) before the subagent is
+     * considered hung and reaped. Unlike `timeoutMs`, an actively-working
+     * agent continuously resets this clock via `markActivity()`, so it never
+     * trips on a long-but-productive run — only on a genuine stall.
+     */
+    idleTimeoutMs?: number;
+}
+/**
+ * Controls how the budget behaves when `onThreshold` is set and a limit is hit.
+ *
+ * `'auto'` — emit `budget.threshold_reached` on the EventBus and wait for a
+ * coordinator response (extend/stop). If no listener responds within
+ * `DECISION_TIMEOUT_MS` the decision defaults to `'stop'`.
+ * `'sync'` — do not emit any event; treat the threshold as a hard stop and
+ * throw `BudgetExceededError` synchronously. Useful for fire-and-forget
+ * subagents that have an `onThreshold` handler for logging/metrics but are
+ * not wired into a coordinator.
+ *
+ * @default 'auto'
+ */
+type BudgetNegotiationMode = 'auto' | 'sync';
+interface BudgetUsage {
+    iterations: number;
+    toolCalls: number;
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    costUsd: number;
+    elapsedMs: number;
+}
+/**
+ * Thrown by `SubagentBudget.record*` when a soft limit is hit and
+ * an `onThreshold` handler is configured that wants to ask the
+ * coordinator (via `budget.threshold_reached` event). The runner
+ * catches this and awaits the embedded `decision` promise to get
+ * the coordinator's extend/stop decision.
+ *
+ * Distinct from `BudgetExceededError` which is a hard stop.
+ */
+declare class BudgetThresholdSignal extends Error {
+    readonly kind: BudgetKind;
+    readonly limit: number;
+    readonly used: number;
+    /** Resolves to 'extend' (with optional new limits) or 'stop' */
+    readonly decision: Promise<BudgetThresholdDecision>;
+    constructor(kind: BudgetKind, limit: number, used: number, decision: Promise<BudgetThresholdDecision>);
+}
+type BudgetThresholdDecision = 'stop' | {
+    extend: Partial<BudgetLimits>;
+};
+/**
+ * Callback invoked when a budget limit is about to be exceeded.
+ * Return 'throw' for hard stop (default — throws BudgetExceededError).
+ * Return 'continue' to allow one more unit and re-check next time.
+ * Return a Promise to ask the coordinator via `budget.threshold_reached`
+ * event (uses the same grant/deny pattern as `iteration.limit_reached`).
+ */
+type BudgetThresholdHandler = (info: {
+    kind: BudgetKind;
+    used: number;
+    limit: number;
+    requestDecision: () => Promise<BudgetThresholdDecision>;
+}) => 'throw' | 'continue' | Promise<BudgetThresholdDecision>;
+/**
+ * Per-subagent budget enforcement. Each subagent gets its own instance so a
+ * runaway agent can't drain the cost ceiling of its siblings. All record/check
+ * methods are O(1) and safe to call from hot paths.
+ *
+ * Behavior without `onThreshold`: hard stops synchronously on every limit hit.
+ *
+ * Behavior with `onThreshold` and `_mode === 'auto'`: emits `budget.threshold_reached`
+ * on the EventBus and throws `BudgetThresholdSignal`. The coordinator's verdict
+ * (extend/stop) resolves the embedded promise. If no listener responds within
+ * `DECISION_TIMEOUT_MS` the decision defaults to `'stop'`.
+ *
+ * Behavior with `onThreshold` and `_mode === 'sync'`: throws `BudgetExceededError`
+ * synchronously regardless of EventBus state or listener presence. This is useful
+ * for fire-and-forget subagents that have an `onThreshold` handler for logging/metrics
+ * but are not wired into a coordinator — the `'sync'` mode makes the hard-stop
+ * behavior explicit and means tests can use `expect().toThrow()` even without
+ * a fully-wired EventBus.
+ */
+declare class SubagentBudget {
+    readonly limits: Readonly<BudgetLimits>;
+    private iterations;
+    private toolCalls;
+    private tokenInput;
+    private tokenOutput;
+    private costUsd;
+    private startTime;
+    /**
+     * Timestamp of the most recent activity (iteration / tool call / token
+     * usage / streamed progress). Drives the idle timeout — reset by
+     * `markActivity()`. Initialised to `start()` time so a never-active agent
+     * still eventually trips its idle window.
+     */
+    private lastActivityTime;
+    private _onThreshold;
+    /**
+     * Hard cap on how long `_negotiateExtension` waits for the coordinator to
+     * respond before defaulting to 'stop'. Without this fallback an absent
+     * or hung listener (Director not built / event filter detached mid-run)
+     * leaves the budget over-limit and never enforces anything.
+     */
+    private static readonly DECISION_TIMEOUT_MS;
+    /**
+     * Injected by the runner when wiring the budget to its EventBus.
+     * Used to emit `budget.threshold_reached` events in `'auto'` mode.
+     */
+    _events?: EventBus;
+    /**
+     * Negotiation mode — controls whether a threshold hit tries to emit
+     * `budget.threshold_reached` and wait for a coordinator decision, or
+     * falls straight through to a synchronous hard stop.
+     *
+     * `'auto'` (default) — emit on the EventBus and wait; times out to 'stop'.
+     * `'sync'` — throw `BudgetExceededError` immediately regardless of listeners.
+     */
+    private _mode;
+    /**
+     * Optional callback for soft-limit handling. When set, the budget will
+     * invoke it rather than throw immediately. The handler decides whether to
+     * throw synchronously, continue, or ask the coordinator for an extension.
+     */
+    get onThreshold(): BudgetThresholdHandler | undefined;
+    set onThreshold(fn: BudgetThresholdHandler | undefined);
+    /** Returns the current negotiation mode. */
+    get mode(): BudgetNegotiationMode;
+    constructor(limits?: BudgetLimits, mode?: BudgetNegotiationMode);
+    start(): void;
+    /**
+     * Reset the idle clock. Called on any sign of forward progress —
+     * iterations, tool calls, token usage, and streamed tool/text progress —
+     * so a long-but-productive subagent never trips its `idleTimeoutMs`.
+     */
+    markActivity(): void;
+    /**
+     * Milliseconds since the last activity signal. Returns 0 before `start()`
+     * (nothing to measure yet). Used by the coordinator watchdog to decide
+     * whether to re-arm (still active) or reap (genuinely idle).
+     */
+    idleMs(): number;
+    /** Returns true if we're within 10% of any limit — useful for pre-flight checks. */
+    isNearLimit(): boolean;
+    /**
+     * Synchronous budget check. Always throws synchronously so callers (especially
+     * test event handlers using `expect().toThrow()`) get an unhandled rejection
+     * when the budget is exceeded without a handler.
+     *
+     * Decision table:
+     * - no `onThreshold` handler         → throw `BudgetExceededError` (hard stop, always)
+     * - `mode === 'sync'`               → throw `BudgetExceededError` (hard stop, always)
+     * - `mode === 'auto'` + no listener  → throw `BudgetExceededError` (hard stop; no one to ask)
+     * - `mode === 'auto'` + listener     → throw `BudgetThresholdSignal` with async decision promise
+     */
+    /**
+     * Collects all exceeded budget kinds into a single NOOP-free negotiation.
+     * Called by recordIteration / recordToolCall / recordUsage — each may call
+     * this for its own kind. The first call starts the negotiation and stores
+     * the Promise in _pendingNegotiation. Subsequent calls for DIFFERENT
+     * kinds (while a negotiation is in flight) are NOOPs — they don't start
+     * new conversations with the coordinator. This prevents an EventBus flood
+     * when multiple budget kinds are exceeded simultaneously in one iteration.
+     *
+     * Returns the kinds that were found to be exceeded (for logging/debugging).
+     */
+    private checkLimits;
+    /**
+     * Per-kind in-flight negotiation Promises. Each budget kind can have its
+     * own concurrent negotiation — e.g. iterations and timeout can both
+     * be exceeded simultaneously without blocking each other. The same kind
+     * cannot start two concurrent negotiations (dedup guard).
+     * Cleared in `_negotiateExtension`'s `finally` block.
+     */
+    private _pendingNegotiations;
+    /**
+     * Drive the threshold handler to a decision. Resolves with `'stop'`
+     * (signal the runner to abort) or `{ extend: ... }` (limits already
+     * patched in-place; the runner should not abort). Clears the
+     * per-kind slot in `_pendingNegotiations` in `finally`.
+     *
+     * The 'continue' return from a sync handler is treated as
+     * `{ extend: {} }` — keep going without patching; next overrun fires
+     * a fresh signal.
+     */
+    private _negotiateExtension;
+    recordIteration(): void;
+    recordToolCall(): void;
+    recordUsage(usage: Usage, costUsd?: number): void;
+    /**
+     * Wall-clock / idle budget check. Delegates to `checkLimits(elapsed)`, so
+     * `timeout` and `idle_timeout` follow the SAME negotiation path as the other
+     * kinds — they are NOT a special-cased hard stop. This is deliberate: a
+     * heartbeat-aware policy (see `attachAutoExtend` and `CollabSession`) grants
+     * a timeout extension only while the agent is making progress and denies it
+     * once the agent is genuinely stuck, which is safer than an unconditional
+     * hard kill of a long-but-working agent. The runner translates the resulting
+     * `BudgetThresholdSignal` decision (`extend` → patch limits in place,
+     * `stop` → abort) just like every other kind.
+     *
+     * Decision table (same as `checkLimits`):
+     * - no `onThreshold` handler        → throw `BudgetExceededError` (hard stop)
+     * - `mode === 'sync'`               → throw `BudgetExceededError` (hard stop)
+     * - `mode === 'auto'` + no listener → throw `BudgetExceededError` (no one to ask)
+     * - `mode === 'auto'` + listener    → throw `BudgetThresholdSignal` (negotiated;
+     *                                     a heartbeat-aware policy may extend the timeout)
+     */
+    checkTimeout(): void;
+    /** Returns true if a wall-clock or idle timeout has occurred without throwing. */
+    isTimedOut(): boolean;
+    usage(): BudgetUsage;
+}
+
+interface SubagentConfig {
+    id?: string;
+    name: string;
+    role?: string;
+    prompt?: string;
+    maxIterations?: number;
+    maxToolCalls?: number;
+    maxTokens?: number;
+    maxCostUsd?: number;
+    /** Hard wall-clock cap (ms) from start. Opt-in; prefer `idleTimeoutMs`. */
+    timeoutMs?: number;
+    /**
+     * Idle timeout (ms): reap the subagent only after this long with no
+     * activity. Resets on every iteration / tool call / streamed progress, so
+     * an actively-working agent runs until its task naturally ends. This is the
+     * default reaper for delegated subagents (see `applyRosterBudget`).
+     */
+    idleTimeoutMs?: number;
+    tools?: string[];
+    model?: string;
+    priority?: number;
+    /**
+     * Working directory for this subagent's tools. Defaults to the factory's
+     * cwd. AutoPhase sets this to a per-phase git worktree so parallel phases
+     * edit isolated checkouts instead of clobbering one shared working tree.
+     * `projectRoot` is intentionally left unchanged — tools resolve the
+     * worktree's `.git` gitlink from `cwd` while staying bounded to the repo.
+     */
+    cwd?: string;
+    /**
+     * Provider registry id (e.g. `'anthropic'`, `'openai'`, `'google'`).
+     * Allows a director to mix providers across siblings — one subagent on
+     * Sonnet, another on GPT-5, another on Haiku. Falls back to the
+     * factory's default provider when omitted, which is the legacy
+     * single-provider behavior.
+     */
+    provider?: string;
+    /**
+     * Per-subagent session JSONL path. When omitted the orchestrator-
+     * supplied factory derives a path under `<sessionRoot>/<runId>/`.
+     * Override to redirect the transcript elsewhere (long-term storage,
+     * a different filesystem, etc.).
+     */
+    sessionPath?: string;
+    /**
+     * Additional text appended to the role's base system prompt. Does not
+     * replace it. Useful for last-mile guidance like "you may only call
+     * read tools, never write" or "respond in JSON only".
+     */
+    systemPromptOverride?: string;
+    /**
+     * Routing for streaming output. `'director'` (default) forwards
+     * text/tool events to the parent's FleetBus so the director can read
+     * the subagent's stream. `'silent'` keeps everything subagent-local;
+     * the director only sees the final task result. `'user'` forwards
+     * direct to the user-facing renderer (gate this behind an explicit
+     * config flag — it can confuse the chat surface).
+     */
+    textStream?: 'director' | 'silent' | 'user';
+    toolStream?: 'director' | 'silent' | 'user';
+}
+/**
+ * Discriminator for every distinct failure mode a subagent can hit. The
+ * coordinator's classifier (`classifySubagentError` in
+ * coordination/multi-agent-coordinator.ts) maps raw exceptions to one of
+ * these — callers (delegate tool, /agents UI, retry policies) can then
+ * branch on `kind` instead of grepping `error.message`. Each kind
+ * documents its retryability so an orchestrator can act on it without
+ * extra knowledge.
+ */
+type SubagentErrorKind = 
+/** Provider returned 5xx. Transient server-side issue — safe to retry with backoff. */
+'provider_5xx'
+/** Provider returned 429. Rate-limited — retry with `backoffMs` delay. */
+ | 'provider_rate_limit'
+/** Provider call timed out at the network layer (TCP / TLS / read). Retry safe. */
+ | 'provider_timeout'
+/** Provider rejected the credentials (401/403). NOT retryable — config fix required. */
+ | 'provider_auth'
+/** Model returned a "context length exceeded" error. Retrying without trimming will fail again. */
+ | 'context_overflow'
+/** A tool's `execute()` returned `ok:false`. Logical task failure, not a crash. */
+ | 'tool_failed'
+/** A tool's `execute()` threw an exception. Often retryable but cause-dependent. */
+ | 'tool_threw'
+/** Hit the per-subagent `maxIterations` budget. Either raise budget or narrow task. */
+ | 'budget_iterations'
+/** Hit the per-subagent `maxToolCalls` budget. Either raise budget or narrow task. */
+ | 'budget_tool_calls'
+/** Hit the per-subagent `maxTokens` budget. */
+ | 'budget_tokens'
+/** Hit the per-subagent `maxCostUsd` budget. */
+ | 'budget_cost'
+/** Hit the per-subagent `timeoutMs` wall-clock budget. */
+ | 'budget_timeout'
+/** Parent agent's AbortController fired (user Ctrl+C, parent unwound, sibling failure cascade). */
+ | 'aborted_by_parent'
+/** LLM returned end_turn with no textual content. Often a prompt issue. */
+ | 'empty_response'
+/** Parent-child bridge transport failed (rare — IPC / writer crash). */
+ | 'bridge_failed'
+/** Everything else. Classifier fallback — should narrow over time as new modes appear. */
+ | 'unknown';
+/**
+ * Structured failure envelope. Replaces the prior `error?: string` so
+ * callers can switch on `kind`, respect `retryable`, and apply
+ * provider-suggested `backoffMs` instead of guessing from substring
+ * matches on the message.
+ */
+interface SubagentError {
+    /** Discriminator — see SubagentErrorKind doc strings for semantics. */
+    kind: SubagentErrorKind;
+    /** Human-readable summary, suitable for direct UI display. Always populated. */
+    message: string;
+    /** True if the operation can be retried as-is (possibly with backoff). */
+    retryable: boolean;
+    /** Suggested backoff before retry, in ms. Set for `provider_rate_limit` and `provider_5xx`. */
+    backoffMs?: number;
+    /** Original cause snapshot for diagnostics — never used for control flow. */
+    cause?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+interface TaskResult<T = unknown> {
+    subagentId: string;
+    taskId: string;
+    status: 'success' | 'failed' | 'timeout' | 'stopped';
+    result?: T;
+    /**
+     * Structured failure envelope. Populated whenever `status !== 'success'`.
+     * Prefer reading `error.kind` over substring-matching `error.message`.
+     */
+    error?: SubagentError;
+    iterations: number;
+    toolCalls: number;
+    durationMs: number;
+}
+interface TaskSpec {
+    id: string;
+    description: string;
+    subagentId?: string;
+    priority?: number;
+    maxToolCalls?: number;
+    timeoutMs?: number;
+    context?: Record<string, unknown>;
+}
+interface DoneCondition {
+    type: 'iterations' | 'tool_calls' | 'output_match' | 'custom' | 'all_tasks_done' | 'directive';
+    maxIterations?: number;
+    maxToolCalls?: number;
+    pattern?: string;
+    predicate?: string;
+    /**
+     * For `directive` type — stop when model emits [done] and keep going
+     * on [continue]/[next step]/[proceed] WITHOUT returning to the outer runner.
+     * When false (default), the runner behaves normally (one agent.run per loop).
+     * When true, the runner passes `autonomousContinue: true` to the agent and
+     * re-runs internally when the model signals continue.
+     */
+    autonomous?: boolean;
+}
+interface MultiAgentConfig {
+    coordinatorId: string;
+    leaderSystemPrompt?: string;
+    subagents?: SubagentConfig[];
+    maxConcurrent?: number;
+    doneCondition: DoneCondition;
+    timeoutMs?: number;
+    /**
+     * Optional default budget applied to every spawned subagent. Per-subagent
+     * fields in `SubagentConfig` override these. Coordinator enforces them by
+     * constructing a `SubagentBudget` per spawn — see `SubagentRunContext.budget`.
+     */
+    defaultBudget?: {
+        maxIterations?: number;
+        maxToolCalls?: number;
+        maxTokens?: number;
+        maxCostUsd?: number;
+        timeoutMs?: number;
+        idleTimeoutMs?: number;
+    };
+}
+interface SpawnResult {
+    subagentId: string;
+    agentId: string;
+}
+interface TaskDelegation {
+    task: TaskSpec;
+    subagentId: string;
+}
+interface CoordinatorEvents {
+    'task.assigned': {
+        task: TaskSpec;
+        subagentId: string;
+    };
+    'task.completed': {
+        task: TaskSpec;
+        result: TaskResult;
+    };
+    'subagent.started': {
+        subagent: SubagentConfig;
+    };
+    'subagent.stopped': {
+        subagentId: string;
+        reason: string;
+    };
+    done: {
+        results: TaskResult[];
+        totalIterations: number;
+    };
+}
+interface MultiAgentCoordinator {
+    readonly coordinatorId: string;
+    readonly config: MultiAgentConfig;
+    spawn(subagent: SubagentConfig): Promise<SpawnResult>;
+    assign(task: TaskSpec): Promise<void>;
+    delegate(to: string, msg: BridgeMessage): Promise<void>;
+    stop(subagentId: string): Promise<void>;
+    stopAll(): Promise<void>;
+    /**
+     * Stop a subagent and remove it from the coordinator. Releases all
+     * associated resources. The subagent id can be reused in a future spawn.
+     */
+    remove(subagentId: string): Promise<void>;
+    getStatus(): CoordinatorStatus;
+    /**
+     * Wait for one or more tasks to complete and return their results.
+     * If a task is already done when called, returns immediately.
+     * Resolves to an array in the same order as `taskIds`.
+     */
+    awaitTasks(taskIds: string[]): Promise<TaskResult[]>;
+    /** Snapshot of completed task results. */
+    results(): readonly TaskResult[];
+}
+/**
+ * Caller-supplied runner that actually executes a task. The coordinator
+ * provides isolated state (own budget, own AbortSignal, own bridge handle)
+ * and enforces concurrency limits — the runner just runs the task and reports
+ * the outcome. This is the injection seam that decouples the coordinator
+ * from `Agent` so it can be tested with mocks and reused for non-Agent
+ * subagents (workers, MCP-driven subagents, etc.).
+ */
+type SubagentRunner = (task: TaskSpec, ctx: SubagentRunContext) => Promise<SubagentRunOutcome>;
+interface SubagentRunContext {
+    subagentId: string;
+    config: SubagentConfig;
+    budget: SubagentBudget;
+    signal: AbortSignal;
+    /** Null until `setSubagentBridge` is called for this subagent. */
+    bridge: AgentBridge | null;
+}
+interface SubagentRunOutcome {
+    result?: unknown;
+    iterations: number;
+    toolCalls: number;
+}
+interface CoordinatorStatus {
+    coordinatorId: string;
+    subagents: {
+        id: string;
+        name: string;
+        status: 'running' | 'idle' | 'stopped' | 'error';
+        currentTask?: string;
+        /** Cumulative budget auto-extensions granted to this subagent, when the
+         *  status is produced by a Director that tracks them. */
+        extensions?: number;
+    }[];
+    pendingTasks: number;
+    completedTasks: number;
+    totalIterations: number;
+    done: boolean;
+}
+interface SubagentContext {
+    subagentId: string;
+    tasks: TaskSpec[];
+    /**
+     * Two-phase initialization: `spawn()` creates the subagent before the
+     * bridge is wired (`setSubagentBridge()`), so `parentBridge` is nullable
+     * by design. Readers must `hasParentBridge()`-guard or null-check before
+     * use; the prior `null as unknown as AgentBridge` cast was a type lie
+     * that hid this from the compiler.
+     */
+    parentBridge: AgentBridge | null;
+    doneCondition: DoneCondition;
+    maxConcurrent: number;
+}
+
+/**
+ * Single fleet-wide event with subagent attribution. Whatever a child
+ * agent emits on its own EventBus gets re-published here, prefixed with
+ * `subagentId` so a single subscriber can multiplex across the fleet.
+ *
+ * The director uses `FleetBus.filter('tool.executed', …)` to see every
+ * tool call across the fleet; the TUI uses
+ * `FleetBus.subscribe(id, handler)` to render a per-subagent panel.
+ */
+interface FleetEvent {
+    subagentId: string;
+    taskId?: string;
+    ts: number;
+    type: string;
+    payload: unknown;
+}
+type FleetHandler = (event: FleetEvent) => void;
+/**
+ * Fan-in for per-subagent EventBuses. Each subagent's bus is plugged in
+ * via `attach()`; the FleetBus re-emits every event with subagent
+ * attribution. Detachment is automatic via the returned disposer — call
+ * it when a subagent terminates so we don't leak listeners.
+ *
+ * The bus exposes two subscription modes: by `subagentId` (everything
+ * from one child) and by `type` (one event-type across the fleet). They
+ * compose — if you need a per-subagent + per-type slice, subscribe by
+ * type and filter on `event.subagentId` in your handler.
+ */
+declare class FleetBus {
+    private readonly byId;
+    private readonly byType;
+    private readonly any;
+    /**
+     * Hook a subagent's EventBus into the fleet. Uses `onAny()` (an alias for
+     * `onPattern('*')`) to forward all events with subagent attribution, so
+     * new kernel event types are automatically forwarded without any manual
+     * registration. `subagent.*` events are excluded because they originate
+     * from MultiAgentHost on the parent bus, not the subagent's own bus.
+     *
+     * Returns a disposer that detaches every subscription; call on
+     * subagent teardown so the listeners don't outlive the run.
+     */
+    attach(subagentId: string, bus: EventBus, taskId?: string): () => void;
+    /** Subscribe to every event from one subagent. */
+    subscribe(subagentId: string, handler: FleetHandler): () => void;
+    /** Subscribe to one event type across all subagents. */
+    filter(type: string, handler: FleetHandler): () => void;
+    /** Subscribe to literally everything. The fleet roll-up uses this. */
+    onAny(handler: FleetHandler): () => void;
+    emit(event: FleetEvent): void;
+}
+/**
+ * Roll-up of token usage + cost across an entire director run. The
+ * director's `fleet_status` tool returns this so the model can reason
+ * about budget in its next turn ("the researcher already burned $0.40,
+ * lean on summaries for the next task").
+ */
+interface FleetUsage {
+    total: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+    };
+    perSubagent: Record<string, SubagentUsageSnapshot>;
+}
+interface SubagentUsageSnapshot {
+    subagentId: string;
+    provider?: string;
+    model?: string;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    toolCalls: number;
+    iterations: number;
+    startedAt: number;
+    lastEventAt: number;
+}
+/**
+ * Aggregates provider.response + tool.executed events from the FleetBus
+ * into a live `FleetUsage` snapshot. Costs are computed by the caller
+ * via a `priceLookup(subagentId)` so we don't bake provider-pricing
+ * coupling into core; the CLI/tests supply a function that resolves
+ * each subagent's per-token rates from the models registry.
+ */
+declare class FleetUsageAggregator {
+    private readonly priceLookup?;
+    private readonly metaLookup?;
+    private readonly perSubagent;
+    private readonly total;
+    private readonly unsub;
+    constructor(bus: FleetBus, priceLookup?: ((subagentId: string, provider?: string, model?: string) => {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    } | undefined) | undefined, metaLookup?: ((subagentId: string) => {
+        provider?: string;
+        model?: string;
+    } | undefined) | undefined);
+    /**
+     * Remove a terminated subagent's data from the aggregator and subtract its
+     * contribution from the running totals. Call this when a subagent is removed
+     * from the fleet so the aggregator doesn't accumulate unbounded data for
+     * entities that will never emit events again.
+     */
+    removeSubagent(subagentId: string): void;
+    /** Disposes all fleet-bus subscriptions. Call when the aggregator is no longer needed. */
+    dispose(): void;
+    /** Live snapshot — safe to call from a tool's execute() body. */
+    snapshot(): FleetUsage;
+    private ensure;
+    private onProviderResponse;
+    private onToolExecuted;
+    private onIterationStarted;
+}
+
+/**
+ * Caller-supplied factory that builds an isolated `Agent` for a subagent.
+ * The factory MUST construct a fresh `Context` per call — sharing context
+ * between subagents defeats isolation. Each Agent should also use either
+ * its own `EventBus` or a forwarded view, so per-subagent metrics can be
+ * attributed correctly.
+ */
+type AgentFactory = (config: SubagentConfig) => Promise<AgentFactoryResult>;
+interface AgentFactoryResult {
+    agent: Agent;
+    /** Event bus the factory wired to this agent — required for budget hookup. */
+    events: EventBus;
+    /**
+     * Optional cleanup hook invoked in the runner's `finally` block once
+     * the task ends (success, failure, abort — same exit path). Factories
+     * that own resources scoped to a single task (per-subagent JSONL
+     * writers, transient providers, throwaway containers) implement this
+     * to close them deterministically instead of relying on GC. Errors
+     * thrown here are swallowed so a flaky cleanup can't mask the task's
+     * real result.
+     */
+    dispose?: () => Promise<void> | void;
+}
+interface AgentRunnerOptions {
+    factory: AgentFactory;
+    /**
+     * Format a TaskSpec into the user input the agent will receive. Defaults
+     * to `task.description ?? ''`. Override when subagents expect structured
+     * input (e.g. JSON contracts, role-prefixed prompts).
+     */
+    formatTaskInput?: (task: TaskSpec, config: SubagentConfig) => AgentInput;
+    /**
+     * When set, the runner attaches the subagent's EventBus to this FleetBus
+     * on task start and detaches it when the task finishes. This is the
+     * injection seam that lets the TUI fleet panel observe subagent activity
+     * live — without it, FleetBus stays empty.
+     */
+    fleetBus?: FleetBus;
+}
+/**
+ * Builds a `SubagentRunner` that drives a real `Agent` per task while honoring
+ * the coordinator's budget and abort signal. This is the production adapter —
+ * the coordinator's `runner` option in CLI/TUI assemblies points here.
+ *
+ * Lifecycle per task:
+ *   1. factory(config) → fresh Agent + EventBus.
+ *   2. Subscribe to events to feed the budget (tool calls, token usage).
+ *   3. Call agent.run(input, { signal }) — the coordinator's signal cancels.
+ *   4. Map RunResult.status onto a `SubagentRunOutcome` or throw on failure.
+ *   5. Unsubscribe and let the factory's resources be GC'd.
+ *
+ * The budget is checked synchronously from event handlers — a runaway agent
+ * that crosses its tool-call limit triggers `BudgetExceededError`, which the
+ * coordinator surfaces as `status: 'failed'` on the task result.
+ */
+declare function makeAgentSubagentRunner(opts: AgentRunnerOptions): SubagentRunner;
+
+export { Agent as A, type BridgeMessage as B, type CoordinatorEvents as C, type DoneCondition as D, type ProviderFactory as E, FleetBus as F, type ProviderRegistryView as G, type SlashCommand as H, type SlashCommandRegistryView as I, type SpawnResult as J, SubagentBudget as K, type SubagentConfig as L, type MCPRegistryView as M, type SubagentContext as N, type SubagentError as O, type Plugin as P, type SubagentErrorKind as Q, type SubagentRunContext as R, type SessionWriterView as S, type SubagentRunOutcome as T, type SubagentRunner as U, type SubagentUsageSnapshot as V, type TaskDelegation as W, type TaskResult as X, type TaskSpec as Y, type ToolRegistryView as Z, makeAgentSubagentRunner as _, type AgentBridge as a, type AgentBridgeConfig as b, type AgentFactory as c, type AgentFactoryResult as d, type AgentRunnerOptions as e, type BridgeTransport as f, BudgetExceededError as g, type BudgetKind as h, type BudgetLimits as i, type BudgetNegotiationMode as j, type BudgetThresholdDecision as k, type BudgetThresholdHandler as l, BudgetThresholdSignal as m, type BudgetUsage as n, type CoordinatorStatus as o, type FleetEvent as p, type FleetHandler as q, type FleetUsage as r, FleetUsageAggregator as s, type MetricsSinkView as t, type MultiAgentConfig as u, type MultiAgentCoordinator as v, type PluginAPI as w, type PluginCapabilities as x, type PluginDependency as y, type PluginPipelines as z };