@wrongstack/core 0.5.7 → 0.6.1

package/dist/{events-DPQKFX7W.d.ts → events-CzkeaVVl.d.ts}

@@ -57,6 +57,7 @@ interface EventMap {
     'provider.tool_use_stop': {
         ctx: Context;
         id: string;
+        name: string;
     };
     /**
      * Fired before each retry of a failed provider call. `attempt` is 1-based
@@ -175,15 +176,20 @@ interface EventMap {
      * runner/budget classes.
      */
     'budget.threshold_reached': {
-        kind: 'iterations' | 'tool_calls' | 'tokens' | 'cost';
+        kind: 'iterations' | 'tool_calls' | 'tokens' | 'cost' | 'timeout';
         used: number;
         limit: number;
-        /** Call to grant more of the same budget type. */
+        /**
+         * Call to grant more of the same budget type. `timeoutMs` extends the
+         * wall-clock budget; the coordinator's watchdog observes the patched
+         * limit and re-arms its timer for the new remainder.
+         */
         extend: (extra: Partial<{
             maxIterations: number;
             maxToolCalls: number;
             maxTokens: number;
             maxCostUsd: number;
+            timeoutMs: number;
         }>) => void;
         /** Call to deny the extension — subagent will stop. */
         deny: () => void;

package/dist/execution/index.d.ts

@@ -1,12 +1,13 @@
-export { C as CompactorOptions, a as DefaultErrorHandler, b as DefaultRetryPolicy, H as HybridCompactor, T as ToolExecutor } from '../tool-executor-DbAFkHdP.js';
+export { C as CompactorOptions, a as DefaultErrorHandler, b as DefaultRetryPolicy, H as HybridCompactor, T as ToolExecutor } from '../tool-executor-40Q6shR-.js';
 import { g as Provider, a2 as Context } from '../context-CDRyrkKQ.js';
 import { a as Compactor, C as CompactReport } from '../compactor-RIPuTtWK.js';
 import { M as MessageSelector } from '../selector-C7HqnZJU.js';
-import { E as EventBus } from '../events-DPQKFX7W.js';
+import { E as EventBus } from '../events-CzkeaVVl.js';
 import { c as MiddlewareHandler } from '../system-prompt-Dl2QY1_B.js';
 import { e as ContextWindowAggressiveOn, i as ContextWindowPolicy } from '../config-BGGuP_Ar.js';
-import { r as Agent, R as RunResult } from '../index-j2WyAyML.js';
-import { D as DoneCondition } from '../multi-agent-Cpp7FXUl.js';
+import { r as Agent, R as RunResult, j as SystemPromptContributor } from '../index-BkKLQjea.js';
+import { D as DoneCondition } from '../multi-agent-MfI6dmv-.js';
+import { J as JournalEntry } from '../goal-store-DVCfj7Ff.js';
 import { a as SkillLoader, b as SkillManifest, S as SkillEntry } from '../skill-CxuWrsKK.js';
 import { W as WstackPaths } from '../wstack-paths-86YPFktR.js';
 import '../retry-policy-LKS8MHsB.js';
@@ -273,4 +274,279 @@ declare class AutonomousRunner {
     stop(): void;
 }
 
-export { AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, DefaultSkillLoader, type DoneCheckResult, DoneConditionChecker, IntelligentCompactor, type IntelligentCompactorOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SkillLoaderOptions };
+/**
+ * Sense-decide-execute-reflect loop on top of a long-running Goal.
+ *
+ * Each iteration:
+ *   1. Sense   — read goal, pending todos, `git status --porcelain`.
+ *   2. Decide  — pick a source (todo / git / brainstorm) and a task.
+ *   3. Execute — single agent.run with a directive prompt.
+ *   4. Reflect — append a journal entry, persist state to disk.
+ *
+ * The loop runs forever until `stop()` is called externally (REPL SIGINT
+ * handler, /autonomy stop). No internal time/cost cap by design — the
+ * user wants "sittin sene". Failures are logged and the loop continues
+ * with a different source on the next tick.
+ */
+interface EternalAutonomyOptions {
+    agent: Agent;
+    projectRoot: string;
+    /**
+     * Per-iteration agent timeout. Defaults to 5 minutes. A single hung
+     * provider call should not freeze the whole eternal loop.
+     */
+    iterationTimeoutMs?: number;
+    /**
+     * Maximum number of internal agent.run iterations the engine grants per
+     * eternal-loop tick. The engine sets `autonomousContinue: true` so the
+     * agent can run multi-step tasks end-to-end within one tick instead of
+     * bouncing back to the engine after every single tool call. Default 50.
+     */
+    iterationMaxAgentSteps?: number;
+    /**
+     * Minimum sleep between iterations. Defaults to 1 s — enough for
+     * SIGINT handlers to fire mid-loop without pegging a core when the
+     * provider is being rate-limited.
+     */
+    cycleGapMs?: number;
+    /**
+     * Maximum consecutive failures before the source rotation forces a
+     * brainstorm cycle. Default 3. Acts as a soft-recovery, not a stop.
+     */
+    failureBudget?: number;
+    /**
+     * Per-todo failed-attempt ceiling. When the engine picks the same todo
+     * and the iteration fails this many times in total, the todo is taken
+     * out of rotation (engine prefers other sources) until it changes
+     * status. Default 3. Prevents the loop from spinning forever on one
+     * stuck task.
+     */
+    todoMaxAttempts?: number;
+    /**
+     * Consecutive brainstorm-DONE responses required to consider the goal
+     * complete and stop the engine. When the LLM's brainstorm step keeps
+     * answering `DONE`, the engine treats that as "no more work" and, after
+     * this many in a row, marks the goal as completed instead of sleeping
+     * forever. Default 3.
+     */
+    brainstormDoneStopThreshold?: number;
+    /** Side-channel notifications (logging, UI updates). */
+    onIteration?: (entry: JournalEntry) => void;
+    onError?: (err: Error, iteration: number) => void;
+    /**
+     * Optional injected git status reader — production code uses git, tests
+     * stub this out so they don't shell out.
+     */
+    gitStatusReader?: () => Promise<string>;
+    /**
+     * Optional clock — tests stub for deterministic timestamps.
+     */
+    now?: () => Date;
+    /**
+     * Optional compactor. When provided, the engine runs compaction every
+     * `compactEveryNIterations` iterations to keep the agent's message
+     * history under control during multi-day eternal loops. Without
+     * compaction, an infinite loop will eventually overflow the provider's
+     * context window and start failing.
+     */
+    compactor?: Compactor;
+    /** How many iterations between compaction calls. Default 25. */
+    compactEveryNIterations?: number;
+    /**
+     * Aggressive compaction threshold. When ctx token usage exceeds this
+     * fraction of `maxContextTokens`, compaction runs in aggressive mode
+     * regardless of the iteration cadence. 0.85 by default.
+     */
+    aggressiveCompactRatio?: number;
+    /**
+     * Model's max context window in tokens. When set, the engine watches
+     * `currentRequestTokens()` against this and triggers aggressive compact
+     * before the next iteration would overflow. Omit to disable threshold
+     * checks (iteration cadence still applies).
+     */
+    maxContextTokens?: number;
+    /**
+     * Base delay (ms) for the first transient-error backoff. Subsequent
+     * transient failures double this, capped at `transientBackoffMaxMs`.
+     * Default 2_000.
+     *
+     * "Transient" means the underlying error is recoverable per
+     * `WrongStackError.recoverable` (ProviderError sets this for 429/529/5xx
+     * /network errors). Permanent errors (auth/invalid request) skip the
+     * backoff and count toward `failureBudget` like before — backing off
+     * on a permanent failure is wasted time.
+     */
+    transientBackoffBaseMs?: number;
+    /** Ceiling for the exponential backoff. Default 60_000 (60 s). */
+    transientBackoffMaxMs?: number;
+}
+type EternalEngineState = 'idle' | 'running' | 'stopped';
+declare class EternalAutonomyEngine {
+    private readonly opts;
+    private state;
+    private stopRequested;
+    private consecutiveFailures;
+    private consecutiveBrainstormDone;
+    /**
+     * Count of consecutive transient (recoverable) provider failures. Drives
+     * the exponential backoff between iterations. Reset on the first
+     * successful iteration so a single bad afternoon doesn't permanently
+     * slow the loop down.
+     */
+    private consecutiveTransientRetries;
+    private currentCtrl;
+    private iterationsSinceCompact;
+    private readonly goalPath;
+    constructor(opts: EternalAutonomyOptions);
+    /** Current engine state — readable for UIs. */
+    get currentState(): EternalEngineState;
+    /** Synchronously request stop. Resolves once the running iteration aborts. */
+    stop(): void;
+    /**
+     * Mark the engine as 'running' on disk + reset stop state so a new
+     * batch of `runOneIteration()` calls can proceed. Called by the REPL
+     * when the user invokes `/autonomy eternal`. Idempotent.
+     */
+    prime(): Promise<void>;
+    /**
+     * Main loop. Returns when stop() is called or the goal file is removed.
+     * Does NOT throw — every iteration is wrapped to keep the loop alive.
+     */
+    run(): Promise<void>;
+    /**
+     * Execute a single sense-decide-execute-reflect cycle.
+     * Returns true on success, false on handled failure / no-op.
+     *
+     * Exposed publicly so the REPL can pace iterations from its main loop
+     * — running the engine and the REPL as a single sequential consumer of
+     * `agent.run()` avoids race conditions on the shared Context.
+     */
+    runOneIteration(): Promise<boolean>;
+    /**
+     * Run compaction when either trigger fires:
+     *   - We've done >= compactEveryNIterations since the last compact.
+     *   - Current request tokens exceed aggressiveCompactRatio * maxContext.
+     *
+     * The second check uses *aggressive* mode to free more headroom; the
+     * cadence check uses non-aggressive (cheaper).
+     */
+    private maybeCompact;
+    /**
+     * Hybrid idea source.
+     *   1. Pending todos on the agent's context.
+     *   2. Dirty git working tree → propose a "review and finish this" task.
+     *   3. Otherwise: brainstorm via the LLM against the goal.
+     *
+     * After failureBudget consecutive failures, force brainstorm so the
+     * engine doesn't loop on the same broken todo or stuck git state.
+     */
+    private decide;
+    private pickPendingTodo;
+    private pickGitTask;
+    private readGitStatus;
+    private brainstormTask;
+    private buildDirective;
+    /**
+     * Exponential backoff for transient provider errors. `2^N * base`
+     * capped at `transientBackoffMaxMs`. Zero base disables backoff.
+     * Public-private to keep `runOneIteration` readable; the value is
+     * recomputed each call from the current retry count, so callers
+     * don't have to track state.
+     */
+    private computeTransientBackoffMs;
+    /**
+     * Sleep that wakes early if `stopRequested` flips. Polls every 250 ms
+     * so SIGINT / `/autonomy stop` can land in the middle of a long
+     * backoff instead of waiting up to a minute for the timer.
+     */
+    private sleepInterruptible;
+    private appendIterationEntry;
+    /**
+     * Persistent per-todo failure counter. Skipped silently when the goal
+     * file has been removed (graceful clear). Each non-success iteration
+     * against a todo source bumps the counter by 1; `pickPendingTodo` reads
+     * the counter to rotate past stuck todos once they cross `todoMaxAttempts`.
+     */
+    private bumpTodoAttempt;
+    /**
+     * Flip the mission to `completed` and journal it. Called from two
+     * paths: (a) `[GOAL_COMPLETE]` marker in a successful iteration's
+     * finalText, (b) `brainstorm` returning DONE consecutively past the
+     * configured threshold. Idempotent — re-entry is a no-op once the
+     * goal is already `completed`.
+     */
+    private markGoalCompleted;
+    private appendFailure;
+    private persistEngineState;
+}
+
+/**
+ * System-prompt contributor that surfaces eternal-autonomy state to the
+ * model on every turn.
+ *
+ * Why this exists: when the engine drives a long-running loop, the
+ * per-iteration directive carries the rules. But the directive is a USER
+ * message — it scrolls out of working memory after a few compactions and
+ * the model forgets it's in autonomy mode (forgets `[GOAL_COMPLETE]`,
+ * forgets the todo-state protocol, forgets the no-confirmation rule).
+ * Injecting the same anchor as a CACHED system-prompt block solves that
+ * — the rules sit next to the identity layer and survive compactions.
+ *
+ * Block is tagged `ephemeral` so its content (journal tail, iteration
+ * counter) changes each turn without invalidating the upstream prefix
+ * cache.
+ */
+
+interface AutonomyPromptContributorOptions {
+    /** Absolute path to the project's `goal.json`. */
+    goalPath: string;
+    /**
+     * Gating function. The contributor consults this on every build and
+     * returns an empty array when `false` — without this, the block would
+     * leak into interactive runs that happen to have a goal on disk and
+     * teach the model loop-control markers it shouldn't emit.
+     *
+     * Typical wiring: `() => autonomyMode === 'eternal'`.
+     */
+    enabled: () => boolean;
+    /** Number of journal entries to include in the recent-tail block. Default 5. */
+    journalTailSize?: number;
+}
+/**
+ * Build a contributor that renders the autonomy-state system block.
+ * Returns `[]` when disabled, no goal exists, or the goal has been
+ * completed/abandoned — all silent fast-paths.
+ */
+declare function makeAutonomyPromptContributor(opts: AutonomyPromptContributorOptions): SystemPromptContributor;
+
+/**
+ * `/goal <description>` preamble — the "no force can stop this" mode.
+ *
+ * Unlike STEERING (which redirects mid-flight), GOAL is a contract:
+ * the user hands over a problem, the agent commits to verifiably
+ * finishing it, and every iteration re-reads this preamble from the
+ * conversation history. The hardening is entirely prompt-level —
+ * the system has already removed implicit budget caps, so this
+ * preamble's job is to remove the MODEL's tendency to hedge, ask
+ * permission, or declare premature success.
+ *
+ * The four sections are intentional:
+ *   1. AUTHORITY — explicit grant of unbounded fan-out + model
+ *      switching. Without this the model self-throttles ("I shouldn't
+ *      spawn too many…") even when budgets are unlimited.
+ *   2. DONE — concrete bar for completion. Forces a verifiable
+ *      artifact (test passing, file written, bug re-run clean).
+ *      Without this the model returns "I believe it's fixed" and
+ *      counts that as done.
+ *   3. NOT DONE — explicit anti-patterns. Each item is something we
+ *      saw real agents do as a "completion" that wasn't.
+ *   4. PERSISTENCE — three-angle rule for blockers. Stops the model
+ *      from giving up on the first tool failure.
+ *
+ * Located in @wrongstack/core (rather than @wrongstack/tui) so headless
+ * callers and the WebUI can issue `/goal set` without dragging the TUI
+ * package in. The tui re-exports this for backward compatibility.
+ */
+declare function buildGoalPreamble(goal: string): string;
+
+export { AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, type AutonomyPromptContributorOptions, DefaultSkillLoader, type DoneCheckResult, DoneConditionChecker, EternalAutonomyEngine, type EternalAutonomyOptions, type EternalEngineState, IntelligentCompactor, type IntelligentCompactorOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SkillLoaderOptions, buildGoalPreamble, makeAutonomyPromptContributor };