@ikarmic/forge-core 5.3.0 → 5.4.0

package/dist/agent/agent.js

@@ -2,13 +2,19 @@ import { existsSync } from 'node:fs';
 import { release } from 'node:os';
 import path from 'node:path';
 import { streamText } from 'ai';
+import { formatFile, formatMessage } from '../format/auto-format.js';
+import { BackgroundProcesses } from '../tools/background-process.js';
+import { networkDenial } from '../tools/network-policy.js';
+import { runnerShell } from '../tools/shell.js';
+import { cancelWakeupTool, scheduleWakeupTool } from '../wakeup/wakeup-tools.js';
 import { lintFile, lintMessage } from '../lint/auto-lint.js';
 import { buildMemoryBlock } from '../memory/memory-store.js';
 import { filesTouchedBy } from '../tools/write-tools.js';
 import { buildExtraInstructionsBlock } from '../steering/extra-instructions.js';
 import { buildProjectInstructionsBlock } from '../steering/project-instructions.js';
 import { buildRepoMap, repoMapBlock } from '../repomap/repo-map.js';
-import { buildLlmSummarizer, compactMessages, effectiveLimitTokens, getModelWindowTokens, shouldCompactForBudget } from '../context/compaction.js';
+import { adaptHistoryForModel, normalizeForModel } from './history-adapt.js';
+import { buildLlmSummarizer, compactMessages, effectiveLimitTokens, estimateMessageTokens, getModelWindowTokens, shouldCompactForBudget } from '../context/compaction.js';
 import { createStepMasker } from '../context/mask.js';
 import { lookupPricing, computeCostUsd } from '../pricing.js';
 import { BrowserSession } from '../browser/session.js';
@@ -19,6 +25,7 @@ import { createCodebaseSearchTool } from '../tools/codebase-search.js';
 import { createGitHubTools, githubFromEnv } from '../github/github-tools.js';
 import { createWebSearchTool, webSearchFromEnv } from '../tools/web-search.js';
 import { embedderFromEnv } from '../semantic/embedder.js';
+import { capToolResult } from '../tools/result-cap.js';
 import { DEFAULT_VERIFY_RETRIES, failureMessage, runVerification } from './verify.js';
 import { LoopGuard, resultKeyOf } from './loop-guard.js';
 import { isListedCommand } from '../tools/command-allow.js';
@@ -27,13 +34,16 @@ import { createLanguageModel } from '../providers.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
 import { ToolResultCache, cachedExecute } from '../tools/result-cache.js';
 import { ThinkSplitter, stripThinkTags } from './think-tags.js';
+import { repairToolCall } from './tool-repair.js';
+import { maxOutputTokensFor } from '../catalog/models-dev.js';
 import { redact } from '../tools/redact.js';
-import { composeSkillsPrompt, selectSkills } from '../skills/activator.js';
+import { buildSkillIndex, composeSkillsPrompt, selectSkills } from '../skills/activator.js';
+import { createSkillTool } from '../skills/skill-tool.js';
 import { MAX_TOOL_INJECTIONS, selectAtStart, selectOnToolTouch, toWorkspaceRelative, wrapSteering } from '../steering/select.js';
-import { applyCacheHints } from './cache-hints.js';
+import { applyCacheHints, cacheProviderOptions } from './cache-hints.js';
 import { raceAbort } from './race-abort.js';
 import { DEFAULT_PROVIDER_RETRIES, DEFAULT_RETRY_BASE_MS, defaultNetworkProbe, errorSummary, isContextOverflowError, isDisconnected, retryDecision, waitForNetwork, waitOrAbort, } from './retry.js';
-import { attachmentParts, formatBytes, mediaPartTokens } from '../attachments.js';
+import { attachmentParts, formatBytes } from '../attachments.js';
 import { renderAnswersBlock } from '../journey/answers-block.js';
 import { CONTINUE_PROMPT, DEFAULT_PLAN_MODE_SUFFIX, DEFAULT_SPEC_MODE_SUFFIX, DEFAULT_SYSTEM_PROMPT, LAST_STEP_PROMPT, environmentBlock, modelGuidanceBlock, todoNudgePrompt } from './prompts.js';
 import { detectStackFacts, stackBlock } from './stack-facts.js';
@@ -45,6 +55,8 @@ const MAX_TODO_NUDGES = 3;
 const MAX_EMPTY_REPLAYS = 2;
 /** Consecutive tool calls with invalid arguments before the run stops (Kilo: REPEATED_TOOL_FAILURE_LIMIT). */
 const MAX_INVALID_CALLS = 3;
+/** Most recent content kept word for word by compaction, at the top end (RB-56). */
+const KEEP_RECENT_TOKENS = 20_000;
 export const DEFAULT_MAX_DURATION_MS = 10 * 60 * 1000;
 const REDACTABLE_TOOLS = new Set(['read_file', 'search_files', 'list_files']);
 /** Tools whose successful `path` argument can trigger mid-run fileMatch steering. */
@@ -81,6 +93,12 @@ export class Agent {
         const allTools = (config.disableBuiltins
             ? [...(config.extraTools ?? [])]
             : [...BUILTIN_TOOLS, ...(config.extraTools ?? [])]);
+        // Wakeups need a chat that can deliver them, so the tools exist only when a surface supplied a scheduler.
+        // The `skill` tool goes with the skills index in the prompt: both exist only when a registry is supplied and not disabled.
+        if (config.skills && !config.skills.disabled)
+            allTools.push(createSkillTool(config.skills.registry));
+        if (config.wakeups)
+            allTools.push(scheduleWakeupTool, cancelWakeupTool);
         if (config.browser) {
             this.browser = new BrowserSession(config.browser === true ? {} : config.browser);
             allTools.push(...createBrowserTools(this.browser));
@@ -96,6 +114,8 @@ export class Agent {
                 ...(config.semanticSearch.extensions ? { extensions: config.semanticSearch.extensions } : {}),
                 ...(config.semanticSearch.minScore !== undefined ? { minScore: config.semanticSearch.minScore } : {}),
                 ...(config.semanticSearch.defaultLimit ? { defaultLimit: config.semanticSearch.defaultLimit } : {}),
+                ...(config.semanticSearch.consent ? { consent: config.semanticSearch.consent } : {}),
+                ...(config.semanticSearch.onStatus ? { onStatus: config.semanticSearch.onStatus } : {}),
             }));
         }
         const memoryFiltered = config.disableMemory
@@ -123,7 +143,7 @@ export class Agent {
         const cfg = this.checkpoints?.captureBeforeTools;
         if (!cfg) {
             // Default: file-mutating tools + run_command (which can mutate via shell).
-            return new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command']);
+            return new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'bg_start']);
         }
         return new Set(cfg);
     }
@@ -197,9 +217,15 @@ export class Agent {
         /** Docs injected mid-run (not skipped ones), so compaction can tell which it removed. */
         const steeringInMessages = new Set();
         let steeringInjections = 0;
+        // The system message is rebuilt on every turn from what is true now (RB-57): files, steering, the mode's prompt
+        // and the date can change between turns. Built in a stable order, it is byte-identical when nothing changed.
+        const systemSteering = options.history
+            ? selectAtStart(steeringDocs, { task: options.task, cwd, includeAlways: true }, this.config.steering?.maxBytes).system
+            : startSteering.system;
+        const system = { role: 'system', content: await buildSystemContent(this.config, options.task, this.skills, systemSteering) };
         const messages = options.history
-            ? [...options.history, { role: 'user', content: userContent }]
-            : await buildInitialMessages(this.config, options.task, this.skills, startSteering.system, userContent);
+            ? [system, ...adaptHistoryForModel(options.history, this.config.model).filter((m, i) => !(i === 0 && m.role === 'system')), { role: 'user', content: userContent }]
+            : [system, { role: 'user', content: userContent }];
         if (options.attachments && options.attachments.length > 0) {
             // Attached files ride in this turn's user message as native parts (see attachments.ts).
             messages[messages.length - 1] = {
@@ -207,6 +233,18 @@ export class Agent {
                 content: [{ type: 'text', text: userContent }, ...attachmentParts(options.attachments)],
             };
         }
+        // This turn's messages on their own (RB-58): compaction replaces `messages`, never these, so a surface can show
+        // the whole conversation. Everything the run adds goes through append().
+        const turnMessages = [messages[messages.length - 1]];
+        const append = (m) => {
+            messages.push(m);
+            turnMessages.push(m);
+        };
+        const unappend = () => {
+            const last = messages.pop();
+            if (last !== undefined && turnMessages[turnMessages.length - 1] === last)
+                turnMessages.pop();
+        };
         // Plan mode: hard-cap iterations to 1 and add a system prompt suffix
         // telling the model to emit a plan as text and stop. Spec mode: allow
         // up to `specMaxIterations` turns (default 15) so the model can
@@ -226,6 +264,7 @@ export class Agent {
             ? createStepMasker({
                 keepRecentTurns: (typeof maskConfig === 'object' ? maskConfig.keepRecentTurns : undefined) ?? 6,
                 minChars: (typeof maskConfig === 'object' ? maskConfig.minChars : undefined) ?? 600,
+                ...(typeof maskConfig === 'object' && maskConfig.protectTokens !== undefined ? { protectTokens: maskConfig.protectTokens } : {}),
                 softBudgetTokens: 0.5 * effectiveLimitTokens(this.config.model, this.config.compactionThreshold ?? 0.7, this.config.contextBudgetTokens),
             })
             : undefined;
@@ -241,6 +280,8 @@ export class Agent {
         let reportedStreamError;
         const modelFactory = this.config.modelFactory ?? createLanguageModel;
         let currentModelConfig = this.config.model;
+        /** The prompt size at which to compact for a given model: its window times the threshold, or the budget. */
+        const limitOf = (m) => effectiveLimitTokens(m, this.config.compactionThreshold ?? 0.7, this.config.contextBudgetTokens);
         let model = modelFactory(currentModelConfig);
         let stepPricing = this.pricing;
         let lastToolNames = [];
@@ -296,7 +337,16 @@ export class Agent {
             ...(this.config.permissionRules ? { permissionRules: this.config.permissionRules } : {}),
             ...(this.config.toolSandbox ? { toolSandbox: this.config.toolSandbox } : {}),
             shownFolderInstructions: new Set(),
+            processes: new BackgroundProcesses(),
+            ...(this.config.shell ? { shell: this.config.shell } : {}),
+            // Earlier grants of this chat (G16), then whatever repo_clone and a yes to a question add during the run.
+            readRoots: [...(this.config.readRoots ?? [])],
+            ...(this.config.askReadOutside ? { askReadOutside: this.config.askReadOutside } : {}),
+            ...(this.config.suggestPlan ? { suggestPlan: true } : {}),
+            ...(this.config.planDeclined ? { planDeclined: true } : {}),
+            ...(this.config.wakeups ? { wakeups: this.config.wakeups } : {}),
             ...(this.config.maxToolOutputChars ? { maxOutputChars: this.config.maxToolOutputChars } : {}),
+            ...(typeof this.config.verify?.lsp === 'object' ? { lspConfig: this.config.verify.lsp } : {}),
             ...(this.config.askUser ? { askUser: this.config.askUser } : {}),
             ...(this.config.askBudget ? { askBudget: this.config.askBudget } : {}),
             todos: {
@@ -318,11 +368,15 @@ export class Agent {
                 await this.hooks.dispatch({ type: 'PreCompact', messagesCount: messages.length, tokens, cwd });
             }
             const summarizer = this.config.compactionSummarizer ?? this.buildDefaultSummarizer();
+            const limit = limitOf(currentModelConfig);
             const result = await compactMessages(messages, summarizer, {
                 keepRecent: this.config.compactionKeepRecent,
+                keepRecentTokens: Math.min(KEEP_RECENT_TOKENS, Math.floor(limit / 4)),
             });
             if (result.droppedCount === 0)
                 return 0;
+            // The last reported size describes the prompt before compaction; until the next call reports, the estimate rules.
+            lastTurnInputTokens = 0;
             messages.length = 0;
             for (const m of result.messages)
                 messages.push(m);
@@ -412,10 +466,20 @@ export class Agent {
                     }
                     wasInThink = thinkSplitter.reasoning;
                 };
+                if (!planMode && !specMode && this.config.enableCompaction) {
+                    const before = Math.max(lastTurnInputTokens, estimateMessageTokens(messages));
+                    if (before >= limitOf(currentModelConfig))
+                        await compactNow(before);
+                }
                 let promptMessages = messages;
                 if (masker) {
-                    const view = masker.apply(messages, Math.max(lastTurnInputTokens, estimateNextPromptTokens(messages)));
-                    promptMessages = view.messages;
+                    const view = masker.apply(messages, Math.max(lastTurnInputTokens, estimateMessageTokens(messages)));
+                    // Stubs are stored in the prompt history (RB-60), so the next turn sends the same prefix and the cache hits.
+                    // The full results stay in turnMessages, which the transcript keeps (RB-58).
+                    for (let i = 0; i < messages.length; i++)
+                        if (view.messages[i] !== messages[i])
+                            messages[i] = view.messages[i];
+                    promptMessages = messages;
                     if (view.stepped)
                         emit({ type: 'context_masked', maskedCount: view.maskedCount, savedTokens: Math.ceil(view.savedChars / 4) });
                 }
@@ -425,17 +489,27 @@ export class Agent {
                     promptMessages = [...promptMessages, { role: 'user', content: LAST_STEP_PROMPT }];
                 const result = streamText({
                     model,
-                    messages: cachePrompts ? applyCacheHints(promptMessages, currentModelConfig) : promptMessages,
+                    // Per-provider clean-up on every call (RB-61), then cache breakpoints on the cleaned messages.
+                    messages: cachePrompts
+                        ? applyCacheHints(normalizeForModel(promptMessages, currentModelConfig), currentModelConfig)
+                        : normalizeForModel(promptMessages, currentModelConfig),
+                    ...(cachePrompts && cacheProviderOptions(currentModelConfig, this.config.sessionId)
+                        ? { providerOptions: cacheProviderOptions(currentModelConfig, this.config.sessionId) }
+                        : {}),
                     // v7 rejects a system-role message inside `messages` by default
                     // ("Invalid prompt: System messages are not allowed in the prompt
                     // or messages fields. Use the instructions option instead.").
-                    // Forge's system prompt lives as messages[0] (buildInitialMessages)
+                    // Forge's system prompt lives as messages[0] (buildSystemContent)
                     //: this is the SDK's own documented escape hatch to keep that
                     // architecture rather than restructuring session persistence and
                     // compaction (both of which also treat messages[0] as the system
                     // message) around a separate `system` option.
                     allowSystemInMessages: true,
                     tools: toAiSdkTools(this.tools),
+                    repairToolCall,
+                    // Ask for the model's own reply length (G8): some hosts default to a few thousand tokens, which cuts a long
+                    // write_file call in half. A half-written tool call cannot be continued, unlike text.
+                    ...(maxOutputTokensFor(currentModelConfig) ? { maxOutputTokens: maxOutputTokensFor(currentModelConfig) } : {}),
                     ...(lastStep ? { toolChoice: 'none' } : {}),
                     abortSignal,
                     // Retries are decided below (retryDecision), for failures before and during the stream alike.
@@ -529,7 +603,7 @@ export class Agent {
                     stepFailure = undefined;
                     if (isContextOverflowError(failure) && this.config.enableCompaction && !planMode && !specMode && overflowCompactions < 2) {
                         overflowCompactions++;
-                        if ((await compactNow(Math.max(lastTurnInputTokens, estimateNextPromptTokens(messages)))) > 0) {
+                        if ((await compactNow(Math.max(lastTurnInputTokens, estimateMessageTokens(messages)))) > 0) {
                             partialStepText = '';
                             iterations--;
                             continue;
@@ -594,7 +668,7 @@ export class Agent {
                 continuedText = '';
                 lastToolNames = (toolCalls ?? []).map((c) => c.toolName);
                 for (const m of response.messages) {
-                    messages.push(m);
+                    append(m);
                 }
                 // Infinite output: a reply cut off by the output-token limit (and not
                 // calling tools) is continued with a follow-up user message rather
@@ -606,7 +680,7 @@ export class Agent {
                     continuations++;
                     continuedText = finalText;
                     emit({ type: 'continuation', count: continuations });
-                    messages.push({ role: 'user', content: CONTINUE_PROMPT });
+                    append({ role: 'user', content: CONTINUE_PROMPT });
                     continue;
                 }
                 if (!toolCalls || toolCalls.length === 0) {
@@ -639,7 +713,7 @@ export class Agent {
                         todoNudges++;
                         answeringNudge = true;
                         todoNudgeMessage = { role: 'user', content: todoNudgePrompt(openTodos) };
-                        messages.push(todoNudgeMessage);
+                        append(todoNudgeMessage);
                         emit({ type: 'todo_nudge', open: openTodos.length });
                         continue;
                     }
@@ -682,7 +756,7 @@ export class Agent {
                         verification = { passed: outcome.passed, attempts: verifyAttempts };
                         if (!outcome.passed && verifyFixes < (this.config.verify.maxRetries ?? DEFAULT_VERIFY_RETRIES)) {
                             verifyFixes++;
-                            messages.push({ role: 'user', content: failureMessage(outcome.failures) });
+                            append({ role: 'user', content: failureMessage(outcome.failures) });
                             continue;
                         }
                     }
@@ -766,12 +840,17 @@ export class Agent {
                     }
                     const toolStartedAt = Date.now();
                     try {
-                        const rawResult = await def.execute(toolArgs, {
+                        // With the sandbox's network off, Forge's own network tools are held to its allowed hosts, from one place (F13).
+                        const denied = networkDenial(def.name, toolArgs, this.config.commandSandbox);
+                        if (denied)
+                            throw new Error(`[sandbox] ${denied}`);
+                        // One size limit for every tool, not only run_command (G6).
+                        const rawResult = capToolResult(await def.execute(toolArgs, {
                             ...ctx,
                             policy: this.config.toolSandbox?.policies?.[def.name],
                             onProgress: (msg) => emit({ type: 'text_delta', text: `\n[${def.name}] ${msg}\n` }),
                             onChildProgress: (event) => emit({ type: 'tool_result', name: def.name, id: call.toolCallId, result: `[child] ${event.event.type}`, isError: false }),
-                        });
+                        }), this.config.maxToolOutputChars);
                         // Apply redaction to read-style tool output. The model gets the
                         // scrubbed version; the user (via the on-event stream) sees the
                         // count so they know something was hidden.
@@ -792,6 +871,15 @@ export class Agent {
                         if (FILE_WRITE_TOOLS.has(call.toolName))
                             for (const p of touchedFiles)
                                 editedFiles.add(p);
+                        if (this.config.autoFormat && FILE_WRITE_TOOLS.has(call.toolName)) {
+                            for (const editedPath of touchedFiles) {
+                                const note = formatMessage(editedPath, await formatFile(editedPath, this.config.autoFormat, { ...ctx, policy: undefined }));
+                                if (note)
+                                    finalResult = typeof finalResult === 'string' ? `${finalResult}
+
+${note}` : { result: finalResult, autoFormat: note };
+                            }
+                        }
                         if (this.config.autoLint && FILE_WRITE_TOOLS.has(call.toolName)) {
                             for (const editedPath of touchedFiles) {
                                 const report = await lintFile(editedPath, this.config.autoLint, { ...ctx, policy: undefined }).catch(() => null);
@@ -861,7 +949,7 @@ export class Agent {
                     toolResultMessages.push({ role: 'tool', content: currentToolResults });
                 }
                 for (const m of toolResultMessages)
-                    messages.push(m);
+                    append(m);
                 if (loopTripped) {
                     emit({ type: 'loop_detected', tool: loopTripped.tool, count: loopTripped.count });
                     reason = 'loop_detected';
@@ -895,7 +983,7 @@ export class Agent {
                         }
                     }
                     if (injected.length > 0) {
-                        messages.push({ role: 'user', content: injected.map(wrapSteering).join('\n\n') });
+                        append({ role: 'user', content: injected.map(wrapSteering).join('\n\n') });
                     }
                 }
                 // Emit updated cache stats after the tool round so the UI sees hits.
@@ -910,8 +998,8 @@ export class Agent {
                     // Two independent estimates of "how big is the next prompt": 
                     // take the larger rather than summing them (they're not additive
                     // components of the same total, they're two guesses at it).
-                    const totalForNextTurn = Math.max(lastTurnInputTokens, estimateNextPromptTokens(messages));
-                    if (shouldCompactForBudget(totalForNextTurn, this.config.model, threshold, this.config.contextBudgetTokens)) {
+                    const totalForNextTurn = Math.max(lastTurnInputTokens, estimateMessageTokens(messages));
+                    if (shouldCompactForBudget(totalForNextTurn, currentModelConfig, threshold, this.config.contextBudgetTokens)) {
                         await compactNow(totalForNextTurn);
                     }
                 }
@@ -959,17 +1047,22 @@ export class Agent {
         // must not hand that unanswered message back as history.
         const lastMessage = messages[messages.length - 1];
         if (continuedText !== '' && lastMessage?.role === 'user' && lastMessage.content === CONTINUE_PROMPT)
-            messages.pop();
+            unappend();
         else if (todoNudgeMessage && lastMessage === todoNudgeMessage)
-            messages.pop();
+            unappend();
         // Stopped mid-answer: keep the part the user already saw, marked as cut short, so "continue" can pick it up
         // instead of starting over. Only when the model is the next speaker (after the user or a tool result).
         if (reason === 'aborted' && partialStepText.trim()) {
             const last = messages[messages.length - 1];
             if (last && (last.role === 'user' || last.role === 'tool')) {
-                messages.push({ role: 'assistant', content: `${partialStepText.trim()}\n\n[Stopped by the user before finishing.]` });
+                append({ role: 'assistant', content: `${partialStepText.trim()}\n\n[Stopped by the user before finishing.]` });
             }
         }
+        // Background processes belong to the run: stop what is still going and say so in the answer.
+        const leftRunning = ctx.processes?.stopAll() ?? [];
+        if (leftRunning.length > 0) {
+            finalText += `${finalText ? '\n\n' : ''}[Stopped ${leftRunning.length} background process${leftRunning.length === 1 ? '' : 'es'} when this run ended: ${leftRunning.map((p) => p.command).join(', ')}]`;
+        }
         // The browser is per-run: never leave a Chrome process behind.
         await this.browser?.close().catch(() => undefined);
         emit({ type: 'done', reason });
@@ -993,6 +1086,7 @@ export class Agent {
             // Snapshot of the final conversation: the REPL passes this back as
             // the `history` argument on the next turn so context persists.
             messages: messages.slice(),
+            turnMessages: turnMessages.slice(),
             ...(verification ? { verification } : {}),
             ...(errorMessage ? { error: errorMessage } : {}),
         };
@@ -1242,7 +1336,9 @@ function extractMediaAttachment(result) {
     const bytes = typeof r.bytes === 'number' ? r.bytes : 0;
     const path = typeof r.path === 'string' ? r.path : '<unknown>';
     const what = mime.startsWith('image/') ? 'Image' : 'Document';
-    const summary = `${what} attached: ${mime} (${formatBytes(bytes)}) at ${path}`;
+    // A tool that sends words with its media (an MCP result) keeps them next to the attachment line.
+    const words = typeof r.text === 'string' && r.text.trim() ? `\n${r.text}` : '';
+    const summary = `${what} attached: ${mime} (${formatBytes(bytes)}) at ${path}${words}`;
     const comma = dataUrl.indexOf(',');
     const filename = typeof r.path === 'string' ? r.path.split(/[\\/]/).pop() : undefined;
     return { dataUrl, base64: dataUrl.slice(comma + 1), mime, ...(filename ? { filename } : {}), summary };
@@ -1281,15 +1377,14 @@ export function applySandbox(tools, sandbox) {
     return result;
 }
 /**
- * Build the initial `[system, user]` messages for a fresh run. If memory
- * is enabled and a `.forge/MEMORY.md` exists somewhere up the cwd tree, we
- * append a `<project-memory>...</project-memory>` block to the system
- * prompt so the agent picks up project conventions on turn one.
+ * Build the system message for a run, on every turn (RB-57). If memory is enabled and a `.forge/MEMORY.md` exists
+ * somewhere up the cwd tree, a `<project-memory>...</project-memory>` block is appended so the agent picks up project
+ * conventions.
  *
  * This is async because memory loading hits the disk. When memory is
  * disabled or no file exists, this is a fast synchronous-feeling path.
  */
-async function buildInitialMessages(config, task, skills, steeringSystem = [], userContent = task) {
+async function buildSystemContent(config, task, skills, steeringSystem = []) {
     let basePrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
     if (config.planMode) {
         basePrompt = basePrompt + (config.planModePrompt ?? DEFAULT_PLAN_MODE_SUFFIX);
@@ -1315,7 +1410,8 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
         try {
             const all = skills.registry.list();
             const selected = selectSkills(all, task, skills.maxSkills ?? 3);
-            skillsBlock = composeSkillsPrompt(selected);
+            // The index of every skill (G12) comes first and is the same every turn; the picked bodies follow.
+            skillsBlock = [buildSkillIndex(all), composeSkillsPrompt(selected)].filter(Boolean).join('\n\n');
         }
         catch {
             // Skill selection failure shouldn't kill a run: just skip.
@@ -1348,12 +1444,7 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
             // A map failure shouldn't kill a run: just skip.
         }
     }
-    // Interview answers from a guided journey. This function runs only when no
-    // history is passed (see the `options.history` branch in `run`), so every
-    // block here is assembled once, on a session's first turn, and then rides
-    // inside `history[0]`. That is why a journey's interview must finish before
-    // the first run: an answer that arrives on turn 3 can never enter the system
-    // message, and a middle turn would be summarised away by compaction.
+    // Interview answers from a guided journey. Rebuilt with the rest of the system message on every turn (RB-57).
     const answersBlock = renderAnswersBlock(config.journeyAnswers ?? []);
     // The versions the workspace's files state, so code is written for them and not for what training saw most.
     let stackFactsBlock = '';
@@ -1374,6 +1465,8 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
         isGitRepo: existsSync(path.join(cwd, '.git')),
         today: new Date().toISOString().slice(0, 10),
         model: config.model?.model,
+        // A custom runner (the VS Code terminal) says which shell it is; Forge's own runner picks one itself.
+        ...(config.runnerShell ? { shell: config.runnerShell } : config.commandRunner ? {} : { shell: runnerShell(config.shell).kind }),
     });
     // Compose the final system prompt: base + (memory, skills) blocks in a
     // stable order so cache hits survive across runs that share state. The
@@ -1381,36 +1474,5 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
     const steeringBlock = steeringSystem.map(wrapSteering).join('\n\n');
     const guidanceBlock = config.model ? modelGuidanceBlock(config.model) : '';
     const blocks = [steeringBlock, instructionsBlock, extraInstructionsBlock, config.mcpInstructions ?? '', config.projectCommands ?? '', memoryBlock, skillsBlock, answersBlock, mapBlock, stackFactsBlock, guidanceBlock, envBlock].filter((b) => b.length > 0);
-    const systemContent = blocks.length > 0 ? `${basePrompt}\n\n${blocks.join('\n\n')}` : basePrompt;
-    return [
-        { role: 'system', content: systemContent },
-        { role: 'user', content: userContent },
-    ];
-}
-/**
- * Rough estimate of the next-turn prompt size from the message list.
- * Used to decide whether to compact before the next model call. We use
- * `Math.ceil(text.length / 4)` (≈ OpenAI's tokenizer behavior): good
- * enough for "are we close to the window?" decisions.
- */
-function estimateNextPromptTokens(messages) {
-    let total = 0;
-    for (const m of messages) {
-        if (typeof m.content === 'string') {
-            total += Math.ceil(m.content.length / 4);
-        }
-        else if (Array.isArray(m.content)) {
-            for (const part of m.content) {
-                if (part && typeof part === 'object' && 'text' in part) {
-                    const text = part.text;
-                    if (typeof text === 'string')
-                        total += Math.ceil(text.length / 4);
-                }
-                else {
-                    total += mediaPartTokens(part);
-                }
-            }
-        }
-    }
-    return total;
+    return blocks.length > 0 ? `${basePrompt}\n\n${blocks.join('\n\n')}` : basePrompt;
 }

package/dist/agent/cache-hints.d.ts

@@ -13,3 +13,5 @@ import type { ModelMessage } from 'ai';
 import type { ModelConfig } from '../types.js';
 export declare function supportsCacheHints(model: ModelConfig): boolean;
 export declare function applyCacheHints(messages: ModelMessage[], model: ModelConfig): ModelMessage[];
+/** Call-level provider options that help the provider's cache: OpenAI routes one chat's calls together by key. */
+export declare function cacheProviderOptions(model: ModelConfig, sessionId: string | undefined): Record<string, Record<string, string>> | undefined;

package/dist/agent/cache-hints.js

@@ -23,8 +23,23 @@ export function applyCacheHints(messages, model) {
     const out = messages.slice();
     if (out[0].role === 'system')
         out[0] = withHint(out[0], hint);
-    const last = out.length - 1;
-    if (last > 0 || out[0].role !== 'system')
-        out[last] = withHint(out[last], hint);
+    // The last two other messages too, as Kilo does: the previous call's breakpoint is then still marked, so a step that
+    // adds many content blocks keeps its cache hit (Anthropic looks back at most 20 blocks from a breakpoint). RB-61.
+    // Three breakpoints in all; Anthropic allows four.
+    const firstOther = out[0].role === 'system' ? 1 : 0;
+    for (let i = Math.max(firstOther, out.length - 2); i < out.length; i++)
+        out[i] = withHint(out[i], hint);
     return out;
 }
+/** Call-level provider options that help the provider's cache: OpenAI routes one chat's calls together by key. */
+export function cacheProviderOptions(model, sessionId) {
+    if (!sessionId)
+        return undefined;
+    if (model.endpoint)
+        return undefined;
+    if (model.provider === 'openai')
+        return { openai: { promptCacheKey: sessionId } };
+    if (model.provider === 'azure')
+        return { openai: { promptCacheKey: sessionId }, azure: { promptCacheKey: sessionId } };
+    return undefined;
+}

package/dist/agent/history-adapt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Make a stored conversation safe to replay to a different provider (RB-53).
+ *
+ * The messages the loop keeps are the AI SDK's own. The assistant parts in them carry the writing provider's
+ * bookkeeping under `providerOptions.<provider>`: Anthropic thinking signatures, OpenAI item ids. Another provider
+ * rejects those, so a chat that switched model failed on the next turn. Reasoning from an earlier turn is not
+ * needed to continue a conversation, so a reasoning part tagged only for other providers is dropped; any other
+ * foreign tag is removed and the part kept.
+ *
+ * Pure: returns new messages and never mutates `history`, which is persisted and reused.
+ */
+import type { ModelMessage } from 'ai';
+import type { ModelConfig } from '../types.js';
+/** The key the AI SDK writes provider data under for this model's client. */
+export declare function providerKeyFor(model: Pick<ModelConfig, 'provider' | 'endpoint'>): string;
+export declare function adaptHistoryForModel(history: readonly ModelMessage[], model: Pick<ModelConfig, 'provider' | 'endpoint'>): ModelMessage[];
+/**
+ * Per-provider clean-up of the messages sent on every call (RB-61): tool-call ids the target accepts (Claude: only
+ * letters, digits, `_` and `-`; Mistral: exactly nine letters or digits), an assistant turn between a tool result and
+ * a user message for Mistral, and no empty text parts (Anthropic refuses an empty text block). Deterministic and
+ * identity-preserving, so a prompt prefix that needs nothing stays byte-identical and the cache keeps hitting.
+ */
+export declare function normalizeForModel(messages: readonly ModelMessage[], model: Pick<ModelConfig, 'provider' | 'model'>): ModelMessage[];

package/dist/agent/history-adapt.js

@@ -0,0 +1,114 @@
+import { COMPACTION_SUMMARY_PREFIX } from '../context/compaction.js';
+/** The key the AI SDK writes provider data under for this model's client. */
+export function providerKeyFor(model) {
+    if (model.endpoint)
+        return model.endpoint.api === 'anthropic' ? 'anthropic' : 'openai';
+    switch (model.provider) {
+        case 'anthropic':
+        case 'google':
+        case 'bedrock':
+        case 'vertex':
+        case 'azure':
+            return model.provider;
+        default:
+            // openai, openrouter, ollama, lmstudio, minimax and openai-compatible all use the OpenAI client.
+            return 'openai';
+    }
+}
+function adaptPart(part, key) {
+    if (typeof part !== 'object' || part === null)
+        return part;
+    const options = part.providerOptions;
+    if (!options || typeof options !== 'object')
+        return part;
+    const keys = Object.keys(options);
+    if (keys.length === 0 || keys.every((k) => k === key))
+        return part;
+    if (part.type === 'reasoning' && !keys.includes(key))
+        return undefined;
+    const { providerOptions: _dropped, ...rest } = part;
+    const kept = Object.fromEntries(Object.entries(options).filter(([k]) => k === key));
+    return Object.keys(kept).length > 0 ? { ...rest, providerOptions: kept } : rest;
+}
+function legacySummary(text) {
+    const body = text.replace(/^\[Compacted summary of [^\]]*\]\s*/, '');
+    return `${COMPACTION_SUMMARY_PREFIX}, written by Forge to save context. It is not a new request.]\n\n${body}`;
+}
+export function adaptHistoryForModel(history, model) {
+    const key = providerKeyFor(model);
+    const out = [];
+    for (const [index, message] of history.entries()) {
+        // Before RB-56, compaction stored its summary as a system message mid-conversation; Gemini and Bedrock refuse it.
+        if (index > 0 && message.role === 'system') {
+            out.push({ role: 'user', content: legacySummary(typeof message.content === 'string' ? message.content : JSON.stringify(message.content)) });
+            continue;
+        }
+        if (message.role !== 'assistant' || !Array.isArray(message.content)) {
+            out.push(message);
+            continue;
+        }
+        const parts = message.content.map((p) => adaptPart(p, key)).filter((p) => p !== undefined);
+        if (parts.length === 0)
+            continue;
+        const unchanged = parts.length === message.content.length && parts.every((p, i) => p === message.content[i]);
+        out.push(unchanged ? message : { ...message, content: parts });
+    }
+    return out;
+}
+const MISTRAL_FAMILIES = ['mistral', 'devstral', 'codestral', 'pixtral', 'mixtral', 'ministral', 'magistral'];
+function isClaude(model) {
+    return model.provider === 'anthropic' || model.model.toLowerCase().includes('claude');
+}
+function isMistral(model) {
+    const id = model.model.toLowerCase();
+    return MISTRAL_FAMILIES.some((f) => id.includes(f));
+}
+/** Nine alphanumeric characters from any id, the same every time; hashing (not cutting) keeps two ids apart. */
+function mistralToolId(id) {
+    if (/^[a-zA-Z0-9]{9}$/.test(id))
+        return id;
+    let a = 0x811c9dc5;
+    let b = 0x01000193;
+    for (let i = 0; i < id.length; i++) {
+        const c = id.charCodeAt(i);
+        a = Math.imul(a ^ c, 0x01000193) >>> 0;
+        b = Math.imul(b ^ c, 0x5bd1e995) >>> 0;
+    }
+    return (a.toString(36) + b.toString(36)).padEnd(9, '0').slice(0, 9);
+}
+function claudeToolId(id) {
+    return /^[a-zA-Z0-9_-]+$/.test(id) ? id : id.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+/**
+ * Per-provider clean-up of the messages sent on every call (RB-61): tool-call ids the target accepts (Claude: only
+ * letters, digits, `_` and `-`; Mistral: exactly nine letters or digits), an assistant turn between a tool result and
+ * a user message for Mistral, and no empty text parts (Anthropic refuses an empty text block). Deterministic and
+ * identity-preserving, so a prompt prefix that needs nothing stays byte-identical and the cache keeps hitting.
+ */
+export function normalizeForModel(messages, model) {
+    const rewriteId = isMistral(model) ? mistralToolId : isClaude(model) ? claudeToolId : undefined;
+    const mistral = isMistral(model);
+    const out = [];
+    for (let i = 0; i < messages.length; i++) {
+        let m = messages[i];
+        if (Array.isArray(m.content) && (m.role === 'assistant' || m.role === 'tool')) {
+            const parts = m.content
+                .filter((p) => !(p.type === 'text' && p.text === ''))
+                .map((p) => {
+                if (!rewriteId || typeof p.toolCallId !== 'string')
+                    return p;
+                const id = rewriteId(p.toolCallId);
+                return id === p.toolCallId ? p : { ...p, toolCallId: id };
+            });
+            if (parts.length === 0 && m.role === 'assistant')
+                continue;
+            const same = parts.length === m.content.length && parts.every((p, k) => p === m.content[k]);
+            if (!same)
+                m = { ...m, content: parts };
+        }
+        out.push(m);
+        if (mistral && m.role === 'tool' && messages[i + 1]?.role === 'user')
+            out.push({ role: 'assistant', content: 'Done.' });
+    }
+    return out;
+}