@wrongstack/core 0.1.9 → 0.2.0

package/dist/plugin-CoYYZKdn.d.ts

@@ -0,0 +1,447 @@
+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 { 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 { W as WireFamily } from './models-registry-Y2xbog0E.js';
+import { L as Logger } from './logger-BMQgxvdy.js';
+
+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;
+    /**
+     * 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;
+    get(name: string): Tool | undefined;
+    ownerOf(name: string): string | undefined;
+    list(): 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';
+
+/**
+ * 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;
+    /**
+     * 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;
+}
+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;
+    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;
+    /**
+     * 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
+     * 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;
+    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[];
+}
+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;
+    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;
+}
+/**
+ * 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[];
+    setup(api: PluginAPI): void | Promise<void>;
+    teardown?(api: PluginAPI): void | Promise<void>;
+}
+
+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 };

package/dist/renderer-0A2ZEtca.d.ts

@@ -0,0 +1,158 @@
+import { T as TextBlock, b as ContentBlock } from './context-u0bryklF.js';
+
+/**
+ * Container — dependency injection with explicit bind / override / decorate.
+ *
+ * Invariants:
+ *   bind()     — throws if token already bound
+ *   override() — throws if nothing to replace
+ *   decorate() — stacks; cached value cleared on register
+ */
+type Token<T> = symbol & {
+    readonly __type?: T;
+};
+type Factory<T> = (c: Container) => T;
+type Decorator<T> = (inner: T, c: Container) => T;
+interface BindOptions {
+    singleton?: boolean;
+    owner?: string;
+}
+declare class Container {
+    private readonly entries;
+    bind<T>(token: Token<T>, factory: Factory<T>, opts?: BindOptions): void;
+    override<T>(token: Token<T>, factory: Factory<T>, opts?: BindOptions): void;
+    decorate<T>(token: Token<T>, decorator: Decorator<T>, owner?: string): void;
+    resolve<T>(token: Token<T>): T;
+    has<T>(token: Token<T>): boolean;
+    ownerOf<T>(token: Token<T>): string | undefined;
+    /**
+     * Remove a token's binding (along with any decorators stacked on it).
+     * Returns true if the token existed. Use this to withdraw temporary
+     * bindings installed by a short-lived run or plugin — without it, the
+     * entry persists in the map forever.
+     */
+    unbind<T>(token: Token<T>): boolean;
+    /**
+     * Drop every binding. Intended for tests and short-lived CLI invocations
+     * that rebuild the container from scratch. Production code should prefer
+     * `unbind` on the specific tokens it owns.
+     */
+    clear(): void;
+    list(): Array<{
+        token: symbol;
+        owner: string;
+    }>;
+    /**
+     * Inspect a binding's full shape, including decorator count and whether
+     * a singleton value is cached. Returns null if the token is unbound.
+     * Decorator and factory function references are not exposed — only counts
+     * and metadata, to keep internal state hidden.
+     */
+    inspect<T>(token: Token<T>): {
+        owner: string;
+        singleton: boolean;
+        decoratorCount: number;
+        cached: boolean;
+    } | null;
+}
+
+/**
+ * Pipeline — Koa-style middleware chain with named middleware
+ * and position-aware insertion. Generic over input type T.
+ */
+type NextFn<T> = (value: T) => Promise<T>;
+type MiddlewareHandler<T> = (value: T, next: NextFn<T>) => Promise<T>;
+/**
+ * Called when a middleware crashes (throws or rejects). Used by the
+ * Pipeline's error boundary to log the offender without aborting the run.
+ *
+ * Return `'rethrow'` to propagate the error (default for core middleware),
+ * or `'swallow'` to skip past the crashing middleware and continue with the
+ * value the previous one produced. Plugin middleware should usually be
+ * swallowed so one bad plugin can't kill an agent run.
+ */
+type PipelineErrorPolicy = 'rethrow' | 'swallow';
+interface PipelineErrorEvent {
+    middleware: string;
+    owner?: string;
+    err: unknown;
+}
+type PipelineErrorHandler = (ev: PipelineErrorEvent) => PipelineErrorPolicy | Promise<PipelineErrorPolicy>;
+interface Middleware<T> {
+    name: string;
+    handler: MiddlewareHandler<T>;
+    owner?: string;
+}
+interface PipelineOptions {
+    /** When true and the target middleware is not found, operations silently no-op instead of throwing. */
+    optional?: boolean;
+}
+/**
+ * Read-only view of a pipeline. Returned to consumers (plugins, hooks)
+ * so they can inspect but not mutate the chain.
+ */
+interface ReadonlyPipeline<T> {
+    readonly size: number;
+    list(): readonly string[];
+    run(input: T): Promise<T>;
+}
+declare class Pipeline<T> {
+    private readonly chain;
+    private errorHandler?;
+    /**
+     * Install an error boundary. When a middleware throws or rejects, the
+     * handler is called and decides whether to swallow (continue with the
+     * pre-handler value) or rethrow. Without a handler, errors propagate.
+     *
+     * Wire one per pipeline at boot — the host CLI typically installs a
+     * single boundary that logs to the operational log and emits a
+     * `pipeline.error` event for /diag.
+     */
+    setErrorHandler(handler: PipelineErrorHandler | undefined): this;
+    use(mw: Middleware<T> | Middleware<unknown>): this;
+    prepend(mw: Middleware<T>): this;
+    /**
+     * Insert middleware at an explicit index. Out-of-range indices are clamped.
+     * Use this when insertBefore/insertAfter are insufficient (e.g. to place
+     * a middleware at a known position regardless of named targets).
+     */
+    insertAt(index: number, mw: Middleware<T>): this;
+    /**
+     * Insert mw immediately before the first occurrence of target.
+     * If called multiple times with the same target, each call inserts
+     * before the target's current position — so after insertBefore('B', X)
+     * then insertBefore('B', Y), the order is Y → X → B.
+     */
+    insertBefore(target: string, mw: Middleware<T>, opts?: PipelineOptions): this;
+    /**
+     * Insert mw immediately after the first occurrence of target.
+     * If called multiple times with the same target, each call inserts
+     * after the target's current position — so after insertAfter('B', X)
+     * then insertAfter('B', Y), the order is B → X → Y.
+     */
+    insertAfter(target: string, mw: Middleware<T>, opts?: PipelineOptions): this;
+    replace(target: string, mw: Middleware<T>, opts?: PipelineOptions): this;
+    remove(name: string, opts?: PipelineOptions): this;
+    list(): readonly string[];
+    size(): number;
+    /** Return a read-only view suitable for passing to plugins. */
+    asReadonly(): ReadonlyPipeline<T>;
+    run(input: T): Promise<T>;
+    private indexOf;
+    private ensureUnique;
+}
+
+interface Renderer {
+    write(text: string | TextBlock): void;
+    writeLine(text?: string): void;
+    writeBlock(block: ContentBlock): void;
+    writeToolCall(name: string, input: unknown): void;
+    writeToolResult(name: string, content: unknown, isError: boolean): void;
+    writeDiff(unifiedDiff: string): void;
+    writeWarning(text: string): void;
+    writeError(text: string): void;
+    writeInfo(text: string): void;
+    clear(): void;
+}
+
+export { type BindOptions as B, Container as C, type Decorator as D, type Factory as F, type Middleware as M, type NextFn as N, Pipeline as P, type Renderer as R, type Token as T, type MiddlewareHandler as a, type PipelineOptions as b, type ReadonlyPipeline as c };