@wrongstack/core 0.2.0 → 0.3.2

package/dist/{plugin-CoYYZKdn.d.ts → index-hWNybrNZ.d.ts}

@@ -1,12 +1,34 @@
-import { u as Tool, z as ToolResultBlock, g as Provider, R as Request, j as Response, D as ToolUseBlock, a0 as Context, b as ContentBlock, T as TextBlock, a7 as RunOptions, W as WrongStackError, J as JSONSchema } from './context-u0bryklF.js';
+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-B6Q03pTu.js';
-import { R as Renderer, C as Container, P as Pipeline, c as ReadonlyPipeline } from './renderer-0A2ZEtca.js';
-import { a as PermissionPolicy, S as SecretScrubber } from './secret-scrubber-3TLUkiCV.js';
-import { e as ProviderConfig, C as Config } from './config-DXrqb41m.js';
+import { E as EventBus, a as EventName, L as Listener } from './events-BHIQs4o1.js';
+import { a as PermissionPolicy, S as SecretScrubber } from './secret-scrubber-CgG2tV2B.js';
+import { l as ProviderConfig, a as Config } from './config-D2qvAxVd.js';
 import { W as WireFamily } from './models-registry-Y2xbog0E.js';
-import { L as Logger } from './logger-BMQgxvdy.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;
@@ -16,6 +38,17 @@ declare class ToolRegistry {
      * 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
@@ -28,9 +61,27 @@ declare class ToolRegistry {
      * 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;
@@ -96,6 +147,224 @@ interface ToolConfirmPendingResult {
 }
 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...' }];
+ * });
+ * ```
+ */
+type 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
@@ -124,6 +393,10 @@ declare class ProviderRegistry {
      * 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
@@ -188,6 +461,14 @@ interface AgentInit {
      * 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>;
@@ -227,6 +508,7 @@ declare class Agent {
     private readonly toolExecutor;
     private readonly autoExtendLimit;
     private readonly tracer;
+    readonly extensions: ExtensionRegistry;
     constructor(init: AgentInit);
     private get logger();
     private get retry();
@@ -238,10 +520,6 @@ declare class Agent {
     use(plugin: Plugin, api: PluginAPI): Promise<void>;
     run(userInput: AgentInput, opts?: RunOptions): Promise<RunResult>;
     private runInner;
-    /**
-     * Normalize user input and emit through userInput pipeline + session append.
-     */
-    private normalizeAndEmitUserInput;
     /**
      * Check if iteration limit has been reached and request extension if needed.
      * Returns the new effective limit (possibly extended) and a RunResult if
@@ -316,6 +594,8 @@ interface SlashCommand {
 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[];
 }
@@ -347,6 +627,31 @@ interface SlashCommandRegistryView {
     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>;
@@ -368,6 +673,18 @@ interface PluginAPI {
     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;
     /**
@@ -376,6 +693,28 @@ interface PluginAPI {
      * 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
@@ -440,8 +779,26 @@ interface Plugin {
     /** 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 { Agent as A, DEFAULT_MAX_ITERATIONS as D, type MCPRegistryView as M, type Plugin as P, type RunResult as R, type SlashCommand as S, type ToolRegistryView as T, type UserInputPayload as U, type PluginAPI as a, type PluginCapabilities as b, type PluginDependency as c, type PluginPipelines as d, type ProviderFactory as e, type ProviderRegistryView as f, type SlashCommandRegistryView as g, type ToolExecutorOptions as h, type ToolExecutorStrategy as i, type ToolBatchResult as j, ToolRegistry as k, ProviderRegistry as l, type AgentInit as m, type AgentInput as n, type AgentPipelines as o, type ProviderFactory$1 as p, createDefaultPipelines as q };
+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 };