@prestyj/cli 5.28.0 → 5.29.0

package/dist/core/agent-session.d.ts

@@ -1,5 +1,5 @@
 import { type AgentTool } from "@prestyj/agent";
-import { type Message, type MessageProvenance, type Provider, type ThinkingLevel } from "@prestyj/ai";
+import { type Message, type MessageProvenance, type Provider, type Usage, type ThinkingLevel } from "@prestyj/ai";
 import { EventBus } from "./event-bus.js";
 import { type CompletionReview } from "./completion-review.js";
 import { SlashCommandRegistry } from "./slash-commands.js";
@@ -9,6 +9,7 @@ import type { BackgroundProcess } from "./process-manager.js";
 import type { MCPElicitHandler } from "./mcp/index.js";
 import { type ContextLimits } from "./context-limits.js";
 import { type ImportForeignTranscriptResult } from "./foreign-session-import.js";
+import { type CacheExpiryStatus } from "./cache-expiry.js";
 import { type EnhanceResult } from "../utils/prompt-enhancer.js";
 import { type VerificationEvidence } from "./verification-evidence.js";
 /** A chat attachment (image / video / other file) prepared for the model. The
@@ -21,6 +22,13 @@ export interface SessionAttachment {
     name: string;
     path?: string;
 }
+/** Per-prompt run controls. */
+export interface PromptRunOptions {
+    /** Offer the model no tools for this prompt. */
+    disableTools?: boolean;
+    /** Hold reasoning effort at the plan-mode ceiling for this prompt. */
+    capThinking?: boolean;
+}
 export interface AgentSessionOptions {
     provider: Provider;
     model: string;
@@ -155,7 +163,7 @@ export interface AgentSessionOptions {
     sessionRootDir?: string;
     /** Register EZ Coder built-in/prompt/custom slash commands. Defaults to true. */
     coderSlashCommands?: boolean;
-    /** Enable loop-break, re-grounding, and Ideal review hooks. Defaults to true. */
+    /** Enable loop-break and re-grounding hooks. Defaults to true. */
     selfCorrectionHooks?: boolean;
     /** Override the semantic-loop judge LLM call (tests). Receives the finished
      *  prompt, returns the model's raw reply. Default: one-shot `stream()` call
@@ -222,6 +230,7 @@ export declare class AgentSession {
     private autopilotMarkers;
     private appMarkers;
     private turnMetrics;
+    private readonly cacheDiagnostics;
     /** Internal-only (EZ_INTERNAL): live per-session cost/reliability recorder.
      * Absent entirely in public builds — see core/internal-diagnostics.ts. */
     private diagnosticsRecorder?;
@@ -230,6 +239,10 @@ export declare class AgentSession {
      *  creation). Called from switchModel so video-capable models get the
      *  read-tool's native-video path after a mid-session model change. */
     private rebuildReadTool;
+    /** Forgets every file read; called whenever the conversation is replaced or
+     *  rewound, so the model must re-read a file before changing it. */
+    private clearReadTracker;
+    private recordBashReads;
     private skills;
     private cacheKeyLogged;
     private hookStats;
@@ -242,20 +255,6 @@ export declare class AgentSession {
     private hookFileEditCounts;
     private hookToolCalls;
     private backgroundVerification;
-    private idealReviewPhase;
-    /** Runtime-only suppression while Nolan owns verification in autopilot mode. */
-    private idealReviewSuppressed;
-    /** Mirror of the last `hook_armed` value broadcast this run, so the event
-     *  fires only on a real edge. */
-    private idealReviewArmed;
-    /** Cached test-drift probe, keyed by the size of the edited-file set. Drift
-     *  depends only on WHICH files were edited and that set only grows, so this
-     *  keeps the arming check off the filesystem on most tool results — the probe
-     *  is several sync existsSync calls per edited file. */
-    private idealDriftProbe;
-    private readonly reviewCoverage;
-    /** Coverage follow-ups spent this run, capped by MAX_REVIEW_COVERAGE_INJECTIONS. */
-    private reviewCoverageInjected;
     /** 0 = none; 1 = first nudge sent; 2 = final stop-and-report injected. */
     private loopBreakInjected;
     private regroundingInjected;
@@ -265,8 +264,6 @@ export declare class AgentSession {
      *  injection at the next steering poll; judge failures fail open (no
      *  injection) and still consume budget + cooldown. */
     private semanticLoop;
-    /** Independent Ideal reviewer spawned once per run (score-gated). */
-    private independentReviewStarted;
     /**
      * The environment as the cached system prompt currently describes it.
      * Re-recorded on every prompt build, so a rebuild (e.g. `/add-dir`) needs no
@@ -277,11 +274,12 @@ export declare class AgentSession {
     private runStartedAt;
     /** Gate injections spent this run, capped by MAX_PROCESS_GATE_INJECTIONS. */
     private processGateInjected;
-    /** Verification gate: code edited this run, nothing proved it since. */
+    /** Verification gate: code edited this run, nothing proved it since. Always
+     *  tracks evidence for run status; the `verificationGateEnabled` setting
+     *  decides whether an unverified stop is also continued once. */
     private readonly verificationGate;
-    /** Mirror of the last verification `hook_armed` value, so the event fires
-     *  only on a real edge. */
-    private verificationArmed;
+    /** Mirror of the last `hook_armed` value, so the event fires only on an edge. */
+    private preFinalArmed;
     private compactionOccurred;
     /**
      * Re-grounding carry-over for post-turn compaction. `resetHookState` clears
@@ -294,6 +292,12 @@ export declare class AgentSession {
     private postTurnCompaction?;
     private lastCompactionCompacted;
     private compactionRetryAfter;
+    /**
+     * SoL-Pi plan-step compaction bookkeeping (see compaction/plan-step-policy.ts).
+     * Step progress comes from `[DONE:n]` markers in assistant text — the same
+     * contract the approved-plan UI tracks.
+     */
+    private planStepState;
     /** A restored oversized checkpoint must be canonicalized before its first prompt is persisted. */
     private deferredCompactionPending;
     /** Latest provider count, anchored to the assistant response it measured. */
@@ -301,8 +305,12 @@ export declare class AgentSession {
     private originalRequest;
     private userQueue;
     private queueSeq;
+    /** Instant interrupt: the running loop's preempt listeners, fired on queueMessage. */
+    private steeringListeners;
     private processManager?;
     private lspManager?;
+    private testImpact?;
+    private debugManager?;
     private subAgentManager?;
     /**
      * Out-of-band push notifications (finished children, background-process
@@ -450,6 +458,14 @@ export declare class AgentSession {
      * registration on an existing catalog would leave those tools unreachable.
      */
     private ensureToolSearchTool;
+    /**
+     * `wait_agent` is deferred, yet nearly every `spawn_agent` is followed by it,
+     * so the model spent a whole turn on `tool_search` just to load it (bench 41:
+     * ~6 s per fan-out). Promote it as soon as a spawn succeeds instead: the tool
+     * list grows exactly as it would after that `tool_search`, one turn earlier,
+     * and sessions that never spawn keep the smaller prefix.
+     */
+    private promoteWaitAgentAfterSpawn;
     /** Append tools, replacing any same-named entry (cached stub → live tool). */
     private replaceOrPushTools;
     /** Swap already-promoted cached stubs for their live equivalents, in place. */
@@ -482,10 +498,10 @@ export declare class AgentSession {
     willExpandPromptTemplate(content: string): Promise<boolean>;
     /**
      * Process user input. Handles slash commands or runs agent loop.
+     * `capThinking` holds reasoning effort at the plan-mode ceiling for this
+     * prompt — for turns that must answer quickly from what is already known.
      */
-    prompt(content: string, provenance?: MessageProvenance, options?: {
-        disableTools?: boolean;
-    }): Promise<void>;
+    prompt(content: string, provenance?: MessageProvenance, options?: PromptRunOptions): Promise<void>;
     /**
      * Prompt with multimodal attachments (images / videos) alongside optional
      * text. Images and videos become native content blocks the model can see;
@@ -508,10 +524,17 @@ export declare class AgentSession {
     private resetHookState;
     /**
      * Fold one agent event into the hook stat accumulators. Pure bookkeeping —
-     * the same signals the TUI's useAgentLoop collects, so the loop-break and
-     * ideal-review decisions match across the CLI and the app.
+     * the same signals the TUI's useAgentLoop collects, so loop-break decisions
+     * match across the CLI and the app.
      */
     private trackHookEvent;
+    /**
+     * Count full-file `cat` output from the step that just finished as reads, so
+     * an edit after `cat` does not cost a second read. Uses the step's results as
+     * stored in the transcript (after per-turn trimming): only bytes the model
+     * actually received count.
+     */
+    private creditBashReads;
     /**
      * Append every message added since the last flush to the session file.
      *
@@ -543,15 +566,6 @@ export declare class AgentSession {
      *  cheaper routing: judging a model's own failure patterns with a weaker
      *  model swaps false negatives for false positives. */
     private callSemanticLoopJudge;
-    /** Independent fresh-context review of the finished work (Codex Guardian
-     *  pattern). Spawns a READ-ONLY child on the ACTIVE model, waits bounded,
-     * and returns findings for the acting agent to address — or nothing when
-     *  the review passes, is unavailable, or fails (in-thread review remains the
-     *  fallback; the feature degrades, never blocks).
-     *
-     *  Runs inside the pre-stop poll, so the candidate final answer is already
-     *  held by arming and this wait cannot race a streamed answer. */
-    private runIndependentReview;
     /**
      * Turn-budget extension gate. The loop consults this instead of stopping
      * mid-task when it exhausts `maxTurns`. Grant ONLY on evidence of progress —
@@ -559,45 +573,31 @@ export declare class AgentSession {
      * with — so reuse the same stuck signals that drive the loop-breaker.
      */
     private shouldExtendTurnBudget;
-    /**
-     * Would the stop AFTER the current turn inject the Ideal review? Same inputs
-     * as the pre-stop gate below, evaluated early so clients know a candidate
-     * final answer is a review draft BEFORE it streams.
-     *
-     * The turn count is looked ahead by one on purpose. `hookStats.turns` only
-     * advances at `turn_end`, so while the model is writing the draft the counter
-     * still reads the PREVIOUS turn; the real gate sees one more. Without the
-     * lookahead a run sitting on score 3 crosses to 4 on the draft's own
-     * `turn_end` — after the text already streamed — which is precisely the
-     * appear-then-vanish flash. Over-arming by one turn point costs only live
-     * token streaming on a final answer that then shows whole; under-arming costs
-     * the flash, so this errs toward arming.
-     */
-    private wouldInjectIdealReview;
-    /** Would a stop right now inject the verification gate? Same conditions as
-     *  the pre-stop branch below, so arming and injection cannot disagree. */
-    private wouldInjectVerification;
+    /** Is the pre-stop verification gate active for this session? Off by the
+     *  `verificationGateEnabled` setting, by `selfCorrectionHooks: false`, and for
+     *  allow-listed sessions that cannot run commands at all. */
+    private verificationGateActive;
+    /** Would a stop right now inject a pre-final follow-up? Queued LSP
+     *  diagnostics (real errors injected below), a mode-owned completion review,
+     *  or the verification gate can, so clients hold the candidate answer only
+     *  then. Same conditions as the pre-stop branch, so arming and injection
+     *  cannot disagree. */
+    private wouldInjectBeforeFinal;
     /** Broadcast pre-final hook arming on change. Both edges matter: armed=false
-     *  after the hook fires is what lets a client stream the REVIEWED final
-     *  answer live again.
-     *
-     *  Callable before `initialize()`: the sidecar sets Nolan's review suppression
-     *  on a freshly constructed session, and every arming predicate below reads
-     *  settings that `initialize()` has not loaded yet. Nothing can be armed
-     *  before the session can run a turn, and the first `tool_result`/`turn_end`
-     *  recomputes both edges — so skipping is the correct answer, not a patch. */
+     *  after the hook fires is what lets a client stream the final answer live
+     *  again. Callable before `initialize()`, when no manager exists yet. */
     private refreshHookArming;
-    private refreshVerificationArmed;
-    private refreshIdealReviewArmed;
     /**
-     * Pre-stop Ideal review phase machine. Once review starts, completion is
-     * blocked until harness-owned post-injection reads cover every changed file.
+     * Pre-stop follow-ups: LSP errors, unread child agents and background
+     * processes, the verification gate (when `verificationGateEnabled`), and a
+     * mode-owned completion review.
      */
     private getHookFollowUpMessages;
-    private reviewLspEvidence;
-    private withReviewLspEvidence;
-    /** Auto-compact if needed, run agent loop with auth retry, and persist messages. */
+    /** Wraps the real run: cancels an in-flight cache prewarm and tracks run
+     *  activity / last real request time for {@link prewarm}. */
     private runLoop;
+    /** Auto-compact if needed, run agent loop with auth retry, and persist messages. */
+    private runLoopInner;
     switchModel(provider: string, model: string): Promise<void>;
     /**
      * Record the switch as its own trailing message at the point it happened,
@@ -624,6 +624,20 @@ export declare class AgentSession {
      * protect it.
      */
     private settlePostTurnCompaction;
+    /**
+     * Advance plan-step bookkeeping over the messages added since the last
+     * observation and, when a plan step was newly completed (`[DONE:n]`), run
+     * the SoL-Pi cost rule. Called between model steps (in-flight) and once
+     * after the run; `scanIndex` and `doneSteps` make each message and each
+     * step count once across both paths. Returns undefined when no step
+     * completed since the last observation.
+     */
+    private observePlanStepProgress;
+    /**
+     * Plan-step bookkeeping after ANY successful compaction (as in the bench:
+     * every compaction leaves a cache-write cost to be repaid by later savings).
+     */
+    private recordPlanStepCompaction;
     /**
      * Post-turn compaction: once the final response has been delivered, compact
      * in the background while the user reads the answer, instead of making the
@@ -632,7 +646,9 @@ export declare class AgentSession {
      * Codex `model_post_turn_compact_threshold_percent` guards: skip when user
      * input is already queued (it would race the next turn), when the run was
      * aborted, or during the failure cooldown — and never let a compaction
-     * error surface in the completed turn.
+     * error surface in the completed turn. Besides the size trigger, a newly
+     * completed approved-plan step may compact when the cache-cost rule in
+     * compaction/plan-step-policy.ts says the shrink pays for itself.
      */
     private maybeCompactPostTurn;
     compact(existingCredentials?: {
@@ -678,13 +694,13 @@ export declare class AgentSession {
         size: number;
         costUsd?: number;
     };
-    getPlanMode(): boolean;
     /**
-     * Suppress only the pre-final Ideal self-review for this live session.
-     * Autopilot uses this while Nolan independently owns verification; loop-break
-     * and post-compaction re-grounding remain active.
+     * Whether the provider's prompt cache has likely lapsed since the last
+     * successful request, and how many tokens the next message would re-read at
+     * full price. Null when the route has no known TTL or the chat is empty.
      */
-    setIdealReviewSuppressed(suppressed: boolean): void;
+    getCacheExpiryStatus(now?: number): CacheExpiryStatus | null;
+    getPlanMode(): boolean;
     /** Queue a user message (optionally with attachments) to be injected mid-run
      *  as steering. Returns the new queue length. No-op semantics are the caller's
      *  concern. */
@@ -716,6 +732,13 @@ export declare class AgentSession {
     listBackgroundProcesses(): BackgroundProcess[];
     /** Stop a background process by id. Returns a human-readable status string. */
     killBackgroundProcess(id: string): Promise<string>;
+    /**
+     * Force-stop every background process tree, synchronously. Background
+     * commands run in their own process group, so the daemon's group kill on
+     * quit never reaches them: this is the only thing that does. Callers on a
+     * shutdown deadline run it before awaiting anything that can hang.
+     */
+    stopBackgroundProcesses(): void;
     /** Replace a host-owned system prompt in place without resetting conversation history. */
     setCustomSystemPrompt(systemPrompt: string, promptCacheKeyPrefix?: string): void;
     /**
@@ -784,6 +807,11 @@ export declare class AgentSession {
      * the standard prompt therefore needs a rebuild. Custom and sub-agent
      * prompts never render packs, so detection is skipped for them.
      */
+    /**
+     * Bring the system prompt to the exact state the next provider request will
+     * send. Shared by real runs and {@link prewarm} so both see one prefix.
+     */
+    private prepareSystemPromptForRequest;
     private refreshActiveLanguages;
     /** Rebuild messages[0] from current plan-mode + approved-plan state. */
     private rebuildSystemPromptInPlace;
@@ -919,6 +947,22 @@ export declare class AgentSession {
     /** Replace the abort signal (e.g. after cancellation). */
     setSignal(signal: AbortSignal): void;
     private bindManagerCancellation;
+    private runLoopDepth;
+    private lastRealRequestAt;
+    private lastPrewarmAt;
+    private prewarmController;
+    /**
+     * Best-effort Anthropic prompt-cache prewarm before the user's next turn
+     * (desktop app calls this on the first keystroke after opening a chat or an
+     * idle pause). Sends the exact request prefix the next real turn will use —
+     * same system/tools/thinking/cache options — with `max_tokens: 1`, so the
+     * first real reply is a cache read instead of a cold write.
+     */
+    prewarm(signal?: AbortSignal): Promise<{
+        ok: boolean;
+        reason: string;
+        usage?: Usage;
+    }>;
     /** True when speedProfile is "optimized" (1-h cache TTL + pre-warm), or the
      *  session was constructed with `forceLongCacheRetention` (Nolan sessions). */
     private isSpeedOptimized;