@kenkaiiii/ggcoder 5.25.0 → 5.26.0

package/dist/core/agent-session.js

@@ -32,13 +32,21 @@ import { detectProjectStack } from "./language-detector.js";
 import { evaluateIdealReview, buildIdealReviewMessage, buildReviewCoverageMessage, withReviewCoverageRequirements, detectTestDrift, ReviewCoverageTracker, } from "./ideal-review.js";
 import { evaluateLoopBreak, buildLoopBreakMessage, CycleDetector, ToolCallProgressTracker, detectTextRepetition, } from "./loop-breaker.js";
 import { buildRegroundingMessage } from "./regrounding.js";
-import { wrapSteeringText, STEERING_PREFIX } from "./steering.js";
+import { wrapSteeringText, buildNotificationSteeringText, STEERING_PREFIX } from "./steering.js";
+import { AgentNotificationQueue } from "./agent-notifications.js";
+import { ProjectJournal, buildJournalPromptTail } from "./memory/journal.js";
+import { buildCompactionNotes } from "./memory/compaction-notes.js";
 import { findUserSessionPrompt, getUserSessionPrompt } from "./session-preview.js";
 import { normalizeMessageImages } from "./message-images.js";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+/**
+ * A run whose tool calls fail more often than this is thrashing, not
+ * progressing — refuse to extend its turn budget.
+ */
+const TURN_EXTENSION_MAX_FAILURE_RATIO = 0.5;
 // ── Tool-result policy ─────────────────────────────────────
 /** Resolve the per-result cap passed to the agent loop for the active transport. */
 export function resolveSessionToolResultCharLimit(model, provider, accountId) {
@@ -57,6 +65,22 @@ export function resolveSessionTurnToolResultCharLimit(model, provider, accountId
     const contextChars = getContextWindow(model, { provider, accountId }) * 3.5;
     return Math.max(100_000, Math.min(Math.floor(contextChars * 0.15), 240_000));
 }
+/** Marker the compactor prepends to the summary message it injects. */
+const COMPACTION_SUMMARY_MARKER = "[Previous conversation summary]";
+/** The compactor's summary text, identified by its marker. */
+function isCompactionSummary(content) {
+    return typeof content === "string" && content.startsWith(COMPACTION_SUMMARY_MARKER);
+}
+/**
+ * True when an assistant message ends a turn with tool calls still awaiting
+ * their results. Inserting a user message there would orphan the tool_use
+ * blocks and the provider rejects the next request.
+ */
+function hasUnresolvedToolCalls(message) {
+    if (typeof message.content === "string" || !Array.isArray(message.content))
+        return false;
+    return message.content.some((part) => part.type === "tool_call");
+}
 // ── Agent Session ──────────────────────────────────────────
 export class AgentSession {
     eventBus = new EventBus();
@@ -132,6 +156,18 @@ export class AgentSession {
     processManager;
     lspManager;
     subAgentManager;
+    /**
+     * Out-of-band push notifications (finished children, background-process
+     * progress). Producers enqueue; `getHookSteeringMessages` drains into the
+     * live turn so the agent never has to spend a turn asking.
+     */
+    notifications = new AgentNotificationQueue();
+    /**
+     * Durable cross-session journal at `<project>/.gg/memory.md`. Written only by
+     * the compactor, and only as past-tense history — see `memory/journal.ts` for
+     * why nothing else may write it. Undefined when `memoryEnabled` is off.
+     */
+    journal;
     managerAbortSignal;
     managerAbortHandler = () => {
         void this.subAgentManager?.interruptAll();
@@ -227,6 +263,12 @@ export class AgentSession {
         await this.settingsManager.load();
         this.authStorage = new AuthStorage(paths.authFile);
         await this.authStorage.load();
+        // Opt-in: it is the only feature here that adds tokens to every turn.
+        // Transient sessions (Ken, sub-agents) never write a project's journal —
+        // their compactions are not the project's history.
+        if (this.settingsManager.get("memoryEnabled") && !this.opts.transient) {
+            this.journal = new ProjectJournal(this.cwd);
+        }
         // Session manager. Agent-specific roots keep chat and coder histories isolated.
         this.sessionManager = new SessionManager(this.opts.sessionRootDir ?? paths.sessionsDir);
         const projectCustomization = this.opts.projectCustomization !== false;
@@ -285,6 +327,7 @@ export class AgentSession {
             getMaxPerModel: () => this.settingsManager.get("subagentMaxPerModel"),
             disableAsyncSubagents: this.opts.subagentWorker,
             onSubAgentState: (snapshot) => this.eventBus.emit("subagent_state", snapshot),
+            notifications: this.notifications,
             // Plan mode: only wired when the host supplies callbacks. The ref is
             // shared so bash/edit/write enforce read-only restrictions live.
             ...(this.opts.onEnterPlan || this.opts.onExitPlan
@@ -324,7 +367,6 @@ export class AgentSession {
             (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment()));
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
-        this.syncUltraOrchestrationPrompt();
         // Load or create session. Transient sessions (subagent spawns) never
         // touch the session store — sessionPath stays empty and persistMessage
         // is a no-op so their transcripts can't pollute `ggcoder continue`.
@@ -728,12 +770,31 @@ export class AgentSession {
         }
     }
     /**
-     * Mid-loop steering hook: fires the loop-breaker when the agent looks stuck,
-     * then post-compaction re-grounding. At most one of each per run. Mirrors the
-     * TUI's getSteeringMessages ordering (minus user steering, which the app
-     * delivers as normal prompts).
+     * Mid-loop steering hook: delivers pushed notifications and queued user
+     * steering, fires the loop-breaker when the agent looks stuck, then
+     * post-compaction re-grounding. At most one loop-break/re-grounding per run.
+     * Mirrors the TUI's getSteeringMessages ordering.
      */
     getHookSteeringMessages() {
+        // Push notifications: a child that finished or a background build that
+        // exited is new *fact*, not a correction, and it is cheap (bounded to 1 KiB
+        // per drain). Drained above the loop-break checks so the agent can act on
+        // it in the very next turn instead of discovering it at the pre-stop
+        // completion gate — but it never displaces user steering, which rides out
+        // in the same batch when both are pending.
+        const notified = this.notifications.drain();
+        const notificationMessage = notified.length > 0
+            ? {
+                role: "user",
+                content: buildNotificationSteeringText(notified.map((entry) => entry.text)),
+            }
+            : null;
+        if (notificationMessage) {
+            log("INFO", "notifications", "Injecting pushed notifications", {
+                count: String(notified.length),
+                chars: String(notificationMessage.content.length),
+            });
+        }
         // User steering wins: drain any messages queued during this run first so the
         // agent sees them mid-loop instead of after it stops.
         if (this.userQueue.length > 0) {
@@ -743,7 +804,7 @@ export class AgentSession {
             // the original task and silently drops it. ONE message per queued item
             // (not merged): each persists as its own user message, so a resumed
             // session shows the same number of bubbles the live run did.
-            return queued.map((m) => {
+            const steeringMessages = queued.map((m) => {
                 if (m.attachments.length === 0) {
                     return { role: "user", content: wrapSteeringText(m.text) };
                 }
@@ -755,7 +816,10 @@ export class AgentSession {
                 ];
                 return { role: "user", content: parts };
             });
+            return notificationMessage ? [...steeringMessages, notificationMessage] : steeringMessages;
         }
+        if (notificationMessage)
+            return [notificationMessage];
         if (this.opts.selfCorrectionHooks === false)
             return null;
         if (!this.settingsManager.get("idealReviewEnabled"))
@@ -797,6 +861,39 @@ export class AgentSession {
         }
         return null;
     }
+    /**
+     * Turn-budget extension gate. The loop consults this instead of stopping
+     * mid-task when it exhausts `maxTurns`. Grant ONLY on evidence of progress —
+     * handing more turns to a spinning agent just buys it more tokens to spin
+     * with — so reuse the same stuck signals that drive the loop-breaker.
+     */
+    shouldExtendTurnBudget(ctx) {
+        const refusals = [];
+        const stuck = evaluateLoopBreak({
+            consecutiveFailures: this.hookConsecutiveFailures,
+            repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
+            textRepetitionDetected: detectTextRepetition(this.hookText),
+            ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
+        });
+        if (stuck.shouldBreak)
+            refusals.push(...stuck.reasons);
+        // Stage 2 means the loop-breaker already detected spinning twice and told
+        // the agent to stop and report. Do not overrule that with more turns.
+        if (this.loopBreakInjected >= 2)
+            refusals.push("loop-breaker already escalated");
+        const { toolCalls, toolFailures } = this.hookStats;
+        if (toolCalls > 0 && toolFailures / toolCalls > TURN_EXTENSION_MAX_FAILURE_RATIO) {
+            refusals.push(`${toolFailures}/${toolCalls} tool calls failed`);
+        }
+        const granted = refusals.length === 0;
+        log("INFO", "turn-budget", granted ? "Extending turn budget" : "Refusing turn-budget extension", {
+            turn: String(ctx.turn),
+            maxTurns: String(ctx.maxTurns),
+            extension: String(ctx.extension),
+            ...(granted ? {} : { reasons: refusals.join(", ") }),
+        });
+        return granted;
+    }
     /**
      * Pre-stop Ideal review phase machine. Once review starts, completion is
      * blocked until harness-owned post-injection reads cover every changed file.
@@ -963,6 +1060,7 @@ export class AgentSession {
                 webSearch: true,
                 maxTokens: this.maxTokens,
                 maxTurns: this.opts.maxTurns,
+                maxTurnExtensions: this.opts.maxTurnExtensions,
                 thinking: this.thinkingLevel,
                 apiKey,
                 baseUrl: effectiveBaseUrl,
@@ -991,6 +1089,7 @@ export class AgentSession {
                 // polled mid-loop; the ideal review is polled when the agent would stop.
                 getSteeringMessages: () => this.getHookSteeringMessages(),
                 getFollowUpMessages: () => this.getHookFollowUpMessages(),
+                onTurnBudgetExhausted: (ctx) => this.shouldExtendTurnBudget(ctx),
                 // Check authoritative provider usage before every model/tool step.
                 // Forced overflow recovery bypasses settings and cooldown; proactive
                 // checks honor both and estimate only messages unseen by the provider.
@@ -1168,6 +1267,11 @@ export class AgentSession {
     }
     async switchModel(provider, model) {
         const prevProvider = this.provider;
+        const prevModel = this.model;
+        // Diff gate: a "switch" to the model already in use is not state change.
+        // Recording it anyway would write a redundant marker and a redundant
+        // history note on every no-op re-selection from the UI.
+        const changed = model !== prevModel || (Boolean(provider) && provider !== prevProvider);
         if (provider)
             this.provider = provider;
         this.model = model;
@@ -1176,7 +1280,6 @@ export class AgentSession {
         // the live selection after an in-session model switch.
         this.opts.provider = this.provider;
         this.opts.model = this.model;
-        this.syncUltraOrchestrationPrompt();
         setEstimatorModel(model);
         // maxTokens must follow the active model — it was frozen at the boot
         // model's `maxOutputTokens` in the constructor, so without this a session
@@ -1197,6 +1300,27 @@ export class AgentSession {
             const newReadTool = this.rebuildReadTool(model);
             this.tools = this.tools.map((t) => (t.name === "read" ? newReadTool : t));
         }
+        // Model-dependent guidance lives in the uncached tail, so this rewrites
+        // only the bytes after the cache marker — the cached prefix survives the
+        // switch intact and the next turn still reads from cache.
+        this.refreshSystemPromptTail();
+        if (changed) {
+            // Durable, replayable record of which model produced which segment. Rides
+            // the existing app-marker path (parentId null, anchored by message count)
+            // so a resumed session reconstructs the switch without the LLM seeing an
+            // extra transcript row.
+            await this.persistAppMarker("model_switch", {
+                from: prevModel,
+                to: this.model,
+                provider: this.provider,
+                fromProvider: prevProvider,
+            }).catch((error) => {
+                log("WARN", "session", "Failed to persist model-switch marker", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+            this.appendModelSwitchNote(prevModel, prevProvider);
+        }
         // Update provider-specific tools when provider changes
         if (provider && provider !== prevProvider) {
             // Add/remove client-side web_search tool based on provider.
@@ -1251,6 +1375,30 @@ export class AgentSession {
             }
         }
     }
+    /**
+     * Record the switch as its own trailing message at the point it happened,
+     * rather than by rewriting the system prompt. Two reasons: the system prompt
+     * is the cached prefix and rewriting it costs a full cache write, and a
+     * resumed transcript can only attribute output to the right model if the
+     * switch sits in message order.
+     *
+     * Skipped before the conversation starts (nothing to disambiguate) and while
+     * an assistant turn has unresolved tool calls, where inserting a user message
+     * would break tool_use/tool_result pairing.
+     */
+    appendModelSwitchNote(prevModel, prevProvider) {
+        const last = this.messages[this.messages.length - 1];
+        if (!last || last.role === "system")
+            return;
+        if (last.role === "assistant" && hasUnresolvedToolCalls(last))
+            return;
+        const from = prevProvider === this.provider ? prevModel : `${prevProvider}/${prevModel}`;
+        const to = prevProvider === this.provider ? this.model : `${this.provider}/${this.model}`;
+        this.messages.push({
+            role: "user",
+            content: `[Model switched from ${from} to ${to}. Everything above was produced under the previous model; continue the current task from here.]`,
+        });
+    }
     async compact(existingCredentials) {
         this.lastCompactionCompacted = false;
         const creds = existingCredentials ??
@@ -1262,6 +1410,7 @@ export class AgentSession {
             accountId: creds.accountId,
         });
         this.eventBus.emit("compaction_start", { messageCount: this.messages.length });
+        const messagesBefore = [...this.messages];
         const result = await compact(this.messages, {
             provider: this.provider,
             model: this.model,
@@ -1272,6 +1421,10 @@ export class AgentSession {
             contextWindow,
             signal: this.opts.signal,
         });
+        // Messages the summary is about to replace, identified by reference:
+        // compaction keeps the retained tail as the same objects it was handed.
+        const retained = new Set(result.messages);
+        const droppedMessages = messagesBefore.filter((message) => !retained.has(message));
         this.messages = result.messages;
         this.lastCompactionCompacted = result.result.compacted;
         if (!result.result.compacted) {
@@ -1283,6 +1436,7 @@ export class AgentSession {
             return;
         }
         this.providerContext = null;
+        await this.writeCompactionJournal(droppedMessages);
         // Transient sessions (Ken chat/autopilot, subagent spawns) must NEVER touch
         // the session store: without this guard, the first auto-compaction called
         // sessionManager.create() and assigned a real sessionPath, silently turning
@@ -1350,7 +1504,6 @@ export class AgentSession {
             (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment()));
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
-        this.syncUltraOrchestrationPrompt();
         // Fresh conversation — new entries must not chain onto the old DAG's leaf.
         this.currentLeafId = null;
         // Transient sessions (Ken chat/autopilot, subagent spawns) never touch the
@@ -1498,7 +1651,6 @@ export class AgentSession {
         else {
             this.messages.unshift({ role: "system", content });
         }
-        this.syncUltraOrchestrationPrompt();
     }
     /**
      * Toggle plan mode: flips the shared ref (so tools enforce read-only
@@ -1593,18 +1745,56 @@ export class AgentSession {
         else {
             this.messages.unshift({ role: "system", content });
         }
-        this.syncUltraOrchestrationPrompt();
     }
+    /**
+     * Compose the system message: stable prefix, then everything volatile behind
+     * the `<!-- uncached -->` marker that providers split on for cache control.
+     *
+     * Anything that varies with the live model/provider/thinking level belongs in
+     * the tail. Putting it in the prefix means every model switch rewrites cached
+     * bytes and the next turn pays a full cache write instead of a read.
+     */
     withSystemPromptTail(basePrompt) {
-        if (!this.opts.getSystemPromptTail)
+        const tailParts = [];
+        const orchestration = this.orchestrationPolicyTail();
+        if (orchestration)
+            tailParts.push(orchestration);
+        // Journal is re-read on every refresh, so an entry written this turn (or a
+        // human edit to .gg/memory.md) is visible on the next one. Uncached by
+        // construction: it changes as work proceeds and must never sit in the
+        // cached prefix.
+        if (this.journal) {
+            const journalTail = buildJournalPromptTail(this.journal);
+            if (journalTail)
+                tailParts.push(journalTail);
+        }
+        const hostTail = this.opts.getSystemPromptTail?.();
+        if (hostTail)
+            tailParts.push(hostTail);
+        if (tailParts.length === 0)
             return basePrompt;
-        return `${basePrompt}\n\n<!-- uncached -->\n${this.opts.getSystemPromptTail()}`;
+        return `${basePrompt}\n\n<!-- uncached -->\n${tailParts.join("\n\n")}`;
+    }
+    /**
+     * Sol/Terra async-orchestration guidance for the CURRENT model and thinking
+     * level. Per-switch volatile by definition, so it is rendered as a tail part
+     * rather than spliced into the cached prefix.
+     */
+    orchestrationPolicyTail() {
+        if (this.opts.orchestrationPrompt === false)
+            return "";
+        return applyAsyncSubagentPolicy("", this.provider, this.model, this.thinkingLevel, this.tools.map((tool) => tool.name)).trim();
     }
+    /**
+     * Re-render the uncached tail of messages[0] in place. The cached prefix is
+     * byte-identical afterwards, so this is safe to call on every model /
+     * thinking-level change.
+     */
     refreshSystemPromptTail() {
-        if (!this.opts.getSystemPromptTail)
-            return;
         const content = this.withSystemPromptTail(this.baseSystemPrompt);
         if (this.messages[0]?.role === "system") {
+            if (this.messages[0].content === content)
+                return;
             this.messages[0] = { role: "system", content };
         }
         else {
@@ -1783,6 +1973,34 @@ export class AgentSession {
         };
         await this.sessionManager.appendEntry(this.sessionPath, entry);
     }
+    /**
+     * Record what this compaction is about to discard as past-tense journal
+     * entries. Compaction is one-way — without this the specifics are gone for
+     * good, which is precisely the hole the journal exists to fill. No-op when
+     * memory is off, and bounded to a few entries so the file stays readable.
+     */
+    async writeCompactionJournal(dropped) {
+        if (!this.journal || dropped.length === 0)
+            return;
+        const summary = this.messages.map((message) => message.content).find(isCompactionSummary) ?? "";
+        const notes = buildCompactionNotes(dropped, summary);
+        if (notes.length === 0)
+            return;
+        try {
+            const written = await this.journal.append(notes);
+            if (written > 0) {
+                log("INFO", "memory", "Recorded compaction history", {
+                    entries: String(written),
+                    file: this.journal.filePath,
+                });
+            }
+        }
+        catch (error) {
+            log("WARN", "memory", "Failed to write journal entries", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     /** Re-append the in-memory app markers to the current session file. Mirrors
      *  `rePersistKenTurns` — called after a continuation/compaction file is
      *  created so display-only rows survive the rewrite. */
@@ -1842,16 +2060,7 @@ export class AgentSession {
      * effect on the next prompt, since the in-flight loop reads it at start. */
     setThinkingLevel(level) {
         this.thinkingLevel = level;
-        this.syncUltraOrchestrationPrompt();
-    }
-    /** Sol/Terra Ultra delegates proactively; lower levels require an explicit request. */
-    syncUltraOrchestrationPrompt() {
-        if (this.opts.orchestrationPrompt === false)
-            return;
-        const systemMessage = this.messages[0];
-        if (systemMessage?.role !== "system" || typeof systemMessage.content !== "string")
-            return;
-        systemMessage.content = applyAsyncSubagentPolicy(systemMessage.content, this.provider, this.model, this.thinkingLevel, this.tools.map((tool) => tool.name));
+        this.refreshSystemPromptTail();
     }
     /** Replace the abort signal (e.g. after cancellation). */
     setSignal(signal) {