@aion0/forge 0.10.53 → 0.10.55

package/lib/chat/agent-loop.ts

@@ -28,6 +28,7 @@ import { buildMemoryContext } from './build-memory-context';
 import { buildReferencePromptSection } from './reference-prompt';
 import { buildMemoryTools } from './memory-tools';
 import { buildStartWatchTool } from '../watch/start-watch-tool';
+import { beginTurn, endTurn, isAborted, consumeNotes } from './turn-control';
 import { estimateTokens } from '../memory/token-estimate';
 import {
   listInstalledConnectors,
@@ -419,9 +420,16 @@ function buildSystemPrompt(
     }
   }
   if (builtinDefs.length > 0) {
+    // Builtins are always-active (no connector_open gate) — list their
+    // FULL description so per-tool rules like "save_tmp_file: output
+    // user_message verbatim" / "dispatch_task: ASK before classifying
+    // a save as a task" reach the LLM here, not just buried in the
+    // tools schema. The connector catalog above can be terse because
+    // those tools only become live after connector_open; builtins
+    // never go through that gate, so terseness here loses real guidance.
     lines.push('', 'Builtin tools (always available):');
     for (const t of builtinDefs) {
-      lines.push(`- ${t.name}: ${t.description.slice(0, 100)}`);
+      lines.push(`- ${t.name}: ${t.description}`);
     }
   }
 
@@ -754,10 +762,52 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
   let lastStop = '';
   let assistantBlocksAccum: ContentBlock[] = [];
 
+  // Mark this turn live so the user can abort it / inject notes mid-flight
+  // (see turn-control.ts). Cleared in the finally below.
+  beginTurn(args.sessionId);
+
   try {
     while (iter < MAX_ITERATIONS) {
       iter += 1;
 
+      // ── User intervention (turn-control) ────────────────────────
+      // Abort: stop the loop cleanly at this boundary with a sentinel so
+      // the turn doesn't just vanish. (The current in-flight LLM call /
+      // tool batch from the previous iteration has already settled here.)
+      if (isAborted(args.sessionId)) {
+        const stopMsg = appendMessage({
+          session_id: args.sessionId,
+          role: 'assistant',
+          blocks: [{ type: 'text', text: '⏹ Stopped by user.' } as TextBlock],
+        });
+        cb({ type: 'message_saved', message_id: stopMsg.id, data: stopMsg });
+        lastStop = 'aborted';
+        break;
+      }
+      // Supplementary notes: splice any queued user notes in as a user
+      // message so THIS iteration's LLM call sees them. Safe after a
+      // tool_result message — the adapter emits that as a `tool` message,
+      // so a following `user` message doesn't collide on role.
+      // Drain notes — each becomes its own user message so the thread
+      // shows them in arrival order (matches the optimistic messages the
+      // client already rendered when the user hit Send). The first note
+      // carries a flag for the model so it knows this is a mid-task
+      // redirect, not ambient chat; subsequent notes go raw to avoid
+      // cluttering the visible thread.
+      const notes = consumeNotes(args.sessionId);
+      if (notes.length > 0) {
+        const FLAG = '[mid-task interjection — sent WHILE you were running tools. Treat as an authoritative redirect that overrides any plan you announced earlier (count, target, scope). Adjust on the very next step.]';
+        for (let i = 0; i < notes.length; i++) {
+          const text = i === 0 ? `${FLAG}\n\n${notes[i]}` : notes[i]!;
+          const noteMsg = appendMessage({
+            session_id: args.sessionId,
+            role: 'user',
+            blocks: [{ type: 'text', text } as TextBlock],
+          });
+          cb({ type: 'message_saved', message_id: noteMsg.id, data: noteMsg });
+        }
+      }
+
       // ── Recompute open set every iteration ──────────────────────
       // Scan history (since last user text msg) + this turn's accumulated
       // blocks → which connectors are open right now. Then filter tools.
@@ -885,10 +935,28 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
 
       if (result.stopReason !== 'tool_use') break;
 
-      // Execute tool calls
+      // Execute tool calls. The LLM can emit several tool_use blocks per
+      // iteration (parallel batch). Without an in-batch abort check, a
+      // user who clicks Stop after the batch starts has to wait for ALL
+      // tools to finish before the loop top-check fires next iter — feels
+      // like Stop did nothing. So: between tools, if abort was requested,
+      // skip the remaining ones with synthetic "aborted" tool_results
+      // (the tool_use/tool_result pairing invariant must hold for the
+      // Anthropic API; an orphan tool_use rejects the next call).
       const toolUses = result.content.filter((b): b is ToolUseBlock => b.type === 'tool_use');
       const toolResults: ToolResultBlock[] = [];
       for (const t of toolUses) {
+        if (isAborted(args.sessionId)) {
+          const block: ToolResultBlock = {
+            type: 'tool_result',
+            tool_use_id: t.id,
+            content: '⏹ Skipped — user requested stop.',
+            is_error: true,
+          };
+          toolResults.push(block);
+          cb({ type: 'tool_result', data: { tool_use_id: t.id, name: t.name, result: { content: block.content, is_error: true } } });
+          continue;
+        }
         const r = await dispatchTool({ id: t.id, name: t.name, input: t.input }, { extraBuiltins: memHandlers, sessionId: args.sessionId });
         const block: ToolResultBlock = {
           type: 'tool_result',
@@ -960,5 +1028,7 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
     });
     cb({ type: 'error', data: { error: msg } });
     return { ok: false, error: msg };
+  } finally {
+    endTurn(args.sessionId);
   }
 }

package/lib/chat/link-patterns.ts

@@ -81,17 +81,40 @@ export const LINK_PATTERNS: LinkPattern[] = [
     url: 'https://nvd.nist.gov/vuln/detail/{1}',
     label: '{1}',
   },
-  // Forge scratch-dir files. LLMs frequently emit paths like
-  // `scratch/foo.md` when they write reports during chat-launched tasks.
-  // Link to the in-browser viewer at /scratch/<path> (page renders .md
-  // through the chat markdown component + download button); the viewer
-  // itself fetches /api/scratch/<path> for raw bytes.
+  // Forge-managed files inside <dataDir>/. LLMs emit:
+  //   • `scratch/foo.md`  — legacy task-workspace writes (kept under
+  //                         <dataDir>/scratch/, served by /scratch viewer)
+  //   • `tmp/foo.md`      — chat's save_tmp_file output (<dataDir>/tmp/)
+  //   • `flows/x.yaml`    — pipeline workflow definitions
+  //   • `prompts/y.yaml`  — schedule prompt bodies
+  // All four resolve through the /files/<dataDir-path> viewer (rendered
+  // markdown + download button), which fetches /api/files for raw bytes.
+  // Sensitive top-level items (encrypt key, sqlite DBs, log, token
+  // caches) are blocked at the API layer, so safe to be liberal here.
   {
     id: 'scratch-file',
     regex: /\bscratch\/([\w\-./]+?\.(?:md|txt|json|yaml|yml|csv|log|html|pdf|png|jpg|jpeg|gif|svg))\b/gi,
     url: '/scratch/{1}',
     label: 'scratch/{1}',
   },
+  {
+    id: 'tmp-file',
+    regex: /\btmp\/([\w\-./]+?\.(?:md|txt|json|yaml|yml|csv|log|html|pdf|png|jpg|jpeg|gif|svg))\b/gi,
+    url: '/files/tmp/{1}',
+    label: 'tmp/{1}',
+  },
+  {
+    id: 'flows-file',
+    regex: /\bflows\/([\w\-./]+?\.(?:yaml|yml|json))\b/gi,
+    url: '/files/flows/{1}',
+    label: 'flows/{1}',
+  },
+  {
+    id: 'prompts-file',
+    regex: /\bprompts\/([\w\-./]+?\.(?:yaml|yml|md|txt))\b/gi,
+    url: '/files/prompts/{1}',
+    label: 'prompts/{1}',
+  },
 ];
 
 export interface CompiledPattern {

package/lib/chat/tool-dispatcher.ts

@@ -37,6 +37,85 @@ export interface ToolResult {
 
 export type BuiltinHandler = (input: unknown) => Promise<string>;
 
+// ─── Data-dir file helpers ────────────────────────────────
+// resolveTmpPath: scoped to <dataDir>/tmp/ — where save_tmp_file drops
+// its files. Kept separate from scratch/ (the synthetic "scratch
+// project" task workspace) so the cache janitor can wipe tmp/ without
+// disturbing in-progress task workdirs.
+async function resolveTmpPath(rel: string): Promise<string> {
+  const { getDataDir } = await import('../dirs');
+  const { join, resolve } = await import('node:path');
+  const clean = rel.replace(/^\/+/, '');
+  if (!clean || clean.includes('..') || clean.includes('\0')) throw new Error('invalid tmp path');
+  const tmpRoot = join(getDataDir(), 'tmp');
+  const target = resolve(tmpRoot, clean);
+  if (!target.startsWith(tmpRoot + '/') && target !== tmpRoot) {
+    throw new Error('resolved path escapes tmp dir');
+  }
+  return target;
+}
+
+// resolveDataPath: scoped to <dataDir>/ — the read/list tools' broader
+// surface. Blocks known sensitive files (encrypt key, enterprise keys,
+// sqlite DBs, server log, anything starting with a dot at the dataDir
+// root). Subpaths under known-safe subdirs (scratch/, flows/, prompts/,
+// connectors/, etc.) are accepted as-is. The agent can use this to
+// inspect its OWN config — but secrets stay invisible.
+function isSensitiveDataPath(target: string, dataRoot: string): string | null {
+  if (target === dataRoot) return null;
+  const rel = target.slice(dataRoot.length + 1); // drop "<root>/"
+  const top = rel.split('/')[0] || '';
+  // Top-level dotfiles (.encrypt-key, .enterprise-keys.json, …) — secrets.
+  if (top.startsWith('.')) return `top-level dotfile "${top}" is sensitive (encryption keys, session state)`;
+  // SQLite databases are binary, large, and contain raw chat / task history.
+  if (/\.(db|db-wal|db-shm)$/i.test(top)) return `sqlite database "${top}" — read via Forge APIs instead`;
+  // forge.log / forge.log.old — large + may contain tokens that leaked into errors.
+  if (/^forge\.log/i.test(top)) return 'forge.log is server diagnostics — ask the user to grep it directly';
+  // Token caches at root.
+  if (/-tokens\.json$/i.test(top)) return `"${top}" stores auth tokens — sensitive`;
+  return null;
+}
+async function resolveDataPath(rel: string): Promise<string> {
+  const { getDataDir } = await import('../dirs');
+  const { resolve } = await import('node:path');
+  const clean = String(rel || '').replace(/^\/+/, '');
+  if (clean.includes('..') || clean.includes('\0')) throw new Error('invalid path');
+  const dataRoot = getDataDir();
+  const target = resolve(dataRoot, clean);
+  if (!target.startsWith(dataRoot + '/') && target !== dataRoot) {
+    throw new Error('resolved path escapes data dir');
+  }
+  const blocked = isSensitiveDataPath(target, dataRoot);
+  if (blocked) throw new Error(`refused: ${blocked}`);
+  return target;
+}
+
+// A connector arg whose WHOLE value is one of these forms is a reference
+// to a Forge-managed file. Path inside the prefix is dataDir-relative —
+// e.g. "scratch://tmp/foo.md", "scratch://flows/x.yaml". The "scratch:"
+// prefix is historical (originally only pointed at <dataDir>/scratch/);
+// kept for compatibility.
+const SCRATCH_REF_RE = /^(?:scratch:\/\/|scratch:|\/api\/scratch\/)(.+)$/;
+
+// Replace any `scratch://<file>` arg with the file's base64 content,
+// server-side. This is the whole point: the LLM can hand a connector a
+// saved file (e.g. onedrive.upload_file content_base64) without ever
+// hand-encoding it — hand-encoding large/non-ASCII content is unreliable
+// and is exactly what wedged the OneDrive upload in an endless retry loop.
+async function resolveScratchRefsInArgs(args: Record<string, unknown>): Promise<void> {
+  const { readFile } = await import('node:fs/promises');
+  for (const [k, v] of Object.entries(args)) {
+    if (typeof v !== 'string') continue;
+    const m = v.match(SCRATCH_REF_RE);
+    if (!m) continue;
+    // Path inside the ref is dataDir-relative. Goes through the same
+    // sensitive-file guard as read_forge_file (no leaking encrypt keys
+    // / DBs into a connector upload).
+    const buf = await readFile(await resolveDataPath(m[1])); // ENOENT → tool error
+    args[k] = buf.toString('base64');
+  }
+}
+
 const BUILTINS: Record<string, BuiltinHandler> = {
   get_current_time: async () => new Date().toISOString(),
 
@@ -310,31 +389,144 @@ const BUILTINS: Record<string, BuiltinHandler> = {
   // gets a download link in the response. Prefer this over dispatch_task for
   // "save / create / export a file" asks — the LLM already has the content
   // in context, no need to spawn a CLI task that may write elsewhere.
-  save_scratch_file: async (input) => {
+  save_tmp_file: async (input) => {
     const params = (input as { filename?: string; content?: string } | undefined) || {};
     const filename = (params.filename || '').trim();
     const content = params.content == null ? '' : String(params.content);
     if (!filename) return JSON.stringify({ ok: false, error: 'filename is required' });
-    if (filename.includes('..') || filename.startsWith('/') || filename.includes('\0')) {
-      return JSON.stringify({ ok: false, error: 'filename must be a bare relative name (no .. / leading /)' });
+    // Bare filename only — no slashes anywhere. The cache janitor
+    // (lib/scratch-cleanup.ts) only sweeps top-level files in tmp/;
+    // allowing nested writes would create files that never expire.
+    // Also keeps the path returned in `path: "tmp/<filename>"` simple.
+    if (filename.includes('..') || filename.includes('/') || filename.includes('\\') || filename.includes('\0')) {
+      return JSON.stringify({ ok: false, error: 'filename must be a bare relative name (no slashes, no ".." — use date-stamped flat names like "report-2026-06-09.md")' });
     }
-    const { getDataDir } = await import('../dirs');
-    const { join, resolve } = await import('node:path');
+    // Land under <dataDir>/tmp/ — cache-managed location the user can
+    // sweep via "forge clean cache" / the user-menu Cache panel. Keeps
+    // <dataDir>/scratch/ for the synthetic "scratch project" workspace
+    // (where dispatched tasks live + edit their own files).
+    let target: string;
+    try { target = await resolveTmpPath(filename); }
+    catch (e) { return JSON.stringify({ ok: false, error: (e as Error).message }); }
     const { mkdir, writeFile } = await import('node:fs/promises');
-    const scratchRoot = join(getDataDir(), 'scratch');
-    const target = resolve(scratchRoot, filename);
-    if (!target.startsWith(scratchRoot + '/') && target !== scratchRoot) {
-      return JSON.stringify({ ok: false, error: 'resolved path escapes scratch dir' });
-    }
     const { dirname } = await import('node:path');
+    // Bare filename → dirname is always <dataDir>/tmp/. mkdir -p idempotent.
     await mkdir(dirname(target), { recursive: true });
     await writeFile(target, content, 'utf8');
+    const sizeBytes = Buffer.byteLength(content, 'utf8');
+    const fileUrl = `file://${target}`;
+    // Pre-format the user-facing message. Tell agent to OUTPUT this
+    // verbatim — agents follow "echo this string" instructions far
+    // more reliably than abstract "include the URL" hints. Past
+    // attempts with hint-only kept producing prose that lost the
+    // file:// URL or wrapped it in markdown the chat UI couldn't
+    // render. This sidesteps the entire link-pattern question.
+    const userMessage = `✓ Saved (${sizeBytes} bytes) — ${fileUrl}`;
+    return JSON.stringify({
+      ok: true,
+      path: `tmp/${filename}`,
+      local_path: target,
+      file_url: fileUrl,
+      bytes: sizeBytes,
+      user_message: userMessage,
+      hint: 'OUTPUT THE `user_message` FIELD VERBATIM as your reply to the user — copy the exact characters, no markdown wrapping, no rephrasing, no shortening, no extra prose. That string contains the file:// URL Chrome can open directly on localhost (and that the user can paste into Finder/Explorer). For follow-up asks like "give me the link" / "where is it" / "提供链接" / "再给我一次" → output the same file:// URL again (' + fileUrl + '). To UPLOAD this file to a connector (e.g. onedrive.upload_file), pass "scratch://tmp/' + filename + '" as the content_base64 arg — Forge base64-encodes server-side; do NOT hand-encode. To read it back later, use read_forge_file with filename:"tmp/' + filename + '". tmp/ is auto-swept by the cache janitor.',
+    });
+  },
+
+  // Read any Forge-managed file under <dataDir>/ — tmp/, scratch/,
+  // flows/, prompts/, connectors/, etc. Sensitive files (encrypt key,
+  // sqlite DBs, log, *-tokens.json) are refused. Text returns decoded
+  // text (capped 256KB); pass as_base64:true for binary. To upload a
+  // file to a connector, prefer passing "scratch://<dataDir-rel>" as
+  // the arg — base64-encoded server-side; no bytes through the model.
+  read_forge_file: async (input) => {
+    const params = (input as { filename?: string; as_base64?: boolean } | undefined) || {};
+    // Normalize: strip the scratch:// / /api/scratch/ prefixes the
+    // agent might have copied from save_tmp_file's response. The
+    // remaining string is a dataDir-relative path (e.g. "tmp/foo.md",
+    // "flows/x.yaml", "prompts/y.yaml").
+    const filename = (params.filename || '').trim().replace(/^(?:scratch:\/\/|scratch:|\/api\/scratch\/)/, '');
+    if (!filename) return JSON.stringify({ ok: false, error: 'filename is required' });
+    let target: string;
+    try { target = await resolveDataPath(filename); }
+    catch (e) { return JSON.stringify({ ok: false, error: (e as Error).message }); }
+    const { readFile } = await import('node:fs/promises');
+    let buf: Buffer;
+    try { buf = await readFile(target); }
+    catch { return JSON.stringify({ ok: false, error: `Forge file not found: ${filename}` }); }
+    if (params.as_base64) {
+      return JSON.stringify({
+        ok: true, path: filename,
+        local_path: target, file_url: `file://${target}`,
+        encoding: 'base64', size_bytes: buf.length, content: buf.toString('base64'),
+        // "scratch://" is the connector-ref protocol name (historical —
+        // not the scratch/ dir). Path after it is dataDir-relative.
+        note: `To upload to a connector, prefer passing "scratch://${filename}" directly as the connector arg — Forge resolves + base64-encodes it server-side, no need to round-trip these bytes through the model.`,
+      });
+    }
+    const MAX = 256 * 1024;
+    const truncated = buf.length > MAX;
+    return JSON.stringify({
+      ok: true, path: filename,
+      local_path: target, file_url: `file://${target}`,
+      encoding: 'utf-8', size_bytes: buf.length, truncated,
+      content: buf.subarray(0, MAX).toString('utf8'),
+      ...(truncated ? { note: `content truncated to ${MAX} bytes — use as_base64 for the full file` } : {}),
+    });
+  },
+
+  // List files anywhere under <dataDir>/ (Forge's own data dir).
+  // Replaces the "dispatch a task just to `ls`" workaround. The `dir`
+  // param is dataDir-relative — pass "tmp" / "scratch" / "flows" /
+  // "connectors" / "prompts" / etc. No dir → lists dataDir root.
+  // Sensitive items (encrypt key, sqlite DBs, log, *-tokens.json at
+  // root) are skipped — see resolveDataPath.
+  list_forge_files: async (input) => {
+    const params = (input as { dir?: string; ext?: string; limit?: number } | undefined) || {};
+    const sub = String(params.dir || '').trim().replace(/^\/+|\/+$/g, '');
+    const ext = String(params.ext || '').trim().toLowerCase();
+    const limit = Math.max(1, Math.min(500, Number(params.limit) || 200));
+    const { getDataDir } = await import('../dirs');
+    const { join, relative } = await import('node:path');
+    const { readdir, stat } = await import('node:fs/promises');
+    const dataRoot = getDataDir();
+    let target: string;
+    try { target = sub ? await resolveDataPath(sub) : dataRoot; }
+    catch (e) { return JSON.stringify({ ok: false, error: (e as Error).message }); }
+    let dirents;
+    try { dirents = await readdir(target, { withFileTypes: true }); }
+    catch (e) { return JSON.stringify({ ok: false, error: `cannot list ${sub || 'data/'}: ${(e as Error).message}` }); }
+    const entries: Array<{ path: string; kind: 'file' | 'dir'; size?: number; mtime?: string; file_url?: string }> = [];
+    for (const d of dirents) {
+      const full = join(target, d.name);
+      // Apply the same sensitive-file filter to entries we list — so the
+      // agent doesn't even see .encrypt-key / *.db etc.
+      if (isSensitiveDataPath(full, dataRoot)) continue;
+      if (ext && d.isFile() && !d.name.toLowerCase().endsWith(ext)) continue;
+      let size: number | undefined;
+      let mtime: string | undefined;
+      if (d.isFile()) {
+        try { const s = await stat(full); size = s.size; mtime = s.mtime.toISOString(); } catch {}
+      }
+      entries.push({
+        path: relative(dataRoot, full),
+        kind: d.isDirectory() ? 'dir' : 'file',
+        ...(size !== undefined ? { size } : {}),
+        ...(mtime ? { mtime } : {}),
+        // file:// URL the user can paste into Chrome (works on localhost).
+        // Provide on dirs too — opening a dir in Chrome shows the listing.
+        file_url: `file://${full}`,
+      });
+      if (entries.length >= limit) break;
+    }
+    entries.sort((a, b) => (b.mtime || '').localeCompare(a.mtime || '') || a.path.localeCompare(b.path));
     return JSON.stringify({
       ok: true,
-      path: `scratch/${filename}`,
-      url: `/api/scratch/${filename}`,
-      bytes: Buffer.byteLength(content, 'utf8'),
-      hint: 'Tell the user the file is ready and reference it inline as `scratch/' + filename + '` — chat will render a download link automatically.',
+      root: relative(dataRoot, target) || '.',
+      local_root: target,
+      count: entries.length,
+      entries,
+      hint: 'When the user asks to show / list files, surface each entry\'s `path` (dataDir-relative, e.g. "tmp/foo.md") and `file_url` (file://… — opens in Chrome on localhost). Use read_forge_file with the same `path` to inspect content. PREFER this over dispatch_task with `ls`.',
     });
   },
 
@@ -365,6 +557,23 @@ const BUILTINS: Record<string, BuiltinHandler> = {
     });
   },
 
+  // Stop a still-running dispatched task. Use when the user says "停止
+  // / cancel / kill the task" — much better than telling them to open
+  // the Tasks UI. No-op (returns terminal:true) if the task already
+  // finished, so it's safe to call without checking status first.
+  cancel_task: async (input) => {
+    const params = (input as { task_id?: string } | undefined) || {};
+    if (!params.task_id) return JSON.stringify({ ok: false, error: 'task_id is required' });
+    const { getTask, cancelTask } = await import('../task-manager');
+    const task = getTask(params.task_id);
+    if (!task) return JSON.stringify({ ok: false, error: `Task "${params.task_id}" not found` });
+    if (task.status !== 'running' && task.status !== 'queued') {
+      return JSON.stringify({ ok: true, task_id: task.id, status: task.status, terminal: true, note: 'already terminal — no cancel needed' });
+    }
+    const cancelled = cancelTask(params.task_id);
+    return JSON.stringify({ ok: cancelled, task_id: task.id, status: cancelled ? 'cancelled' : task.status, terminal: cancelled });
+  },
+
   // Companion to dispatch_task — read a task's status + result. Returns JSON
   // so start_watch can poll via done_path="terminal" or done_match
   // {path:"status", equals:"done"}.
@@ -630,7 +839,7 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
   },
   {
     name: 'dispatch_task',
-    description: 'Dispatch a one-shot background Claude task in a Forge project. Use for longer-running asks the user wants to fire-and-forget ("analyze X codebase and write findings to a file", "run the test suite and summarize failures"). Returns JSON: {ok, task_id, project, status, hint}. The task runs in the background; if the user wants to be notified on completion, follow the hint — call start_watch on get_task_status and STOP polling in this conversation.',
+    description: 'Dispatch a one-shot background Claude CLI task in a Forge project. EXPENSIVE — spawns a fresh Claude subprocess that reads/edits code in the target project. Use ONLY for genuine codebase work: "analyze X repo and write findings", "run the test suite and summarize", "fix bug in <project>", "refactor module Y". \n\nDO NOT use for: \n  • Saving a file with content YOU already have → use save_tmp_file. \n  • Reading a Forge-owned file (tmp/scratch/flows/prompts/...) → use read_forge_file. \n  • Listing files in <dataDir>/ → use list_forge_files. \n  • Running a pipeline → use trigger_pipeline. \n  • Inspecting a saved task → use get_task_status. \n\nFor "create / write / save a file with this content" the right tool is ALWAYS save_tmp_file — the LLM has the content, no CLI subprocess needed. \n\nIf the user\'s ask is ambiguous (might be a quick save vs a real codebase task), STOP and ask before dispatching — a user reporting "I just wanted a file" after seeing a task spawn is a clear signal you misclassified. \n\nReturns JSON: {ok, task_id, project, status, hint}. The task runs in the background; if the user wants completion notification, follow the hint — call start_watch on get_task_status and STOP polling in this conversation.',
     input_schema: {
       type: 'object',
       properties: {
@@ -651,8 +860,8 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
     },
   },
   {
-    name: 'save_scratch_file',
-    description: 'Save text content to a file under <dataDir>/scratch/ and return a clickable download URL. USE THIS — not dispatch_task — when the user says "save this to a file", "create a file with X", "export the results", "give me a downloadable copy". The LLM provides the content directly (you already have it in context); no CLI task needed. Chat will auto-link any `scratch/<filename>` mention in your reply as a download link, so just mention the returned path in prose. Scratch is EPHEMERAL — files are auto-deleted after settings.scratchRetentionDays (default 7 days); tell the user this when handing over the link. Filename must be a bare relative name (no .. or /). Allowed extensions for the auto-link: .md .txt .json .yaml .yml .csv .log .html .pdf .png .jpg .jpeg .gif .svg.',
+    name: 'save_tmp_file',
+    description: 'Save text content to <dataDir>/tmp/<filename>. USE THIS — never dispatch_task — when the user says "save this to a file", "create a file with X", "export the results", "give me a downloadable copy". The LLM already has the content; no CLI task needed. Returns `file_url` (file://… that opens directly in Chrome on localhost) plus `path` ("tmp/<filename>") + `local_path`. tmp/ is cache-managed and gets swept by the cache janitor / "forge clean cache" — tell the user it\'s ephemeral. To UPLOAD this file to a connector (e.g. onedrive.upload_file content_base64), pass "scratch://tmp/<filename>" as the arg — Forge base64-encodes server-side; do NOT hand-encode. To read it back: read_forge_file with filename:"tmp/<filename>". Filename must be a bare relative name (no .. or /).',
     input_schema: {
       type: 'object',
       properties: {
@@ -668,6 +877,41 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
       required: ['filename', 'content'],
     },
   },
+  {
+    name: 'read_forge_file',
+    description: 'Read any file Forge manages under <dataDir>/ — tmp/ (chat-saved), scratch/ (task workspaces), flows/, prompts/, connectors/, etc. PREFER THIS over dispatch_task when the user wants to inspect a Forge-owned file. filename is a dataDir-relative path: "tmp/report.md", "flows/x.yaml", "connectors/onedrive/manifest.yaml". Sensitive files (encrypt key, sqlite DBs, server log, *-tokens.json at root) are refused. Text returns decoded UTF-8 (capped 256KB); pass as_base64:true for binary (pdf, images, zip). To UPLOAD to a connector, prefer "scratch://<dataDir-rel>" arg — bytes never traverse the model.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        filename: { type: 'string', description: 'dataDir-relative path, e.g. "tmp/report.md", "flows/mantis-bug-fix.yaml", "connectors/mantis/manifest.yaml".' },
+        as_base64: { type: 'boolean', description: 'Return raw bytes base64-encoded instead of decoded UTF-8 text. Use for binary files.' },
+      },
+      required: ['filename'],
+    },
+  },
+  {
+    name: 'list_forge_files',
+    description: 'List files / subdirs anywhere under <dataDir>/ (Forge\'s own data dir). PREFER THIS over `dispatch_task` with `ls` — it\'s sync, in-process, no LLM detour. `dir` is dataDir-relative: pass "tmp" for chat-saved temp files, "scratch" for task workspaces, "flows" / "prompts" / "connectors" for configs. Omit `dir` to see the dataDir root. Each entry has `path` (dataDir-relative), `kind` (file/dir), and `file_url` (file://… opens in Chrome on localhost). Sensitive items (encrypt key, sqlite DBs, server log, *-tokens.json) are filtered out automatically.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: 'dataDir-relative directory. Examples: "tmp", "scratch", "flows", "prompts", "connectors/mantis". Omit to list dataDir root.' },
+        ext: { type: 'string', description: 'Optional file-extension filter (e.g. ".md", ".yaml"). Lowercase match on suffix.' },
+        limit: { type: 'number', description: 'Max entries (default 200, capped at 500).' },
+      },
+    },
+  },
+  {
+    name: 'cancel_task',
+    description: 'Cancel a still-running dispatched task by id. Use when the user says "停止 / cancel / kill the task" — much cleaner than telling them to open the Tasks UI. Safe to call on an already-terminal task (returns ok with note). task_id comes from dispatch_task\'s response.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task id from dispatch_task.' },
+      },
+      required: ['task_id'],
+    },
+  },
   {
     name: 'get_task_status',
     description: "Check a dispatched Forge task's status + result by id. Pass task_id (returned by dispatch_task). Returns JSON: {id, status: 'queued'|'running'|'done'|'failed'|'cancelled', terminal: bool, project, result_summary?, error?, completed_at?}. For start_watch, use done_path=\"terminal\" (fires on done/failed/cancelled) or done_match={path:\"status\",equals:\"done\"}.",
@@ -1090,6 +1334,15 @@ export async function dispatchTool(
   const cfgGap = preflightConnectorSettings(def, effectiveSettings);
   if (cfgGap) return { content: cfgGap, is_error: true };
 
+  // Resolve any `scratch://<file>` arg into the file's base64 content,
+  // server-side — so the LLM can hand a saved file to a connector
+  // (e.g. onedrive.upload_file content_base64) without hand-encoding it.
+  try {
+    await resolveScratchRefsInArgs(argInput);
+  } catch (e) {
+    return { content: `scratch reference failed: ${(e as Error).message}`, is_error: true };
+  }
+
   try {
     let result: ToolResult;
     switch (protocol) {

package/lib/chat/turn-control.ts

@@ -0,0 +1,81 @@
+/**
+ * Per-session control channel for an in-flight agent turn.
+ *
+ * A tool-call loop (agent-loop.ts) can otherwise run unattended for up to
+ * MAX_ITERATIONS with no way for the user to intervene — which is exactly
+ * how a doomed task melts an instance. This gives two levers, both scoped
+ * to a CURRENTLY RUNNING turn:
+ *   • abort — break the loop cleanly at the next iteration boundary
+ *   • notes — supplementary text the agent picks up on its next iteration
+ *
+ * State is in-process (chat-standalone owns the loop) and ephemeral: it is
+ * reset when the turn begins and cleared when it ends. Both levers no-op
+ * when no turn is running, so the caller can tell the user to just send a
+ * normal message instead.
+ */
+
+interface TurnControl {
+  running: boolean;
+  aborted: boolean;
+  notes: string[];
+}
+
+const controls = new Map<string, TurnControl>();
+
+function get(sessionId: string): TurnControl {
+  let c = controls.get(sessionId);
+  if (!c) {
+    c = { running: false, aborted: false, notes: [] };
+    controls.set(sessionId, c);
+  }
+  return c;
+}
+
+/** Mark a turn as live. Resets abort + drains stale notes from any prior turn. */
+export function beginTurn(sessionId: string): void {
+  const c = get(sessionId);
+  c.running = true;
+  c.aborted = false;
+  c.notes = [];
+}
+
+/** Turn finished (normally or via abort) — clear all transient state. */
+export function endTurn(sessionId: string): void {
+  const c = get(sessionId);
+  c.running = false;
+  c.aborted = false;
+  c.notes = [];
+}
+
+/** User asked to stop. Returns false if no turn is running (nothing to abort). */
+export function requestAbort(sessionId: string): boolean {
+  const c = get(sessionId);
+  if (!c.running) return false;
+  c.aborted = true;
+  return true;
+}
+
+export function isAborted(sessionId: string): boolean {
+  return get(sessionId).aborted;
+}
+
+export function isTurnRunning(sessionId: string): boolean {
+  return get(sessionId).running;
+}
+
+/** Queue supplementary info for the running turn. Returns false if idle. */
+export function addNote(sessionId: string, text: string): boolean {
+  const c = get(sessionId);
+  if (!c.running) return false;
+  c.notes.push(text);
+  return true;
+}
+
+/** Take + clear the queued notes (called by the loop each iteration). */
+export function consumeNotes(sessionId: string): string[] {
+  const c = get(sessionId);
+  if (c.notes.length === 0) return [];
+  const out = c.notes;
+  c.notes = [];
+  return out;
+}