@wrongstack/core 0.54.1 → 0.66.13

package/dist/extension/index.d.ts

@@ -1,10 +1,10 @@
-export { A as AfterIterationHook, a as AfterRunHook, b as AfterToolExecutionHook, d as AgentExtension, B as BeforeIterationHook, h as BeforeRunHook, i as BeforeToolExecutionHook, E as ExtensionRegistry, O as OnErrorHook, s as ProviderRunnerFn, t as ProviderRunnerWrapper } from '../index-CI271MjL.js';
-import '../context-DtPKqKYV.js';
+export { A as AfterIterationHook, a as AfterRunHook, b as AfterToolExecutionHook, c as AgentExtension, B as BeforeIterationHook, g as BeforeRunHook, h as BeforeToolExecutionHook, E as ExtensionRegistry, O as OnErrorHook, n as ProviderRunnerFn, o as ProviderRunnerWrapper } from '../index-DKUvyTvV.js';
+import '../context-y87Jc5ei.js';
 import '../logger-DDd5C--Z.js';
-import '../system-prompt-dtzV_mLm.js';
+import '../system-prompt-b61lOd49.js';
+import '../config--86aHSln.js';
+import '../models-registry-BcYJDKLm.js';
 import '../observability-BhnVLBLS.js';
-import '../events-CbHTS4ZZ.js';
+import '../events-CIplI98R.js';
 import '../secret-scrubber-3MHDDAtm.js';
-import '../permission-Drm7LpPo.js';
-import '../config-bht0txXS.js';
-import '../models-registry-BcYJDKLm.js';
+import '../permission-C1A5whY5.js';

package/dist/goal-store-C7jcumEh.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Long-running autonomous mission. A goal survives across sessions and
+ * drives the EternalAutonomyEngine — every iteration of the engine
+ * consults the goal to choose what to do next.
+ *
+ * Storage: `~/.wrongstack/projects/<hash>/goal.json`. Persistent and
+ * project-scoped on purpose: the goal belongs to the codebase, not the
+ * REPL session.
+ */
+interface JournalEntry {
+    /** ISO timestamp of the iteration. */
+    at: string;
+    /** Sequential iteration counter (1-based, monotonically increasing). */
+    iteration: number;
+    /** Source that produced the action ('todo' | 'git' | 'brainstorm' | 'resume' | 'manual' | 'parallel'). */
+    source: 'todo' | 'git' | 'brainstorm' | 'resume' | 'manual' | 'parallel';
+    /** Short one-line description of what the iteration set out to do. */
+    task: string;
+    /** Outcome status. */
+    status: 'success' | 'failure' | 'aborted' | 'skipped';
+    /** Optional free-form note (error message, summary, etc.). */
+    note?: string;
+    /** Optional token usage delta for this iteration. */
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    /** Optional USD cost delta for this iteration (provider-estimated). */
+    costUsd?: number;
+}
+interface GoalFile {
+    version: 1;
+    /** The mission statement. */
+    goal: string;
+    /** When the goal was first set or last replaced. */
+    setAt: string;
+    /** Updated on every iteration completion. */
+    lastActivityAt: string;
+    /** Total iterations the engine has run against this goal (cumulative). */
+    iterations: number;
+    /** Engine lifecycle state — 'running' means another process owns this goal. */
+    engineState: 'idle' | 'running' | 'stopped';
+    /**
+     * Mission-level lifecycle. `active` is the default; `completed` is set
+     * when the engine detects `[GOAL_COMPLETE]` in a successful iteration's
+     * final text AND a verification pass agrees; `abandoned` is set by the
+     * user (e.g. `/goal abandon`) or when the engine exceeds a configured
+     * failure ceiling. Once not `active`, the engine refuses to run further
+     * iterations against this goal — protects against accidental restarts
+     * burning through API quota after the work is done.
+     *
+     * Optional for backward compatibility — pre-existing `goal.json` files
+     * without this field load as `active`.
+     */
+    goalState?: 'active' | 'paused' | 'completed' | 'abandoned';
+    /**
+     * Per-todo attempt counter. Keyed by TodoItem id. Used by the engine
+     * to skip a todo that has failed N times rather than spinning on it
+     * forever. Persisted so attempt counts survive restarts (`/autonomy
+     * stop` + resume should not reset progress against a stuck task).
+     */
+    todoAttempts?: Record<string, number>;
+    /** Bounded ring buffer of recent iterations (newest last). */
+    journal: JournalEntry[];
+}
+/** Cap on persisted journal entries — older entries are evicted FIFO. */
+declare const MAX_JOURNAL_ENTRIES = 500;
+/**
+ * Resolve the goal file path for a given project root.
+ * Exposed so the engine and CLI use one canonical path.
+ * Uses `~/.wrongstack/projects/<hash>/goal.json` .<hash>/`.
+ */
+declare function goalFilePath(projectRoot: string): string;
+declare function loadGoal(filePath: string): Promise<GoalFile | null>;
+declare function saveGoal(filePath: string, goal: GoalFile): Promise<void>;
+declare function emptyGoal(goal: string): GoalFile;
+/**
+ * Append a journal entry, bumping iteration counters and trimming the
+ * ring buffer. Returns a new GoalFile — does not mutate the argument.
+ */
+declare function appendJournal(goal: GoalFile, entry: Omit<JournalEntry, 'iteration' | 'at'>): GoalFile;
+/**
+ * Aggregate cumulative cost + tokens across all journal entries. Entries
+ * without telemetry are skipped (legacy entries from before the field
+ * was added still load cleanly).
+ */
+declare function summarizeUsage(goal: GoalFile): {
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    iterationsWithUsage: number;
+};
+/** Format the goal + recent journal as a human-readable status block. */
+declare function formatGoal(goal: GoalFile, journalLimit?: number): string;
+
+export { type GoalFile as G, type JournalEntry as J, MAX_JOURNAL_ENTRIES as M, appendJournal as a, summarizeUsage as b, emptyGoal as e, formatGoal as f, goalFilePath as g, loadGoal as l, saveGoal as s };

package/dist/index-DKUvyTvV.d.ts

@@ -0,0 +1,560 @@
+import { T as TextBlock, Q as Tool, Y as ToolResultBlock, _ as ToolUseBlock, d as Context, p as Request, q as Response, m as Provider, a0 as WrongStackError, c as ContentBlock } from './context-y87Jc5ei.js';
+import { a as Logger } from './logger-DDd5C--Z.js';
+import { a as BuildContext, H as HookRegistry, e as Renderer, P as Pipeline, C as Container } from './system-prompt-b61lOd49.js';
+import { l as HookEvent, r as ProviderConfig } from './config--86aHSln.js';
+import { T as Tracer } from './observability-BhnVLBLS.js';
+import { E as EventBus } from './events-CIplI98R.js';
+import { S as SecretScrubber } from './secret-scrubber-3MHDDAtm.js';
+import { a as PermissionPolicy } from './permission-C1A5whY5.js';
+import { W as WireFamily } from './models-registry-BcYJDKLm.js';
+
+/**
+ * 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...' }];
+ * });
+ * ```
+ */
+type SystemPromptContributor = (ctx: BuildContext) => Promise<TextBlock[]>;
+
+/**
+ * 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;
+    /**
+     * Return a new ToolRegistry with the same registered tools and owners.
+     * Useful for creating filtered copies in multi-agent scenarios.
+     */
+    clone(): ToolRegistry;
+}
+
+/** Minimal run-state the runner reads. `Context` structurally satisfies it. */
+interface HookRunEnv {
+    cwd: string;
+}
+interface HookRunnerOptions {
+    registry: HookRegistry;
+    logger?: Logger;
+    /**
+     * When false, shell hooks are skipped entirely (in-process hooks still run).
+     * Set by the boot path under `--bare` / `--no-hooks` / untrusted sessions.
+     */
+    allowShell?: boolean;
+    /** Resolves the active session id for the `HookInput` payload. */
+    sessionId?: () => string | undefined;
+}
+interface PreToolUseResult {
+    block?: boolean;
+    reason?: string;
+    /** Present only when a hook replaced the tool input. */
+    input?: Record<string, unknown>;
+}
+interface PromptResult {
+    block?: boolean;
+    reason?: string;
+    additionalContext?: string;
+}
+/**
+ * Drives the registered hooks at each lifecycle phase. Pure orchestration —
+ * the executor / pipeline / agent extension call the matching method and act on
+ * the returned decision. Hook failures are caught and logged; they never abort
+ * the agent.
+ */
+declare class HookRunner {
+    private readonly opts;
+    private readonly registry;
+    constructor(opts: HookRunnerOptions);
+    /** Cheap guard so callers can skip building payloads when nothing listens. */
+    has(event: HookEvent): boolean;
+    preToolUse(toolName: string, toolInput: Record<string, unknown>, env: HookRunEnv): Promise<PreToolUseResult>;
+    postToolUse(toolName: string, toolInput: unknown, result: {
+        content: string;
+        isError: boolean;
+    }, env: HookRunEnv): Promise<{
+        additionalContext?: string;
+    }>;
+    userPromptSubmit(prompt: string, env: HookRunEnv): Promise<PromptResult>;
+    sessionStart(env: HookRunEnv): Promise<{
+        additionalContext?: string;
+    }>;
+    stop(env: HookRunEnv): Promise<void>;
+    private base;
+    private matching;
+    private invoke;
+    private collectContext;
+}
+
+/**
+ * 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;
+    /**
+     * Optional lifecycle hook runner. When present, `PreToolUse` hooks run
+     * before the permission check (and can block the call or rewrite its input)
+     * and `PostToolUse` hooks run after the tool returns (and can append context
+     * to the result the model sees).
+     */
+    hookRunner?: HookRunner | undefined;
+}
+/**
+ * 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';
+/**
+ * Minimal contract for tool execution.
+ *
+ * Defined here (in `types/`) so `core/` does not need to import the
+ * concrete `ToolExecutor` class from `execution/`. Callers that create
+ * the executor (e.g. CLI wiring) implement this interface.
+ *
+ * Only the methods actually called by `Agent` are included — keeping the
+ * interface narrow prevents unnecessary coupling.
+ */
+interface ToolExecutorLike {
+    /**
+     * Execute a batch of tool uses. The strategy controls whether tools run
+     * sequentially, in parallel, or smart (parallel non-mutating + sequential mutating).
+     */
+    executeBatch(toolUses: ToolUseBlock[], ctx: Context, strategy: ToolExecutorStrategy): Promise<ToolBatchResult>;
+    /**
+     * Clear the interactive confirm awaiter so the executor returns
+     * `ToolConfirmPendingResult` instead of blocking.
+     */
+    clearConfirmAwaiter(): void;
+    /**
+     * Execute a single tool with timeout and output capping.
+     * Used by the agent when it needs to run one tool at a time.
+     */
+    executeTool(tool: Tool, use: ToolUseBlock, ctx: Context, budget: number): Promise<ToolResultBlock>;
+}
+
+/**
+ * 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 {
+    /**
+     * 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): void;
+    /**
+     * Bulk-register multiple provider factories at once.
+     */
+    registerAll(factories: ProviderFactory[]): 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): 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';
+    error?: WrongStackError;
+    finalText?: string;
+    iterations: number;
+    delegateSummaries?: Array<{
+        summary: string;
+        ok: boolean;
+    }>;
+}
+interface AgentInit {
+    container: Container;
+    tools: ToolRegistry;
+    providers: ProviderRegistry;
+    events: EventBus;
+    pipelines: AgentPipelines;
+    context: Context;
+    maxIterations?: number;
+    iterationTimeoutMs?: number;
+    executionStrategy?: 'parallel' | 'sequential' | 'smart';
+    perIterationOutputCapBytes?: number;
+    autoExtendLimit?: boolean;
+    autonomousContinue?: boolean;
+    confirmAwaiter?: ConfirmAwaiter | undefined;
+    permissionPolicy?: PermissionPolicy;
+    tracer?: Tracer | undefined;
+    extensions?: ExtensionRegistry | undefined;
+    toolExecutor: ToolExecutorLike;
+}
+interface AgentPipelines {
+    request: Pipeline<Request>;
+    response: Pipeline<Response>;
+    toolCall: Pipeline<ToolCallPipelinePayload>;
+    userInput: Pipeline<UserInputPayload>;
+    assistantOutput: Pipeline<TextBlock>;
+    contextWindow: Pipeline<Context>;
+}
+interface UserInputPayload {
+    content: ContentBlock[];
+    text: string;
+    ctx: Context;
+}
+type AgentInput = string | ContentBlock[];
+interface ToolCallPipelinePayload {
+    toolUse: ToolUseBlock;
+    result: ToolResultBlock;
+    ctx: Context;
+    tool?: Tool;
+}
+declare function createDefaultPipelines(): AgentPipelines;
+
+export { type AfterIterationHook as A, type BeforeIterationHook as B, DEFAULT_MAX_ITERATIONS as D, ExtensionRegistry as E, type HookRunEnv as H, type OnErrorHook as O, type PreToolUseResult as P, type RunResult as R, type SystemPromptContributor as S, type ToolBatchResult as T, type UserInputPayload as U, type AfterRunHook as a, type AfterToolExecutionHook as b, type AgentExtension as c, type AgentInit as d, type AgentInput as e, type AgentPipelines as f, type BeforeRunHook as g, type BeforeToolExecutionHook as h, HookRunner as i, type HookRunnerOptions as j, type PromptResult as k, type ProviderFactory as l, ProviderRegistry as m, type ProviderRunnerFn as n, type ProviderRunnerWrapper as o, type ToolCallPipelinePayload as p, type ToolExecutorLike as q, type ToolExecutorOptions as r, type ToolExecutorStrategy as s, ToolRegistry as t, type ToolWrapper as u, createDefaultPipelines as v };