@ikarmic/forge-core 5.0.0 → 5.1.1

package/README.md

@@ -1,6 +1,6 @@
 # `@ikarmic/forge-core`
 
-The agent engine for [IKarmic AI Forge](https://github.com/ikarmic/forge). Shared by the CLI and the planned VS Code extension.
+The agent engine for [IKarmic AI Forge](https://github.com/ikarmicai/ikarmic-forge). Shared by the CLI and the VS Code extension.
 
 ## What's in the box
 

package/dist/agent/agent.d.ts

@@ -15,6 +15,8 @@ export declare class Agent {
     private readonly checkpoints;
     private readonly browser;
     private readonly audit;
+    private readonly permissionRules;
+    private todoList;
     constructor(config: AgentConfig);
     /** Files whose modification should trigger a pre-tool checkpoint. */
     private get captureBeforeTools();
@@ -42,6 +44,12 @@ export declare class Agent {
      * we never want to "skip".
      */
     private wrapToolsWithCache;
+    /**
+     * What the permission rules say about one tool call: `allow` (every target allowed), `deny` (any target denied,
+     * with the reason the model sees), `ask` (a target asks, a `.env` file is read, or a command leaves the workspace),
+     * or undefined when no rule applies and the normal approval flow decides.
+     */
+    private decidePermission;
     private requestApproval;
     /**
      * Build the default LLM-based summarizer for compaction. Picks the

package/dist/agent/agent.js

@@ -1,6 +1,11 @@
+import { existsSync } from 'node:fs';
+import { release } from 'node:os';
+import path from 'node:path';
 import { streamText } from 'ai';
 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';
@@ -17,6 +22,7 @@ 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 { compilePermissionRules, evaluatePermission, isSensitiveFile, permissionFor, touchesOutsideCwd, } from '../tools/permission-rules.js';
 import { createLanguageModel } from '../providers.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
 import { ToolResultCache, cachedExecute } from '../tools/result-cache.js';
@@ -26,15 +32,16 @@ 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';
+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';
 /** 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', 'edit_notebook']);
+const STEERING_FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file', 'edit_notebook', 'apply_patch']);
 /** Tools that change a file, so auto-lint checks their `path` afterwards. */
-const FILE_WRITE_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook']);
+const FILE_WRITE_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch']);
 /** 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', 'web_search']);
 /**
@@ -52,12 +59,16 @@ export class Agent {
     checkpoints;
     browser;
     audit;
+    permissionRules;
+    todoList = [];
     constructor(config) {
         // Organization policy first: everything below sees the already-tightened config.
         const policy = config.policy === undefined ? getOrgPolicy()?.policy : (config.policy ?? undefined);
         config = applyPolicy(config, policy);
         this.audit = config.audit ?? (policy?.audit?.enabled ? createFileAuditSink(policy.audit.file) : undefined);
         this.config = config;
+        this.permissionRules = compilePermissionRules(config.permissionRules);
+        this.todoList = config.initialTodos ? [...config.initialTodos] : [];
         const allTools = (config.disableBuiltins
             ? [...(config.extraTools ?? [])]
             : [...BUILTIN_TOOLS, ...(config.extraTools ?? [])]);
@@ -72,12 +83,19 @@ export class Agent {
         if (webSearch)
             allTools.push(createWebSearchTool(webSearch));
         if (config.semanticSearch) {
-            allTools.push(createCodebaseSearchTool(config.semanticSearch.embedder ?? embedderFromEnv()));
+            allTools.push(createCodebaseSearchTool(config.semanticSearch.embedder ?? embedderFromEnv(), {
+                ...(config.semanticSearch.extensions ? { extensions: config.semanticSearch.extensions } : {}),
+                ...(config.semanticSearch.minScore !== undefined ? { minScore: config.semanticSearch.minScore } : {}),
+                ...(config.semanticSearch.defaultLimit ? { defaultLimit: config.semanticSearch.defaultLimit } : {}),
+            }));
         }
         const memoryFiltered = config.disableMemory
             ? allTools.filter((t) => t.name !== 'memory_read' && t.name !== 'memory_write' && t.name !== 'memory_forget')
             : allTools;
-        const sandboxedTools = applySandbox(memoryFiltered, config.toolSandbox);
+        // `ask_user` is offered only when a surface can answer and the run is not autonomous.
+        const canAsk = Boolean(config.askUser) && !config.auto && !config.disableAskUser;
+        const askFiltered = canAsk ? memoryFiltered : memoryFiltered.filter((t) => t.name !== 'ask_user');
+        const sandboxedTools = applySandbox(askFiltered, config.toolSandbox);
         this.tools = this.wrapToolsWithCache(sandboxedTools, config.cacheSize, config.cacheTtlMs, config.disableCache);
         this.cache = new ToolResultCache({
             maxSize: config.disableCache ? 0 : (config.cacheSize ?? 256),
@@ -96,7 +114,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', 'run_command']);
+            return new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command']);
         }
         return new Set(cfg);
     }
@@ -235,12 +253,30 @@ export class Agent {
         let verification;
         // Infinite output: text of a reply that hit the output limit and is being continued.
         let continuedText = '';
+        // The answer text of the step now streaming, kept so a Stop does not throw away what was already said.
+        let partialStepText = '';
         let continuations = 0;
         const maxContinuations = this.config.maxContinuations ?? DEFAULT_MAX_CONTINUATIONS;
         const ctx = {
             cwd: this.config.cwd ?? process.cwd(),
             auto: this.config.auto ?? false,
             parentModel: this.config.model,
+            ...(this.config.subAgentModel ? { subAgentModel: this.config.subAgentModel } : {}),
+            ...(this.config.backgroundAgents ? { background: this.config.backgroundAgents } : {}),
+            ...(this.config.autoApproveTools ? { autoApproveTools: this.config.autoApproveTools } : {}),
+            ...(this.config.permissionRules ? { permissionRules: this.config.permissionRules } : {}),
+            ...(this.config.toolSandbox ? { toolSandbox: this.config.toolSandbox } : {}),
+            shownFolderInstructions: new Set(),
+            ...(this.config.maxToolOutputChars ? { maxOutputChars: this.config.maxToolOutputChars } : {}),
+            ...(this.config.askUser ? { askUser: this.config.askUser } : {}),
+            ...(this.config.askBudget ? { askBudget: this.config.askBudget } : {}),
+            todos: {
+                get: () => this.todoList,
+                set: (todos) => {
+                    this.todoList = todos;
+                    emit({ type: 'todo_updated', todos });
+                },
+            },
             ...(this.config.commandRunner ? { commandRunner: this.config.commandRunner } : {}),
             ...(abortSignal ? { abortSignal } : {}),
             ...(this.config.memoryMaxBodyChars !== undefined ? { memoryMaxBodyChars: this.config.memoryMaxBodyChars } : {}),
@@ -289,13 +325,16 @@ 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 = '';
+                partialStepText = '';
                 // Inline <think> blocks (MiniMax over OpenAI-compatible, some open models) become reasoning events.
                 const thinkSplitter = new ThinkSplitter();
                 let wasInThink = false;
                 const emitSegments = (segments) => {
                     for (const seg of segments) {
-                        if (seg.kind === 'text')
+                        if (seg.kind === 'text') {
+                            partialStepText += seg.text;
                             emit({ type: 'text_delta', text: seg.text });
+                        }
                         else {
                             reasoningText += seg.text;
                             emit({ type: 'reasoning_delta', text: seg.text });
@@ -329,6 +368,7 @@ export class Agent {
                     tools: toAiSdkTools(this.tools),
                     abortSignal,
                     ...(this.config.model.reasoningEffort ? { reasoning: this.config.model.reasoningEffort } : {}),
+                    ...(this.config.model.temperature !== undefined ? { temperature: this.config.model.temperature } : {}),
                     onChunk: ({ chunk }) => {
                         if (chunk.type === 'text-delta') {
                             emitSegments(thinkSplitter.push(chunk.text));
@@ -351,6 +391,7 @@ export class Agent {
                     },
                     onFinish: ({ text: rawText, usage }) => {
                         emitSegments(thinkSplitter.flush());
+                        partialStepText = '';
                         if (reasoningText) {
                             emit({ type: 'reasoning_done', text: reasoningText });
                             reasoningText = '';
@@ -577,12 +618,16 @@ export class Agent {
                         this.audit?.record({ event: 'tool_result', tool: call.toolName, isError: false, durationMs: Date.now() - toolStartedAt }, auditCtx);
                         if (FILE_WRITE_TOOLS.has(call.toolName))
                             editedSinceVerify = true;
-                        const editedPath = toolArgs.path;
-                        if (FILE_WRITE_TOOLS.has(call.toolName) && typeof editedPath === 'string')
-                            editedFiles.add(editedPath);
-                        if (this.config.autoLint && FILE_WRITE_TOOLS.has(call.toolName) && typeof editedPath === 'string') {
-                            const report = await lintFile(editedPath, this.config.autoLint, { ...ctx, policy: undefined }).catch(() => null);
-                            if (report) {
+                        // Every file the call worked on: a patch can change several (RB-13).
+                        const touchedFiles = filesTouchedBy(call.toolName, toolArgs);
+                        if (FILE_WRITE_TOOLS.has(call.toolName))
+                            for (const p of touchedFiles)
+                                editedFiles.add(p);
+                        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);
+                                if (!report)
+                                    continue;
                                 emit({ type: 'lint', path: report.path, passed: report.passed, problems: report.problems.length });
                                 if (!report.passed) {
                                     const note = lintMessage(report);
@@ -600,11 +645,8 @@ export class Agent {
                         }
                         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')
-                                touchedPaths.push(touched);
-                        }
+                        if (STEERING_FILE_TOOLS.has(call.toolName))
+                            touchedPaths.push(...filesTouchedBy(call.toolName, toolArgs));
                         emit({
                             type: 'tool_result',
                             name: call.toolName,
@@ -780,6 +822,14 @@ export class Agent {
         const lastMessage = messages[messages.length - 1];
         if (continuedText !== '' && lastMessage?.role === 'user' && lastMessage.content === CONTINUE_PROMPT)
             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()) {
+            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.]` });
+            }
+        }
         // The browser is per-run: never leave a Chrome process behind.
         await this.browser?.close().catch(() => undefined);
         emit({ type: 'done', reason });
@@ -883,21 +933,68 @@ export class Agent {
             return { ...t, execute: invalidating };
         });
     }
+    /**
+     * What the permission rules say about one tool call: `allow` (every target allowed), `deny` (any target denied,
+     * with the reason the model sees), `ask` (a target asks, a `.env` file is read, or a command leaves the workspace),
+     * or undefined when no rule applies and the normal approval flow decides.
+     */
+    decidePermission(toolName, args, cwd) {
+        const p = permissionFor(toolName, args, cwd);
+        if (!p || p.targets.length === 0)
+            return undefined;
+        const rules = this.permissionRules;
+        const explicit = rules.filter((r) => r.pattern !== '*' && r.pattern !== '**');
+        const actions = p.targets.map((t) => {
+            // A broad rule never covers a secrets file: only a rule that names it can allow it.
+            // Headless runs (no approve callback) have nobody to ask, so they keep reading as before.
+            if (p.permission === 'read' && isSensitiveFile(t))
+                return evaluatePermission(explicit, 'read', t) ?? (this.config.approve ? 'ask' : evaluatePermission(rules, 'read', t));
+            return evaluatePermission(rules, p.permission, t);
+        });
+        if (p.permission === 'bash') {
+            const command = args.command;
+            if (typeof command === 'string' && touchesOutsideCwd(command, cwd)) {
+                const external = evaluatePermission(rules, 'external_directory', command);
+                if (external === 'deny')
+                    return { action: 'deny', reason: `Blocked by permission rule (external_directory ${command}).` };
+                if (external !== 'allow' && this.config.approve)
+                    actions.push('ask');
+            }
+        }
+        const denied = actions.indexOf('deny');
+        if (denied >= 0)
+            return { action: 'deny', reason: `Blocked by permission rule (${p.permission} ${p.targets[denied]}).` };
+        if (actions.includes('ask'))
+            return { action: 'ask', reason: '' };
+        if (actions.every((a) => a === 'allow'))
+            return { action: 'allow', reason: '' };
+        return undefined;
+    }
     async requestApproval(def, id, args, abortSignal, ctx) {
+        // Bookkeeping tools (the todo list) never ask.
+        if (def.noApproval)
+            return { approved: true };
+        // Permission rules come first: deny blocks, allow runs, ask skips every shortcut below.
+        const rule = this.decidePermission(def.name, args, ctx?.cwd ?? this.config.cwd ?? process.cwd());
+        if (rule?.action === 'deny')
+            return { approved: false, note: rule.reason };
+        if (rule?.action === 'allow')
+            return { approved: true };
+        const forceAsk = rule?.action === 'ask';
         // Read-only tools the user chose not to be asked about (never a destructive one).
-        if (!def.destructive && this.config.autoApproveTools?.includes(def.name)) {
+        if (!forceAsk && !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) {
+        if (!forceAsk && 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)) {
+        if (!forceAsk && def.name === 'run_command' && this.config.autoApproveCommands?.length && isListedCommand(args, this.config.autoApproveCommands)) {
             return { approved: true };
         }
         const auto = this.config.auto ?? false;
-        if (auto && !(def.destructive && !this.config.allowDestructive)) {
+        if (!forceAsk && auto && !(def.destructive && !this.config.allowDestructive)) {
             return { approved: true };
         }
         let preview;
@@ -1093,6 +1190,15 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
             // Unreadable instruction files are skipped, never fatal.
         }
     }
+    let extraInstructionsBlock = '';
+    if (config.extraInstructions?.length) {
+        try {
+            extraInstructionsBlock = await buildExtraInstructionsBlock(cwd, config.extraInstructions);
+        }
+        catch {
+            // Skipped, never fatal.
+        }
+    }
     let mapBlock = '';
     if (config.repoMap) {
         try {
@@ -1102,10 +1208,28 @@ 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.
+    const answersBlock = renderAnswersBlock(config.journeyAnswers ?? []);
+    // Facts the model would otherwise have to guess: the platform decides
+    // whether `cat` or `type` works, and it cannot see the date at all.
+    const envBlock = environmentBlock({
+        cwd,
+        platform: process.platform,
+        osVersion: release(),
+        isGitRepo: existsSync(path.join(cwd, '.git')),
+        today: new Date().toISOString().slice(0, 10),
+        model: config.model?.model,
+    });
     // Compose the final system prompt: base + (memory, skills) blocks in a
-    // stable order so cache hits survive across runs that share state.
+    // 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, config.projectCommands ?? '', memoryBlock, skillsBlock, mapBlock].filter((b) => b.length > 0);
+    const blocks = [steeringBlock, instructionsBlock, extraInstructionsBlock, config.mcpInstructions ?? '', config.projectCommands ?? '', memoryBlock, skillsBlock, answersBlock, mapBlock, 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/background.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Sub-agents that keep working after `sub_agent` has returned. The chat owns one registry per conversation: the
+ * model starts a run with `sub_agent { background: true }` and gets an id back at once; it collects the answer with
+ * `sub_agent_wait`, or the chat hands it every finished answer it has not seen with the next message. The person sees
+ * the runs in a strip above the message box and can stop one, stop all, or dismiss a finished one.
+ */
+import type { SubAgentResult } from '../tools/sub-agent.js';
+export type BackgroundState = 'running' | 'done' | 'failed' | 'stopped';
+export interface BackgroundAgent {
+    id: string;
+    task: string;
+    /** The agent file it runs as, when it was started with one. */
+    agent?: string;
+    state: BackgroundState;
+    startedAt: number;
+    endedAt?: number;
+    result?: SubAgentResult;
+    error?: string;
+}
+/** More than this at once costs more than anyone meant to spend. */
+export declare const MAX_RUNNING_BACKGROUND = 4;
+export interface StartOptions {
+    task: string;
+    agent?: string | undefined;
+    /** Runs the work; must finish soon after `signal` aborts. */
+    run: (signal: AbortSignal) => Promise<SubAgentResult>;
+}
+export declare class BackgroundAgents {
+    private readonly entries;
+    private readonly listeners;
+    private counter;
+    start(options: StartOptions): BackgroundAgent;
+    list(): BackgroundAgent[];
+    get(id: string): BackgroundAgent | undefined;
+    stop(id: string): void;
+    stopAll(): void;
+    /** Stop everything and forget it all (a new chat starts with none). */
+    clear(): void;
+    /** Remove a finished entry from the list. A running one must be stopped first. */
+    dismiss(id: string): boolean;
+    /**
+     * Wait until the named runs (default: all that are running) have finished, or the timeout passes. Never throws:
+     * the answer is the current state of each run.
+     */
+    wait(ids?: readonly string[], options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<BackgroundAgent[]>;
+    /** Finished runs the model has not been told about yet; each is returned once. */
+    takeUndelivered(): BackgroundAgent[];
+    /** Mark runs as already known to the model (a `sub_agent_wait` answered for them). */
+    markDelivered(ids: readonly string[]): void;
+    onChange(listener: () => void): () => void;
+    private changed;
+    private view;
+}
+/** The model-facing text for finished runs: what each was asked and what it answered. */
+export declare function backgroundResultsBlock(finished: readonly BackgroundAgent[]): string;

package/dist/agent/background.js

@@ -0,0 +1,139 @@
+/** More than this at once costs more than anyone meant to spend. */
+export const MAX_RUNNING_BACKGROUND = 4;
+export class BackgroundAgents {
+    entries = new Map();
+    listeners = new Set();
+    counter = 0;
+    start(options) {
+        const running = [...this.entries.values()].filter((e) => e.state === 'running').length;
+        if (running >= MAX_RUNNING_BACKGROUND) {
+            throw new Error(`At most ${MAX_RUNNING_BACKGROUND} background agents can run at once; wait for one to finish or stop one.`);
+        }
+        this.counter += 1;
+        const controller = new AbortController();
+        const entry = {
+            id: `bg-${this.counter}`,
+            task: options.task,
+            ...(options.agent ? { agent: options.agent } : {}),
+            state: 'running',
+            startedAt: Date.now(),
+            controller,
+            finished: Promise.resolve(),
+            delivered: false,
+        };
+        entry.finished = options.run(controller.signal).then((result) => {
+            entry.result = result;
+            // A stop makes the child return with reason "aborted": that is a stopped run, not a finished one.
+            entry.state = controller.signal.aborted || result.reason === 'aborted' ? 'stopped' : 'done';
+            entry.endedAt = Date.now();
+            this.changed();
+        }, (err) => {
+            entry.error = err?.message ?? String(err);
+            entry.state = controller.signal.aborted ? 'stopped' : 'failed';
+            entry.endedAt = Date.now();
+            this.changed();
+        });
+        this.entries.set(entry.id, entry);
+        this.changed();
+        return this.view(entry);
+    }
+    list() {
+        return [...this.entries.values()].map((e) => this.view(e));
+    }
+    get(id) {
+        const e = this.entries.get(id);
+        return e ? this.view(e) : undefined;
+    }
+    stop(id) {
+        const e = this.entries.get(id);
+        if (e?.state === 'running')
+            e.controller.abort();
+    }
+    stopAll() {
+        for (const e of this.entries.values())
+            if (e.state === 'running')
+                e.controller.abort();
+    }
+    /** Stop everything and forget it all (a new chat starts with none). */
+    clear() {
+        this.stopAll();
+        this.entries.clear();
+        this.changed();
+    }
+    /** Remove a finished entry from the list. A running one must be stopped first. */
+    dismiss(id) {
+        const e = this.entries.get(id);
+        if (!e || e.state === 'running')
+            return false;
+        this.entries.delete(id);
+        this.changed();
+        return true;
+    }
+    /**
+     * Wait until the named runs (default: all that are running) have finished, or the timeout passes. Never throws:
+     * the answer is the current state of each run.
+     */
+    async wait(ids, options = {}) {
+        const chosen = ids ? ids.map((id) => this.entries.get(id)).filter((e) => e !== undefined) : [...this.entries.values()].filter((e) => e.state === 'running');
+        const all = Promise.all(chosen.map((e) => e.finished));
+        const races = [all];
+        let timer;
+        if (options.timeoutMs !== undefined)
+            races.push(new Promise((resolve) => (timer = setTimeout(resolve, options.timeoutMs))));
+        if (options.signal) {
+            const signal = options.signal;
+            races.push(new Promise((resolve) => (signal.aborted ? resolve(undefined) : signal.addEventListener('abort', () => resolve(undefined), { once: true }))));
+        }
+        await Promise.race(races);
+        if (timer)
+            clearTimeout(timer);
+        return chosen.map((e) => this.view(e));
+    }
+    /** Finished runs the model has not been told about yet; each is returned once. */
+    takeUndelivered() {
+        const out = [];
+        for (const e of this.entries.values()) {
+            if (e.state !== 'running' && !e.delivered) {
+                e.delivered = true;
+                out.push(this.view(e));
+            }
+        }
+        return out;
+    }
+    /** Mark runs as already known to the model (a `sub_agent_wait` answered for them). */
+    markDelivered(ids) {
+        for (const id of ids) {
+            const e = this.entries.get(id);
+            if (e && e.state !== 'running')
+                e.delivered = true;
+        }
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    changed() {
+        for (const l of this.listeners) {
+            try {
+                l();
+            }
+            catch {
+                // a listener that throws must not stop the run bookkeeping
+            }
+        }
+    }
+    view(e) {
+        const { controller: _c, finished: _f, delivered: _d, ...rest } = e;
+        return { ...rest };
+    }
+}
+/** The model-facing text for finished runs: what each was asked and what it answered. */
+export function backgroundResultsBlock(finished) {
+    if (finished.length === 0)
+        return '';
+    const parts = finished.map((a) => {
+        const body = a.state === 'done' ? (a.result?.finalText ?? '').trim() || '(no text)' : a.state === 'failed' ? `failed: ${a.error ?? 'unknown error'}` : `stopped by the user${a.result?.finalText ? `; it had said: ${a.result.finalText.trim()}` : ''}`;
+        return `<background-agent id="${a.id}" state="${a.state}" task="${a.task.replace(/"/g, "'").slice(0, 200)}">\n${body}\n</background-agent>`;
+    });
+    return `<background-agents>\n${parts.join('\n')}\n</background-agents>`;
+}

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

@@ -1,7 +1,9 @@
 import type { LanguageModel } from 'ai';
 import type { ModelConfig } from '../types.js';
+/** The prompt for rewriting `input`: the user's own instruction when given (a blank one is ignored), else the built-in. */
+export declare function enhanceRequestPrompt(input: string, instruction?: string): string;
 /**
  * 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>;
+export declare function enhancePrompt(input: string, model: ModelConfig | undefined, modelFactory?: (cfg: ModelConfig) => LanguageModel, instruction?: string): Promise<string>;

package/dist/agent/enhance-prompt.js

@@ -3,15 +3,19 @@ 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.';
+/** The prompt for rewriting `input`: the user's own instruction when given (a blank one is ignored), else the built-in. */
+export function enhanceRequestPrompt(input, instruction) {
+    return `${instruction?.trim() || ENHANCE_INSTRUCTIONS}\n\nRequest:\n${input}`;
+}
 /**
  * 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) {
+export async function enhancePrompt(input, model, modelFactory = createLanguageModel, instruction) {
     if (!model || !input.trim())
         return input;
     try {
-        const result = await generateText({ model: modelFactory(model), prompt: `${ENHANCE_INSTRUCTIONS}\n\nRequest:\n${input}` });
+        const result = await generateText({ model: modelFactory(model), prompt: enhanceRequestPrompt(input, instruction) });
         return clean(result.text) || input;
     }
     catch {

package/dist/agent/goal.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+/**
+ * Session goals: one objective kept in focus across turns. Pure state machine plus the `goal_report` tool the
+ * model uses to say it is done or stuck. The loop that runs the turns lives in the surface (VS Code chat).
+ */
+export type GoalStatus = 'active' | 'paused' | 'blocked' | 'complete';
+export interface GoalState {
+    objective: string;
+    status: GoalStatus;
+    /** The model's own closing report (complete or blocked); not independently verified. */
+    report?: string;
+    /** Turns used so far. */
+    turns: number;
+}
+export interface GoalReport {
+    kind: 'complete' | 'blocked';
+    reason: string;
+}
+export interface TurnOutcome {
+    /** Tool calls the turn made; zero with no report means the model made no progress. */
+    toolCalls: number;
+    error?: boolean;
+    stopped?: boolean;
+    report?: GoalReport;
+    /** A permission request or tool call was rejected. */
+    rejected?: boolean;
+}
+export declare const MAX_OBJECTIVE_CHARS = 10000;
+export declare function startGoal(objective: string): GoalState;
+/**
+ * The goal after one turn. Stop, an error, no progress or an exhausted turn budget pause it; a rejection or a
+ * `blocked` report blocks it; a `complete` report finishes it. A report counts only when the turn ended cleanly.
+ */
+export declare function applyTurnOutcome(g: GoalState, o: TurnOutcome, maxTurns: number): GoalState;
+export declare function pauseGoal(g: GoalState): GoalState;
+/** Paused and blocked goals continue; a complete one restarts from zero turns. */
+export declare function resumeGoal(g: GoalState): GoalState;
+/** The message that drives one goal turn. */
+export declare function goalPrompt(g: GoalState): string;
+declare const reportParams: z.ZodObject<{
+    kind: z.ZodEnum<["complete", "blocked"]>;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "blocked" | "complete";
+    reason: string;
+}, {
+    kind: "blocked" | "complete";
+    reason: string;
+}>;
+export declare function createGoalReportTool(onReport: (r: GoalReport) => void): ToolDefinition<z.infer<typeof reportParams>, {
+    recorded: true;
+}>;
+export {};