@wrongstack/core 0.284.1 → 0.285.0

package/dist/execution/regex-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex-patterns.d.ts","sourceRoot":"","sources":["../../src/execution/regex-patterns.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gEAAgE;AAChE,eAAO,MAAM,cAAc,QAA4D,CAAC"}

package/dist/execution/retry-policy.d.ts

@@ -0,0 +1,35 @@
+import { ProviderError } from '../types/provider.js';
+import type { RetryPolicy } from '../types/retry-policy.js';
+/**
+ * Upper bound for any Retry-After hint surfaced by a provider.
+ *
+ * The HTTP `Retry-After` header can carry either a delta-seconds
+ * integer or an absolute HTTP-date. The latter can legitimately be
+ * far in the future if the provider is asking us to back off for
+ * minutes or hours. We never want to be stuck waiting that long —
+ * the agent kernel has its own pacing and a multi-minute single
+ * retry would freeze the user. 60 seconds is the conventional cap
+ * (it matches what most providers document as the practical upper
+ * bound for a single rate-limit window).
+ */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+export declare class DefaultRetryPolicy implements RetryPolicy {
+    shouldRetry(err: Error | ProviderError, attempt: number): boolean;
+    maxAttempts(err: Error | ProviderError): number;
+    /**
+     * Compute the retry delay.
+     *
+     * Precedence:
+     *   1. If `err` is a `ProviderError` with a populated
+     *      `body.retryAfterMs`, honour it — clamped into
+     *      [0, MAX_RETRY_AFTER_MS]. The provider told us exactly when
+     *      to come back; we should listen.
+     *   2. Otherwise fall through to the exponential-with-jitter
+     *      schedule (`1000 * 2^attempt + jitter`, capped at 30s).
+     *
+     * `err` is optional for back-compat with the existing interface;
+     * callers should pass it whenever available.
+     */
+    delayMs(attempt: number, err?: Error | ProviderError): number;
+}
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/execution/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../src/execution/retry-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAA0B,MAAM,sBAAsB,CAAC;AAE7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAuBzC,qBAAa,kBAAmB,YAAW,WAAW;IACpD,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAShE;IAED,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,aAAa,GAAG,MAAM,CAK9C;IAED;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG,aAAa,GAAG,MAAM,CAmB5D;CACF"}

package/dist/execution/selective-compactor.d.ts

@@ -0,0 +1,94 @@
+import type { Context } from '../core/context.js';
+import type { CompactReport, Compactor } from '../types/compactor.js';
+import type { Provider } from '../types/provider.js';
+import type { MessageSelector } from '../types/selector.js';
+/**
+ * Options for SelectiveCompactor — the most configurable compactor.
+ */
+export interface SelectiveCompactorOptions {
+    /** Provider for LLM calls (selector + summarizer). Required. */
+    provider: Provider;
+    /** Selector for LLM-driven importance analysis. */
+    selector?: MessageSelector | undefined;
+    /** Fraction of maxContext that triggers a warning (default 0.6). */
+    warnThreshold?: number | undefined;
+    /** Fraction of maxContext that triggers soft compaction (default 0.75). */
+    softThreshold?: number | undefined;
+    /** Fraction of maxContext that triggers hard compaction (default 0.9). */
+    hardThreshold?: number | undefined;
+    /** Max context window in tokens (used for threshold fraction math). */
+    maxContext?: number | undefined;
+    /** How many recent (user+assistant) pairs to always preserve (default 4). */
+    preserveK?: number | undefined;
+    /** Token threshold below which tool results are not elided (default 500). */
+    eliseThreshold?: number | undefined;
+    /** Model for selector LLM calls (default: same as provider default). */
+    selectorModel?: string | undefined;
+    /** Max output tokens for the selector LLM call (default: 1024). */
+    selectorMaxOutputTokens?: number | undefined;
+    /** Summarizer model for collapsed ranges (default: same as selectorModel). */
+    summarizerModel?: string | undefined;
+    /** Prompt for the summarizer sub-LLM. */
+    summarizerPrompt?: string | undefined;
+}
+/**
+ * SelectiveCompactor uses an LLM-driven MessageSelector to make
+ * surgical decisions about which message ranges to keep vs collapse.
+ *
+ * Compared to HybridCompactor / IntelligentCompactor:
+ * - HybridCompactor: rule-based (preserveK + elision), no LLM calls
+ * - IntelligentCompactor: LLM summarization but no structured selection
+ * - SelectiveCompactor: full LLM-driven selection + optional summarization
+ */
+export declare class SelectiveCompactor implements Compactor {
+    private readonly provider;
+    private readonly selector;
+    private readonly warnThreshold;
+    private readonly softThreshold;
+    private readonly hardThreshold;
+    private readonly maxContext;
+    private readonly preserveK;
+    private readonly eliseThreshold;
+    private readonly summarizerModel;
+    private readonly summarizerPrompt;
+    constructor(opts: SelectiveCompactorOptions);
+    compact(ctx: Context, opts?: {
+        aggressive?: boolean | undefined;
+    }): Promise<CompactReport>;
+    /**
+     * Estimate the full API request token count: messages + systemPrompt + toolDefs.
+     * This is the accurate figure for context-window pressure monitoring.
+     */
+    private estimateFullRequest;
+    private repairProtocolAdjacency;
+    /**
+     * Run the LLM selector to decide what to keep vs collapse.
+     * Returns the token savings achieved.
+     */
+    private runSelector;
+    /**
+     * Execute a SelectorResult plan: collapse/remove ranges and
+     * insert summaries where the selector provided them.
+     */
+    private executePlan;
+    private summarizeRange;
+    private messagePreview;
+    /**
+     * Fallback when selector fails: aggressively trim from the oldest end
+     * until we hit targetBudget.
+     */
+    private aggressiveRecencyTrim;
+    private computeTargetBudget;
+    private eliseOldToolResults;
+    private hasTextContent;
+    /**
+     * Estimate message-array tokens via the shared `estimateMessages` primitive
+     * so SelectiveCompactor's before/after/load figures agree with the
+     * middleware threshold math and the other compactors. Previously this used a
+     * private `ceil(len/3.5)` walk that diverged from the calibrated shared
+     * estimator, causing the selective `load`/`targetBudget` comparison to mix
+     * two incompatible token scales.
+     */
+    private estimateTokens;
+}
+//# sourceMappingURL=selective-compactor.d.ts.map

package/dist/execution/selective-compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selective-compactor.d.ts","sourceRoot":"","sources":["../../src/execution/selective-compactor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,KAAK,EAAE,QAAQ,EAAW,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,sBAAsB,CAAC;AAS5E;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,QAAQ,EAAE,QAAQ,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACvC,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,SAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,YAAY,IAAI,EAAE,yBAAyB,EA0B1C;IAEK,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE;QAAE,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAkDnG;IAED;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,uBAAuB;IAY/B;;;OAGG;YACW,WAAW;IAkBzB;;;OAGG;YACW,WAAW;YA6BX,cAAc;IA6B5B,OAAO,CAAC,cAAc;IAStB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IA8B7B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,cAAc;IAKtB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;CAGvB"}

package/dist/execution/skill-loader.d.ts

@@ -0,0 +1,43 @@
+import type { SkillEntry, SkillLoader, SkillManifest } from '../types/skill.js';
+import type { WstackPaths } from '../utils/wstack-paths.js';
+export interface SkillLoaderOptions {
+    paths: WstackPaths;
+    bundledDir?: string | undefined;
+    /** Read foreign `.claude/skills` dirs (project + user). Default `true`. */
+    readClaudeSkills?: boolean | undefined;
+    /** Scan other agents' skill dirs (codex/cursor/agents/qwen/trae/…). Default `true` (all); `string[]` restricts, `false` disables. */
+    foreignSources?: boolean | string[] | undefined;
+    /** Extra skill directories to scan (lowest priority, before bundled). */
+    extraDirs?: string[] | undefined;
+}
+/**
+ * Discovery order (we walk highest priority first and skip names already
+ * seen, so earlier layers shadow later ones):
+ *   1. Project-committed:   <project>/.wrongstack/skills/
+ *   2. Project foreign:     <project>/.claude/skills/      (opt-out)
+ *   3. Project foreign:     <project>/.{codex,cursor,agents,…}/skills/
+ *   4. User-global:         ~/.wrongstack/skills/
+ *   5. User foreign:        ~/.claude/skills/              (opt-out)
+ *   6. User foreign:        ~/.{codex,cursor,agents,…}/skills/
+ *   7. Extra dirs:          config.skills.extraDirs         (user config only)
+ *   8. Bundled with build:  packages/core/skills/
+ *
+ * The `.claude/*` layers let skills authored for other coding agents (Claude
+ * Code, Codex, Gemini, `asm`, `gh skill`) be used without copying. They are
+ * read-only — the installer never writes there.
+ */
+export declare class DefaultSkillLoader implements SkillLoader {
+    private readonly dirs;
+    private cache?;
+    private entriesCache?;
+    private readonly bodyCache;
+    constructor(opts: SkillLoaderOptions);
+    list(): Promise<SkillManifest[]>;
+    find(name: string): Promise<SkillManifest | undefined>;
+    manifestText(): Promise<string>;
+    listEntries(): Promise<SkillEntry[]>;
+    invalidateCache(): void;
+    readBody(name: string): Promise<string>;
+    readSaveBody(name: string): Promise<string>;
+}
+//# sourceMappingURL=skill-loader.d.ts.map

package/dist/execution/skill-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-loader.d.ts","sourceRoot":"","sources":["../../src/execution/skill-loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA+D5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,qIAAqI;IACrI,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0E;IAC/F,OAAO,CAAC,KAAK,CAAC,CAA8B;IAC5C,OAAO,CAAC,YAAY,CAAC,CAA2B;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD,YAAY,IAAI,EAAE,kBAAkB,EAyBnC;IAEK,IAAI,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAwCrC;IAEK,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAI3D;IAEK,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAUpC;IAEK,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAmBzC;IAED,eAAe,IAAI,IAAI,CAItB;IAEK,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS5C;IAEK,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBhD;CACF"}

package/dist/execution/strategy-compactor.d.ts

@@ -0,0 +1,43 @@
+import type { Compactor } from '../types/compactor.js';
+export type CompactorStrategy = 'hybrid' | 'intelligent' | 'selective';
+export interface StrategyCompactorOptions {
+    /** Which compactor to use. Defaults to 'hybrid' (lossless, no LLM). */
+    strategy?: CompactorStrategy | string | undefined;
+    /** Recent user/assistant pairs to always preserve. */
+    preserveK?: number | undefined;
+    /** Token threshold below which tool results are not elided. */
+    eliseThreshold?: number | undefined;
+    /**
+     * Enable content-aware smart digest for 'hybrid' strategy. When true,
+     * collapsed ancient turns use buildSmartDigest: critical content (errors,
+     * corrections, decisions) stays verbatim; normal exchanges get first-sentence
+     * summaries; noise (repeated failures, large tool outputs) is aggressively
+     * compressed. Defaults to false (lossless digest).
+     */
+    smart?: boolean | undefined;
+    /** Model used by the LLM-backed strategies for summarization/selection. */
+    summarizerModel?: string | undefined;
+    /** Max output tokens for the selector LLM call in 'selective' strategy (default: 1024). */
+    selectorMaxOutputTokens?: number | undefined;
+    /**
+     * Legacy shortcut for `strategy: 'selective'`. When `strategy` is unset (or
+     * 'hybrid') and this is true, the selective (LLM-driven) compactor is used.
+     * An explicit `strategy` always wins.
+     */
+    llmSelector?: boolean | undefined;
+}
+/**
+ * Build the compactor named by `config.context.strategy`.
+ *
+ * - `hybrid` (default): lossless rule-based — no provider needed.
+ * - `intelligent` / `selective`: LLM-backed. These need a `provider`, which is
+ *   only known per-run, so we return a thin wrapper that resolves the concrete
+ *   compactor from `ctx` at `compact()`-time. This deliberately avoids the
+ *   container/provider construction-ordering problem: `TOKENS.Compactor` is
+ *   resolved (and memoized) before `context.provider` exists, but `ctx.provider`
+ *   is always present once a run is actually compacting. If no provider is
+ *   available at compact-time the wrapper degrades to the lossless hybrid rules
+ *   rather than failing.
+ */
+export declare function createStrategyCompactor(opts?: StrategyCompactorOptions): Compactor;
+//# sourceMappingURL=strategy-compactor.d.ts.map

package/dist/execution/strategy-compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-compactor.d.ts","sourceRoot":"","sources":["../../src/execution/strategy-compactor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAQtE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AAEvE,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAC;IAClD,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,2FAA2F;IAC3F,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,wBAA6B,GAAG,SAAS,CActF"}

package/dist/execution/tool-executor.d.ts

@@ -0,0 +1,112 @@
+import type { Context } from '../core/context.js';
+import type { ToolResultBlock, ToolUseBlock } from '../types/blocks.js';
+import type { Tool, ToolErrorCategory } from '../types/tool.js';
+import type { ToolBatchResult, ToolExecutorOptions, ToolExecutorStrategy } from '../types/tool-executor.js';
+export declare class ToolExecutor {
+    private readonly registry;
+    private opts;
+    /** Minimum gap between coalesced `partial_output` tool.progress emits. */
+    static readonly PROGRESS_EMIT_INTERVAL_MS = 100;
+    /** Max chars of accumulated stream text carried per coalesced emit (tail). */
+    static readonly PROGRESS_TAIL_CHARS = 16384;
+    /** Max chars of the head (beginning of output) kept alongside the tail. */
+    static readonly PROGRESS_HEAD_CHARS = 16384;
+    private readonly serializer;
+    private readonly iterationTimeoutMs;
+    private readonly maxToolTimeoutMs;
+    constructor(registry: {
+        get(name: string): Tool | undefined;
+        list(): Tool[];
+    }, opts: ToolExecutorOptions);
+    /**
+     * Clear the interactive confirm awaiter so the executor returns
+     * `ToolConfirmPendingResult` instead of blocking on stdin. Used by
+     * the CLI to switch from inline prompts (REPL) to event-driven
+     * confirmation (TUI) at runtime.
+     */
+    clearConfirmAwaiter(): void;
+    /**
+     * Push the tool's per-tool result-render mode into the renderer as the
+     * next-result render mode. The config key is `tools.resultRenderMode[name]`
+     * — independent of the LLM-side `descriptionMode` so the two can be
+     * toggled separately (`/tool read desc simple` vs `/tool read result
+     * simple`). Defaults to `extend` when no entry is set.
+     *
+     * The hint is one-shot: the renderer consumes it on the next
+     * `writeToolResult` call so an unset follow-up doesn't inherit a
+     * previous tool's mode. Safe no-op when the renderer doesn't implement
+     * `setResultRenderMode` (e.g. headless/test renderers).
+     */
+    private hintRenderMode;
+    private toolLogBase;
+    private logToolSuccess;
+    private logToolFailure;
+    /**
+     * Execute a batch of tool uses using the configured strategy.
+     * Returns the execution results and the remaining output budget.
+     */
+    executeBatch(toolUses: ToolUseBlock[], ctx: Context, strategy: ToolExecutorStrategy): Promise<ToolBatchResult>;
+    /**
+     * Execute a single tool with timeout, permission check, and output capping.
+     * Emits `tool.started` via the injected EventBus (if any) right before
+     * invoking the tool — closes the observability gap between "model decided
+     * to call a tool" and "tool.executed".
+     */
+    executeTool(tool: Tool, use: ToolUseBlock, ctx: Context, budget: number): Promise<{
+        block: ToolResultBlock;
+        bytes: number;
+    }>;
+    /**
+     * Async "produce" phase: run the tool, serialize, scrub, and spill an
+     * oversized output to a disk artifact. Returns the pre-cap text. This is
+     * the long-running, concurrency-safe part — it touches NO shared budget
+     * state, so multiple invocations can run in parallel without racing.
+     *
+     * The `budgetHint` only gates the disk-spill threshold (a heuristic for
+     * "is this output large enough to persist"); it is NOT the output cap.
+     * The authoritative cap is applied synchronously in settleToolOutput()
+     * against the live budget.
+     */
+    private produceToolOutput;
+    /**
+     * Synchronous "settle" phase: enforce the output cap against the CURRENT
+     * budget, render, and build the result block. This MUST stay synchronous
+     * (no awaits) so that, in the parallel/smart strategies, two tools settling
+     * one after another against the shared closure budget can't interleave a
+     * stale read with a write. The first to settle consumes its bytes; the next
+     * settles against the reduced budget; once the budget hits 0, enforceCap
+     * truncates — making the per-iteration cap genuinely CUMULATIVE across
+     * parallel tools instead of degrading into a per-tool cap.
+     */
+    private settleToolOutput;
+    private runWithTimeout;
+    /** Best-effort tool cleanup; never let it mask the original error. */
+    private runToolCleanup;
+    private runStreamedTool;
+    private unknownToolResult;
+    private malformedInputResult;
+    private deniedResult;
+    private blockedByHookResult;
+    /**
+     * Subtract a string-content result's UTF-8 byte length from the
+     * iteration output budget. Used for synthesized results (unknown tool,
+     * validation error, blocked, threw) where the content is a small
+     * string built in the executor. The success path no longer goes
+     * through here — `executeTool` carries the exact byte count it spent
+     * in its return value, derived from `enforceCap`'s `newBudget`.
+     *
+     * Floors the result at 0 to match the pre-fix `decrementBudget`
+     * semantics (over-budget spends don't underflow the running total).
+     */
+    private budgetForString;
+}
+/**
+ * Classify a tool execution error into a structured ToolErrorCategory.
+ * Used for observability (span attributes) and retry strategy decisions.
+ */
+export declare function classifyToolError(err: unknown): {
+    category: ToolErrorCategory;
+    retryable: boolean;
+    detail?: string;
+};
+//# sourceMappingURL=tool-executor.d.ts.map

package/dist/execution/tool-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.d.ts","sourceRoot":"","sources":["../../src/execution/tool-executor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAKlD,OAAO,KAAK,EAAgB,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,KAAK,EAAE,IAAI,EAAqB,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEnF,OAAO,KAAK,EACV,eAAe,EAGf,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAYnC,qBAAa,YAAY;IAarB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,IAAI;IAbd,0EAA0E;IAC1E,MAAM,CAAC,QAAQ,CAAC,yBAAyB,OAAO;IAChD,8EAA8E;IAC9E,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAAU;IAC7C,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAAU;IAE7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,YACmB,QAAQ,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;QAAC,IAAI,IAAI,IAAI,EAAE,CAAA;KAAE,EAC1E,IAAI,EAAE,mBAAmB,EAOlC;IAED;;;;;OAKG;IACH,mBAAmB,IAAI,IAAI,CAE1B;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,cAAc;IAwBtB,OAAO,CAAC,cAAc;IAuCtB;;;OAGG;IACG,YAAY,CAChB,QAAQ,EAAE,YAAY,EAAE,EACxB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAoa1B;IAED;;;;;OAKG;IACG,WAAW,CACf,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,KAAK,EAAE,eAAe,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAGpD;IAED;;;;;;;;;;OAUG;YACW,iBAAiB;IAmB/B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;YA4BV,cAAc;IA+E5B,sEAAsE;YACxD,cAAc;YASd,eAAe;IA0H7B,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,mBAAmB;IAS3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;CAIxB;AAiED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAqFpH"}

package/dist/extension/extension-points.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+import type { RunResult, UserInputPayload } from '../core/agent.js';
+import type { Context } from '../core/context.js';
+import type { ToolUseBlock } from '../types/blocks.js';
+import type { Request, Response } from '../types/provider.js';
+import type { ToolExecutionOutput } from '../types/tool-executor.js';
+/**
+ * Called before Agent.run() begins the main iteration loop.
+ * Returns `false` or throws to prevent the run from starting.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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 | undefined }` 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.
+ */
+export type OnErrorHook = (ctx: Context, err: unknown, phase: 'provider' | 'tool' | 'agent', iterationIndex: number) => {
+    action: 'retry';
+    model?: string | undefined;
+} | {
+    action: 'fail';
+} | {
+    action: 'continue';
+} | void | Promise<{
+    action: 'retry';
+    model?: string | undefined;
+} | {
+    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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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);
+ * ```
+ */
+export interface AgentExtension {
+    /** Unique name for this extension. Used in diagnostics and logging. */
+    name: string;
+    /** Optional owner tag (plugin name or host identifier). */
+    owner?: string | undefined;
+    beforeRun?: BeforeRunHook | undefined;
+    afterRun?: AfterRunHook | undefined;
+    beforeIteration?: BeforeIterationHook | undefined;
+    afterIteration?: AfterIterationHook | undefined;
+    onError?: OnErrorHook | undefined;
+    wrapProviderRunner?: ProviderRunnerWrapper | undefined;
+    beforeToolExecution?: BeforeToolExecutionHook | undefined;
+    afterToolExecution?: AfterToolExecutionHook | undefined;
+}
+//# sourceMappingURL=extension-points.d.ts.map

package/dist/extension/extension-points.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-points.d.ts","sourceRoot":"","sources":["../../src/extension/extension-points.ts"],"names":[],"mappings":"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"}

package/dist/extension/index.d.ts

@@ -1,10 +1,3 @@
-export { k as AfterIterationHook, l as AfterRunHook, m as AfterToolExecutionHook, j as AgentExtension, B as BeforeIterationHook, n as BeforeRunHook, o as BeforeToolExecutionHook, E as ExtensionRegistry, O as OnErrorHook, w as ProviderRunnerFn, u as ProviderRunnerWrapper } from '../index--Gm41aBJ.js';
-import '../tool-BNlnIJvo.js';
-import '../logger-B63L5bTg.js';
-import '../pipeline-DGDyIohT.js';
-import '../mailbox-types-BGZWrYTJ.js';
-import '../config-MRqn1V-u.js';
-import '../permission-ByDKXEcG.js';
-import '../observability-D-HZN_mF.js';
-import '../events-Bgnh43r9.js';
-import '../secret-scrubber-3MHDDAtm.js';
+export { ExtensionRegistry } from './registry.js';
+export type { AgentExtension, BeforeRunHook, AfterRunHook, BeforeIterationHook, AfterIterationHook, OnErrorHook, ProviderRunnerWrapper, ProviderRunnerFn, BeforeToolExecutionHook, AfterToolExecutionHook, } from './extension-points.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extension/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extension/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC"}

package/dist/extension/index.js

@@ -1,7 +1,7 @@
 // src/utils/expect-defined.ts
 function expectDefined(value, label) {
   if (value === null || value === void 0) {
-    const err = new Error("Expected value to be defined");
+    const err = new Error(label ? `Expected ${label} to be defined` : "Expected value to be defined");
     err.name = "ExpectDefinedError";
     throw err;
   }
@@ -10,7 +10,61 @@ function expectDefined(value, label) {
 
 // src/types/errors.ts
 var ERROR_CODES = {
-  REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE"};
+  // Provider
+  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
+  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
+  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
+  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
+  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
+  PROVIDER_CONTEXT_OVERFLOW: "PROVIDER_CONTEXT_OVERFLOW",
+  // Tool
+  TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+  TOOL_PERMISSION_DENIED: "TOOL_PERMISSION_DENIED",
+  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+  TOOL_TIMEOUT: "TOOL_TIMEOUT",
+  TOOL_INPUT_INVALID: "TOOL_INPUT_INVALID",
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED",
+  CONFIG_MIGRATION_NEEDED: "CONFIG_MIGRATION_NEEDED",
+  // Plugin
+  PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED",
+  PLUGIN_API_MISMATCH: "PLUGIN_API_MISMATCH",
+  PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY",
+  // Agent
+  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
+  AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW",
+  AGENT_ABORTED: "AGENT_ABORTED",
+  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
+  // Session
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  SESSION_CORRUPTED: "SESSION_CORRUPTED",
+  SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED",
+  // Container / Registry
+  CONTAINER_TOKEN_ALREADY_BOUND: "CONTAINER_TOKEN_ALREADY_BOUND",
+  CONTAINER_TOKEN_NOT_BOUND: "CONTAINER_TOKEN_NOT_BOUND",
+  CONTAINER_CIRCULAR_DEPENDENCY: "CONTAINER_CIRCULAR_DEPENDENCY",
+  REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE",
+  REGISTRY_NOT_FOUND: "REGISTRY_NOT_FOUND",
+  REGISTRY_INVALID: "REGISTRY_INVALID",
+  // File system
+  FS_READ_FAILED: "FS_READ_FAILED",
+  FS_WRITE_FAILED: "FS_WRITE_FAILED",
+  FS_MKDIR_FAILED: "FS_MKDIR_FAILED",
+  FS_DELETE_FAILED: "FS_DELETE_FAILED",
+  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY",
+  // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  PARSE_FAILED: "PARSE_FAILED",
+  UNKNOWN: "UNKNOWN"
+};
 var WrongStackError = class extends Error {
   code;
   subsystem;
@@ -249,7 +303,7 @@ var ExtensionRegistry = class {
     }
   }
 };
-
-export { ExtensionRegistry };
+export {
+  ExtensionRegistry
+};
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map