@wrongstack/core 0.1.1 → 0.1.3

package/dist/defaults/index.d.ts

@@ -1,5 +1,7 @@
-import { j as Logger, i as LogLevel, P as PathResolver, S as SecretScrubber, O as RetryPolicy, A as ProviderError, E as ErrorHandler, c as Compactor, ag as Context, K as Response, a1 as TokenCounter, s as ModelsRegistry, ai as EventBus, a8 as Usage, G as ResolvedModel, C as CacheStats, V as SessionStore, U as SessionMetadata, X as SessionWriter, N as ResumedSession, Q as SessionData, W as SessionSummary, f as ContentBlock, m as MemoryStore, l as MemoryScope, v as PermissionPolicy, a2 as Tool, h as InputReader, u as PermissionDecision, Y as SkillLoader, Z as SkillManifest, d as Config, e as ConfigLoader, b as CompactReport, y as Provider, n as Message, as as MiddlewareHandler, q as ModelsDevPayload, H as ResolvedProvider, a9 as WireFamily, a5 as ToolUseBlock, a4 as ToolResultBlock } from '../secret-scrubber-Dax_Ou_o.js';
-import { g as AttachmentStore, A as AddAttachmentInput, f as AttachmentRef, c as Attachment, S as SecretVault, q as ModeStore, o as ModeConfig, n as Mode, s as MultiAgentCoordinator, r as MultiAgentConfig, Q as SubagentConfig, z as SpawnResult, a2 as TaskSpec, B as BridgeMessage, a as AgentBridge, j as CoordinatorStatus, a0 as TaskResult, b as AgentBridgeConfig, i as BridgeTransport, ah as Agent, m as DoneCondition, an as RunResult, O as Specification, F as SpecAnalysis, N as SpecValidationResult, Y as TaskGraph, Z as TaskNode, X as TaskFilter, a1 as TaskSort, $ as TaskProgress, a4 as TaskType, _ as TaskPriority, a9 as ToolExecutorOptions, aa as ToolExecutorStrategy, a5 as ToolBatchResult } from '../tool-executor-DjnMELMV.js';
+import { g as Logger, f as LogLevel, P as PathResolver, n as ModelsRegistry, B as EventBus, u as ResolvedModel, j as MemoryStore, i as MemoryScope, S as SecretScrubber, p as PermissionPolicy, I as InputReader, o as PermissionDecision, w as RetryPolicy, E as ErrorHandler, a as Compactor, x as SkillLoader, y as SkillManifest, b as Config, c as ConfigLoader, d as ConfigStore, C as CompactReport, U as MiddlewareHandler, l as ModelsDevPayload, v as ResolvedProvider, W as WireFamily, M as MCPServerConfig } from '../secret-scrubber-qU3AwEiI.js';
+import { u as TokenCounter, U as Usage, C as CacheStats, p as SessionStore, o as SessionMetadata, r as SessionWriter, l as ResumedSession, S as SessionData, q as SessionSummary, c as ContentBlock, v as Tool, a0 as Context, i as ProviderError, k as Response, h as Provider, M as Message, F as ToolUseBlock, B as ToolResultBlock, n as SessionEvent } from '../provider-DovtyuM8.js';
+import { h as AttachmentStore, A as AddAttachmentInput, g as AttachmentRef, d as Attachment, S as SecretVault, F as ModeStore, y as ModeConfig, x as Mode, I as MultiAgentCoordinator, G as MultiAgentConfig, ae as SubagentRunner, aa as SubagentConfig, a0 as SpawnResult, aq as TaskSpec, B as BridgeMessage, a as AgentBridge, l as CoordinatorStatus, ao as TaskResult, aH as Agent, aJ as AgentInput, j as BridgeTransport, b as AgentBridgeConfig, p as DoneCondition, aR as RunResult, a9 as Specification, a1 as SpecAnalysis, a8 as SpecValidationResult, ak as TaskGraph, al as TaskNode, aj as TaskFilter, ap as TaskSort, an as TaskProgress, as as TaskType, am as TaskPriority, ay as ToolExecutorOptions, az as ToolExecutorStrategy, at as ToolBatchResult, V as SessionReader, o as DefaultSessionReaderOptions, U as SessionQuery, Y as SessionSummaryLite, X as SessionSearchQuery, W as SessionSearchHit, T as SessionExportOptions, v as MetricsSink, t as MetricLabels, w as MetricsSnapshot, r as HealthRegistry, H as HealthCheck, c as AggregateHealth, aB as Tracer, $ as Span } from '../session-reader-DR4u3bu9.js';
+export { aL as BudgetExceededError, aM as BudgetKind, aN as BudgetLimits, aO as BudgetUsage, aS as SubagentBudget } from '../session-reader-DR4u3bu9.js';
 import { a as WstackPaths } from '../wstack-paths-D24ynAz1.js';
 import { EventEmitter } from 'node:events';
 
@@ -34,39 +36,6 @@ declare class DefaultPathResolver implements PathResolver {
     ensureInsideRoot(absPath: string): string;
 }
 
-declare class DefaultSecretScrubber implements SecretScrubber {
-    scrub(text: string): string;
-    scrubObject<T>(obj: T): T;
-}
-
-declare class DefaultRetryPolicy implements RetryPolicy {
-    shouldRetry(err: Error | ProviderError, attempt: number): boolean;
-    maxAttempts(err: Error | ProviderError): number;
-    delayMs(attempt: number): number;
-}
-
-/**
- * Tiered error recovery strategies.
- * Each strategy is attempted in order until one succeeds.
- */
-interface RecoveryStrategy {
-    /** Human-readable label for logs. */
-    label: string;
-    /** Optional compactor for context_overflow recovery. */
-    compactor?: Compactor;
-    /** Returns a substitute Response, or null to fall through to the next strategy. */
-    attempt: (err: unknown, ctx: Context) => Promise<Response | null>;
-}
-declare class DefaultErrorHandler implements ErrorHandler {
-    private readonly strategies;
-    constructor(strategies?: RecoveryStrategy[]);
-    classify(err: unknown): {
-        kind: 'rate_limit' | 'overloaded' | 'server' | 'client' | 'network' | 'abort' | 'context_overflow' | 'unknown';
-        retryable: boolean;
-    };
-    recover(err: unknown, ctx: Context): Promise<Response | null>;
-}
-
 /**
  * Token counter that derives pricing from the ModelsRegistry instead of a
  * hardcoded table. If a model is unknown to the registry (or the registry is
@@ -125,79 +94,6 @@ declare class DefaultSessionStore implements SessionStore {
     private replay;
 }
 
-/**
- * Per-project lockfile used for crash detection. The CLI writes one of
- * these alongside the session JSONLs (`<projectSessions>/active.json`)
- * when an interactive run starts, and deletes it on clean exit. If we
- * find one on the next launch whose owning PID is dead (or whose host
- * doesn't match), we know the previous run was killed mid-flight and
- * the session it was writing to is a recovery candidate.
- *
- * The lockfile is intentionally per-project (already isolated by
- * `wpaths.projectSessions`), so two TUIs in two different repos do not
- * fight each other.
- */
-interface RecoveryLockOptions {
-    /** Directory the lockfile lives in. Usually `wpaths.projectSessions`. */
-    dir: string;
-    /** This process's PID. Default: `process.pid`. */
-    pid?: number;
-    /** Hostname recorded for the lock. Default: `os.hostname()`. */
-    hostname?: string;
-    /** Locks older than this are considered orphaned (disk wiped, etc.). Default 24h. */
-    maxAgeMs?: number;
-    /** Used to check whether the abandoned session was actually closed cleanly. */
-    sessionStore?: SessionStore;
-    /**
-     * Override the PID-liveness probe. Default: `process.kill(pid, 0)` —
-     * succeeds (or throws EPERM) when the PID is alive, throws ESRCH when
-     * it is gone. Tests inject a deterministic stub.
-     */
-    isPidAlive?: (pid: number) => boolean;
-}
-interface AbandonedSession {
-    sessionId: string;
-    pid: number;
-    startedAt: string;
-    /** Lockfile age in ms at the time of the check. */
-    ageMs: number;
-    /** Number of messages already on disk for this session. */
-    messageCount: number;
-}
-declare class RecoveryLock {
-    private readonly file;
-    private readonly pid;
-    private readonly hostname;
-    private readonly maxAgeMs;
-    private readonly sessionStore?;
-    private readonly probe;
-    constructor(opts: RecoveryLockOptions);
-    /**
-     * Examine the lockfile and decide whether it represents an abandoned
-     * session. Returns `null` if the file is missing, points to a live
-     * instance, references a clean-closed session, is too old, or is
-     * malformed. Otherwise returns enough detail to prompt the user.
-     *
-     * Important: this is a read-only check. We never delete an active
-     * lock from here — if another wstack instance is alive, the caller
-     * should bail or run with a fresh session instead.
-     */
-    checkAbandoned(): Promise<AbandonedSession | null>;
-    /**
-     * Claim the lock for the given session. Overwrites any existing lock
-     * — the caller should have already handled abandonment (via
-     * `checkAbandoned`) before calling this.
-     */
-    write(sessionId: string): Promise<void>;
-    /**
-     * Release the lock. Idempotent — silently succeeds if the file is
-     * already gone (e.g. someone else cleared it, or the directory was
-     * wiped).
-     */
-    clear(): Promise<void>;
-    private readLock;
-}
-
 /**
  * The persisted form of a single queued user message. The TUI's
  * in-memory QueueItem has a render id; that's pure UI bookkeeping, so
@@ -258,6 +154,31 @@ declare class DefaultAttachmentStore implements AttachmentStore {
     private toBlock;
 }
 
+interface MemoryStoreOptions {
+    paths: WstackPaths;
+}
+/**
+ * Three scopes:
+ *   project-agents → <project>/.wrongstack/AGENTS.md     (committed)
+ *   project-memory → ~/.wrongstack/projects/<hash>/memory.md   (per-project agent notes)
+ *   user-memory    → ~/.wrongstack/memory.md             (global personal memory)
+ */
+declare class DefaultMemoryStore implements MemoryStore {
+    private readonly files;
+    constructor(opts: MemoryStoreOptions);
+    readAll(): Promise<string>;
+    read(scope: MemoryScope): Promise<string>;
+    remember(text: string, scope?: MemoryScope): Promise<void>;
+    forget(query: string, scope?: MemoryScope): Promise<number>;
+    consolidate(scope: MemoryScope): Promise<void>;
+    clear(scope?: MemoryScope): Promise<void>;
+}
+
+declare class DefaultSecretScrubber implements SecretScrubber {
+    scrub(text: string): string;
+    scrubObject<T>(obj: T): T;
+}
+
 interface SecretVaultOptions {
     /** Absolute path to the key file. Created with mode 0o600 if missing. */
     keyFile: string;
@@ -302,26 +223,6 @@ declare function migratePlaintextSecrets(configPath: string, vault: SecretVault)
     file: string;
 }>;
 
-interface MemoryStoreOptions {
-    paths: WstackPaths;
-}
-/**
- * Three scopes:
- *   project-agents → <project>/.wrongstack/AGENTS.md     (committed)
- *   project-memory → ~/.wrongstack/projects/<hash>/memory.md   (per-project agent notes)
- *   user-memory    → ~/.wrongstack/memory.md             (global personal memory)
- */
-declare class DefaultMemoryStore implements MemoryStore {
-    private readonly files;
-    constructor(opts: MemoryStoreOptions);
-    readAll(): Promise<string>;
-    read(scope: MemoryScope): Promise<string>;
-    remember(text: string, scope?: MemoryScope): Promise<void>;
-    forget(query: string, scope?: MemoryScope): Promise<number>;
-    consolidate(scope: MemoryScope): Promise<void>;
-    clear(scope?: MemoryScope): Promise<void>;
-}
-
 interface PermissionPolicyOptions {
     trustFile: string;
     yolo?: boolean;
@@ -345,6 +246,34 @@ declare class DefaultPermissionPolicy implements PermissionPolicy {
     private findNamespaceEntry;
 }
 
+declare class DefaultRetryPolicy implements RetryPolicy {
+    shouldRetry(err: Error | ProviderError, attempt: number): boolean;
+    maxAttempts(err: Error | ProviderError): number;
+    delayMs(attempt: number): number;
+}
+
+/**
+ * Tiered error recovery strategies.
+ * Each strategy is attempted in order until one succeeds.
+ */
+interface RecoveryStrategy {
+    /** Human-readable label for logs. */
+    label: string;
+    /** Optional compactor for context_overflow recovery. */
+    compactor?: Compactor;
+    /** Returns a substitute Response, or null to fall through to the next strategy. */
+    attempt: (err: unknown, ctx: Context) => Promise<Response | null>;
+}
+declare class DefaultErrorHandler implements ErrorHandler {
+    private readonly strategies;
+    constructor(strategies?: RecoveryStrategy[]);
+    classify(err: unknown): {
+        kind: 'rate_limit' | 'overloaded' | 'server' | 'client' | 'network' | 'abort' | 'context_overflow' | 'unknown';
+        retryable: boolean;
+    };
+    recover(err: unknown, ctx: Context): Promise<Response | null>;
+}
+
 interface SkillLoaderOptions {
     paths: WstackPaths;
     bundledDir?: string;
@@ -404,6 +333,114 @@ declare class DefaultConfigLoader implements ConfigLoader {
     private validateIdentity;
 }
 
+/**
+ * Reference implementation of `ConfigStore`. Stores a single frozen Config
+ * and notifies watchers synchronously on every update. Updates use a deep
+ * clone so callers can mutate their `partial` argument freely without
+ * tainting state.
+ *
+ * For the CLI: instantiate once at boot, pass the store (not the Config)
+ * to subsystems that care about runtime changes (provider switching,
+ * extension reload).
+ */
+declare class DefaultConfigStore implements ConfigStore {
+    private current;
+    private watchers;
+    constructor(initial: Config);
+    get(): Readonly<Config>;
+    getSection<K extends keyof Config>(key: K): Readonly<Config[K]>;
+    getExtension(pluginName: string): Readonly<Record<string, unknown>>;
+    update(partial: Partial<Config>): Readonly<Config>;
+    watch(cb: (next: Readonly<Config>, prev: Readonly<Config>) => void): () => void;
+}
+
+/**
+ * L2-D: Config version migration framework. Pure functions, decoupled
+ * from disk/CLI — caller passes a parsed JSON object and gets back the
+ * up-to-date `Config` shape (or a structured error explaining why
+ * migration failed).
+ *
+ * Migrations are registered as `{ from, to, migrate }` triples and run
+ * sequentially. Each migration is independently testable. Adding a new
+ * version means appending one migration; existing user configs are
+ * upgraded in place at load time.
+ */
+interface MigrationContext {
+    /**
+     * Original on-disk version of the input. Migrations may use this to
+     * decide between in-place patches and rewrites.
+     */
+    fromVersion: number;
+    /**
+     * Set when the migration writes back to disk. Callers persist the
+     * migrated config when this is true so the user doesn't see the same
+     * migration banner on every boot.
+     */
+    shouldPersist: boolean;
+}
+interface ConfigMigration {
+    /** Version of the input this migration accepts. */
+    from: number;
+    /** Version of the output it produces. */
+    to: number;
+    /** Pure transform — no I/O. */
+    migrate(input: Record<string, unknown>, ctx: MigrationContext): Record<string, unknown>;
+    /** Optional human-readable description for migration logs / banners. */
+    describe?: string;
+}
+interface MigrationResult {
+    /** Final config (still typed as `unknown`-keyed — caller validates). */
+    config: Record<string, unknown>;
+    /** Ordered list of `from→to` versions that ran. */
+    applied: string[];
+    /** True when at least one migration produced changes worth persisting. */
+    shouldPersist: boolean;
+}
+declare class ConfigMigrationError extends Error {
+    readonly fromVersion: number;
+    readonly targetVersion: number;
+    readonly missingStep: number | null;
+    constructor(opts: {
+        message: string;
+        fromVersion: number;
+        targetVersion: number;
+        missingStep: number | null;
+    });
+}
+/**
+ * Run registered migrations until the input reaches `targetVersion`.
+ *
+ * Resolution rules:
+ * 1. If `input.version === targetVersion`, no migrations run; `shouldPersist`
+ *    is false.
+ * 2. Otherwise walk the migration chain from `input.version` upward,
+ *    picking the migration whose `from` matches the current version.
+ * 3. Stop when `current.version === targetVersion`.
+ * 4. If no migration matches at some point, throw `ConfigMigrationError`
+ *    with the missing step recorded for diagnostics.
+ *
+ * Migrations may be downward (e.g. for staged rollouts), but `targetVersion`
+ * must be reachable strictly via the registered chain — there's no implicit
+ * "skip" or transitive resolution.
+ */
+declare function runConfigMigrations(input: Record<string, unknown>, targetVersion: number, migrations: readonly ConfigMigration[]): MigrationResult;
+/**
+ * Default empty migration registry. Real migrations are appended as new
+ * Config versions are introduced. Example (when v2 lands):
+ *
+ *   export const CONFIG_MIGRATIONS: readonly ConfigMigration[] = [
+ *     {
+ *       from: 1, to: 2, describe: 'rename `apiKey` → `auth.apiKey`',
+ *       migrate(cfg) {
+ *         const apiKey = cfg.apiKey;
+ *         delete cfg.apiKey;
+ *         return { ...cfg, auth: { ...(cfg.auth ?? {}), apiKey } };
+ *       },
+ *     },
+ *   ];
+ */
+declare const DEFAULT_CONFIG_MIGRATIONS: readonly ConfigMigration[];
+
 interface CompactorOptions {
     preserveK?: number;
     eliseThreshold?: number;
@@ -480,7 +517,6 @@ declare class IntelligentCompactor implements Compactor {
     private eliseOldToolResults;
     private hasTextContent;
     private estimateTokens;
-    private roughTokenEstimate;
 }
 
 /**
@@ -732,37 +768,104 @@ interface ModeLoaderOptions {
 declare function loadProjectModes(modesDir: string): Promise<Mode[]>;
 declare function loadUserModes(modesDir: string): Promise<Mode[]>;
 
+interface MultiAgentCoordinatorOptions {
+    /**
+     * Callback that executes a task on behalf of a subagent. Required for
+     * `assign()` to actually run anything — without it, tasks queue forever.
+     * The coordinator provides per-subagent isolation (own budget, own signal,
+     * own bridge) and enforces timeout + concurrency.
+     */
+    runner?: SubagentRunner;
+}
 declare class DefaultMultiAgentCoordinator extends EventEmitter implements MultiAgentCoordinator {
     readonly coordinatorId: string;
     readonly config: MultiAgentConfig;
+    private readonly runner?;
     private readonly subagents;
     private pendingTasks;
     private completedResults;
     private totalIterations;
-    constructor(config: MultiAgentConfig);
+    private inFlight;
+    constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
     spawn(subagent: SubagentConfig): Promise<SpawnResult>;
     assign(task: TaskSpec): Promise<void>;
     delegate(to: string, msg: BridgeMessage): Promise<void>;
     /**
-     * Wire up the communication bridge for a subagent. Call this after `spawn()`
-     * once the caller has created the bidirectional bridge connection.
+     * Wire up the communication bridge for a subagent. Call after spawn() once
+     * the caller has created the bidirectional connection.
      */
     setSubagentBridge(subagentId: string, bridge: AgentBridge): void;
     stop(subagentId: string): Promise<void>;
     stopAll(): Promise<void>;
     getStatus(): CoordinatorStatus;
-    private getAvailableSubagent;
-    private dispatch;
-    private isDone;
+    /** Expose snapshot of completed results — useful for callers awaiting all done. */
+    results(): readonly TaskResult[];
+    /**
+     * Manual completion — for callers that drive subagents without a runner
+     * (e.g. external orchestrators). When a runner is configured the coordinator
+     * calls this itself.
+     */
     completeTask(result: TaskResult): void;
+    private tryDispatchNext;
+    private canDispatch;
+    private findIdleSubagent;
+    private runDispatched;
+    private executeWithTimeout;
+    private recordCompletion;
+    private isDone;
+}
+
+/**
+ * Caller-supplied factory that builds an isolated `Agent` for a subagent.
+ * The factory MUST construct a fresh `Context` per call — sharing context
+ * between subagents defeats isolation. Each Agent should also use either
+ * its own `EventBus` or a forwarded view, so per-subagent metrics can be
+ * attributed correctly.
+ */
+type AgentFactory = (config: SubagentConfig) => Promise<AgentFactoryResult>;
+interface AgentFactoryResult {
+    agent: Agent;
+    /** Event bus the factory wired to this agent — required for budget hookup. */
+    events: EventBus;
 }
+interface AgentRunnerOptions {
+    factory: AgentFactory;
+    /**
+     * Format a TaskSpec into the user input the agent will receive. Defaults
+     * to `task.description ?? ''`. Override when subagents expect structured
+     * input (e.g. JSON contracts, role-prefixed prompts).
+     */
+    formatTaskInput?: (task: TaskSpec, config: SubagentConfig) => AgentInput;
+}
+/**
+ * Builds a `SubagentRunner` that drives a real `Agent` per task while honoring
+ * the coordinator's budget and abort signal. This is the production adapter —
+ * the coordinator's `runner` option in CLI/TUI assemblies points here.
+ *
+ * Lifecycle per task:
+ *   1. factory(config) → fresh Agent + EventBus.
+ *   2. Subscribe to events to feed the budget (tool calls, token usage).
+ *   3. Call agent.run(input, { signal }) — the coordinator's signal cancels.
+ *   4. Map RunResult.status onto a `SubagentRunOutcome` or throw on failure.
+ *   5. Unsubscribe and let the factory's resources be GC'd.
+ *
+ * The budget is checked synchronously from event handlers — a runaway agent
+ * that crosses its tool-call limit triggers `BudgetExceededError`, which the
+ * coordinator surfaces as `status: 'failed'` on the task result.
+ */
+declare function makeAgentSubagentRunner(opts: AgentRunnerOptions): SubagentRunner;
 
+/**
+ * In-memory pub/sub transport for agent-to-agent messaging.
+ * Subscribers register by agentId and receive messages via callback.
+ */
 declare class InMemoryBridgeTransport implements BridgeTransport {
-    private subs;
+    private readonly subs;
     send(msg: BridgeMessage, to: string): Promise<void>;
     subscribe(agentId: string, handler: (msg: BridgeMessage) => void): () => void;
     close(agentId: string): Promise<void>;
 }
+
 declare class InMemoryAgentBridge implements AgentBridge {
     readonly agentId: string;
     readonly coordinatorId: string;
@@ -1015,6 +1118,79 @@ declare class SpecDrivenDev {
     }[];
 }
 
+/**
+ * Per-project lockfile used for crash detection. The CLI writes one of
+ * these alongside the session JSONLs (`<projectSessions>/active.json`)
+ * when an interactive run starts, and deletes it on clean exit. If we
+ * find one on the next launch whose owning PID is dead (or whose host
+ * doesn't match), we know the previous run was killed mid-flight and
+ * the session it was writing to is a recovery candidate.
+ *
+ * The lockfile is intentionally per-project (already isolated by
+ * `wpaths.projectSessions`), so two TUIs in two different repos do not
+ * fight each other.
+ */
+interface RecoveryLockOptions {
+    /** Directory the lockfile lives in. Usually `wpaths.projectSessions`. */
+    dir: string;
+    /** This process's PID. Default: `process.pid`. */
+    pid?: number;
+    /** Hostname recorded for the lock. Default: `os.hostname()`. */
+    hostname?: string;
+    /** Locks older than this are considered orphaned (disk wiped, etc.). Default 24h. */
+    maxAgeMs?: number;
+    /** Used to check whether the abandoned session was actually closed cleanly. */
+    sessionStore?: SessionStore;
+    /**
+     * Override the PID-liveness probe. Default: `process.kill(pid, 0)` —
+     * succeeds (or throws EPERM) when the PID is alive, throws ESRCH when
+     * it is gone. Tests inject a deterministic stub.
+     */
+    isPidAlive?: (pid: number) => boolean;
+}
+interface AbandonedSession {
+    sessionId: string;
+    pid: number;
+    startedAt: string;
+    /** Lockfile age in ms at the time of the check. */
+    ageMs: number;
+    /** Number of messages already on disk for this session. */
+    messageCount: number;
+}
+declare class RecoveryLock {
+    private readonly file;
+    private readonly pid;
+    private readonly hostname;
+    private readonly maxAgeMs;
+    private readonly sessionStore?;
+    private readonly probe;
+    constructor(opts: RecoveryLockOptions);
+    /**
+     * Examine the lockfile and decide whether it represents an abandoned
+     * session. Returns `null` if the file is missing, points to a live
+     * instance, references a clean-closed session, is too old, or is
+     * malformed. Otherwise returns enough detail to prompt the user.
+     *
+     * Important: this is a read-only check. We never delete an active
+     * lock from here — if another wstack instance is alive, the caller
+     * should bail or run with a fresh session instead.
+     */
+    checkAbandoned(): Promise<AbandonedSession | null>;
+    /**
+     * Claim the lock for the given session. Overwrites any existing lock
+     * — the caller should have already handled abandonment (via
+     * `checkAbandoned`) before calling this.
+     */
+    write(sessionId: string): Promise<void>;
+    /**
+     * Release the lock. Idempotent — silently succeeds if the file is
+     * already gone (e.g. someone else cleared it, or the directory was
+     * wiped).
+     */
+    clear(): Promise<void>;
+    private readLock;
+}
+
 declare class ToolExecutor {
     private readonly registry;
     private readonly opts;
@@ -1037,11 +1213,377 @@ declare class ToolExecutor {
      */
     executeTool(tool: Tool, use: ToolUseBlock, ctx: Context, budget: number): Promise<ToolResultBlock>;
     private runWithTimeout;
+    private runStreamedTool;
     private unknownToolResult;
     private deniedResult;
-    private confirmResult;
+    private decrementBudget;
+    /**
+     * Compute the suggestedPattern string for a tool+input pair.
+     * Matches the logic in DefaultPermissionPolicy so the TUI shows the
+     * same subject that the trust file would use.
+     */
+    private subjectFor;
 }
 
+/**
+ * L2-A: read-only view over a `SessionStore` with query, replay, search,
+ * and export helpers. Implemented on top of the public `SessionStore`
+ * surface so any concrete store can be inspected without re-implementation.
+ *
+ * The heavy operations re-parse the JSONL stream on every call — fine for
+ * /resume and one-off analytics. Wrap with a memoizing decorator if needed.
+ */
+declare class DefaultSessionReader implements SessionReader {
+    private readonly store;
+    constructor(opts: DefaultSessionReaderOptions);
+    query(q?: SessionQuery): Promise<SessionSummaryLite[]>;
+    replay(sessionId: string): AsyncIterable<SessionEvent>;
+    search(q: SessionSearchQuery, sessionId?: string): Promise<SessionSearchHit[]>;
+    export(sessionId: string, opts: SessionExportOptions): Promise<string>;
+    metadata(sessionId: string): Promise<SessionMetadata>;
+}
+
+/**
+ * In-memory metrics sink. Suitable for embedded use, tests, and /metrics
+ * scrape over HTTP. For production push-based pipelines, write an adapter
+ * that implements MetricsSink and forwards to OTLP/StatsD/Prometheus.
+ */
+declare class InMemoryMetricsSink implements MetricsSink {
+    private counters;
+    private gauges;
+    private histograms;
+    counter(name: string, value?: number, labels?: MetricLabels): void;
+    gauge(name: string, value: number, labels?: MetricLabels): void;
+    histogram(name: string, value: number, labels?: MetricLabels): void;
+    snapshot(): MetricsSnapshot;
+    reset(): void;
+    private getOrCreate;
+}
+/** Cheap noop sink — drop-in default when observability is not configured. */
+declare class NoopMetricsSink implements MetricsSink {
+    counter(): void;
+    gauge(): void;
+    histogram(): void;
+    snapshot(): MetricsSnapshot;
+    reset(): void;
+}
+
+/**
+ * Aggregates registered health checks. Worst status wins — one unhealthy check
+ * makes the whole system unhealthy. Use timeouts so a slow probe can't stall
+ * the response.
+ */
+declare class DefaultHealthRegistry implements HealthRegistry {
+    private checks;
+    private readonly timeoutMs;
+    constructor(opts?: {
+        timeoutMs?: number;
+    });
+    register(check: HealthCheck): void;
+    unregister(name: string): void;
+    run(): Promise<AggregateHealth>;
+    private runOne;
+}
+
+/**
+ * Default tracer is a noop — zero overhead when observability is not wired up.
+ * Replace at runtime with an OpenTelemetry-backed Tracer to enable real spans.
+ */
+declare class NoopTracer implements Tracer {
+    startSpan(): Span;
+}
+
+/**
+ * Lightweight OTel adapter. Doesn't pull in `@opentelemetry/api` directly —
+ * the user passes their already-initialized OTel Tracer through, and this
+ * wrapper translates our minimal Span surface onto theirs.
+ *
+ * Usage:
+ *   import { trace } from '@opentelemetry/api';
+ *   const tracer = trace.getTracer('wrongstack', '1.0');
+ *   const wrappedTracer = new OTelTracer(tracer);
+ *   // pass `wrappedTracer` as Agent.tracer / ToolExecutor.tracer.
+ *
+ * The shape of the upstream Tracer is intentionally typed loosely so we
+ * don't need a build-time dependency. Anything OTel-compatible works,
+ * including OpenInference, Tempo, etc.
+ */
+
+interface OTelLikeSpan {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    recordException(err: {
+        message: string;
+        stack?: string;
+        name?: string;
+    }): unknown;
+    setStatus?(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): unknown;
+}
+interface OTelLikeTracer {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): OTelLikeSpan;
+}
+declare class OTelTracer implements Tracer {
+    private readonly upstream;
+    constructor(upstream: OTelLikeTracer);
+    startSpan(name: string, attrs?: Record<string, string | number | boolean>): Span;
+}
+
+/**
+ * Subscribes a MetricsSink to the EventBus. Returns an unsubscribe function
+ * that detaches all listeners. This is the single integration point between
+ * the agent's event stream and the observability layer — no metric calls
+ * leak into core call sites.
+ */
+declare function wireMetricsToEvents(events: EventBus, sink: MetricsSink): () => void;
+
+/**
+ * Render a `MetricsSnapshot` as Prometheus text-format bytes. The output
+ * always ends with a trailing newline (Prometheus requires it).
+ */
+declare function renderPrometheus(snapshot: MetricsSnapshot): string;
+/** MIME type Prometheus servers must respond with on /metrics. */
+declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+interface MetricsServerOptions {
+    port: number;
+    /** Bind address. Defaults to 127.0.0.1 so we don't accidentally expose metrics publicly. */
+    host?: string;
+    sink: MetricsSink;
+    /** Path to serve on. Defaults to /metrics. */
+    path?: string;
+    /**
+     * V2-C: optional health registry. When provided, the server also responds
+     * on `/healthz` (configurable via `healthPath`) with a JSON aggregate of
+     * every registered health check. K8s probes expect a single HTTP server
+     * exposing both `/metrics` and `/healthz`, so we mount them on the same
+     * port rather than opening a sibling listener.
+     */
+    healthRegistry?: HealthRegistry;
+    /** Path to serve health JSON on. Defaults to /healthz. */
+    healthPath?: string;
+}
+interface MetricsServerHandle {
+    port: number;
+    url: string;
+    close(): Promise<void>;
+}
+/**
+ * Start an HTTP server that exposes a Prometheus scrape endpoint.
+ * Uses node:http directly to avoid pulling a framework into the core graph.
+ *
+ * Why bind to 127.0.0.1 by default: telemetry endpoints inside an agent
+ * process can leak prompt content via metric labels (tool name, error
+ * message, etc.). The default keeps that on the loopback interface;
+ * operators who want network scraping opt in explicitly with host: '0.0.0.0'.
+ */
+declare function startMetricsServer(opts: MetricsServerOptions): Promise<MetricsServerHandle>;
+
+/**
+ * V2-A: OTLP/JSON metrics push exporter.
+ *
+ * Periodically POSTs `MetricsSink.snapshot()` to an OTLP HTTP receiver
+ * (the OpenTelemetry Collector, vendor agents like Honeycomb, Datadog,
+ * Grafana Cloud, etc.). The wire format is OTLP/JSON v1.0 — covered by
+ * the spec at github.com/open-telemetry/opentelemetry-proto.
+ *
+ * Why no `@opentelemetry/*` dep: the core graph is intentionally
+ * dependency-free. The JSON shape is well-defined and stable; bringing
+ * in the official SDK would add ~3MB and pin us to its release cadence.
+ * Operators who need the OTLP gRPC transport or vendor-specific quirks
+ * can wrap an `@opentelemetry/exporter-metrics-otlp-grpc` in a custom
+ * `MetricsSink` instead — the seam exists.
+ */
+interface OtlpMetricsExporterOptions {
+    /** Source of metric data. The exporter reads `snapshot()` per interval. */
+    sink: MetricsSink;
+    /**
+     * OTLP HTTP endpoint base URL. Path `/v1/metrics` is appended unless
+     * the URL already ends with `/v1/metrics` (idempotent).
+     * Example: `http://otel-collector:4318` or `https://otlp.example.com`.
+     */
+    endpoint: string;
+    /** Push interval in milliseconds. Defaults to 30s (Prometheus default). */
+    intervalMs?: number;
+    /** Optional bearer token / API key (sent as `Authorization`). */
+    authorization?: string;
+    /** Extra request headers (vendor-specific keys go here). */
+    headers?: Record<string, string>;
+    /** Resource attributes attached to every export. Defaults: `service.name=wrongstack`. */
+    resourceAttributes?: Record<string, string>;
+    /** Instrumentation scope. Default: `wrongstack`. */
+    scopeName?: string;
+    /** Per-request timeout. Defaults to 10s. */
+    timeoutMs?: number;
+    /** Override fetch (for tests). Defaults to global `fetch`. */
+    fetchImpl?: typeof globalThis.fetch;
+    /** Called when a push fails. Defaults to silent (telemetry must never crash the host). */
+    onError?: (err: unknown) => void;
+}
+interface OtlpMetricsExporterHandle {
+    /** Push immediately (in addition to the scheduled interval). */
+    flush(): Promise<void>;
+    /** Stop the timer, attempt a final flush, then resolve. */
+    stop(): Promise<void>;
+}
+interface OtlpAttribute$1 {
+    key: string;
+    value: {
+        stringValue: string;
+    };
+}
+interface OtlpDataPoint {
+    attributes: OtlpAttribute$1[];
+    timeUnixNano: string;
+    asDouble?: number;
+    asInt?: string;
+    count?: string;
+    sum?: number;
+    quantileValues?: {
+        quantile: number;
+        value: number;
+    }[];
+}
+interface OtlpMetric {
+    name: string;
+    description?: string;
+    unit?: string;
+    sum?: {
+        dataPoints: OtlpDataPoint[];
+        aggregationTemporality: 2;
+        isMonotonic: true;
+    };
+    gauge?: {
+        dataPoints: OtlpDataPoint[];
+    };
+    summary?: {
+        dataPoints: OtlpDataPoint[];
+    };
+}
+interface OtlpExportRequest {
+    resourceMetrics: {
+        resource: {
+            attributes: OtlpAttribute$1[];
+        };
+        scopeMetrics: {
+            scope: {
+                name: string;
+                version?: string;
+            };
+            metrics: OtlpMetric[];
+        }[];
+    }[];
+}
+/**
+ * Build the OTLP/JSON export body from a sink snapshot. Exported for tests
+ * and for callers that want to ship via their own transport.
+ */
+declare function buildOtlpMetricsRequest(sink: MetricsSink, opts?: {
+    resourceAttributes?: Record<string, string>;
+    scopeName?: string;
+}): OtlpExportRequest;
+/**
+ * Start pushing metrics to an OTLP HTTP receiver. Returns a handle with
+ * `flush()` and `stop()`.
+ */
+declare function startOtlpMetricsExporter(opts: OtlpMetricsExporterOptions): OtlpMetricsExporterHandle;
+
+type SpanAttrValue = string | number | boolean;
+interface RecordedSpan {
+    traceId: string;
+    spanId: string;
+    name: string;
+    startTimeUnixNano: bigint;
+    endTimeUnixNano?: bigint;
+    attributes: Record<string, SpanAttrValue>;
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+interface OtlpTraceExporterOptions {
+    /** OTLP HTTP endpoint base URL. `/v1/traces` is appended unless already present. */
+    endpoint: string;
+    /** Push interval in milliseconds. Defaults to 5s (traces are bursty). */
+    intervalMs?: number;
+    /** Hard cap on buffered spans. When exceeded, oldest are dropped. Defaults to 2048. */
+    maxBufferedSpans?: number;
+    /** Authorization header. */
+    authorization?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+    /** Resource attributes. Defaults to `service.name=wrongstack`. */
+    resourceAttributes?: Record<string, string>;
+    /** Instrumentation scope name. Default `wrongstack`. */
+    scopeName?: string;
+    /** Per-request timeout in ms. Default 10s. */
+    timeoutMs?: number;
+    /** Override fetch (for tests). */
+    fetchImpl?: typeof globalThis.fetch;
+    /** Called on push failure. Defaults to silent. */
+    onError?: (err: unknown) => void;
+}
+interface OtlpTraceExporterHandle {
+    /** The Tracer to install on Agent / ToolExecutor. */
+    readonly tracer: Tracer;
+    /** Push buffered spans immediately. */
+    flush(): Promise<void>;
+    /** Stop the timer, push remaining spans, resolve. */
+    stop(): Promise<void>;
+    /** Test helper: snapshot of spans currently in the buffer (not yet pushed). */
+    readonly buffered: () => readonly RecordedSpan[];
+}
+interface OtlpAttribute {
+    key: string;
+    value: {
+        stringValue: string;
+    } | {
+        boolValue: boolean;
+    } | {
+        doubleValue: number;
+    } | {
+        intValue: string;
+    };
+}
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    name: string;
+    kind: 1;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpAttribute[];
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+interface OtlpTracesRequest {
+    resourceSpans: {
+        resource: {
+            attributes: OtlpAttribute[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+            };
+            spans: OtlpSpan[];
+        }[];
+    }[];
+}
+declare function buildOtlpTracesRequest(spans: readonly RecordedSpan[], opts?: {
+    resourceAttributes?: Record<string, string>;
+    scopeName?: string;
+}): OtlpTracesRequest;
+/**
+ * Start the OTLP trace exporter. Returns a `Tracer` to install on the
+ * runtime (`Agent.run` etc.) and `flush()`/`stop()` controls.
+ */
+declare function startOtlpTraceExporter(opts: OtlpTraceExporterOptions): OtlpTraceExporterHandle;
+
 type ContextManagerAction = 'check' | 'summary' | 'prune' | 'add_note' | 'compact';
 interface ContextManagerInput {
     action: ContextManagerAction;
@@ -1079,4 +1621,62 @@ declare function createContextManagerTool(opts?: ContextManagerToolOptions): Too
 /** Pre-built instance with no compactor — compact action will return an error. */
 declare const contextManagerTool: Tool<ContextManagerInput, ContextManagerResult>;
 
-export { type AbandonedSession, type AttachmentStoreOptions, AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, type CompactorOptions, type ConfigLoaderOptions, type ConfigSource, type ContextManagerAction, type ContextManagerInput, type ContextManagerResult, type ContextManagerToolOptions, DefaultAttachmentStore, DefaultConfigLoader, DefaultErrorHandler, DefaultLogger, type DefaultLoggerOptions, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, type DefaultModelsRegistryOptions, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionStore, DefaultSkillLoader, DefaultTaskStore, DefaultTokenCounter, type DoneCheckResult, DoneConditionChecker, type GeneratedTask, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, IntelligentCompactor, type IntelligentCompactorOptions, LLMSelector, type LLMSelectorOptions, type MemoryStoreOptions, type ModeLoaderOptions, type PermissionPolicyOptions, type PersistedQueueItem, QueueStore, RecoveryLock, type RecoveryLockOptions, type SecretVaultOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SessionStoreOptions, type SkillLoaderOptions, SpecDrivenDev, type SpecDrivenDevOptions, SpecParser, type SpecParserOptions, TaskFlow, type TaskFlowEventMap, type TaskFlowEventName, type TaskFlowExecutionContext, type TaskFlowOptions, type TaskFlowPhase, TaskGenerator, type TaskGeneratorOptions, type TaskStore, TaskTracker, type TaskTrackerOptions, type TaskTransition, ToolExecutor, classifyFamily, contextManagerTool, createContextManagerTool, createMessage, decryptConfigSecrets, encryptConfigSecrets, loadProjectModes, loadUserModes, migratePlaintextSecrets, rewriteConfigEncrypted };
+/**
+ * Built-in MCP server presets available to all WrongStack users out of the box.
+ * These servers must be explicitly enabled in config (disabled by default).
+ *
+ * To enable: set `mcpServers: { serverName: { enabled: true } }` in your config.
+ *
+ * Some servers require environment variables or additional config — see notes below.
+ *
+ * Transport types:
+ *   stdio       — spawns a local npm package binary via child_process
+ *   sse         — HTTP SSE endpoint (client POSTs requests)
+ *   streamable-http — session-based HTTP with NDJSON responses
+ */
+/** Filesystem access: read, write, list, search, tree. Good for exploring projects. */
+declare const filesystemServer: () => MCPServerConfig;
+/** GitHub API: issues, PRs, repos, search, file operations. Requires GITHUB_PERSONAL_ACCESS_TOKEN. */
+declare const githubServer: () => MCPServerConfig;
+/**
+ * Context7 — codebase-aware documentation and Q&A using context from your code.
+ * Live documentation for any library, grounded in your actual versions.
+ */
+declare const context7Server: () => MCPServerConfig;
+/**
+ * Brave Search — web search via Brave Browser's API.
+ * Requires BRAVE_SEARCH_API_KEY. Free tier: 2,000 queries/month.
+ * Sign up at https://api.search.brave.com/
+ */
+declare const braveSearchServer: () => MCPServerConfig;
+/**
+ * Block (Block, Inc.) — Postgres database access via SQL.
+ * Useful for running queries against a connected database during development.
+ */
+declare const blockServer: () => MCPServerConfig;
+/**
+ * EverArt — AI image generation via various providers.
+ * Requires EVERART_API_KEY.
+ */
+declare const everArtServer: () => MCPServerConfig;
+/**
+ * Slack — messaging, channels, search.
+ * Requires SLACK_BOT_TOKEN and either SLACK_TEAM_ID or SLACK_USER_TOKEN.
+ */
+declare const slackServer: () => MCPServerConfig;
+/**
+ * AWS knowledge base — EC2, S3, Lambda, IAM, CloudFormation, cost management.
+ * Requires AWS access key + secret in environment.
+ */
+declare const awsServer: () => MCPServerConfig;
+/**
+ * Google Maps — directions, distance matrix, geocoding, places.
+ * Requires GOOGLE_MAPS_API_KEY.
+ */
+declare const googleMapsServer: () => MCPServerConfig;
+/** Sentinel — security vulnerability scanning (sentinel-labs). */
+declare const sentinelServer: () => MCPServerConfig;
+/** Everything bundled — full set of built-in servers. Useful for `wstack mcp add --all`. */
+declare const allServers: () => Record<string, MCPServerConfig>;
+
+export { type AbandonedSession, type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, type AttachmentStoreOptions, AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, type CompactorOptions, type ConfigLoaderOptions, type ConfigMigration, ConfigMigrationError, type ConfigSource, type ContextManagerAction, type ContextManagerInput, type ContextManagerResult, type ContextManagerToolOptions, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, type DefaultLoggerOptions, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, type DefaultModelsRegistryOptions, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultTaskStore, DefaultTokenCounter, type DoneCheckResult, DoneConditionChecker, type GeneratedTask, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, IntelligentCompactor, type IntelligentCompactorOptions, LLMSelector, type LLMSelectorOptions, type MemoryStoreOptions, type MetricsServerHandle, type MetricsServerOptions, type MigrationContext, type MigrationResult, type ModeLoaderOptions, type MultiAgentCoordinatorOptions, NoopMetricsSink, NoopTracer, OTelTracer, type OtlpMetricsExporterHandle, type OtlpMetricsExporterOptions, type OtlpTraceExporterHandle, type OtlpTraceExporterOptions, PROMETHEUS_CONTENT_TYPE, type PermissionPolicyOptions, type PersistedQueueItem, QueueStore, RecoveryLock, type RecoveryLockOptions, type SecretVaultOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SessionStoreOptions, type SkillLoaderOptions, SpecDrivenDev, type SpecDrivenDevOptions, SpecParser, type SpecParserOptions, TaskFlow, type TaskFlowEventMap, type TaskFlowEventName, type TaskFlowExecutionContext, type TaskFlowOptions, type TaskFlowPhase, TaskGenerator, type TaskGeneratorOptions, type TaskStore, TaskTracker, type TaskTrackerOptions, type TaskTransition, ToolExecutor, allServers, awsServer, blockServer, braveSearchServer, buildOtlpMetricsRequest, buildOtlpTracesRequest, classifyFamily, context7Server, contextManagerTool, createContextManagerTool, createMessage, decryptConfigSecrets, encryptConfigSecrets, everArtServer, filesystemServer, githubServer, googleMapsServer, loadProjectModes, loadUserModes, makeAgentSubagentRunner, migratePlaintextSecrets, renderPrometheus, rewriteConfigEncrypted, runConfigMigrations, sentinelServer, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents };