@wrongstack/core 0.1.10 → 0.3.1

package/dist/index-BDb0cAMP.d.ts

@@ -0,0 +1,806 @@
+import { u as Tool, z as ToolResultBlock, T as TextBlock, a0 as Context, R as Request, j as Response, D as ToolUseBlock, g as Provider, W as WrongStackError, b as ContentBlock, a7 as RunOptions, J as JSONSchema } from './context-IovtuTf8.js';
+import { L as Logger } from './logger-BMQgxvdy.js';
+import { R as Renderer, B as BuildContext, C as Container, P as Pipeline, e as ReadonlyPipeline } from './system-prompt-Dk1qm8ey.js';
+import { T as Tracer } from './observability-BhnVLBLS.js';
+import { E as EventBus, a as EventName, L as Listener } from './events-CNB9PALO.js';
+import { a as PermissionPolicy, S as SecretScrubber } from './secret-scrubber-CgG2tV2B.js';
+import { e as ProviderConfig, C as Config } from './config-CKLYPkCi.js';
+import { W as WireFamily } from './models-registry-Y2xbog0E.js';
+
+/**
+ * A function that wraps (decorates) an existing tool. Receives the
+ * original tool and returns a modified version — typically the same
+ * tool with a wrapped `execute` / `executeStream`, or with modified
+ * metadata (description, permission).
+ *
+ * Use `ToolRegistry.wrap()` to apply; the wrapper is called immediately
+ * and the result replaces the registered tool. Multiple wraps stack —
+ * each wrapper receives the output of the previous.
+ *
+ * @example
+ * ```ts
+ * registry.wrap('read', (original) => ({
+ *   ...original,
+ *   async execute(input, ctx, opts) {
+ *     console.log('read called');
+ *     return original.execute(input, ctx, opts);
+ *   }
+ * }));
+ * ```
+ */
+type ToolWrapper = (tool: Tool) => Tool;
+declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool, owner?: string): void;
+    /**
+     * Attempt to register a tool. Returns true if successful, false if a tool
+     * with the same name is already registered. Useful in multi-agent or plugin
+     * scenarios where duplicate registration may be intentional.
+     */
+    tryRegister(tool: Tool, owner?: string): boolean;
+    /**
+     * Bulk-register multiple tools at once. Each tool that conflicts with an
+     * existing registration is silently skipped — use `registerAllOrThrow`
+     * if you want it to throw on conflicts.
+     */
+    registerAll(tools: Tool[], owner?: string): void;
+    /**
+     * Bulk-register and throw on the first conflict. Use when you need
+     * strict registration (e.g. at boot time).
+     */
+    registerAllOrThrow(tools: Tool[], owner?: string): void;
+    /**
+     * Register a tool as a default. If the tool name is already registered,
+     * this is a no-op — the existing registration (from core or another
+     * plugin) takes precedence. Use `override` to intentionally replace.
+     */
+    registerDefault(tool: Tool, owner?: string): void;
+    unregister(name: string): boolean;
+    /**
+     * Override an existing tool. Throws if the tool is not already registered.
+     * Plugins use this to replace built-in tools with custom implementations.
+     */
+    override(name: string, tool: Tool, owner?: string): void;
+    /**
+     * Wrap (decorate) an existing tool. The wrapper receives the current
+     * tool and must return a new tool — typically the same tool with a
+     * wrapped `execute` or `executeStream`. Throws if the tool is not
+     * registered.
+     *
+     * Multiple wraps stack: each wrapper gets the output of the previous.
+     *
+     * @example
+     * registry.wrap('bash', (t) => ({ ...t, permission: 'confirm' }));
+     */
+    wrap(name: string, wrapper: ToolWrapper, owner?: string): void;
+    get(name: string): Tool | undefined;
+    ownerOf(name: string): string | undefined;
+    list(): Tool[];
+    /**
+     * Group tools by their `category` field. Tools without a category
+     * are placed under the key `""` (empty string). Returns a Map of
+     * category → tools, sorted by registration order within each category.
+     */
+    listByCategory(): Map<string, Tool[]>;
+    listWithOwner(): {
+        tool: Tool;
+        owner: string;
+    }[];
+    clear(): void;
+}
+
+/**
+ * Output from a single tool execution.
+ */
+interface ToolExecutionOutput {
+    result: ToolResultBlock | ToolConfirmPendingResult;
+    tool?: Tool;
+    durationMs: number;
+}
+/**
+ * Result of running a batch of tools for a single agent iteration.
+ */
+interface ToolBatchResult {
+    outputs: ToolExecutionOutput[];
+    remainingBudget: number;
+}
+type ConfirmAwaiter = (tool: Tool, input: unknown, toolUseId: string, suggestedPattern: string) => Promise<'yes' | 'no' | 'always' | 'deny'>;
+interface ToolExecutorOptions {
+    permissionPolicy: PermissionPolicy;
+    secretScrubber: SecretScrubber;
+    renderer?: Renderer | undefined;
+    /**
+     * Optional event bus. When provided, the executor emits `tool.started`
+     * before invoking each tool's `execute()`. Closes the observability gap
+     * between "model decided to call tool" and "tool finished".
+     */
+    events?: EventBus | undefined;
+    /**
+     * Optional tracer. When provided, every tool execution opens a
+     * `tool.<name>` span with attributes for tool name, permission decision,
+     * input size, output size, and outcome. Spans are no-op by default.
+     */
+    tracer?: Tracer | undefined;
+    /**
+     * Async callback invoked when a tool needs user confirmation.
+     * When omitted and confirmation is required, the executor returns a
+     * failure result immediately (TUI path). When provided (CLI path),
+     * the callback handles the interactive prompt and returns a decision.
+     */
+    confirmAwaiter?: ConfirmAwaiter | undefined;
+    iterationTimeoutMs?: number;
+    perIterationOutputCapBytes?: number;
+}
+/**
+ * Result returned by executeBatch when a tool needs confirmation and
+ * no confirmAwaiter is available. The TUI catches this and surfaces a
+ * confirmation dialog; once resolved the tool is re-executed.
+ * The string tag identifies it as a "pending confirm" result so callers
+ * can distinguish it from an error without inspecting content strings.
+ */
+interface ToolConfirmPendingResult {
+    type: 'tool_confirm_pending';
+    toolUseId: string;
+    toolName: string;
+    input: unknown;
+    suggestedPattern: string;
+}
+type ToolExecutorStrategy = 'parallel' | 'sequential' | 'smart';
+
+/**
+ * A contributor that injects additional TextBlocks into the system prompt.
+ *
+ * Contributors are called on every `build()` in registration order.
+ * Their output is inserted after the core blocks (identity, tool usage,
+ * environment) but before the mode and plan blocks. This lets plugins
+ * inject ephemeral context — current state, recent events, plugin-specific
+ * instructions — without replacing the entire system prompt builder.
+ *
+ * @example
+ * ```ts
+ * api.extensions.registerSystemPromptContributor(async (ctx) => {
+ *   return [{ type: 'text', text: '## My Plugin Context\n...' }];
+ * });
+ * ```
+ */
+interface SystemPromptContributor {
+    (ctx: BuildContext): Promise<TextBlock[]>;
+}
+
+/**
+ * Extension points for the Agent lifecycle.
+ *
+ * Each extension point is a hook that gets called at a specific phase.
+ * Extensions are always optional and failures are isolated — a failing
+ * extension never aborts the agent run.
+ *
+ * Plugins register extensions via `PluginAPI.extensions`, not by
+ * directly importing this module. The Agent calls the registry in
+ * order at each phase.
+ */
+
+/**
+ * Called before Agent.run() begins the main iteration loop.
+ * Returns `false` or throws to prevent the run from starting.
+ */
+type BeforeRunHook = (ctx: Context, input: UserInputPayload) => void | Promise<void>;
+/**
+ * Called after Agent.run() completes (or fails/aborts).
+ * Receives the final RunResult, always called regardless of outcome.
+ */
+type AfterRunHook = (ctx: Context, result: RunResult) => void | Promise<void>;
+/**
+ * Called right before each iteration of the agent loop.
+ * The context is live (messages, signal, etc.) and can be inspected.
+ * Modifications to ctx (e.g. ctx.messages, ctx.model) take effect
+ * for the upcoming iteration.
+ */
+type BeforeIterationHook = (ctx: Context, iterationIndex: number) => void | Promise<void>;
+/**
+ * Called after each iteration completes (tool results appended,
+ * compaction done, but before the next loop iteration check).
+ */
+type AfterIterationHook = (ctx: Context, iterationIndex: number) => void | Promise<void>;
+/**
+ * Called when the agent encounters an error during the provider call
+ * or tool execution phase. The hook can return a modified context
+ * or signal that recovery should be attempted.
+ *
+ * Return `{ action: 'retry', model?: string }` to retry the turn
+ * (possibly with a different model).
+ * Return `{ action: 'fail' }` to propagate the error.
+ * Return `{ action: 'continue' }` to skip and continue the loop.
+ */
+type OnErrorHook = (ctx: Context, err: unknown, phase: 'provider' | 'tool' | 'agent', iterationIndex: number) => {
+    action: 'retry';
+    model?: string;
+} | {
+    action: 'fail';
+} | {
+    action: 'continue';
+} | void | Promise<{
+    action: 'retry';
+    model?: string;
+} | {
+    action: 'fail';
+} | {
+    action: 'continue';
+} | void>;
+/**
+ * The default provider runner function signature — what the Agent's
+ * built-in provider runner looks like. Extensions that wrap the provider
+ * runner receive this as the `inner` parameter they can delegate to.
+ */
+type ProviderRunnerFn = (ctx: Context, request: Request) => Promise<Response>;
+/**
+ * Wrap or replace the provider call in the agent loop.
+ *
+ * The `inner` function is the default provider runner (with retries).
+ * The extension can call it, modify the request/response, add caching,
+ * or bypass it entirely.
+ */
+type ProviderRunnerWrapper = (ctx: Context, request: Request, inner: ProviderRunnerFn) => Promise<Response>;
+/**
+ * Called before a batch of tools is executed. Can modify or reject
+ * the tool list. Return the (possibly filtered/modified) tool uses.
+ */
+type BeforeToolExecutionHook = (ctx: Context, toolUses: ToolUseBlock[]) => ToolUseBlock[] | Promise<ToolUseBlock[]>;
+/**
+ * Called after a batch of tools has been executed and results
+ * are available. The extension can inspect or transform results
+ * before they're appended to context.
+ */
+type AfterToolExecutionHook = (ctx: Context, outputs: ToolExecutionOutput[]) => void | Promise<void>;
+/**
+ * An extension registered by a plugin or the host application.
+ *
+ * Every hook is optional — implement only the phases you need.
+ * Hooks are called in registration order. A hook failure is
+ * caught, logged, and does not prevent subsequent hooks from running.
+ *
+ * @example
+ * ```ts
+ * const myExt: AgentExtension = {
+ *   name: 'my-plugin-ext',
+ *   beforeIteration: async (ctx, idx) => {
+ *     console.log('Starting iteration', idx);
+ *   },
+ * };
+ * api.extensions.register(myExt);
+ * ```
+ */
+interface AgentExtension {
+    /** Unique name for this extension. Used in diagnostics and logging. */
+    name: string;
+    /** Optional owner tag (plugin name or host identifier). */
+    owner?: string;
+    beforeRun?: BeforeRunHook;
+    afterRun?: AfterRunHook;
+    beforeIteration?: BeforeIterationHook;
+    afterIteration?: AfterIterationHook;
+    onError?: OnErrorHook;
+    wrapProviderRunner?: ProviderRunnerWrapper;
+    beforeToolExecution?: BeforeToolExecutionHook;
+    afterToolExecution?: AfterToolExecutionHook;
+}
+
+/**
+ * ExtensionRegistry — manages AgentExtension registrations.
+ *
+ * Extensions are called in registration order at each lifecycle phase.
+ * Each extension hook failure is caught and logged independently so
+ * one bad extension can't take down the agent.
+ */
+
+declare class ExtensionRegistry {
+    private readonly extensions;
+    private readonly promptContributors;
+    private log;
+    setLogger(log: Logger): void;
+    /**
+     * Register a system prompt contributor. Returns an unregister function.
+     * Contributors are called on every system prompt build in registration
+     * order. Their output blocks are inserted after the core environment
+     * block, before the mode and plan blocks.
+     */
+    registerSystemPromptContributor(c: SystemPromptContributor): () => void;
+    /**
+     * Build all registered system prompt contributions.
+     * Failures are caught and logged — one bad contributor doesn't
+     * break the prompt assembly.
+     */
+    buildSystemPromptContributions(ctx: Parameters<SystemPromptContributor>[0]): Promise<TextBlock[]>;
+    /**
+     * Returns the live array of contributors (readonly snapshot for
+     * passing to DefaultSystemPromptBuilder at build time).
+     */
+    listSystemPromptContributors(): readonly SystemPromptContributor[];
+    /**
+     * Register an extension. Duplicate names are rejected.
+     * Returns an unregister function.
+     */
+    register(ext: AgentExtension): () => void;
+    /**
+     * Register an extension, silently replacing any previous registration
+     * with the same name. Use this when overriding a default extension.
+     */
+    registerOrReplace(ext: AgentExtension): () => void;
+    /**
+     * Unregister an extension by name. Returns true if found.
+     */
+    unregister(name: string): boolean;
+    /**
+     * List registered extension names in order.
+     */
+    list(): readonly string[];
+    /**
+     * Check if an extension with the given name is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Remove all registered extensions and contributors.
+     */
+    clear(): void;
+    runBeforeRun(...args: Parameters<BeforeRunHook>): Promise<void>;
+    runAfterRun(...args: Parameters<AfterRunHook>): Promise<void>;
+    runBeforeIteration(...args: Parameters<BeforeIterationHook>): Promise<void>;
+    runAfterIteration(...args: Parameters<AfterIterationHook>): Promise<void>;
+    /**
+     * Run onError hooks in order. The first hook that returns a non-void
+     * result wins; subsequent hooks are skipped.
+     */
+    runOnError(...args: Parameters<OnErrorHook>): Promise<{
+        action: 'retry';
+        model?: string;
+    } | {
+        action: 'fail';
+    } | {
+        action: 'continue';
+    } | void>;
+    /**
+     * Build a composed provider runner. Extensions with `wrapProviderRunner`
+     * form a middleware-style chain: the innermost extension wraps the
+     * default runner, each subsequent wrapper wraps the previous.
+     */
+    wrapProviderRunner(inner: ProviderRunnerFn): ProviderRunnerFn;
+    runBeforeToolExecution(...args: Parameters<BeforeToolExecutionHook>): Promise<Parameters<BeforeToolExecutionHook>[1]>;
+    runAfterToolExecution(...args: Parameters<AfterToolExecutionHook>): Promise<void>;
+}
+
+/**
+ * Factory for constructing a Provider instance. The `family` field
+ * declares the wire protocol so callers can route without inspecting
+ * the returned instance. The `type` is the registry key (e.g. a
+ * provider's models.dev id or a user-chosen alias).
+ */
+interface ProviderFactory$1 {
+    /**
+     * Unique identifier used as the registry key. When registered via
+     * a plugin, this becomes `cfg.type` in `ProviderRegistry.create(cfg)`.
+     */
+    type: string;
+    /**
+     * Declares the wire protocol family so consumers can route based on
+     * capability (e.g. which tool-format converter to use) without
+     * instantiating the provider.
+     */
+    family: WireFamily;
+    create(cfg: ProviderConfig): Provider;
+}
+declare class ProviderRegistry {
+    private readonly factories;
+    /**
+     * Register a provider factory. If a factory with the same type already
+     * exists, it is replaced. Use this for both initial registration and
+     * runtime overrides (e.g. from plugins or CLI flags).
+     */
+    register(f: ProviderFactory$1): void;
+    /**
+     * Bulk-register multiple provider factories at once.
+     */
+    registerAll(factories: ProviderFactory$1[]): void;
+    /**
+     * Override an existing factory. Throws if no factory is registered
+     * for the given type. Use this to safely replace a provider at runtime
+     * (e.g. in tests or when a plugin provides a custom implementation).
+     */
+    override(type: string, f: ProviderFactory$1): void;
+    has(type: string): boolean;
+    create(cfg: ProviderConfig): Provider;
+    list(): string[];
+}
+
+/** Default iteration cap. Use 0 or Infinity via config to disable. */
+declare const DEFAULT_MAX_ITERATIONS = 100;
+interface RunResult {
+    status: 'done' | 'failed' | 'max_iterations' | 'aborted';
+    /**
+     * Set when `status === 'failed'` (always) or `'aborted'` (when the abort
+     * carried an error context). Always a `WrongStackError` so callers can
+     * branch on `code`, `severity`, and `recoverable` without parsing strings.
+     * Raw throws are wrapped into an `AgentError` with code `AGENT_RUN_FAILED`
+     * by `Agent.run` before they reach this field.
+     */
+    error?: WrongStackError;
+    finalText?: string;
+    iterations: number;
+}
+interface AgentInit {
+    container: Container;
+    tools: ToolRegistry;
+    providers: ProviderRegistry;
+    events: EventBus;
+    pipelines: AgentPipelines;
+    context: Context;
+    maxIterations?: number;
+    iterationTimeoutMs?: number;
+    executionStrategy?: 'parallel' | 'sequential' | 'smart';
+    perIterationOutputCapBytes?: number;
+    /**
+     * When true (default), the agent automatically extends its iteration
+     * limit by 100 when hit, without asking the user. Set to false to
+     * emit `iteration.limit_reached` and wait for a listener to grant/deny.
+     */
+    autoExtendLimit?: boolean;
+    /**
+     * Optional confirm handler. When set, the executor calls it synchronously
+     * when a tool needs user confirmation (CLI path). When omitted, the
+     * executor returns a `ToolConfirmPendingResult` and the agent emits
+     * `tool.confirm_needed` for the TUI to resolve.
+     */
+    confirmAwaiter?: ConfirmAwaiter | undefined;
+    /**
+     * Override the PermissionPolicy resolved from the container. Subagents
+     * use this to force auto-approval — they cannot respond to interactive
+     * permission prompts, so inheriting the leader's non-YOLO policy would
+     * silently hang the entire delegated run on the first tool call.
+     */
+    permissionPolicy?: PermissionPolicy;
+    /**
+     * Optional tracer. When provided, `Agent.run` opens an `agent.run` span,
+     * per-iteration `agent.iteration` spans, and `provider.complete` spans
+     * inside the retry loop. Tool spans are opened by the ToolExecutor.
+     * Default is `NoopTracer` (zero overhead).
+     */
+    tracer?: Tracer | undefined;
+    /**
+     * Optional extension registry. Plugins and host applications register
+     * extensions here to hook into the agent lifecycle (beforeRun, afterRun,
+     * beforeIteration, onError, wrapProviderRunner, etc.).
+     * When not provided, the agent creates an empty registry internally —
+     * no overhead, zero breakage.
+     */
+    extensions?: ExtensionRegistry | undefined;
+}
+interface AgentPipelines {
+    request: Pipeline<Request>;
+    response: Pipeline<Response>;
+    toolCall: Pipeline<ToolCallPipelinePayload>;
+    userInput: Pipeline<UserInputPayload>;
+    assistantOutput: Pipeline<TextBlock>;
+    contextWindow: Pipeline<Context>;
+}
+interface UserInputPayload {
+    content: ContentBlock[];
+    /** Concatenation of text blocks — convenience for middleware that only cares about text. */
+    text: string;
+    ctx: Context;
+}
+type AgentInput = string | ContentBlock[];
+interface ToolCallPipelinePayload {
+    toolUse: ToolUseBlock;
+    result: ToolResultBlock;
+    ctx: Context;
+    /** Undefined when the model invoked a tool name we don't know. */
+    tool?: Tool;
+}
+declare function createDefaultPipelines(): AgentPipelines;
+declare class Agent {
+    readonly container: Container;
+    readonly tools: ToolRegistry;
+    readonly providers: ProviderRegistry;
+    readonly events: EventBus;
+    readonly pipelines: AgentPipelines;
+    readonly ctx: Context;
+    private readonly maxIterations;
+    private readonly iterationTimeoutMs;
+    private readonly executionStrategy;
+    private readonly perIterationOutputCapBytes;
+    private readonly plugins;
+    private readonly toolExecutor;
+    private readonly autoExtendLimit;
+    private readonly tracer;
+    readonly extensions: ExtensionRegistry;
+    constructor(init: AgentInit);
+    private get logger();
+    private get retry();
+    private get errorHandler();
+    private get permission();
+    private get scrubber();
+    private get renderer();
+    register(tool: Tool): void;
+    use(plugin: Plugin, api: PluginAPI): Promise<void>;
+    run(userInput: AgentInput, opts?: RunOptions): Promise<RunResult>;
+    private runInner;
+    /**
+     * Check if iteration limit has been reached and request extension if needed.
+     * Returns the new effective limit (possibly extended) and a RunResult if
+     * the loop should exit. Returns `{ limit }` with no result when the
+     * iteration may proceed.
+     */
+    private checkIterationLimit;
+    /**
+     * Build request and run through request pipeline.
+     */
+    private buildAndRunRequestPipeline;
+    /**
+     * Process the provider response: run response pipeline, emit events,
+     * update session, render text, handle abort.
+     */
+    private processResponse;
+    /**
+     * Execute tools and append tool results to context.
+     * When a tool returns `tool_confirm_pending` (no confirmAwaiter set),
+     * we pause and emit `tool.confirm_needed`. The run is blocked until
+     * the event listener resolves the confirmation, then we re-run the
+     * single tool.
+     */
+    private executeTools;
+    private waitForConfirm;
+    private executeSingleWithDecision;
+    /**
+     * Run context window pipeline. The pipeline may be empty, or it may contain
+     * middleware with its own injected dependencies.
+     */
+    private compactContextIfNeeded;
+}
+
+/**
+ * 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 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.
+     */
+    run(args: string, ctx: Context): Promise<{
+        exit?: boolean;
+        message?: string;
+        runText?: string;
+    } | 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;
+    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;
+    }>;
+}
+
+export { type AfterIterationHook as A, type BeforeIterationHook as B, type ToolWrapper as C, DEFAULT_MAX_ITERATIONS as D, ExtensionRegistry as E, createDefaultPipelines as F, type ProviderRunnerFn as G, type MCPRegistryView as M, type OnErrorHook as O, type Plugin as P, type RunResult as R, type SessionWriterView as S, type ToolRegistryView as T, type UserInputPayload as U, type MetricsSinkView as a, type PluginAPI as b, type PluginCapabilities as c, type PluginDependency as d, type PluginPipelines as e, type ProviderFactory as f, type ProviderRegistryView as g, type SlashCommand as h, type SlashCommandRegistryView as i, type SystemPromptContributor as j, type ToolExecutorOptions as k, type ToolExecutorStrategy as l, type ToolBatchResult as m, ToolRegistry as n, ProviderRegistry as o, type AfterRunHook as p, type AfterToolExecutionHook as q, Agent as r, type AgentExtension as s, type AgentInit as t, type AgentInput as u, type AgentPipelines as v, type BeforeRunHook as w, type BeforeToolExecutionHook as x, type ProviderFactory$1 as y, type ProviderRunnerWrapper as z };