@ikarmic/forge-core 4.4.0 → 5.0.0

package/LICENSE

@@ -1,21 +1,44 @@
-MIT License
-
-Copyright (c) 2025 IKarmic
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+IKarmic Forge Core: Proprietary License
+
+Copyright (c) 2025-2026 IKarmic. All rights reserved.
+
+This license covers "@ikarmic/forge-core" version 5.0.0 and later
+(the "Software"). Earlier versions (4.5.0 and before) were released under
+the MIT License and stay under it.
+
+1. Grant. IKarmic grants you a non-exclusive, non-transferable, royalty-free
+   licence to install and run the Software, in the form distributed by
+   IKarmic, as a dependency of the IKarmic Forge VS Code extension and the
+   IKarmic Forge command line tool (the "Forge Clients"), for any purpose,
+   including commercial use.
+
+2. Restrictions. You may not, and may not let others:
+   a. copy, modify, translate or create derivative works of the Software;
+   b. redistribute, sublicense, sell, lease or host the Software, alone or
+      bundled in another product, except as part of an unmodified Forge
+      Client distributed by IKarmic;
+   c. reverse engineer, decompile or disassemble the Software, except to the
+      extent applicable law forbids this restriction;
+   d. use the Software to build a product or service that competes with the
+      Forge Clients or with IKarmic's paid editions;
+   e. remove or alter any copyright, licence or attribution notice.
+
+3. Enterprise features. Features marked as enterprise features need a valid
+   licence key from IKarmic. Using them without one is not permitted.
+
+4. Ownership. IKarmic and its licensors keep all rights not granted here.
+   No right is granted by implication or estoppel.
+
+5. Open-source Forge Clients. The Forge Clients' own source code is licensed
+   separately under AGPL-3.0-only (see the LICENSE and NOTICE files of the
+   Forge Clients). That licence does not extend to this Software, and
+   nothing in it lets you redistribute this Software.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND. IKARMIC IS NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+   ARISING FROM THE SOFTWARE OR ITS USE, TO THE EXTENT THE LAW ALLOWS.
+
+7. Termination. This licence ends automatically if you break it. On
+   termination you must stop using and delete all copies of the Software.
+
+Contact: ikarmicaiss@gmail.com

package/README.md

@@ -14,7 +14,7 @@ The agent engine for [IKarmic AI Forge](https://github.com/ikarmic/forge). Share
 - **Cost tracking**: `lookupPricing` + `computeCostUsd` against a built-in pricing table; surfaced as `cost` events and `costUsd` on `AgentRunResult`.
 - **Secret redaction**: `redact()` scrubs provider keys, JWTs, PEM keys, and `.env`-style secrets from tool output before the model sees them.
 - **Tool result cache**: `ToolResultCache` (LRU + TTL, never caches destructive tools) survives across turns within a session.
-- **Project memory**: `buildMemoryBlock()` auto-loads `.forge/MEMORY.md` into the system prompt; `memory_read` / `memory_write` tools let the agent record conventions mid-run.
+- **Project memory**: `buildMemoryBlock()` auto-loads `.forge/MEMORY.md` into the system prompt; `memory_read` / `memory_write` / `memory_forget` tools let the agent record and retire conventions mid-run (typed sections, relevance-ranked injection, stale-ref markers).
 - **Plan mode**: `AgentConfig.planMode` runs a single-turn, tool-free pass that emits a numbered plan as text. Pair with an approve/edit/cancel flow.
 - **Context compaction**: opt-in summarization of older turns when approaching the model's context window. `AgentConfig.enableCompaction` toggles it; the rest are knobs.
 - **Skills system**: `discoverSkills()` finds `SKILL.md` files in `./skills/`, `./.forge/skills/`, `~/.forge/skills/`. `selectSkills()` + `composeSkillsPrompt()` score and inject the top matches for the current task.
@@ -154,4 +154,4 @@ MCP tools appear in the agent's prompt with fully-qualified names like `mcp__fil
 
 ## License
 
-MIT
+Proprietary, free to run with the Forge extension and CLI. See [LICENSE](LICENSE). Versions 4.5.0 and earlier stay MIT.

package/dist/agent/agent.d.ts

@@ -58,4 +58,3 @@ export declare class Agent {
  * we don't want to fail just because the user typed a stale name.
  */
 export declare function applySandbox(tools: ToolDefinition[], sandbox: ToolSandbox | undefined): ToolDefinition[];
-//# sourceMappingURL=agent.d.ts.map

package/dist/agent/agent.js

@@ -11,8 +11,11 @@ import { createFileAuditSink } from '../policy/audit.js';
 import { applyPolicy, getOrgPolicy } from '../policy/policy.js';
 import { createBrowserTools } from '../tools/browser-tools.js';
 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 { DEFAULT_VERIFY_RETRIES, failureMessage, runVerification } from './verify.js';
+import { LoopGuard, resultKeyOf } from './loop-guard.js';
 import { isListedCommand } from '../tools/command-allow.js';
 import { createLanguageModel } from '../providers.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
@@ -22,17 +25,18 @@ import { redact } from '../tools/redact.js';
 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 { attachmentParts, formatBytes, mediaPartTokens } from '../attachments.js';
 import { CONTINUE_PROMPT, DEFAULT_PLAN_MODE_SUFFIX, DEFAULT_SPEC_MODE_SUFFIX, DEFAULT_SYSTEM_PROMPT } from './prompts.js';
 /** Read-only tool names whose output flows through the redactor. */
 const DEFAULT_MAX_CONTINUATIONS = 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. */
-const STEERING_FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file']);
+const STEERING_FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file', 'edit_notebook']);
 /** Tools that change a file, so auto-lint checks their `path` afterwards. */
-const FILE_WRITE_TOOLS = new Set(['write_file', 'edit_file']);
+const FILE_WRITE_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook']);
 /** Pure reads whose results may be reused within a run. Every other tool invalidates the cache. */
-const CACHEABLE_TOOLS = new Set(['read_file', 'read_image', 'list_files', 'search_files', 'find_symbol', 'list_symbols', 'find_references', 'codebase_search', 'memory_read', 'fetch_url']);
+const CACHEABLE_TOOLS = new Set(['read_file', 'read_image', 'list_files', 'search_files', 'find_symbol', 'list_symbols', 'find_references', 'codebase_search', 'memory_read', 'fetch_url', 'web_search']);
 /**
  * The agent: orchestrates the model + tool loop. One Agent instance is
  * single-use; create a new one per user task.
@@ -61,11 +65,17 @@ export class Agent {
             this.browser = new BrowserSession(config.browser === true ? {} : config.browser);
             allTools.push(...createBrowserTools(this.browser));
         }
+        const github = config.github === true ? githubFromEnv() : config.github;
+        if (github)
+            allTools.push(...createGitHubTools(github));
+        const webSearch = config.webSearch === true ? webSearchFromEnv() : config.webSearch;
+        if (webSearch)
+            allTools.push(createWebSearchTool(webSearch));
         if (config.semanticSearch) {
             allTools.push(createCodebaseSearchTool(config.semanticSearch.embedder ?? embedderFromEnv()));
         }
         const memoryFiltered = config.disableMemory
-            ? allTools.filter((t) => t.name !== 'memory_read' && t.name !== 'memory_write')
+            ? allTools.filter((t) => t.name !== 'memory_read' && t.name !== 'memory_write' && t.name !== 'memory_forget')
             : allTools;
         const sandboxedTools = applySandbox(memoryFiltered, config.toolSandbox);
         this.tools = this.wrapToolsWithCache(sandboxedTools, config.cacheSize, config.cacheTtlMs, config.disableCache);
@@ -86,7 +96,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', 'run_command']);
+            return new Set(['write_file', 'edit_file', 'edit_notebook', 'run_command']);
         }
         return new Set(cfg);
     }
@@ -163,6 +173,13 @@ export class Agent {
         const messages = options.history
             ? [...options.history, { role: 'user', content: userContent }]
             : await buildInitialMessages(this.config, options.task, this.skills, startSteering.system, 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] = {
+                role: 'user',
+                content: [{ type: 'text', text: userContent }, ...attachmentParts(options.attachments)],
+            };
+        }
         // 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
@@ -200,6 +217,14 @@ export class Agent {
         let model = modelFactory(currentModelConfig);
         let stepPricing = this.pricing;
         let lastToolNames = [];
+        // Stops a run that repeats one identical tool call (off unless `loopGuardThreshold` is set).
+        const loopGuard = new LoopGuard(this.config.loopGuardThreshold ?? 0);
+        let loopTripped;
+        // Every call outcome feeds the guard (results, errors, invalid or denied calls), so a different call in between resets the streak.
+        const trackLoop = (tool, args, outcome) => {
+            if (loopGuard.record(tool, args, resultKeyOf(outcome)) && !loopTripped)
+                loopTripped = { tool, count: loopGuard.streak };
+        };
         // Verify loop state: only run checks when the run actually edited files.
         let editedSinceVerify = false;
         const editedFiles = new Set();
@@ -218,6 +243,7 @@ export class Agent {
             parentModel: this.config.model,
             ...(this.config.commandRunner ? { commandRunner: this.config.commandRunner } : {}),
             ...(abortSignal ? { abortSignal } : {}),
+            ...(this.config.memoryMaxBodyChars !== undefined ? { memoryMaxBodyChars: this.config.memoryMaxBodyChars } : {}),
         };
         // Emit initial cache stats so the UI knows the cache is wired up.
         emit({ type: 'cache_stats', ...this.cache.getStats() });
@@ -466,19 +492,22 @@ export class Agent {
                     if (!def) {
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, `Unknown tool: ${call.toolName}`));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: `Unknown tool`, isError: true });
+                        trackLoop(call.toolName, call.input, 'unknown tool');
                         continue;
                     }
                     const argsParsed = def.parameters.safeParse(call.input);
                     if (!argsParsed.success) {
                         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;
                     }
-                    const approval = await this.requestApproval(def, call.toolCallId, argsParsed.data, abortSignal);
+                    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) {
                         const denial = approval.note ? `Denied by user. ${approval.note}` : `Denied by user.`;
+                        trackLoop(call.toolName, argsParsed.data, denial);
                         currentToolResults.push(toolResult(call.toolCallId, call.toolName, denial));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: denial, isError: false });
                         continue;
@@ -490,6 +519,7 @@ export class Agent {
                         const edited = def.parameters.safeParse(approval.args);
                         if (!edited.success) {
                             const message = `Invalid edited arguments for ${call.toolName}: ${edited.error.message}`;
+                            trackLoop(call.toolName, approval.args, message);
                             currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                             emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
                             continue;
@@ -545,7 +575,7 @@ export class Agent {
                             redactedCount = scrubbed.count;
                         }
                         this.audit?.record({ event: 'tool_result', tool: call.toolName, isError: false, durationMs: Date.now() - toolStartedAt }, auditCtx);
-                        if (call.toolName === 'write_file' || call.toolName === 'edit_file')
+                        if (FILE_WRITE_TOOLS.has(call.toolName))
                             editedSinceVerify = true;
                         const editedPath = toolArgs.path;
                         if (FILE_WRITE_TOOLS.has(call.toolName) && typeof editedPath === 'string')
@@ -569,6 +599,7 @@ export class Agent {
                                     : { result: finalResult, userNote: approval.note };
                         }
                         currentToolResults.push(toolResult(call.toolCallId, call.toolName, finalResult));
+                        trackLoop(call.toolName, toolArgs, finalResult);
                         if (STEERING_FILE_TOOLS.has(call.toolName)) {
                             const touched = toolArgs.path;
                             if (typeof touched === 'string')
@@ -600,6 +631,7 @@ export class Agent {
                         const message = errorMessageOf(err);
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
+                        trackLoop(call.toolName, toolArgs, `error:${message}`);
                         if (this.hooks) {
                             await this.hooks.dispatch({
                                 type: 'PostToolUse',
@@ -619,6 +651,11 @@ export class Agent {
                 }
                 for (const m of toolResultMessages)
                     messages.push(m);
+                if (loopTripped) {
+                    emit({ type: 'loop_detected', tool: loopTripped.tool, count: loopTripped.count });
+                    reason = 'loop_detected';
+                    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 = [];
@@ -846,11 +883,15 @@ export class Agent {
             return { ...t, execute: invalidating };
         });
     }
-    async requestApproval(def, id, args, abortSignal) {
+    async requestApproval(def, id, args, abortSignal, ctx) {
         // Read-only tools the user chose not to be asked about (never a destructive one).
         if (!def.destructive && this.config.autoApproveTools?.includes(def.name)) {
             return { approved: true };
         }
+        // Memory writes the user chose not to be asked about. memory_forget is deleted data: always asked.
+        if (def.name === 'memory_write' && this.config.memoryAutoApproveWrites) {
+            return { approved: true };
+        }
         // A plain command the user already said "always allow" for: exact match only (see command-allow.ts).
         if (def.name === 'run_command' && this.config.autoApproveCommands?.length && isListedCommand(args, this.config.autoApproveCommands)) {
             return { approved: true };
@@ -859,12 +900,22 @@ export class Agent {
         if (auto && !(def.destructive && !this.config.allowDestructive)) {
             return { approved: true };
         }
+        let preview;
+        if (def.previewApproval && ctx) {
+            try {
+                preview = (await def.previewApproval(args, ctx)) || undefined;
+            }
+            catch {
+                // A failed preview never blocks the approval prompt.
+            }
+        }
         const request = {
             name: def.name,
             id,
             args,
             destructive: def.destructive === true,
             description: def.description,
+            ...(preview ? { preview } : {}),
         };
         if (this.config.approve) {
             // Stop must work while a prompt is open: an unanswered approval never resolves on its own,
@@ -907,12 +958,12 @@ function toAiSdkTools(tools) {
     return out;
 }
 function toolResult(toolCallId, toolName, result) {
-    // Detect multimodal content (read_image returns a `dataUrl` +
-    // `mime`). When found, attach the image so vision-capable models can
-    // actually see it instead of just reading the base64 string. Providers
-    // that don't support this will gracefully fall back to the text value.
-    const image = extractImageAttachment(result);
-    if (image) {
+    // Detect multimodal content (read_image returns an image, read_file a PDF, each as
+    // `dataUrl` + `mime`). When found, attach the bytes so vision and document-capable
+    // models see them instead of a base64 string. Providers that don't support this
+    // gracefully fall back to the text value.
+    const media = extractMediaAttachment(result);
+    if (media) {
         return {
             type: 'tool-result',
             toolCallId,
@@ -920,8 +971,10 @@ function toolResult(toolCallId, toolName, result) {
             output: {
                 type: 'content',
                 value: [
-                    { type: 'text', text: image.summary },
-                    { type: 'image-data', data: image.dataUrl, mediaType: image.mime },
+                    { type: 'text', text: media.summary },
+                    media.mime.startsWith('image/')
+                        ? { type: 'image-data', data: media.dataUrl, mediaType: media.mime }
+                        : { type: 'file', data: { type: 'data', data: media.base64 }, mediaType: media.mime, ...(media.filename ? { filename: media.filename } : {}) },
                 ],
             },
         };
@@ -932,11 +985,10 @@ function toolResultError(toolCallId, toolName, message) {
     return { type: 'tool-result', toolCallId, toolName, output: { type: 'error-text', value: message } };
 }
 /**
- * Inspect a tool result for multimodal content. Returns the attachment
- * to include in `experimental_content` if the result looks like an
- * image (dataUrl + mime present); null otherwise.
+ * Inspect a tool result for multimodal content: an image or a PDF (dataUrl + mime
+ * present). Returns null otherwise.
  */
-function extractImageAttachment(result) {
+function extractMediaAttachment(result) {
     if (!result || typeof result !== 'object')
         return null;
     const r = result;
@@ -946,19 +998,17 @@ function extractImageAttachment(result) {
         return null;
     if (!dataUrl.startsWith('data:'))
         return null;
+    if (!mime.startsWith('image/') && mime !== 'application/pdf')
+        return null;
     // Best-effort summary line so the model has something textual
-    // alongside the image describing what it's looking at.
+    // alongside the media describing what it's looking at.
     const bytes = typeof r.bytes === 'number' ? r.bytes : 0;
     const path = typeof r.path === 'string' ? r.path : '<unknown>';
-    const summary = `Image attached: ${mime} (${formatBytes(bytes)}) at ${path}`;
-    return { dataUrl, mime, summary };
-}
-function formatBytes(n) {
-    if (n < 1024)
-        return `${n} B`;
-    if (n < 1024 * 1024)
-        return `${(n / 1024).toFixed(1)} KB`;
-    return `${(n / 1024 / 1024).toFixed(2)} MB`;
+    const what = mime.startsWith('image/') ? 'Image' : 'Document';
+    const summary = `${what} attached: ${mime} (${formatBytes(bytes)}) at ${path}`;
+    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 };
 }
 function errorMessageOf(err) {
     if (err instanceof Error)
@@ -1014,7 +1064,7 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
     let memoryBlock = '';
     if (!config.disableMemory) {
         try {
-            memoryBlock = await buildMemoryBlock(cwd, config.memoryInjectionBudget);
+            memoryBlock = await buildMemoryBlock(cwd, config.memoryInjectionBudget, { task });
         }
         catch {
             // Memory load failure shouldn't kill a run: just skip.
@@ -1081,9 +1131,11 @@ function estimateNextPromptTokens(messages) {
                     if (typeof text === 'string')
                         total += Math.ceil(text.length / 4);
                 }
+                else {
+                    total += mediaPartTokens(part);
+                }
             }
         }
     }
     return total;
 }
-//# sourceMappingURL=agent.js.map

package/dist/agent/architect.d.ts

@@ -4,6 +4,7 @@
  * normal tools (phase 2). Two ordinary Agent runs; the loop is unchanged.
  */
 import type { ModelMessage } from 'ai';
+import type { Attachment } from '../attachments.js';
 import type { AgentConfig, AgentEvent, AgentRunResult, ModelConfig } from '../types.js';
 export interface ArchitectOptions {
     task: string;
@@ -12,6 +13,8 @@ export interface ArchitectOptions {
     editorModel: ModelConfig;
     /** Prior conversation, given to both phases. */
     history?: ModelMessage[];
+    /** Files attached to this turn, given to both phases. */
+    attachments?: Attachment[];
     /** Interactive approval of the plan. Omit to apply it without asking (auto mode). */
     approvePlan?: (plan: string) => Promise<{
         approved: boolean;
@@ -42,4 +45,3 @@ export declare function editorLimits(base: AgentConfig, architect: {
 };
 export declare function editorTask(task: string, plan: string): string;
 export declare function runArchitect(opts: ArchitectOptions): Promise<AgentRunResult>;
-//# sourceMappingURL=architect.d.ts.map

package/dist/agent/architect.js

@@ -54,6 +54,7 @@ export async function runArchitect(opts) {
     const runOptions = (task, history) => ({
         task,
         ...(history ? { history } : {}),
+        ...(opts.attachments && opts.attachments.length > 0 ? { attachments: opts.attachments } : {}),
         ...(opts.onEvent ? { onEvent: opts.onEvent } : {}),
         ...(opts.abortSignal ? { abortSignal: opts.abortSignal } : {}),
     });
@@ -90,4 +91,3 @@ export async function runArchitect(opts) {
         costKnown: architect.costKnown && editor.costKnown,
     };
 }
-//# sourceMappingURL=architect.js.map

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

@@ -13,4 +13,3 @@ 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[];
-//# sourceMappingURL=cache-hints.d.ts.map

package/dist/agent/cache-hints.js

@@ -28,4 +28,3 @@ export function applyCacheHints(messages, model) {
         out[last] = withHint(out[last], hint);
     return out;
 }
-//# sourceMappingURL=cache-hints.js.map

package/dist/agent/cost-router.d.ts

@@ -9,4 +9,3 @@ export declare function createExploreEditRouter(models: {
     strong: ModelConfig;
     cheap: ModelConfig;
 }): ModelRouter;
-//# sourceMappingURL=cost-router.d.ts.map

package/dist/agent/cost-router.js

@@ -8,6 +8,8 @@ const READ_ONLY_TOOLS = new Set([
     'read_image',
     'memory_read',
     'fetch_url',
+    'github_pr_read',
+    'web_search',
 ]);
 export function createExploreEditRouter(models) {
     return ({ iteration, lastToolNames }) => {
@@ -16,4 +18,3 @@ export function createExploreEditRouter(models) {
         return lastToolNames.every((n) => READ_ONLY_TOOLS.has(n)) ? models.cheap : models.strong;
     };
 }
-//# sourceMappingURL=cost-router.js.map

package/dist/agent/enhance-prompt.d.ts

@@ -0,0 +1,7 @@
+import type { LanguageModel } from 'ai';
+import type { ModelConfig } from '../types.js';
+/**
+ * Rewrite a draft chat message into a clearer request using `model` (typically the cheap model).
+ * Never throws: an empty input, a missing model, a model error or an empty reply all return `input` unchanged.
+ */
+export declare function enhancePrompt(input: string, model: ModelConfig | undefined, modelFactory?: (cfg: ModelConfig) => LanguageModel): Promise<string>;

package/dist/agent/enhance-prompt.js

@@ -0,0 +1,30 @@
+import { generateText } from 'ai';
+import { createLanguageModel } from '../providers.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.';
+/**
+ * Rewrite a draft chat message into a clearer request using `model` (typically the cheap model).
+ * Never throws: an empty input, a missing model, a model error or an empty reply all return `input` unchanged.
+ */
+export async function enhancePrompt(input, model, modelFactory = createLanguageModel) {
+    if (!model || !input.trim())
+        return input;
+    try {
+        const result = await generateText({ model: modelFactory(model), prompt: `${ENHANCE_INSTRUCTIONS}\n\nRequest:\n${input}` });
+        return clean(result.text) || input;
+    }
+    catch {
+        return input;
+    }
+}
+function clean(text) {
+    // Reasoning models put an inline <think> block in the reply; only what follows it is the rewrite.
+    return stripThinkTags(text)
+        .trim()
+        .replace(/^```[a-z]*\s*\n?/i, '')
+        .replace(/\n?```$/, '')
+        .trim()
+        .replace(/^["'“”](.*)["'“”]$/s, '$1')
+        .trim();
+}

package/dist/agent/index.d.ts

@@ -1,3 +1,2 @@
 export { Agent } from './agent.js';
 export { DEFAULT_SYSTEM_PROMPT } from './prompts.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.js

@@ -1,3 +1,2 @@
 export { Agent } from './agent.js';
 export { DEFAULT_SYSTEM_PROMPT } from './prompts.js';
-//# sourceMappingURL=index.js.map

package/dist/agent/loop-guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Detects a run that is stuck repeating one tool call. A call counts as a repeat only when the tool
+ * name, the arguments (key order ignored) and the result all match the previous call, so re-reading
+ * a file after an edit changed it never trips the guard.
+ */
+export declare class LoopGuard {
+    private lastKey;
+    private count;
+    private readonly threshold;
+    /**
+     * `threshold` identical calls in a row trip the guard; 0 turns it off. A threshold of 1 would stop
+     * every run at its first call, so it counts as 2.
+     */
+    constructor(threshold: number);
+    /** Length of the current run of identical calls. */
+    get streak(): number;
+    /** Record a finished call. Returns true when the streak has reached the threshold. */
+    record(toolName: string, args: unknown, resultKey: string): boolean;
+}
+/** A short stable key for a tool result, so the guard never holds large outputs in memory. */
+export declare function resultKeyOf(value: unknown): string;

package/dist/agent/loop-guard.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+/**
+ * Detects a run that is stuck repeating one tool call. A call counts as a repeat only when the tool
+ * name, the arguments (key order ignored) and the result all match the previous call, so re-reading
+ * a file after an edit changed it never trips the guard.
+ */
+export class LoopGuard {
+    lastKey;
+    count = 0;
+    threshold;
+    /**
+     * `threshold` identical calls in a row trip the guard; 0 turns it off. A threshold of 1 would stop
+     * every run at its first call, so it counts as 2.
+     */
+    constructor(threshold) {
+        this.threshold = threshold >= 1 ? Math.max(2, threshold) : 0;
+    }
+    /** Length of the current run of identical calls. */
+    get streak() {
+        return this.count;
+    }
+    /** Record a finished call. Returns true when the streak has reached the threshold. */
+    record(toolName, args, resultKey) {
+        if (this.threshold <= 0)
+            return false;
+        const key = `${toolName}\u0000${canonical(args)}\u0000${resultKey}`;
+        this.count = key === this.lastKey ? this.count + 1 : 1;
+        this.lastKey = key;
+        return this.count >= this.threshold;
+    }
+}
+/** A short stable key for a tool result, so the guard never holds large outputs in memory. */
+export function resultKeyOf(value) {
+    const text = typeof value === 'string' ? value : (JSON.stringify(value) ?? '');
+    return createHash('sha1').update(text).digest('hex');
+}
+function canonical(value) {
+    return JSON.stringify(value, (_k, v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : v);
+}

package/dist/agent/prompts.d.ts

@@ -22,4 +22,3 @@ export declare const DEFAULT_SPEC_MODE_SUFFIX = "\n\nSPEC MODE \u2014 IMPORTANT:
 export declare const CONTINUE_PROMPT = "Continue exactly where you stopped. Do not repeat anything you already wrote.";
 /** 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";
-//# sourceMappingURL=prompts.d.ts.map

package/dist/agent/prompts.js

@@ -78,4 +78,3 @@ write code outside the plan. Your final message must contain only:
 
 Be exact: the editor applies your plan literally and cannot ask questions.
 `;
-//# sourceMappingURL=prompts.js.map

package/dist/agent/think-tags.d.ts

@@ -26,4 +26,3 @@ export declare class ThinkSplitter {
 }
 /** The visible answer: everything outside `<think>…</think>` (an unclosed block runs to the end). */
 export declare function stripThinkTags(text: string): string;
-//# sourceMappingURL=think-tags.d.ts.map

package/dist/agent/think-tags.js

@@ -81,4 +81,3 @@ export function stripThinkTags(text) {
         .replace(/<think>[\s\S]*$/, '')
         .trim();
 }
-//# sourceMappingURL=think-tags.js.map

package/dist/agent/verify.d.ts

@@ -14,4 +14,3 @@ export interface VerifyOutcome {
 export declare function runVerification(config: VerifyConfig, ctx: ToolContext, editedFiles?: string[]): Promise<VerifyOutcome>;
 /** The message shown to the model after a failed verification. */
 export declare function failureMessage(failures: VerifyFailure[]): string;
-//# sourceMappingURL=verify.d.ts.map

package/dist/agent/verify.js

@@ -53,4 +53,3 @@ export function failureMessage(failures) {
 function tail(text) {
     return text.length <= MAX_FAILURE_CHARS ? text : `...\n${text.slice(text.length - MAX_FAILURE_CHARS)}`;
 }
-//# sourceMappingURL=verify.js.map

package/dist/ai-comments/index.d.ts

@@ -21,4 +21,3 @@ export interface AiCommentFile {
 }
 /** Build the agent task for the files that carry AI comments. */
 export declare function aiCommentTask(files: AiCommentFile[], action: 'change' | 'question'): string;
-//# sourceMappingURL=index.d.ts.map

package/dist/ai-comments/index.js

@@ -38,4 +38,3 @@ export function aiCommentTask(files, action) {
         ? `Apply the instructions left as AI comments in these files, then remove the AI comments you resolved:\n\n${body}`
         : `Answer the questions left as AI comments in these files. Do not edit any file:\n\n${body}`;
 }
-//# sourceMappingURL=index.js.map