aiden-runtime 4.1.4 → 4.5.0

package/dist/core/v4/aidenAgent.js

@@ -42,6 +42,32 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AidenAgent = void 0;
+// v4.1.6 spike — Task Completion Engine (TCE) per-turn loop detector
+// + recovery controller. Default ON as of v4.2 Phase 6 — set
+// AIDEN_TCE=0 to disable. Zero
+// behavioral change when unset. See core/v4/turnState.ts.
+const turnState_1 = require("./turnState");
+// v4.2 Phase 1 — per-tool result verifier. Same TCE gate as
+// TurnState (default ON, opt-out via AIDEN_TCE=0); classification
+// feeds the recovery controller.
+const verifier_1 = require("./verifier");
+// v4.2 Phase 2 — tool-failure WHY-classifier. Runs after the verifier
+// when verification.ok === false. Records-only; Phase 3 will act.
+const failureClassifier_1 = require("./failureClassifier");
+// v4.2 Phase 3 — structured RecoveryReport. Built ONLY when the
+// recovery controller's surface stage fires (tool_loop); enriches the
+// existing surface card with summary + category breakdown + dominant
+// guidance. Implicitly gated by TCE being enabled (surface only
+// reachable when TurnState is enabled — default ON as of Phase 6).
+const recoveryReport_1 = require("./recoveryReport");
+// v4.2 Phase 4 — checkpoint / restore. Lets the recovery controller
+// roll conversation messages + TurnState internals back to before a
+// looping tool started failing, so the model retries from a clean
+// baseline. Hard-blocked on iterations containing mutating tools
+// (never claim to undo executed side effects). All-no-op when
+// TCE is opted out via AIDEN_TCE=0 — capture / mark / find /
+// restore all short-circuit.
+const checkpoint_1 = require("./checkpoint");
 const skillEnforcement_1 = require("./agent/skillEnforcement");
 const urlProvenance_1 = require("./agent/urlProvenance");
 const intentPreArm_1 = require("./agent/intentPreArm");
@@ -92,6 +118,7 @@ class AidenAgent {
         this.onSkillCandidate = opts.onSkillCandidate;
         this.resolveVerifiedFlag = opts.resolveVerifiedFlag;
         this.resolveToolset = opts.resolveToolset;
+        this.resolveMutates = opts.resolveMutates;
         this.promptBuilder = opts.promptBuilder;
         this.promptBuilderOptions = opts.promptBuilderOptions;
         this.contextCompressor = opts.contextCompressor;
@@ -103,7 +130,20 @@ class AidenAgent {
         this.onCompression = opts.onCompression;
         this.refreshMemorySnapshot = opts.refreshMemorySnapshot;
         this.onMemoryRefresh = opts.onMemoryRefresh;
+        // v4.1.5 Issue K — phase hooks (all optional, fire defensively).
+        this.onMemoryRefreshStart = opts.onMemoryRefreshStart;
+        this.onPromptBuilt = opts.onPromptBuilt;
+        this.onProviderRequestStart = opts.onProviderRequestStart;
         this.lookupSkillRequiredTools = opts.lookupSkillRequiredTools;
+        // v4.5 Phase 7 — explicit sessionId. Existing access path
+        // `(this as { sessionId?: string }).sessionId` at line 751–752
+        // already reads from `this.sessionId`; setting it here keys
+        // docker / browser / TurnState per session for daemon-mode
+        // turns. Interactive REPL callers don't pass this and continue
+        // hitting the 'session' fallback.
+        if (typeof opts.sessionId === 'string' && opts.sessionId.length > 0) {
+            this.sessionId = opts.sessionId;
+        }
         // Phase v4.1.2-slice3: optional health registry (constructor-
         // injected per the slice3 decision tree — no singleton). When
         // wired, the caller already plumbed trackers into each subsystem
@@ -300,7 +340,21 @@ class AidenAgent {
             }
         }
         // 10. SkillTeacher post-loop observation + proposal.
+        //
+        // v4.1.6 Polish 2 — `handleProposal` previously ran INLINE here,
+        // awaiting `callbacks.promptUser` (an inquirer modal) before
+        // `runConversation` returned. That made the modal fire BEFORE
+        // chatSession rendered the agent's reply on screen, so users
+        // saw "Save this as a reusable skill?" pop up mid-turn — feels
+        // like an interruption.
+        //
+        // New flow: agent ONLY observes here. When a proposal needs user
+        // confirmation (tier_3_propose with a promptUser callback), the
+        // proposal is surfaced in `AidenAgentResult.skillProposal` and
+        // chatSession handles the prompt + create dance AFTER rendering
+        // the reply. Tier_4_auto still runs inline (no prompt needed).
         let skillCreated;
+        let skillProposal;
         if (this.skillTeacher) {
             try {
                 const traceForTeacher = loopResult.toolCallTrace.map((entry, i) => ({
@@ -312,9 +366,20 @@ class AidenAgent {
                 }));
                 const proposal = await this.skillTeacher.observeTurn(history, traceForTeacher, loopResult.finishReason !== 'stop');
                 if (proposal) {
-                    const result = await this.skillTeacher.handleProposal(proposal, this.skillTeacherCallbacks);
-                    if (result.created && result.skillName) {
-                        skillCreated = result.skillName;
+                    // Defer to chatSession only when there's a prompt callback
+                    // wired (tier_3_propose path). Otherwise run inline to
+                    // preserve tier_4_auto and tier_off behaviour.
+                    const hasPromptCallback = typeof this.skillTeacherCallbacks?.promptUser === 'function';
+                    if (hasPromptCallback) {
+                        // Surface the proposal back to chatSession; do NOT call
+                        // handleProposal here.
+                        skillProposal = proposal;
+                    }
+                    else {
+                        const result = await this.skillTeacher.handleProposal(proposal, this.skillTeacherCallbacks);
+                        if (result.created && result.skillName) {
+                            skillCreated = result.skillName;
+                        }
                     }
                 }
             }
@@ -365,11 +430,20 @@ class AidenAgent {
             toolCallTrace: loopResult.toolCallTrace,
             honestyFindings,
             skillCreated,
+            // v4.1.6 Polish 2 — deferred to chatSession's post-render
+            // handler when the SkillTeacher proposal needs user
+            // confirmation. Undefined when no proposal, when tier auto-
+            // handled inline, or when the teacher's observation faulted.
+            skillProposal,
             compressionEvents: this.compressionEvents,
             auxiliaryUsage: this.auxiliaryClient?.getUsage() ?? {},
             skillEnforcement: { ...this.skillEnforcementMetrics },
             urlProvenance: { ...this.urlProvenanceMetrics },
             emptyResponse: { ...this.emptyResponseMetrics },
+            // v4.1.6 spike (TCE) — surfaced when TurnState hit the surface
+            // threshold mid-turn. chatSession reads this to render the
+            // structured-failure card; undefined on all other finishReasons.
+            toolLoopCard: loopResult.toolLoopCard,
         };
     }
     // ── Private helpers ──────────────────────────────────────────────────
@@ -386,6 +460,14 @@ class AidenAgent {
         // / 'user' need a snapshot refresh first.
         const needsSnapshot = this.memoryDirty.has('memory') || this.memoryDirty.has('user');
         if (needsSnapshot && this.refreshMemorySnapshot) {
+            // v4.1.5 Issue K — fire BEFORE the file I/O so the display layer
+            // can switch the activity verb to "refreshing memory" while the
+            // read is in flight. Defensive try/catch so a misbehaving hook
+            // never blocks the refresh.
+            try {
+                this.onMemoryRefreshStart?.();
+            }
+            catch { /* defensive */ }
             let snapshot;
             try {
                 snapshot = await this.refreshMemorySnapshot();
@@ -410,6 +492,21 @@ class AidenAgent {
         if (this.cachedSystemPrompt !== null)
             return this.cachedSystemPrompt;
         this.cachedSystemPrompt = await this.promptBuilder.build(this.promptBuilderOptions);
+        // v4.1.5 Issue K — fire AFTER the prompt has been assembled, with
+        // cardinality so the display layer can surface "preparing prompt:
+        // N tools, M skills" or similar. Only fires when the cache MISSED
+        // (which is what made us actually build); cached returns skip the
+        // hook because nothing was prepared this turn. Defensive try/catch.
+        if (this.onPromptBuilt) {
+            try {
+                this.onPromptBuilt({
+                    tools: this.tools.length,
+                    skills: this.promptBuilderOptions.skillsList?.length ?? 0,
+                    memoryFacts: countMemoryFacts(this.promptBuilderOptions.memorySnapshot),
+                });
+            }
+            catch { /* defensive */ }
+        }
         return this.cachedSystemPrompt;
     }
     async narrowTools(userMsg, history) {
@@ -438,6 +535,10 @@ class AidenAgent {
         // off the same entry index.
         const fullTrace = [];
         const totalUsage = { inputTokens: 0, outputTokens: 0 };
+        // v4.2 Phase 3 — turn start timestamp for RecoveryReport duration.
+        // Captured here so any code path (early-return / error / surface)
+        // can compute wallclock duration consistently.
+        const turnStartedAt = Date.now();
         let turnCount = 0;
         let toolCallCount = 0;
         let fallbackActivated = false;
@@ -446,7 +547,27 @@ class AidenAgent {
         let emptyRetriesUsed = 0;
         let finishReason = 'stop';
         let finalContent = '';
+        // v4.1.6 spike (TCE) — per-turn loop detection + recovery state.
+        // Default ON as of v4.2 Phase 6 — set AIDEN_TCE=0 to disable.
+        // When disabled, TurnState.recordToolCall short-circuits with
+        // `{kind: 'allow'}` and the entire v4.2 recovery surface stays
+        // dormant (zero behavioural change vs v4.1.6).
+        const turnState = new turnState_1.TurnState();
+        // v4.2 Phase 1 — per-tool verifier registry. Constructed
+        // unconditionally (cheap, no side effects) but only used to
+        // classify tool outcomes when TCE is enabled; verification args
+        // are passed to TurnState only inside the gated branch below.
+        const verifierRegistry = (0, verifier_1.buildDefaultRegistry)();
+        // v4.2 Phase 2 — per-tool failure classifier. Same gating as
+        // the verifier; only runs when verification.ok === false. Phase 2
+        // records-only — Phase 3 wires recovery actions off the category.
+        const failureClassifier = (0, failureClassifier_1.buildDefaultClassifier)();
+        let toolLoopCard = undefined;
         while (true) {
+            // v4.1.6 spike — decrement cooldown counters once per iteration
+            // so cooled-down tools eventually return to the schemas. No-op
+            // when TCE is disabled.
+            turnState.advanceIteration();
             if (turnCount >= this.maxTurns) {
                 finishReason = 'budget_exhausted';
                 break;
@@ -464,9 +585,22 @@ class AidenAgent {
                 this.onBudgetWarning?.('warning', turnCount, this.maxTurns);
             }
             // ── Provider call (stream or non-stream) ──────────────────────────
+            //
+            // v4.1.6 spike (TCE) — filter cooled-down tools out of the
+            // schemas we send to the provider. The model literally cannot
+            // see (and therefore cannot request) a cooled-down tool until
+            // its cooldown counter decrements to zero via
+            // `turnState.advanceIteration()`. No-op when TCE disabled
+            // (`getCooledDownTools()` returns []).
+            let effectiveTools = tools;
+            const cooledDown = turnState.getCooledDownTools();
+            if (cooledDown.length > 0) {
+                const cdSet = new Set(cooledDown);
+                effectiveTools = tools.filter((t) => !cdSet.has(t.name));
+            }
             let output;
             try {
-                output = await this.callProvider(messages, tools, runOptions);
+                output = await this.callProvider(messages, effectiveTools, runOptions);
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -484,6 +618,25 @@ class AidenAgent {
             }
             totalUsage.inputTokens += output.usage?.inputTokens ?? 0;
             totalUsage.outputTokens += output.usage?.outputTokens ?? 0;
+            // v4.2 Phase 4 — capture the state going INTO this iteration's
+            // tool dispatch. MUST run BEFORE `messages.push(assistantMsg)`
+            // so the checkpoint represents "the conversation before the
+            // model decided to call this iteration's tools". If rollback
+            // fires later, truncating `messages.length` to
+            // `checkpoint.messages.length` drops the assistant tool_call
+            // message together with its tool result messages — preserving
+            // tool_call/tool_result pairing in the rolled-back state.
+            //
+            // Capturing AFTER the assistant push (the prior placement) was
+            // a real bug: rollback would leave the assistant tool_call in
+            // history without its tool results, producing strict-provider
+            // 400 errors of the form "No tool output found for function
+            // call <id>". Tests in tests/v4/core/checkpoint-integration
+            // assert the post-rollback messages array contains zero orphan
+            // assistant tool_calls — this position is part of the contract.
+            //
+            // No-op when TCE is disabled (AIDEN_TCE=0) or checkpointDepth=0.
+            turnState.captureCheckpoint(messages, turnCount);
             // ── Append assistant message ──────────────────────────────────────
             const assistantMsg = output.toolCalls.length > 0
                 ? { role: 'assistant', content: output.content ?? '', toolCalls: output.toolCalls }
@@ -558,8 +711,30 @@ class AidenAgent {
             }
             // ── Dispatch tools sequentially ──────────────────────────────────
             const turnToolMessages = [];
+            // v4.1.6 spike (TCE) — set when TurnState surfaces a tool_loop
+            // mid-batch. The agent stops dispatching remaining calls in the
+            // batch and breaks out of the outer iteration loop cleanly.
+            let surfaceDecision = null;
+            // v4.2 Phase 4 — set when TurnState's recovery controller asks
+            // for a rollback. The agent loop truncates messages + restores
+            // TurnState internals + pushes a corrective system message,
+            // then continues the outer iteration loop from a clean baseline.
+            let rollbackDecision = null;
             for (const call of output.toolCalls) {
                 this.onToolCall?.(call, 'before');
+                // v4.2 Phase 4 — mark any active checkpoints as containing a
+                // mutating call BEFORE dispatch. Done pre-dispatch (not post)
+                // so that even if the tool throws / errors / produces a
+                // partial side effect, the mutation flag is set — rollback
+                // safety errs on the side of "this iteration mutated state".
+                // The mutability resolver is wired from the CLI's tool
+                // registry (`resolveMutates`); unknown tools return undefined,
+                // which we treat as non-mutating (leave the flag alone).
+                // Plugin authors should declare `mutates` honestly on their
+                // tool handlers — this is the structural enforcement point.
+                if (turnState.isEnabled() && this.resolveMutates?.(call.name) === true) {
+                    turnState.markMutationOnLiveCheckpoint(call.name);
+                }
                 let result;
                 try {
                     result = await this.toolExecutor(call);
@@ -573,11 +748,46 @@ class AidenAgent {
                     };
                 }
                 toolCallCount += 1;
+                // v4.2 Phase 1 — verifier classification. Runs only when TCE
+                // is enabled; the registry resolves a per-tool verifier or
+                // falls back to the heuristic default. Synchronous + pure;
+                // no network, no side effects.
+                let verification;
+                let classification = null;
+                if (turnState.isEnabled()) {
+                    try {
+                        verification = verifierRegistry.resolve(call.name)(call.name, call.arguments, result);
+                    }
+                    catch {
+                        // Defensive — a buggy verifier never breaks the agent loop.
+                        verification = undefined;
+                    }
+                    // v4.2 Phase 2 — classify WHY when the verifier said !ok.
+                    // classify(...) returns null for ok results, so happy-path
+                    // calls incur zero classifier work.
+                    if (verification && !verification.ok) {
+                        try {
+                            classification = failureClassifier.classify(verification, call.name, call.arguments, result);
+                        }
+                        catch {
+                            // Defensive — a buggy classifier never breaks the loop.
+                            classification = null;
+                        }
+                    }
+                }
                 toolCallTrace.push({
                     name: call.name,
                     result: result.result,
                     error: result.error,
                     verified: this.resolveVerifiedFlag?.(result),
+                    // v4.2 Phase 1 — verification surfaces alongside the trace
+                    // entry for downstream callers (chatSession, loopTrace,
+                    // future RecoveryReport). Undefined when TCE is off.
+                    verification,
+                    // v4.2 Phase 2 — classification surfaces alongside verification.
+                    // Undefined for verifier-ok calls (classifier skips them) and
+                    // when TCE is off.
+                    classification: classification ?? undefined,
                 });
                 fullTrace.push({ name: call.name, args: call.arguments });
                 // URL ledger ingest — extracts ids from result body for next turn.
@@ -596,6 +806,126 @@ class AidenAgent {
                         ? `[error] ${result.error}`
                         : stringifyToolResult(result.result),
                 });
+                // v4.1.6 spike (TCE) — after the tool result lands in the
+                // message history, consult the recovery controller. Returns
+                // `allow` immediately when TCE disabled (zero overhead).
+                // v4.2 Phase 1 — pass the verifier outcome so TurnState's
+                // consecFailed counter can fast-fail on demonstrably failing
+                // tool calls before the slower signature/name counters fire.
+                // v4.2 Phase 2 — also pass the classification so TurnState
+                // records the WHY for Phase 3's RecoveryReport.
+                const recovery = turnState.recordToolCall(call.name, call.arguments, verification, classification);
+                if (recovery.kind === 'hint' && recovery.hintMessage) {
+                    // Stage 1: append a corrective system message so the model
+                    // sees it on the next provider call. Same pattern as the
+                    // existing skill-enforcement + URL-provenance correctives.
+                    turnToolMessages.push({
+                        role: 'system',
+                        content: recovery.hintMessage,
+                    });
+                }
+                else if (recovery.kind === 'cooldown_with_rollback' && recovery.rollback) {
+                    // v4.2 Phase 4 — controller asks us to roll back. Capture
+                    // the decision; we apply it AFTER the inner dispatch loop
+                    // exits so we don't leave partial turnToolMessages in a
+                    // half-state. Break out of dispatch immediately — no point
+                    // running more tools whose results we're about to drop.
+                    rollbackDecision = recovery;
+                    break;
+                }
+                else if (recovery.kind === 'cooldown' && recovery.cooldownMessage) {
+                    // Stage 2: cooldown has already been recorded internally
+                    // (next iteration's schema-filter step excludes this tool).
+                    // Inject a system message announcing the cooldown so the
+                    // model knows why the tool just disappeared from its menu.
+                    turnToolMessages.push({
+                        role: 'system',
+                        content: recovery.cooldownMessage,
+                    });
+                }
+                else if (recovery.kind === 'surface' && recovery.surfaceCard) {
+                    // Stage 3: structured failure. Stop dispatching the rest of
+                    // the batch — anything else is throwing good budget after
+                    // bad. The outer loop reads `surfaceDecision` below and
+                    // exits cleanly.
+                    surfaceDecision = recovery;
+                    break;
+                }
+            }
+            // v4.2 Phase 4 — apply rollback if the controller asked for it.
+            // Truncate messages to the captured snapshot length, restore
+            // TurnState internals, then push a corrective system message
+            // and continue the OUTER iteration loop. We deliberately drop
+            // any partial `turnToolMessages` collected before the rollback
+            // trigger — those are the noise we're trying to undo.
+            //
+            // Hard-block invariant: TurnState only emits
+            // `cooldown_with_rollback` when the target checkpoint has
+            // `containedMutations === false`, so we never get here for an
+            // iteration that ran a mutating tool. The optional
+            // `rollback.blockedBy` is empty in Phase 4 (kept on the type
+            // for a Phase 5+ soft-rollback variant).
+            if (rollbackDecision && rollbackDecision.rollback) {
+                const { checkpoint, blockedBy } = rollbackDecision.rollback;
+                // Truncate messages array to the captured length. The captured
+                // items are immutable Message references; we keep them as-is
+                // and just shorten the live array.
+                messages.length = checkpoint.messages.length;
+                // Restore TurnState mutable internals (stage / streaks /
+                // cooledDownTools / arrays). The cooled-down tools map is
+                // preserved as it was at checkpoint time — but the controller
+                // already added the looping tool to `cooledDownTools` before
+                // emitting the decision, so we need to RE-apply that cooldown
+                // after restore to honour the cooldown intent.
+                turnState.restoreInternalsFrom(checkpoint);
+                // Re-cool the tool that triggered the rollback so the next
+                // provider call sees the constrained schema.
+                if (rollbackDecision.toolName) {
+                    turnState.reapplyCooldown(rollbackDecision.toolName);
+                }
+                // Inject corrective system message so the model sees what
+                // happened and why the tool just disappeared from its menu.
+                messages.push({
+                    role: 'system',
+                    content: (0, checkpoint_1.buildRollbackMessage)({
+                        iteration: checkpoint.iteration,
+                        toolName: rollbackDecision.toolName,
+                        blockedBy,
+                    }),
+                });
+                // Continue the outer iteration loop from the restored
+                // baseline. The next provider call gets the filtered tool
+                // schema (cooldown applied) and the corrective message.
+                continue;
+            }
+            // v4.1.6 spike (TCE) — terminal surface handling.
+            if (surfaceDecision && surfaceDecision.kind === 'surface') {
+                finishReason = 'tool_loop';
+                // v4.2 Phase 3 — enrich the base surface card with a
+                // structured RecoveryReport. Pure synthesis from TurnState's
+                // diagnostic snapshot + first-user-message goal + duration.
+                // Implicit gating: this branch is only reachable when
+                // TurnState is enabled, so AIDEN_TCE=0 (opt-out) never
+                // builds a report.
+                if (surfaceDecision.surfaceCard) {
+                    const report = (0, recoveryReport_1.buildRecoveryReport)({
+                        snapshot: turnState.getDiagnosticSnapshot(),
+                        goal: (0, recoveryReport_1.extractGoal)(messages),
+                        exitReason: 'tool_loop',
+                        durationMs: Date.now() - turnStartedAt,
+                    });
+                    toolLoopCard = (0, recoveryReport_1.enrichCardWithReport)(surfaceDecision.surfaceCard, report);
+                }
+                else {
+                    toolLoopCard = surfaceDecision.surfaceCard;
+                }
+                // Push the partial tool messages we collected so honesty +
+                // history downstream see the full sequence including the
+                // loop-trigger call. No final assistant message — the
+                // tool_loop card IS the user-facing surface.
+                messages.push(...turnToolMessages);
+                finalContent = '';
+                break;
             }
             // ── Iteration-budget injection on the LAST tool message ──────────
             if (this.iterationBudgetInjection && turnToolMessages.length > 0) {
@@ -618,6 +948,7 @@ class AidenAgent {
             totalUsage,
             toolCallTrace,
             fullTrace,
+            toolLoopCard,
         };
     }
     /**
@@ -629,6 +960,18 @@ class AidenAgent {
      */
     async callProvider(messages, tools, runOptions) {
         const wantStream = runOptions.stream === true && typeof this.provider.callStream === 'function';
+        // v4.1.5 Issue K — fire just before the HTTP request opens, so the
+        // display layer can transition the activity verb from local-prep
+        // ("preparing prompt", "selecting tools") to a network verb
+        // ("calling provider"). The wait for TTFT (time-to-first-token) is
+        // the longest gap in most turns and is what the wave bar covers.
+        // Fires for both streaming and non-streaming paths — caller may use
+        // it to add a one-shot indicator on non-streaming providers too.
+        // Defensive try/catch (a misbehaving hook must not block dispatch).
+        try {
+            this.onProviderRequestStart?.(this.providerId);
+        }
+        catch { /* defensive */ }
         if (!wantStream) {
             return this.provider.call({ messages, tools });
         }
@@ -671,6 +1014,30 @@ class AidenAgent {
 }
 exports.AidenAgent = AidenAgent;
 // ── Free helpers ────────────────────────────────────────────────────────
+/**
+ * v4.1.5 Issue K — best-effort count of "memory facts" from a
+ * MemorySnapshot. Counts markdown bullet-list lines (`- `) in both
+ * MEMORY.md and USER.md. This is a fuzzy proxy — the agent stores
+ * facts as bullets by convention but free-form prose can also carry
+ * fact-like content. Surfaced verbatim to the display layer; treat as
+ * "approximately N items in the persistent memory file" rather than
+ * a precise inventory.
+ */
+function countMemoryFacts(snapshot) {
+    if (!snapshot || typeof snapshot !== 'object')
+        return 0;
+    const s = snapshot;
+    let count = 0;
+    for (const md of [s.memoryMd, s.userMd]) {
+        if (typeof md !== 'string' || md.length === 0)
+            continue;
+        for (const line of md.split('\n')) {
+            if (line.trim().startsWith('- '))
+                count += 1;
+        }
+    }
+    return count;
+}
 function lastUserMessageContent(history) {
     for (let i = history.length - 1; i >= 0; i--) {
         const m = history[i];