@ikarmic/forge-core 5.2.0 → 5.3.0

package/dist/agent/agent.js

@@ -32,12 +32,19 @@ import { composeSkillsPrompt, selectSkills } from '../skills/activator.js';
 import { MAX_TOOL_INJECTIONS, selectAtStart, selectOnToolTouch, toWorkspaceRelative, wrapSteering } from '../steering/select.js';
 import { applyCacheHints } 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 { renderAnswersBlock } from '../journey/answers-block.js';
-import { CONTINUE_PROMPT, DEFAULT_PLAN_MODE_SUFFIX, DEFAULT_SPEC_MODE_SUFFIX, DEFAULT_SYSTEM_PROMPT, environmentBlock } from './prompts.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';
 /** Read-only tool names whose output flows through the redactor. */
 const DEFAULT_MAX_CONTINUATIONS = 3;
+/** Nudges per run when a turn ends with open todos; never two without a tool call between them. */
+const MAX_TODO_NUDGES = 3;
+/** Times an empty or reasoning-only reply is asked for again before it is accepted. */
+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;
 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. */
@@ -259,6 +266,26 @@ export class Agent {
         let partialStepText = '';
         let continuations = 0;
         const maxContinuations = this.config.maxContinuations ?? DEFAULT_MAX_CONTINUATIONS;
+        // Open-todo nudges: the one sent last (so a run that ends before answering it drops it) and whether
+        // the step just answered was a nudge (a second text-only reply in a row is the model's answer).
+        // Only a list this run wrote counts: the chat carries the last turn's list over, and an unrelated
+        // question answered while it is open must not be pushed back onto the old task.
+        let todoNudges = 0;
+        let todoNudgeMessage;
+        let answeringNudge = false;
+        let todosWrittenThisRun = false;
+        // Provider failures and empty replies retried for the step now running; both reset when a step succeeds.
+        const maxProviderRetries = this.config.providerRetry?.maxRetries ?? DEFAULT_PROVIDER_RETRIES;
+        const retryBaseMs = this.config.providerRetry?.baseDelayMs ?? DEFAULT_RETRY_BASE_MS;
+        let providerFailures = 0;
+        let emptyReplays = 0;
+        // Time spent waiting for the network in this run, across every offline spell.
+        const offlinePollMs = this.config.providerRetry?.offlinePollMs ?? 3000;
+        const maxOfflineMs = this.config.providerRetry?.maxOfflineMs ?? 15 * 60_000;
+        let offlineWaitedMs = 0;
+        let offlineWaits = 0;
+        // Consecutive tool calls whose arguments failed the schema, across steps; any valid call resets it.
+        let invalidStreak = { tool: '', count: 0 };
         const ctx = {
             cwd: this.config.cwd ?? process.cwd(),
             auto: this.config.auto ?? false,
@@ -276,13 +303,49 @@ export class Agent {
                 get: () => this.todoList,
                 set: (todos) => {
                     this.todoList = todos;
+                    todosWrittenThisRun = true;
                     emit({ type: 'todo_updated', todos });
                 },
             },
             ...(this.config.commandRunner ? { commandRunner: this.config.commandRunner } : {}),
+            ...(this.config.commandSandbox ? { commandSandbox: this.config.commandSandbox } : {}),
             ...(abortSignal ? { abortSignal } : {}),
             ...(this.config.memoryMaxBodyChars !== undefined ? { memoryMaxBodyChars: this.config.memoryMaxBodyChars } : {}),
         };
+        // Summarize older turns in place; returns how many messages were dropped (0: nothing could be compacted).
+        const compactNow = async (tokens) => {
+            if (this.hooks) {
+                await this.hooks.dispatch({ type: 'PreCompact', messagesCount: messages.length, tokens, cwd });
+            }
+            const summarizer = this.config.compactionSummarizer ?? this.buildDefaultSummarizer();
+            const result = await compactMessages(messages, summarizer, {
+                keepRecent: this.config.compactionKeepRecent,
+            });
+            if (result.droppedCount === 0)
+                return 0;
+            messages.length = 0;
+            for (const m of result.messages)
+                messages.push(m);
+            masker?.reset(); // the history was replaced, so the frozen boundary no longer applies
+            // A mid-run steering doc summarized away may be injected again on the next touch.
+            for (const name of [...steeringInMessages]) {
+                const marker = `<steering name="${name}">`;
+                if (messages.some((m) => typeof m.content === 'string' && m.content.includes(marker)))
+                    continue;
+                steeringInMessages.delete(name);
+                steeringInjected.delete(name);
+                steeringInjections--;
+            }
+            emit({
+                type: 'compaction',
+                droppedCount: result.droppedCount,
+                savedTokens: result.savedTokens,
+                summary: result.summary,
+            });
+            return result.droppedCount;
+        };
+        // The provider refused the prompt as too long: compact once and ask again (Kilo does the same).
+        let overflowCompactions = 0;
         // Emit initial cache stats so the UI knows the cache is wired up.
         emit({ type: 'cache_stats', ...this.cache.getStats() });
         try {
@@ -327,6 +390,7 @@ export class Agent {
                 // Track per-turn token deltas so we can compute per-turn cost.
                 const turnStart = { input: inputTokens, output: outputTokens, cacheRead: cacheReadTokens, cacheWrite: cacheWriteTokens };
                 let reasoningText = '';
+                let stepFailure;
                 partialStepText = '';
                 // Inline <think> blocks (MiniMax over OpenAI-compatible, some open models) become reasoning events.
                 const thinkSplitter = new ThinkSplitter();
@@ -355,6 +419,10 @@ export class Agent {
                     if (view.stepped)
                         emit({ type: 'context_masked', maskedCount: view.maskedCount, savedTokens: Math.ceil(view.savedChars / 4) });
                 }
+                // The last allowed step: no tools, and a note asking for a summary instead of stopping mid-task.
+                const lastStep = !planMode && !specMode && effectiveMaxIter > 1 && iterations >= effectiveMaxIter;
+                if (lastStep)
+                    promptMessages = [...promptMessages, { role: 'user', content: LAST_STEP_PROMPT }];
                 const result = streamText({
                     model,
                     messages: cachePrompts ? applyCacheHints(promptMessages, currentModelConfig) : promptMessages,
@@ -368,7 +436,10 @@ export class Agent {
                     // message) around a separate `system` option.
                     allowSystemInMessages: true,
                     tools: toAiSdkTools(this.tools),
+                    ...(lastStep ? { toolChoice: 'none' } : {}),
                     abortSignal,
+                    // Retries are decided below (retryDecision), for failures before and during the stream alike.
+                    maxRetries: 0,
                     ...(this.config.model.reasoningEffort ? { reasoning: this.config.model.reasoningEffort } : {}),
                     ...(this.config.model.temperature !== undefined ? { temperature: this.config.model.temperature } : {}),
                     onChunk: ({ chunk }) => {
@@ -388,8 +459,9 @@ export class Agent {
                         // Pressing Stop aborts the request; that is not a failure to report.
                         if (abortSignal?.aborted)
                             return;
+                        // Reported only if it is not retried (below); the SDK then throws a generic "No output generated".
+                        stepFailure = error;
                         reportedStreamError = errorMessageOf(error);
-                        emit({ type: 'error', error: reportedStreamError });
                     },
                     onFinish: ({ text: rawText, usage }) => {
                         emitSegments(thinkSplitter.flush());
@@ -439,12 +511,88 @@ export class Agent {
                         }
                     },
                 });
-                await result.consumeStream();
-                finalText = continuedText + stripThinkTags(await result.text);
+                let stepText;
+                let toolCalls;
+                let response;
+                try {
+                    await result.consumeStream();
+                    stepText = stripThinkTags(await result.text);
+                    toolCalls = await result.toolCalls;
+                    response = await result.response;
+                    if (stepFailure !== undefined)
+                        throw stepFailure;
+                }
+                catch (err) {
+                    if (abortSignal?.aborted)
+                        throw err;
+                    const failure = stepFailure ?? err;
+                    stepFailure = undefined;
+                    if (isContextOverflowError(failure) && this.config.enableCompaction && !planMode && !specMode && overflowCompactions < 2) {
+                        overflowCompactions++;
+                        if ((await compactNow(Math.max(lastTurnInputTokens, estimateNextPromptTokens(messages)))) > 0) {
+                            partialStepText = '';
+                            iterations--;
+                            continue;
+                        }
+                    }
+                    // No network at all: wait for it to come back instead of spending retries (Kilo's offline guard).
+                    // Only when a probe confirms it: a mistyped provider host fails DNS too while the network is fine.
+                    const probe = this.config.providerRetry?.networkProbe ?? defaultNetworkProbe;
+                    if (isDisconnected(failure) && offlineWaitedMs < maxOfflineMs && !(await probe().catch(() => false))) {
+                        offlineWaits++;
+                        emit({ type: 'retry', kind: 'offline', attempt: offlineWaits, maxRetries: 0, delayMs: offlinePollMs, reason: errorSummary(failure) });
+                        const waited = await waitForNetwork(probe, {
+                            pollMs: offlinePollMs,
+                            budgetMs: maxOfflineMs - offlineWaitedMs,
+                            ...(abortSignal ? { abortSignal } : {}),
+                        });
+                        offlineWaitedMs += waited.waitedMs;
+                        if (waited.outcome === 'aborted') {
+                            reason = 'aborted';
+                            break;
+                        }
+                        if (waited.outcome === 'online') {
+                            partialStepText = '';
+                            iterations--;
+                            continue;
+                        }
+                        throw failure;
+                    }
+                    const decision = retryDecision(failure, providerFailures + 1, retryBaseMs);
+                    if (!decision.retry || providerFailures >= maxProviderRetries)
+                        throw failure;
+                    providerFailures++;
+                    // The step is thrown away whole: nothing it streamed is kept, and it does not count as a step.
+                    partialStepText = '';
+                    emit({ type: 'retry', kind: 'provider_error', attempt: providerFailures, maxRetries: maxProviderRetries, delayMs: decision.delayMs, reason: decision.message });
+                    iterations--;
+                    if ((await waitOrAbort(decision.delayMs, abortSignal)) === 'aborted') {
+                        reason = 'aborted';
+                        break;
+                    }
+                    continue;
+                }
+                // A reply with neither text nor a tool call (empty, or reasoning only) is an unfinished answer, not the end.
+                if ((!toolCalls || toolCalls.length === 0) &&
+                    !stepText.trim() &&
+                    !continuedText &&
+                    (await result.finishReason) !== 'length' &&
+                    emptyReplays < MAX_EMPTY_REPLAYS) {
+                    emptyReplays++;
+                    const delayMs = retryBaseMs * emptyReplays;
+                    emit({ type: 'retry', kind: 'empty_reply', attempt: emptyReplays, maxRetries: MAX_EMPTY_REPLAYS, delayMs, reason: 'The model sent an empty reply.' });
+                    iterations--;
+                    if ((await waitOrAbort(delayMs, abortSignal)) === 'aborted') {
+                        reason = 'aborted';
+                        break;
+                    }
+                    continue;
+                }
+                providerFailures = 0;
+                emptyReplays = 0;
+                finalText = continuedText + stepText;
                 continuedText = '';
-                const toolCalls = await result.toolCalls;
                 lastToolNames = (toolCalls ?? []).map((c) => c.toolName);
-                const response = await result.response;
                 for (const m of response.messages) {
                     messages.push(m);
                 }
@@ -479,6 +627,22 @@ export class Agent {
                         reason = 'spec';
                         break;
                     }
+                    // A reply that ends the turn while the model's own todo list has open items ("Now I'll implement X…")
+                    // is usually a stall, not an answer. Nudge once, if the model can still update the list and has a step left.
+                    const openTodos = this.todoList.filter((t) => t.status !== 'completed');
+                    if (openTodos.length > 0 &&
+                        todosWrittenThisRun &&
+                        !answeringNudge &&
+                        todoNudges < MAX_TODO_NUDGES &&
+                        iterations < effectiveMaxIter &&
+                        this.tools.some((t) => t.name === 'todo_write')) {
+                        todoNudges++;
+                        answeringNudge = true;
+                        todoNudgeMessage = { role: 'user', content: todoNudgePrompt(openTodos) };
+                        messages.push(todoNudgeMessage);
+                        emit({ type: 'todo_nudge', open: openTodos.length });
+                        continue;
+                    }
                     if (this.config.verify && (this.config.verify.commands.length > 0 || this.config.verify.lsp) && editedSinceVerify) {
                         if (verifyApproved === undefined) {
                             // Like a tool approval, the question must not outlive Stop: race it against the abort signal.
@@ -525,6 +689,7 @@ export class Agent {
                     reason = 'completed';
                     break;
                 }
+                answeringNudge = false;
                 // Resolve which tools the model called (only those without `execute`
                 // reach this code path; tools with `execute` are handled by the SDK).
                 const toolResultMessages = [];
@@ -540,12 +705,14 @@ export class Agent {
                     }
                     const argsParsed = def.parameters.safeParse(call.input);
                     if (!argsParsed.success) {
+                        invalidStreak = { tool: call.toolName, count: invalidStreak.count + 1 };
                         const message = `Invalid arguments for ${call.toolName}: ${argsParsed.error.message}`;
                         trackLoop(call.toolName, call.input, message);
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
                         continue;
                     }
+                    invalidStreak = { tool: '', count: 0 };
                     const approval = await this.requestApproval(def, call.toolCallId, argsParsed.data, abortSignal, ctx);
                     this.audit?.record({ event: 'tool_call', tool: call.toolName, args: approval.args ?? argsParsed.data, approved: approval.approved, auto: this.config.auto === true }, auditCtx);
                     if (!approval.approved) {
@@ -569,7 +736,7 @@ export class Agent {
                         }
                         toolArgs = edited.data;
                     }
-                    emit({ type: 'tool_call', name: call.toolName, id: call.toolCallId, args: toolArgs });
+                    emit({ type: 'tool_call', name: call.toolName, id: call.toolCallId, args: toolArgs, ...(approval.source ? { approval: approval.source } : {}) });
                     if (this.hooks) {
                         await this.hooks.dispatch({
                             type: 'PreToolUse',
@@ -700,6 +867,12 @@ export class Agent {
                     reason = 'loop_detected';
                     break;
                 }
+                if (invalidStreak.count >= MAX_INVALID_CALLS) {
+                    errorMessage = `Stopped: the model sent invalid arguments for ${invalidStreak.tool} ${invalidStreak.count} times in a row.`;
+                    emit({ type: 'error', error: errorMessage });
+                    reason = 'error';
+                    break;
+                }
                 // Mid-run fileMatch steering: one extra user message per round, each doc once per run.
                 if (steeringDocs.length > 0 && touchedPaths.length > 0) {
                     const injected = [];
@@ -739,39 +912,7 @@ export class Agent {
                     // 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)) {
-                        if (this.hooks) {
-                            await this.hooks.dispatch({
-                                type: 'PreCompact',
-                                messagesCount: messages.length,
-                                tokens: totalForNextTurn,
-                                cwd,
-                            });
-                        }
-                        const summarizer = this.config.compactionSummarizer ?? this.buildDefaultSummarizer();
-                        const result = await compactMessages(messages, summarizer, {
-                            keepRecent: this.config.compactionKeepRecent,
-                        });
-                        if (result.droppedCount > 0) {
-                            messages.length = 0;
-                            for (const m of result.messages)
-                                messages.push(m);
-                            masker?.reset(); // the history was replaced, so the frozen boundary no longer applies
-                            // A mid-run steering doc summarized away may be injected again on the next touch.
-                            for (const name of [...steeringInMessages]) {
-                                const marker = `<steering name="${name}">`;
-                                if (messages.some((m) => typeof m.content === 'string' && m.content.includes(marker)))
-                                    continue;
-                                steeringInMessages.delete(name);
-                                steeringInjected.delete(name);
-                                steeringInjections--;
-                            }
-                            emit({
-                                type: 'compaction',
-                                droppedCount: result.droppedCount,
-                                savedTokens: result.savedTokens,
-                                summary: result.summary,
-                            });
-                        }
+                        await compactNow(totalForNextTurn);
                     }
                 }
             }
@@ -809,14 +950,9 @@ export class Agent {
             else {
                 reason = 'error';
                 const message = errorMessageOf(err);
-                if (reportedStreamError && /^No output generated/i.test(message)) {
-                    // The SDK follows a failed call with this generic error; the first one is the useful one.
-                    errorMessage = reportedStreamError;
-                }
-                else {
-                    errorMessage = message;
-                    emit({ type: 'error', error: errorMessage });
-                }
+                // The SDK follows a failed call with this generic error; the first one is the useful one.
+                errorMessage = reportedStreamError && /^No output generated/i.test(message) ? reportedStreamError : message;
+                emit({ type: 'error', error: errorMessage });
             }
         }
         // A run that ends between pushing the continue message and sending it (stop, timeout)
@@ -824,6 +960,8 @@ export class Agent {
         const lastMessage = messages[messages.length - 1];
         if (continuedText !== '' && lastMessage?.role === 'user' && lastMessage.content === CONTINUE_PROMPT)
             messages.pop();
+        else if (todoNudgeMessage && lastMessage === todoNudgeMessage)
+            messages.pop();
         // 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()) {
@@ -981,23 +1119,23 @@ export class Agent {
         if (rule?.action === 'deny')
             return { approved: false, note: rule.reason };
         if (rule?.action === 'allow')
-            return { approved: true };
+            return { approved: true, source: 'rule' };
         const forceAsk = rule?.action === 'ask';
         // Read-only tools the user chose not to be asked about (never a destructive one).
         if (!forceAsk && !def.destructive && this.config.autoApproveTools?.includes(def.name)) {
-            return { approved: true };
+            return { approved: true, source: 'list' };
         }
         // Memory writes the user chose not to be asked about. memory_forget is deleted data: always asked.
         if (!forceAsk && def.name === 'memory_write' && this.config.memoryAutoApproveWrites) {
-            return { approved: true };
+            return { approved: true, source: 'memory' };
         }
         // A plain command the user already said "always allow" for: exact match only (see command-allow.ts).
         if (!forceAsk && def.name === 'run_command' && this.config.autoApproveCommands?.length && isListedCommand(args, this.config.autoApproveCommands)) {
-            return { approved: true };
+            return { approved: true, source: 'always' };
         }
         const auto = this.config.auto ?? false;
         if (!forceAsk && auto && !(def.destructive && !this.config.allowDestructive)) {
-            return { approved: true };
+            return { approved: true, source: 'autonomous' };
         }
         let preview;
         if (def.previewApproval && ctx) {
@@ -1025,7 +1163,8 @@ export class Agent {
             const decision = await raceAbort(answered, abortSignal, 'aborted');
             if (decision === 'aborted')
                 return { approved: false };
-            return typeof decision === 'boolean' ? { approved: decision } : decision;
+            const answer = typeof decision === 'boolean' ? { approved: decision } : decision;
+            return answer.approved ? { ...answer, source: 'person' } : answer;
         }
         return { approved: false };
     }
@@ -1240,7 +1379,8 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
     // stable order so cache hits survive across runs that share state. The
     // environment block goes last: it is the part that varies per session.
     const steeringBlock = steeringSystem.map(wrapSteering).join('\n\n');
-    const blocks = [steeringBlock, instructionsBlock, extraInstructionsBlock, config.mcpInstructions ?? '', config.projectCommands ?? '', memoryBlock, skillsBlock, answersBlock, mapBlock, stackFactsBlock, envBlock].filter((b) => b.length > 0);
+    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 },

package/dist/agent/enhance-prompt.js

@@ -1,5 +1,6 @@
 import { generateText } from 'ai';
 import { createLanguageModel } from '../providers.js';
+import { withModelRetry } from './retry.js';
 import { stripThinkTags } from './think-tags.js';
 const ENHANCE_INSTRUCTIONS = 'Rewrite the request below so a coding agent can act on it: say what to change and where, name the expected result, and keep every file, symbol and constraint the user mentioned. ' +
     'Do not invent requirements or add steps the user did not ask for. Reply with the rewritten request only, no quotes, no code fences, no preface.';
@@ -15,7 +16,7 @@ export async function enhancePrompt(input, model, modelFactory = createLanguageM
     if (!model || !input.trim())
         return input;
     try {
-        const result = await generateText({ model: modelFactory(model), prompt: enhanceRequestPrompt(input, instruction) });
+        const result = await withModelRetry(() => generateText({ model: modelFactory(model), prompt: enhanceRequestPrompt(input, instruction), maxRetries: 0 }), { maxRetries: 2 });
         return clean(result.text) || input;
     }
     catch {

package/dist/agent/prompts.d.ts

@@ -29,6 +29,14 @@ export interface EnvironmentFacts {
  * uses in `run_command`: `cmd.exe` on Windows, `/bin/sh` elsewhere.
  */
 export declare function environmentBlock(facts: EnvironmentFacts): string;
+/**
+ * Extra instructions for model families that need them (Kilo chooses a whole prompt per family; Forge appends a
+ * block so the base prompt stays the same for prompt caching and mode switching, RB-27). Empty for the rest.
+ */
+export declare function modelGuidanceBlock(model: {
+    provider: string;
+    model: string;
+}): string;
 /**
  * System-prompt suffix appended when the agent runs in plan mode. The
  * model is told to emit a numbered plan as plain text and stop without
@@ -44,5 +52,12 @@ export declare const DEFAULT_PLAN_MODE_SUFFIX = "\n\nPLAN MODE \u2014 IMPORTANT:
 export declare const DEFAULT_SPEC_MODE_SUFFIX = "\n\nSPEC MODE \u2014 IMPORTANT:\n- You may use read-only tools (read_file, search_files, list_files, find_symbol, list_symbols, find_references) to explore the codebase as needed. Do NOT call write_file, edit_file, run_command, or any other tool.\n- When you have enough context, stop calling tools and produce your final answer as exactly three markdown sections, in this order, each starting with its own heading line:\n\n## requirements.md\n<user stories with EARS-syntax acceptance criteria, e.g. \"WHEN <trigger> THE SYSTEM SHALL <response>\". Number each requirement (1, 2, 3, ...) so tasks.md can reference them.>\n\n## design.md\n<technical design grounded in what you actually found in the codebase: data flow, schemas, interfaces, API endpoints, existing patterns to follow.>\n\n## tasks.md\n<sequenced implementation tasks as a markdown checklist. Write each task as \"- [ ] 1. Title\", numbering them 1, 2, 3, ...; indent subtasks as \"  - [ ] 1.1 Title\". Directly under each task add a line like \"_Requirements: 2.1, 3.2_\" referencing the requirement numbers it satisfies. Put every task and every subtask on its own line; never write a second checkbox on the same line as another.>\n\n- Do not proceed to implement anything. The user will review these three documents and decide whether to approve, edit, or cancel.\n";
 /** User message sent after a reply was cut off by the output-token limit. */
 export declare const CONTINUE_PROMPT = "Continue exactly where you stopped. Do not repeat anything you already wrote.";
+/** Added to the last step a run is allowed (tools are off for it); never kept in the conversation. */
+export declare const LAST_STEP_PROMPT: string;
+/** User message sent when a reply ends the turn while the model's own todo list still has open items. */
+export declare function todoNudgePrompt(open: ReadonlyArray<{
+    content: string;
+    status: string;
+}>): string;
 /** Spec-mode prompt override for architect phase 1 (see agent/architect.ts). */
 export declare const ARCHITECT_PROMPT = "\n\nYou are the ARCHITECT. Explore the codebase with your read-only tools, then\nreply with a precise change plan for a separate editor model to apply. Do not\nwrite code outside the plan. Your final message must contain only:\n\n1. Files to change \u2014 for each file, the exact edits (what to find, what to\n   replace it with, or the new code to add and where).\n2. New files \u2014 path and full contents.\n3. Verification \u2014 the commands to run to check the change.\n\nBe exact: the editor applies your plan literally and cannot ask questions.\n";

package/dist/agent/prompts.js

@@ -69,6 +69,26 @@ export function environmentBlock(facts) {
     ];
     return `<environment>\n${lines.join('\n')}\n</environment>`;
 }
+/** Model ids of families that tend to end a turn early or announce a tool call without making it. */
+const PERSISTENCE_FAMILIES = /minimax|kimi|moonshot|deepseek|qwen|qwq|glm|llama|mistral|mixtral|codestral|devstral|gpt-oss|grok|nemotron|phi-|gemma|ling-|trinity/i;
+/** Providers that serve local open-weight models, whatever their name. */
+const LOCAL_PROVIDERS = new Set(['ollama', 'lmstudio']);
+/**
+ * Extra instructions for model families that need them (Kilo chooses a whole prompt per family; Forge appends a
+ * block so the base prompt stays the same for prompt caching and mode switching, RB-27). Empty for the rest.
+ */
+export function modelGuidanceBlock(model) {
+    if (!LOCAL_PROVIDERS.has(model.provider) && !PERSISTENCE_FAMILIES.test(model.model))
+        return '';
+    return [
+        '<model-guidance>',
+        '- Keep working until the task is fully done before you end your turn; the user expects you to finish it, not to describe what you would do next.',
+        '- When you say you are about to call a tool, call it in the same reply. Never end a reply with "Now I will…" and no tool call.',
+        '- For a task with several steps, keep the list in `todo_write`: mark one item in_progress, and mark each item completed as soon as it is done.',
+        '- End your turn only when every item is done, when you need the user to decide something, or when the user asked you to stop.',
+        '</model-guidance>',
+    ].join('\n');
+}
 /**
  * System-prompt suffix appended when the agent runs in plan mode. The
  * model is told to emit a numbered plan as plain text and stop without
@@ -108,6 +128,20 @@ SPEC MODE — IMPORTANT:
 `;
 /** User message sent after a reply was cut off by the output-token limit. */
 export const CONTINUE_PROMPT = 'Continue exactly where you stopped. Do not repeat anything you already wrote.';
+/** Added to the last step a run is allowed (tools are off for it); never kept in the conversation. */
+export const LAST_STEP_PROMPT = '[Automatic note by Forge, not a message from the user.]\n' +
+    'This is the last step this run is allowed, and tools are turned off for it. Reply with text only, to the user: ' +
+    'say briefly that the step limit was reached, what is done, and what is left to do, so they can press Continue.';
+/** User message sent when a reply ends the turn while the model's own todo list still has open items. */
+export function todoNudgePrompt(open) {
+    const items = open.map((t) => `- [${t.status}] ${t.content}`).join('\n');
+    return ('[Automatic check by Forge, not a message from the user.]\n' +
+        `Your todo list still has open items:\n${items}\n\n` +
+        "The user's own instructions come first. If the user asked you to stop or wait, or you need their answer, " +
+        'do not continue: leave the open items as they are and end with one short sentence to the user, addressed as "you" (do not mention this check). ' +
+        'If an item no longer applies, update the list with `todo_write`. ' +
+        'Otherwise you stopped before finishing: carry on with the next item now, using your tools.');
+}
 /** Spec-mode prompt override for architect phase 1 (see agent/architect.ts). */
 export const ARCHITECT_PROMPT = `
 

package/dist/agent/retry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * When a failed model call is worth repeating, and how long to wait first. Patterns follow Kilo's
+ * session/retry.ts: status codes, the provider's own retry-after headers, and the wordings providers and
+ * Node use for overloads and dropped connections.
+ */
+export declare const DEFAULT_PROVIDER_RETRIES = 5;
+export declare const DEFAULT_RETRY_BASE_MS = 2000;
+export type RetryDecision = {
+    retry: true;
+    delayMs: number;
+    message: string;
+} | {
+    retry: false;
+};
+/** The first line of the error a person should see. */
+export declare function errorSummary(err: unknown): string;
+export declare function isContextOverflowError(err: unknown): boolean;
+/**
+ * Whether to retry after failed attempt number `attempt` (1-based) and how long to wait.
+ * `random` in [0, 1) adds up to 25% jitter to the back-off.
+ */
+export declare function retryDecision(err: unknown, attempt: number, baseDelayMs?: number, random?: number): RetryDecision;
+/** True when the failure looks like no network (DNS or route gone), not a busy or resetting server. */
+export declare function isDisconnected(err: unknown): boolean;
+/** Opens a TCP connection to a few well-known hosts by address (no DNS needed); true when any of them answers. */
+export declare function defaultNetworkProbe(): Promise<boolean>;
+/**
+ * Poll `probe` every `pollMs` until it reports a network, the signal fires, or `budgetMs` runs out.
+ * Returns how long it waited and why it stopped.
+ */
+export declare function waitForNetwork(probe: () => Promise<boolean>, opts: {
+    pollMs: number;
+    budgetMs: number;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    outcome: 'online' | 'aborted' | 'gave_up';
+    waitedMs: number;
+}>;
+/**
+ * Run a one-shot model call (generateText with `maxRetries: 0`) under the agent loop's retry policy.
+ * Throws the failure itself when it is not worth retrying, when the retries are used up, or on abort.
+ */
+export declare function withModelRetry<T>(call: () => Promise<T>, opts?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    abortSignal?: AbortSignal;
+    onRetry?: (attempt: number, delayMs: number, reason: string) => void;
+}): Promise<T>;
+/** Resolves after `ms`, or early (to 'aborted') when the signal fires; leaves no listener behind (RB-36). */
+export declare function waitOrAbort(ms: number, signal: AbortSignal | undefined): Promise<'waited' | 'aborted'>;