@wrongstack/core 0.1.9 → 0.1.10

package/dist/events-BMNaEFZl.d.ts

@@ -0,0 +1,218 @@
+import { U as Usage, a0 as Context, y as ToolProgressEvent, u as Tool } from './context-BmM2xGUZ.js';
+
+/**
+ * EventBus — observe-only typed event bus.
+ * Subscribers cannot modify or cancel. Subscriber exceptions are caught.
+ */
+
+interface EventMap {
+    'session.started': {
+        id: string;
+    };
+    'session.ended': {
+        id: string;
+        usage: Usage;
+    };
+    'session.damaged': {
+        sessionId: string;
+        detail: string;
+    };
+    'iteration.started': {
+        ctx: Context;
+        index: number;
+    };
+    'iteration.completed': {
+        ctx: Context;
+        index: number;
+    };
+    /**
+     * Fired when the agent hits its iteration limit. Listeners (CLI/TUI) can
+     * call `grant(extra)` to allow more iterations, or `deny()` to stop.
+     * If no listener responds within 30s the run ends with 'max_iterations'.
+     */
+    'iteration.limit_reached': {
+        currentIterations: number;
+        currentLimit: number;
+        grant: (extraIterations: number) => void;
+        deny: () => void;
+    };
+    'provider.response': {
+        ctx: Context;
+        usage: Usage;
+        stopReason: string;
+    };
+    'provider.text_delta': {
+        ctx: Context;
+        text: string;
+    };
+    'provider.thinking_delta': {
+        ctx: Context;
+        text: string;
+    };
+    'provider.tool_use_start': {
+        ctx: Context;
+        id: string;
+        name: string;
+    };
+    'provider.tool_use_stop': {
+        ctx: Context;
+        id: string;
+    };
+    /**
+     * Fired before each retry of a failed provider call. `attempt` is 1-based
+     * (the first retry is attempt 1, etc.). `description` is the human-readable
+     * one-liner from `ProviderError.describe()` — render this in the CLI/TUI
+     * instead of grepping logger output for the raw JSON body.
+     */
+    'provider.retry': {
+        providerId: string;
+        attempt: number;
+        delayMs: number;
+        status: number;
+        description: string;
+    };
+    /**
+     * Fired once when a provider call ultimately fails (retries exhausted, or
+     * non-retryable error). Same shape as `provider.retry` minus the delay.
+     */
+    'provider.error': {
+        providerId: string;
+        status: number;
+        description: string;
+        retryable: boolean;
+    };
+    'tool.started': {
+        name: string;
+        id: string;
+        input?: unknown;
+    };
+    /**
+     * Fired for each ToolProgressEvent yielded by `Tool.executeStream`. UIs
+     * subscribe to render incremental progress (streaming bash output, file
+     * tree counts, etc.) without the tool having to know about the UI.
+     */
+    'tool.progress': {
+        name: string;
+        id: string;
+        event: ToolProgressEvent;
+    };
+    /**
+     * Fired when a tool call needs user confirmation and no confirmHandler
+     * is registered on the executor. The TUI renders a confirmation dialog
+     * from this event. Resolution is driven by calling the resolve function
+     * passed in the payload with a decision string ('yes' | 'no' | 'always' | 'deny').
+     */
+    'tool.confirm_needed': {
+        tool: Tool;
+        input: unknown;
+        toolUseId: string;
+        suggestedPattern: string;
+        resolve: (decision: 'yes' | 'no' | 'always' | 'deny') => void;
+    };
+    /**
+     * `output` is a truncated preview of the tool's serialized result text
+     * (capped at ~400 chars by the emitter). UIs render this inline in the
+     * tool history line without re-fetching from the session log.
+     */
+    'tool.executed': {
+        /**
+         * The tool_use id (e.g. "toolu_…") issued by the provider for this call.
+         * Pairs with `tool.started.id` so subscribers can correlate start/finish
+         * even when the model fires multiple tools in parallel with identical
+         * inputs. Optional only for legacy emit sites — new code should always
+         * set it.
+         */
+        id?: string;
+        name: string;
+        durationMs: number;
+        ok: boolean;
+        input?: unknown;
+        output?: string;
+        /**
+         * Full UTF-8 byte length of the serialized tool result that the model
+         * actually sees (post-cap, post-scrub). The `output` preview is capped
+         * at ~400 chars for transport; this number lets UIs surface what the
+         * model is really paying tokens for. Optional only for legacy emit
+         * sites that may not yet populate it.
+         */
+        outputBytes?: number;
+        /**
+         * Estimated token count for the full result body the model sees.
+         * Computed from `outputBytes` with the standard ~3.5 chars/token
+         * heuristic. Cheap to show in the TUI; not authoritative — the real
+         * provider count lives in `provider.response.usage`. */
+        outputTokens?: number;
+        /**
+         * For tools whose output has a clear "line" notion (file reads with
+         * numbered prefixes, grep hits, bash stdout), the agent counts the
+         * actual lines the model received and forwards it here. Undefined
+         * for tools without a meaningful line count. */
+        outputLines?: number;
+    };
+    'token.threshold': {
+        used: number;
+        limit: number;
+    };
+    'compaction.fired': {
+        before: number;
+        after: number;
+    };
+    /**
+     * Fired when the auto-compaction middleware's compactor.compact() call
+     * throws. Compaction is best-effort by design so we don't crash the agent
+     * loop, but a persistent failure (misconfigured summarizer model, network
+     * outage) means the next iteration may hit context overflow. Observability
+     * layers / dashboards subscribe to this to surface the silent regression.
+     */
+    'compaction.failed': {
+        err: Error;
+        aggressive: boolean;
+        level: 'warn' | 'soft' | 'hard';
+        tokens: number;
+        maxContext: number;
+        load: number;
+        fatal: boolean;
+    };
+    'mcp.server.connected': {
+        name: string;
+        toolCount: number;
+    };
+    'mcp.server.reconnected': {
+        name: string;
+        toolCount: number;
+    };
+    'mcp.server.disconnected': {
+        name: string;
+        reason: string;
+    };
+    'token.cost_estimate_unavailable': {
+        model: string;
+    };
+    error: {
+        err: Error;
+        phase: string;
+    };
+}
+type EventName = keyof EventMap;
+type Listener<E extends EventName> = (payload: EventMap[E]) => void;
+interface EventLogger {
+    error(msg: string, ctx?: unknown): void;
+}
+declare class EventBus {
+    private readonly listeners;
+    private logger?;
+    setLogger(logger: EventLogger): void;
+    on<E extends EventName>(event: E, fn: Listener<E>): () => void;
+    off<E extends EventName>(event: E, fn: Listener<E>): void;
+    once<E extends EventName>(event: E, fn: Listener<E>): () => void;
+    emit<E extends EventName>(event: E, payload: EventMap[E]): void;
+    clear(): void;
+    /**
+     * V2-D: introspection helper. Pass an `event` to count handlers for a
+     * single key, or omit to get the total across every event. Used by the
+     * leak-detection smoke test to flag handler accumulation across runs.
+     */
+    listenerCount(event?: EventName): number;
+}
+
+export { EventBus as E, type Listener as L, type EventName as a, type EventLogger as b, type EventMap as c };

package/dist/execution/index.d.ts

@@ -0,0 +1,260 @@
+export { C as CompactorOptions, D as DefaultErrorHandler, a as DefaultRetryPolicy, H as HybridCompactor, T as ToolExecutor } from '../tool-executor-CpuJPYm9.js';
+import { g as Provider, a0 as Context } from '../context-BmM2xGUZ.js';
+import { C as Compactor, a as CompactReport } from '../compactor-B4mQZXf2.js';
+import { M as MessageSelector } from '../selector-BbJqiEP4.js';
+import { E as EventBus } from '../events-BMNaEFZl.js';
+import { a as MiddlewareHandler } from '../renderer-rk_1Swwc.js';
+import { A as Agent, R as RunResult } from '../plugin-DJk6LL8B.js';
+import { D as DoneCondition } from '../multi-agent-fmkRHtof.js';
+import { a as SkillLoader, b as SkillManifest, S as SkillEntry } from '../skill-DhfSizKv.js';
+import { a as WstackPaths } from '../wstack-paths-BGu2INTm.js';
+import '../models-registry-Y2xbog0E.js';
+import '../observability-BhnVLBLS.js';
+import '../secret-scrubber-CicHLN4G.js';
+import '../config-BU9f_5yH.js';
+import '../logger-BMQgxvdy.js';
+
+interface SkillLoaderOptions {
+    paths: WstackPaths;
+    bundledDir?: string;
+}
+/**
+ * Discovery order (later layers shadow earlier ones at boot, but we walk
+ * highest priority first and skip names already seen):
+ *   1. Project-committed:  <project>/.wrongstack/skills/
+ *   2. User-global:        ~/.wrongstack/skills/
+ *   3. Bundled with build: packages/core/skills/
+ */
+declare class DefaultSkillLoader implements SkillLoader {
+    private readonly dirs;
+    private cache?;
+    constructor(opts: SkillLoaderOptions);
+    list(): Promise<SkillManifest[]>;
+    find(name: string): Promise<SkillManifest | undefined>;
+    manifestText(): Promise<string>;
+    listEntries(): Promise<SkillEntry[]>;
+    readBody(name: string): Promise<string>;
+}
+
+/**
+ * Options for IntelligentCompactor.
+ */
+interface IntelligentCompactorOptions {
+    /** Provider to use for LLM-assisted summarization. Required. */
+    provider: Provider;
+    /** Fraction of maxContext that triggers a warning (default 0.6). */
+    warnThreshold?: number;
+    /** Fraction of maxContext that triggers soft compaction (default 0.75). */
+    softThreshold?: number;
+    /** Fraction of maxContext that triggers hard compaction (default 0.9). */
+    hardThreshold?: number;
+    /** Max context window in tokens (used only for threshold fraction math). */
+    maxContext?: number;
+    /** How many recent (user+assistant) pairs to always preserve (default 4). */
+    preserveK?: number;
+    /** Token threshold below which tool results are not elided (default 500). */
+    eliseThreshold?: number;
+    /** System prompt for the summarizer sub-LLM. */
+    summarizerPrompt?: string;
+    /**
+     * Model ID to use for summarization. When not set, the same model as the
+     * agent is used (which risks cascading failure on context overflow). Set to
+     * a fast/cheap model like `claude-3-5-haiku-20240620` for resilience.
+     */
+    summarizerModel?: string;
+}
+/**
+ * IntelligentCompactor uses an LLM to:
+ *  - Analyze message importance and preserve critical context
+ *  - Generate semantic summaries for old message ranges
+ *  - Make intelligent decisions about what to compact
+ *
+ * It extends HybridCompactor's elision logic with LLM-assisted summarization.
+ */
+declare class IntelligentCompactor implements Compactor {
+    private readonly provider;
+    private readonly warnThreshold;
+    private readonly softThreshold;
+    private readonly hardThreshold;
+    private readonly maxContext;
+    private readonly preserveK;
+    private readonly eliseThreshold;
+    private readonly summarizerPrompt;
+    private readonly summarizerModel?;
+    constructor(opts: IntelligentCompactorOptions);
+    compact(ctx: Context, opts?: {
+        aggressive?: boolean;
+    }): Promise<CompactReport>;
+    private summarizeAncientTurns;
+    private findSafeBoundary;
+    private findExchangeStart;
+    private callSummarizer;
+    private messagesToText;
+    private lightweightCompact;
+    private eliseOldToolResults;
+    private hasTextContent;
+    private estimateTokens;
+}
+
+/**
+ * Options for SelectiveCompactor — the most configurable compactor.
+ */
+interface SelectiveCompactorOptions {
+    /** Provider for LLM calls (selector + summarizer). Required. */
+    provider: Provider;
+    /** Selector for LLM-driven importance analysis. */
+    selector?: MessageSelector;
+    /** Fraction of maxContext that triggers a warning (default 0.6). */
+    warnThreshold?: number;
+    /** Fraction of maxContext that triggers soft compaction (default 0.75). */
+    softThreshold?: number;
+    /** Fraction of maxContext that triggers hard compaction (default 0.9). */
+    hardThreshold?: number;
+    /** Max context window in tokens (used for threshold fraction math). */
+    maxContext?: number;
+    /** How many recent (user+assistant) pairs to always preserve (default 4). */
+    preserveK?: number;
+    /** Token threshold below which tool results are not elided (default 500). */
+    eliseThreshold?: number;
+    /** Model for selector LLM calls (default: same as provider default). */
+    selectorModel?: string;
+    /** Summarizer model for collapsed ranges (default: same as selectorModel). */
+    summarizerModel?: string;
+    /** Prompt for the summarizer sub-LLM. */
+    summarizerPrompt?: string;
+}
+/**
+ * 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
+ */
+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;
+    }): Promise<CompactReport>;
+    /**
+     * 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;
+    private estimateTokens;
+    private roughTokenEstimate;
+}
+
+type CompactionFailureMode = 'throw' | 'throw_on_hard' | 'continue';
+interface AutoCompactionOptions {
+    aggressiveOn?: 'hard' | 'soft' | 'warn';
+    events?: EventBus;
+    failureMode?: CompactionFailureMode;
+}
+/**
+ * Pipeline middleware that monitors context token load and automatically
+ * triggers compaction when the warn/soft/hard thresholds are crossed.
+ * Runs before the next agent iteration.
+ */
+declare class AutoCompactionMiddleware {
+    readonly name = "AutoCompaction";
+    private readonly compactor;
+    private readonly warnThreshold;
+    private readonly softThreshold;
+    private readonly hardThreshold;
+    private readonly maxContext;
+    private readonly estimator;
+    private readonly aggressiveOn;
+    private readonly events?;
+    private readonly failureMode;
+    /**
+     * @param compactor        Compactor to use for compaction.
+     * @param maxContext       Provider's max context window in tokens.
+     * @param estimator        Token estimation function.
+     * @param thresholds       Threshold fractions (0-1) of maxContext.
+     * @param opts             Optional behavior. By default, failures at the
+     *                         hard threshold throw AGENT_CONTEXT_OVERFLOW so
+     *                         the agent does not continue into a likely
+     *                         provider context overflow. Warn/soft failures
+     *                         still emit compaction.failed and continue.
+     */
+    constructor(compactor: Compactor, maxContext: number, estimator: (ctx: Context) => number, thresholds: {
+        warn: number;
+        soft: number;
+        hard: number;
+    }, optsOrAggressiveOn?: AutoCompactionOptions | 'hard' | 'soft' | 'warn', events?: EventBus);
+    handler(): MiddlewareHandler<Context>;
+    private compact;
+}
+
+type AutonomousResult = RunResult & {
+    toolCalls: number;
+    reason?: string;
+};
+interface DoneCheckResult {
+    done: boolean;
+    reason?: string;
+    iterations: number;
+    toolCalls: number;
+}
+declare class DoneConditionChecker {
+    private readonly condition;
+    private readonly compiledRegex;
+    constructor(condition: DoneCondition);
+    check(state: {
+        iterations: number;
+        toolCalls: number;
+        lastOutput?: string;
+    }): DoneCheckResult;
+}
+interface AutonomousRunnerOptions {
+    agent: Agent;
+    context: Context;
+    doneCondition: DoneCondition;
+    iterationTimeoutMs?: number;
+    onIteration?: (state: {
+        iteration: number;
+        toolCalls: number;
+    }) => void;
+    onDone?: (result: AutonomousResult) => void;
+}
+declare class AutonomousRunner {
+    private readonly opts;
+    private iterations;
+    private toolCalls;
+    private lastOutput?;
+    private stopped;
+    private readonly doneChecker;
+    constructor(opts: AutonomousRunnerOptions);
+    run(): Promise<AutonomousResult>;
+    private runLoop;
+    stop(): void;
+}
+
+export { AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, DefaultSkillLoader, type DoneCheckResult, DoneConditionChecker, IntelligentCompactor, type IntelligentCompactorOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SkillLoaderOptions };