@wrongstack/core 0.89.1 → 0.89.3

package/dist/{agent-subagent-runner-CQaLFNnA.d.ts → agent-subagent-runner-C6eqID1t.d.ts}

@@ -1,344 +1,133 @@
-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-Dx-CnrDN.js';
-import { C as Container, e as Renderer, R as ReadonlyPipeline } from './system-prompt-C0rLCeyn.js';
-import { E as EventBus, k as EventName, L as Listener } from './events-DzyLtja6.js';
-import { a as RetryPolicy, E as ErrorHandler } from './retry-policy-DSu6O6rD.js';
-import { a as Logger } from './logger-B72yyPc6.js';
-import { T as Tracer } from './observability-CoSNZdhX.js';
-import { a as PermissionPolicy } from './permission-14CChMmO.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-ToHAp4-U.js';
-import { l as HookEvent, n as HookMatcher, I as InProcessHook, a as Config } from './config-_DZ7dN-T.js';
-import { W as WireFamily } from './models-registry-Be3osGt5.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>;
-}
+import { c as ToolCallPipelinePayload, d as ToolWrapper, E as ExtensionRegistry, S as SystemPromptContributor, e as ToolRegistry, P as ProviderRegistry, A as AgentPipelines, f as ToolExecutorLike, g as AgentInit, h as AgentInput, R as RunResult } from './index-D3Nax3YU.js';
+import { C as Container, R as ReadonlyPipeline, a as Renderer } from './pipeline-C1Ad9OjI.js';
+import { E as EventBus, a as EventName, L as Listener } from './brain-s9DyD_Vf.js';
+import { R as RetryPolicy, E as ErrorHandler } from './retry-policy-BcmuT_V0.js';
+import { L as Logger } from './logger-B63L5bTg.js';
+import { T as Tracer } from './observability-D-HZN_mF.js';
+import { P as PermissionPolicy } from './permission-BDv7z0mk.js';
+import { U as Usage, C as Context, J as JSONSchema, R as Request, b as Response, g as ContentBlock, l as TextBlock, T as Tool, P as Provider, o as RunOptions } from './context-CNRYfhUv.js';
+import { H as HookEvent, a as HookMatcher, I as InProcessHook, C as Config } from './config-84VaZpH6.js';
+import { W as WireFamily } from './models-registry-B6_KfS65.js';
 
 /**
- * A slash command registered with the CLI or available to plugins.
- * Plugins receive a view of the registry via PluginAPI.slashCommands.
+ * 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.
  *
- * Commands registered by plugins use a namespaced name: `pluginName:commandName`.
- * This prevents collisions with built-in commands and other plugins.
+ * 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 SlashCommand {
-    /** Unique command name. For plugins: `pluginName:commandName`. */
-    name: string;
-    /** Short aliases — also prefixed automatically: `pluginName:alias`. */
-    aliases?: string[] | undefined;
-    description: string;
-    /**
-     * Category used to group commands in the slash picker. Defaults to 'App'
-     * when omitted.
-     */
-    category?: 'Run' | 'Session' | 'Inspect' | 'Agent' | 'Config' | 'App' | undefined;
-    /**
-     * 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 | undefined;
-    /**
-     * 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 | undefined;
-    /**
-     * 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 | undefined;
-        message?: string | undefined;
-        runText?: string | undefined;
-        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 {
+interface FleetEvent {
+    subagentId: string;
+    taskId?: string | undefined;
+    ts: number;
     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[];
+    payload: unknown;
 }
+type FleetHandler = (event: FleetEvent) => void;
 /**
- * Read-only view of the session writer. Plugins can append custom events
- * to the JSONL session log and read the transcript path.
+ * 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 `append` method accepts any JSON-serializable payload — custom
- * event types are persisted verbatim next to the built-in events.
+ * 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.
  */
-interface SessionWriterView {
-    readonly transcriptPath?: string | undefined;
-    append(event: Record<string, unknown> & {
-        type: string;
-        ts: string;
-    }): Promise<void>;
+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;
+    clear(): 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).
+ * 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 MetricsSinkView {
-    counter(name: string, value?: number | undefined, 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 FleetUsage {
+    total: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+    };
+    perSubagent: Record<string, SubagentUsageSnapshot>;
 }
-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 SubagentUsageSnapshot {
+    subagentId: string;
+    provider?: string | undefined;
+    model?: string | undefined;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    toolCalls: number;
+    iterations: number;
+    startedAt: number;
+    lastEventAt: number;
 }
-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;
+/**
+ * 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 | undefined, model?: string | undefined) => {
+        input?: number | undefined;
+        output?: number | undefined;
+        cacheRead?: number | undefined;
+        cacheWrite?: number | undefined;
+    } | undefined) | undefined, metaLookup?: ((subagentId: string) => {
+        provider?: string | undefined;
+        model?: string | undefined;
+    } | undefined) | undefined);
     /**
-     * Register a system prompt contributor. Plugins call this to inject
-     * ephemeral TextBlocks into the system prompt on every build.
-     * Returns an unregister function.
+     * 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.
      */
-    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 | undefined;
-    /** Will register provider factories via `api.providers.register()`. */
-    providers?: boolean | undefined;
-    /**
-     * 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[] | undefined;
-    /** Will register slash commands via `api.slashCommands.register()`. */
-    slashCommands?: boolean | undefined;
-    /** Will start MCP servers via `api.mcp.start()`. */
-    mcp?: boolean | undefined;
-}
-/**
- * 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 | undefined;
-}
-interface Plugin {
-    name: string;
-    version?: string | undefined;
-    /** One-line summary for `wstack plugins list` and error messages. */
-    description?: string | undefined;
-    /** 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 | undefined;
-    /**
-     * 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 | undefined;
-    /**
-     * 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)[] | undefined;
-    /** Optional plugin dependencies — silently skipped if absent. */
-    optionalDeps?: (string | PluginDependency)[] | undefined;
-    conflictsWith?: string[] | undefined;
-    /**
-     * 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 | undefined;
-    }>;
-}
-
-type BridgeMessageType = 'task' | 'result' | 'progress' | 'error' | 'heartbeat' | 'stop' | 'delegate' | 'budget_threshold';
-interface BridgeMessage<T = unknown> {
-    id: string;
-    type: BridgeMessageType;
-    from: string;
-    to?: string | undefined;
-    payload: T;
-    timestamp: number;
-    priority?: 'low' | 'normal' | 'high' | 'critical' | undefined;
-}
-interface AgentBridgeConfig {
-    agentId: string;
-    coordinatorId: string;
-    timeoutMs?: number | undefined;
-    bufferSize?: number | undefined;
-}
-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>> | undefined;
-    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>;
+    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;
 }
 
 type BudgetKind = 'tool_calls' | 'iterations' | 'tokens' | 'timeout' | 'idle_timeout' | 'cost';
@@ -578,6 +367,37 @@ declare class SubagentBudget {
     usage(): BudgetUsage;
 }
 
+type BridgeMessageType = 'task' | 'result' | 'progress' | 'error' | 'heartbeat' | 'stop' | 'delegate' | 'budget_threshold';
+interface BridgeMessage<T = unknown> {
+    id: string;
+    type: BridgeMessageType;
+    from: string;
+    to?: string | undefined;
+    payload: T;
+    timestamp: number;
+    priority?: 'low' | 'normal' | 'high' | 'critical' | undefined;
+}
+interface AgentBridgeConfig {
+    agentId: string;
+    coordinatorId: string;
+    timeoutMs?: number | undefined;
+    bufferSize?: number | undefined;
+}
+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>> | undefined;
+    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>;
+}
+
 interface SubagentConfig {
     id?: string | undefined;
     name: string;
@@ -876,124 +696,304 @@ interface SubagentContext {
 }
 
 /**
- * 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 | undefined;
-    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.
+ * A slash command registered with the CLI or available to plugins.
+ * Plugins receive a view of the registry via PluginAPI.slashCommands.
  *
- * 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.
+ * Commands registered by plugins use a namespaced name: `pluginName:commandName`.
+ * This prevents collisions with built-in commands and other plugins.
  */
-declare class FleetBus {
-    private readonly byId;
-    private readonly byType;
-    private readonly any;
+interface SlashCommand {
+    /** Unique command name. For plugins: `pluginName:commandName`. */
+    name: string;
+    /** Short aliases — also prefixed automatically: `pluginName:alias`. */
+    aliases?: string[] | undefined;
+    description: string;
     /**
-     * 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.
+     * Category used to group commands in the slash picker. Defaults to 'App'
+     * when omitted.
      */
-    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;
-    clear(): 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").
+    category?: 'Run' | 'Session' | 'Inspect' | 'Agent' | 'Config' | 'App' | undefined;
+    /**
+     * 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 | undefined;
+    /**
+     * 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 | undefined;
+    /**
+     * 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 | undefined;
+        message?: string | undefined;
+        runText?: string | undefined;
+        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 FleetUsage {
-    total: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        cost: number;
-    };
-    perSubagent: Record<string, SubagentUsageSnapshot>;
+interface SessionWriterView {
+    readonly transcriptPath?: string | undefined;
+    append(event: Record<string, unknown> & {
+        type: string;
+        ts: string;
+    }): Promise<void>;
 }
-interface SubagentUsageSnapshot {
-    subagentId: string;
-    provider?: string | undefined;
-    model?: string | undefined;
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    cost: number;
-    toolCalls: number;
-    iterations: number;
-    startedAt: number;
-    lastEventAt: number;
+/**
+ * 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 | undefined, 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;
 }
 /**
- * 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.
+ * 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.
  */
-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 | undefined, model?: string | undefined) => {
-        input?: number | undefined;
-        output?: number | undefined;
-        cacheRead?: number | undefined;
-        cacheWrite?: number | undefined;
-    } | undefined) | undefined, metaLookup?: ((subagentId: string) => {
-        provider?: string | undefined;
-        model?: string | undefined;
-    } | undefined) | undefined);
+interface PluginCapabilities {
+    /** Will register tools via `api.tools.register()`. */
+    tools?: boolean | undefined;
+    /** Will register provider factories via `api.providers.register()`. */
+    providers?: boolean | 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.
+     * Pipelines the plugin hooks into. Use the standard names
+     * (`request | response | toolCall | userInput | assistantOutput | contextWindow`)
+     * or custom pipeline names exposed by other plugins.
      */
-    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;
+    pipelines?: string[] | undefined;
+    /** Will register slash commands via `api.slashCommands.register()`. */
+    slashCommands?: boolean | undefined;
+    /** Will start MCP servers via `api.mcp.start()`. */
+    mcp?: boolean | undefined;
+}
+/**
+ * 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 | undefined;
+}
+interface Plugin {
+    name: string;
+    version?: string | undefined;
+    /** One-line summary for `wstack plugins list` and error messages. */
+    description?: string | undefined;
+    /** 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 | undefined;
+    /**
+     * 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 | undefined;
+    /**
+     * 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)[] | undefined;
+    /** Optional plugin dependencies — silently skipped if absent. */
+    optionalDeps?: (string | PluginDependency)[] | undefined;
+    conflictsWith?: string[] | undefined;
+    /**
+     * 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 | undefined;
+    }>;
+}
+
+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>;
 }
 
 /**
@@ -1053,4 +1053,4 @@ interface AgentRunnerOptions {
  */
 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 };
+export { type AgentBridge as A, type BridgeTransport as B, type CoordinatorStatus as C, type PluginPipelines as D, type ToolRegistryView as E, FleetBus as F, type ProviderRegistryView as G, type MCPRegistryView as H, type SlashCommandRegistryView as I, type SessionWriterView as J, type MetricsSinkView as K, type Plugin as L, type MultiAgentCoordinator as M, type CoordinatorEvents as N, type DoneCondition as O, type PluginAPI as P, type PluginCapabilities as Q, type PluginDependency as R, type SubagentConfig as S, type TaskSpec as T, type SubagentContext as U, type SubagentError as V, type SubagentErrorKind as W, type SubagentRunContext as X, type SubagentRunOutcome as Y, type TaskDelegation as Z, type ProviderFactory as _, type BridgeMessage as a, type AgentBridgeConfig as b, type MultiAgentConfig as c, type SubagentRunner as d, type SpawnResult as e, type TaskResult as f, Agent as g, type AgentFactory as h, type AgentFactoryResult as i, type AgentRunnerOptions as j, BudgetExceededError as k, type BudgetKind as l, type BudgetLimits as m, type BudgetNegotiationMode as n, type BudgetThresholdDecision as o, type BudgetThresholdHandler as p, BudgetThresholdSignal as q, type BudgetUsage as r, type FleetEvent as s, type FleetHandler as t, type FleetUsage as u, FleetUsageAggregator as v, SubagentBudget as w, type SubagentUsageSnapshot as x, makeAgentSubagentRunner as y, type SlashCommand as z };