@aion0/forge 0.10.53 → 0.10.55

package/lib/chat-standalone.ts

@@ -36,6 +36,7 @@ import {
   clearSessionMessages, ensureMainSession, forkSession, appendMessage,
 } from './chat/session-store';
 import { runTurn, type AgentEvent } from './chat/agent-loop';
+import { requestAbort, addNote, isTurnRunning } from './chat/turn-control';
 import { bridgePush } from './chat/bridge-client';
 import { startWatchRunner } from './watch/watch-runner';
 
@@ -173,6 +174,22 @@ async function handleMessagePost(req: IncomingMessage, res: ServerResponse, id:
   const text = String(body?.text || '').trim();
   if (!text) return sendJson(res, 400, { error: 'text is required' });
 
+  // Merge instead of forking: if a turn is already running on this session,
+  // queue the text as a note for the running turn instead of starting a
+  // second concurrent runTurn. Two parallel loops on the same session
+  // (e.g. extension + webchat both sending) would otherwise interleave
+  // tool calls and share turn-control state — one abort would stop both,
+  // and the user sees the same task twice. This makes the merge happen
+  // server-side so it doesn't depend on which client is sending.
+  if (isTurnRunning(id)) {
+    const queued = addNote(id, text);
+    if (queued) {
+      return sendJson(res, 202, { accepted: true, merged: true, topic: `chat:${id}` });
+    }
+    // Tiny race window: isTurnRunning was true but turn ended before we
+    // queued. Fall through to start a fresh turn with this text.
+  }
+
   const startedAt = Date.now();
   void runTurn({
     sessionId: id,
@@ -211,6 +228,34 @@ async function handleInjectMessage(req: IncomingMessage, res: ServerResponse, id
   sendJson(res, 200, { ok: true, message_id: saved.id });
 }
 
+// Abort the in-flight tool-call loop for a session. The loop breaks at its
+// next iteration boundary and persists a "⏹ Stopped" sentinel. No-op (409)
+// when no turn is running.
+async function handleAbortPost(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  // Loud log: every abort goes through here. If "Stop" fires without a
+  // visible UI click, this print pins the culprit (user-agent / referer).
+  const accepted = requestAbort(id);
+  if (!accepted) return sendJson(res, 409, { ok: false, running: false, error: 'no active turn to stop' });
+  return sendJson(res, 200, { ok: true, running: true });
+}
+
+// Queue supplementary info for the running turn — the loop splices it in as
+// a user message the agent sees on its next iteration. 409 when idle (the
+// client should just send a normal message instead). The note appears in
+// the transcript when the loop consumes it (single source of truth).
+async function handleNotePost(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const body = await readJson(req);
+  const text = String(body?.text || '').trim();
+  if (!text) return sendJson(res, 400, { error: 'text is required' });
+  const queued = addNote(id, text);
+  if (!queued) return sendJson(res, 409, { ok: false, running: false, error: 'no active turn — send it as a normal message instead' });
+  return sendJson(res, 200, { ok: true, running: true });
+}
+
 function handleEventsSse(_req: IncomingMessage, res: ServerResponse, id: string): void {
   // Verify the session exists before opening the stream.
   const session = getSession(id);
@@ -276,6 +321,12 @@ async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
   const inject = /^\/api\/sessions\/([^/]+)\/inject$/.exec(url.pathname);
   if (inject && m === 'POST') return handleInjectMessage(req, res, inject[1]!);
 
+  const abort = /^\/api\/sessions\/([^/]+)\/abort$/.exec(url.pathname);
+  if (abort && m === 'POST') return handleAbortPost(req, res, abort[1]!);
+
+  const note = /^\/api\/sessions\/([^/]+)\/note$/.exec(url.pathname);
+  if (note && m === 'POST') return handleNotePost(req, res, note[1]!);
+
   const fork = /^\/api\/sessions\/([^/]+)\/fork$/.exec(url.pathname);
   if (fork && m === 'POST') return handleSessionFork(req, res, fork[1]!);
 

package/lib/help-docs/10-troubleshooting.md

@@ -88,6 +88,22 @@ rm -rf $(npm root -g)/@aion0/forge $(npm root -g)/@aion0/.forge-*
 npm install -g @aion0/forge
 ```
 
+### Chat keeps looping / "thinking…" never finishes
+The agent got stuck retrying a tool that can't succeed (e.g. a truncated
+result it keeps re-fetching). While a turn is running the `/chat` composer
+stays usable:
+- **■ Stop** — aborts the tool-call loop at the next step and posts a
+  "⏹ Stopped by user" message. Use this to break a runaway turn.
+- **Send** — type a correction/extra instruction and send it; while a turn
+  is running it's spliced into THAT turn (the agent reads it on its next
+  step), so you can redirect without cancelling. A normal `POST /messages`
+  is deliberately NOT used here — it would spawn a second concurrent loop on
+  the same session.
+
+These hit `POST /api/sessions/:id/abort` and `/note` on the chat backend, so
+any client (web `/chat`, extension) can drive them. `/note` no-ops (409) when
+no turn is running — the page then sends it as a normal new message instead.
+
 ## Logs
 
 - Background server: `~/.forge/data/forge.log`

package/lib/help-docs/17-connectors.md

@@ -165,6 +165,25 @@ tools:
 - `{base_url}` / `{settings.<name>}` → expanded server-side from saved settings
 - `{args.<name>}` → expanded by the runtime from the LLM's tool input
 
+**Forge-file args (`scratch://` connector-ref protocol)**: any tool arg
+whose whole value is a `scratch://<path>` reference is read from
+`<dataDir>/<path>` and replaced with the file's **base64** content,
+server-side, before the tool runs. The `scratch://` prefix is the
+ref protocol name (historical — not tied to the `scratch/` subdir); the
+path after it is **dataDir-relative**, so `scratch://tmp/foo.md`,
+`scratch://scratch/report.md`, `scratch://flows/x.yaml` all work.
+Sensitive items (encryption keys, sqlite DBs, server log, `*-tokens.json`
+at root) are refused. Bare-form references (`scratch/<file>` and
+`/api/scratch/<file>`) are accepted for back-compat — same dataDir-rooted
+resolution. This lets the chat agent hand a saved file straight to a
+connector (e.g. `onedrive.upload_file` `content_base64:
+"scratch://tmp/report.md"`) without hand-encoding it — hand-encoding
+large or non-ASCII content is unreliable. A missing file fails the call
+with a clear error (no retry). The companion builtin `read_forge_file`
+pulls Forge-managed file content back into chat context (same dataDir-
+relative paths, same sensitive blacklist). For *uploading*, prefer the
+`scratch://` ref so the bytes never round-trip through the model.
+
 **`script` contract**:
 - Receives `args` (the LLM's parameters)
 - Returns a JSON-serializable value (no DOM nodes, no functions)

package/lib/help-docs/25-chat-tools.md

@@ -0,0 +1,125 @@
+# Chat tools — what the chat agent can do directly
+
+The chat agent (Forge's `/chat` page + the IDE plugin + Telegram bot) talks
+to LLMs that can call **builtin tools** without round-tripping through a
+background task. These cover the everyday "Forge knows / Forge owns" cases
+so the agent doesn't have to dispatch a Claude CLI task just to read a
+file or fire a pipeline.
+
+This doc lists the tools the agent has by default and the workflows they
+unlock. (Connector tools — `mantis.search_bugs`, `gitlab.list_my_todos`,
+etc. — are documented in `17-connectors.md`.)
+
+## File access — `<dataDir>/`
+
+Forge's data dir (`~/.forge/data/` by default, override with `FORGE_DATA_DIR`)
+holds everything Forge owns: pipelines, schedules, prompts, connectors,
+the sqlite DB, the encryption key, and two cache pools — `cloned-projects/`
+and `tmp/`. The chat agent can read most of it and write to `tmp/`.
+
+### `save_tmp_file` — write to `<dataDir>/tmp/`
+Use case: the user says *"save this report to a file"*, *"give me a
+downloadable copy"*, *"export the results"*. The agent already has the
+content in context — no CLI task needed.
+
+The file lands in `<dataDir>/tmp/<filename>`. The response includes:
+- `path`: `tmp/<filename>` — chat auto-links this string to the in-browser
+  viewer at `/files/tmp/<filename>` (renders markdown, download button)
+- `file_url`: `file://<abs-path>` — opens directly in Chrome on localhost,
+  or the user can right-click → Show in Finder/Explorer
+- `local_path`: absolute filesystem path
+
+`tmp/` is **cache-managed** — counts in the user-menu Cache panel and gets
+swept by the janitor after `scratchRetentionDays` (default 7 days). Tell
+users their saved file is ephemeral; if they want it permanent, ask them
+to copy it out.
+
+### `read_forge_file` — read anywhere under `<dataDir>/`
+Path is dataDir-relative: `tmp/foo.md`, `scratch/report.md`, `flows/x.yaml`,
+`prompts/y.yaml`, `connectors/mantis/manifest.yaml`, etc. Use this instead
+of dispatching a `cat` task when the user wants to inspect a Forge-owned
+file.
+
+Sensitive items at the dataDir root are refused: `.encrypt-key`,
+`.enterprise-keys.json`, any `*.db*`, `forge.log*`, `*-tokens.json`. The
+chat agent can't accidentally leak these into chat context.
+
+Pass `as_base64: true` for binary files (pdf, images, zip).
+
+### `list_forge_files` — list files anywhere under `<dataDir>/`
+Pass `dir` as a dataDir-relative subdir (`tmp`, `scratch`, `flows`,
+`connectors/mantis`). Each entry returns `path`, `kind` (file/dir),
+`size`, `mtime`, and a `file_url` (file:// link).
+
+Use this for *"what files are in tmp?"* / *"list my flows"* — never
+dispatch a `ls` task for these.
+
+### `scratch://<path>` — connector-arg ref protocol
+Use case: the agent wants to **upload** a Forge-owned file to a connector
+(e.g. `onedrive.upload_file`, `teams.send_message` with an attachment).
+Instead of reading the file into context and base64-encoding it via the
+model (unreliable for non-ASCII, expensive for large files), pass
+`scratch://tmp/report.md` as the connector arg's value. Forge resolves
+the path under `<dataDir>/`, base64-encodes server-side, then dispatches.
+
+`scratch://` is the historical name for the **ref protocol**, not the
+`scratch/` subdir — the path after it is dataDir-relative. Bare forms
+(`scratch/<file>`, `/api/scratch/<file>`) are also accepted for
+back-compat. Same sensitive-file blacklist as `read_forge_file`.
+
+## Background tasks
+
+### `dispatch_task` — fire-and-forget a Claude CLI task
+For longer-running asks the user wants in the background ("analyze this
+codebase and write findings", "run the test suite and summarize"). Returns
+a `task_id`. Pair with `get_task_status` (or `start_watch`) to follow up.
+
+### `cancel_task` — stop a running task by id
+Use when the user says *"停止 / cancel / kill that task"*. Safe to call
+on already-terminal tasks (returns ok + a note). Much cleaner than
+telling the user to open the Tasks UI.
+
+### `get_task_status` — check a dispatched task
+Returns `status`, `terminal`, `result_summary` (truncated to 1KB),
+`error`, `completed_at`. For long-running polls, prefer `start_watch`
+over manual polling — see `24-watch.md`.
+
+## Pipelines + schedules
+
+The chat agent owns the full schedule CRUD surface and pipeline triggers:
+`create_schedule`, `list_schedules`, `update_schedule`, `delete_schedule`,
+`run_schedule_now`, `trigger_pipeline`, `get_pipeline_status`. See
+`05-pipelines.md` and `13-schedules.md` for details on what the
+underlying objects look like.
+
+## Stop / mid-task interjection
+
+The user can interrupt a runaway tool-call loop at any time:
+- **Stop button** — aborts the loop at the next iteration boundary, OR
+  between parallel tool calls (so a 5-way parallel batch can be stopped
+  mid-way). Persists a "⏹ Stopped by user." message in the thread.
+- **Send during streaming** — typed text is queued as a **note** for the
+  running turn; the loop splices it in as a user message at the start of
+  the next iteration. The first such note carries a `[mid-task
+  interjection — …]` prefix so the model treats it as an authoritative
+  redirect, not ambient chat.
+
+Both work on the web `/chat` page and the extension. If the user opens the
+same chat session from two clients (e.g. extension + webchat) and posts a
+follow-up while a turn is running, the server merges it into the running
+loop as a note — no parallel turns on one session.
+
+See `10-troubleshooting.md` § "Chat keeps looping" for recovery when a
+runaway loop pre-dates Stop being available.
+
+## Help + introspection
+
+`list_help_docs` + `read_help_doc` give the agent access to these same
+docs so it can answer Forge questions directly. `list_forge_context`
+returns the current instance's projects / agent profiles / installed
+skills — call it before passing project / agent / skill names to
+`dispatch_task` or `trigger_pipeline` to validate them.
+
+`add_enterprise_key` registers a pasted enterprise marketplace key
+(`fortinet:github_pat_…`) and triggers an immediate sync — see
+`01-settings.md` § Marketplace Providers.

package/lib/help-docs/CLAUDE.md

@@ -51,6 +51,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `18-chrome-mcp.md` | Connect Forge Claude Code sessions to a real Chrome via chrome-devtools-mcp — dev-time browser access for connector authoring |
 | `23-automation-states.md` | Fortinet pipeline automation: GitLab MR stage labels, Mantis status flow, Teams notify policy |
 | `24-watch.md` | Background watches — async polling of long jobs (device upgrade, Jenkins build, test run) that report back in chat. Two triggers: connectors' declarative `async` block, and the `start_watch` builtin the assistant calls on the fly. Where to see/cancel them. |
+| `25-chat-tools.md` | Builtin tools the chat agent has by default — file access (`save_tmp_file` / `read_forge_file` / `list_forge_files`), `scratch://` connector-ref protocol, `dispatch_task` / `cancel_task`, schedules CRUD, pipelines, Stop + mid-task notes. |
 
 ## Matching questions to docs
 
@@ -86,3 +87,4 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Recipe / "From recipe" form / parameterized job → tell user: **recipes deprecated** along with Jobs; fire pipelines manually or via Schedules.
 - Mantis bug fix / fortinet-mantis-bug-fix / open MR for Mantis bug / fortinet-mr-review / pre-review / GitLab stage labels → `23-automation-states.md` (kept Fortinet pipelines)
 - Background watch / "watch this build" / "tell me when the upgrade is done" / progress chip / start_watch / async long job / why is the assistant polling → `24-watch.md`
+- save_tmp_file / read_forge_file / list_forge_files / cancel_task / scratch:// ref / `<dataDir>/tmp/` / Stop / mid-task note / "what tools does the chat agent have" → `25-chat-tools.md`

package/lib/scratch-cleanup.ts

@@ -1,14 +1,14 @@
 /**
- * Scratch directory janitor — deletes stale files under <dataDir>/scratch/.
+ * Cache-dir janitor — deletes stale files under:
+ *   <dataDir>/tmp/      — chat-saved files (save_tmp_file)
+ *   <dataDir>/scratch/  — legacy chat-saved location (kept for back-compat)
  *
- * The save_scratch_file chat tool drops generated reports here so the user
- * can download them; without periodic sweeping the directory grows forever.
- * Retention is settings.scratchRetentionDays (default 7).
+ * Without periodic sweeping the dirs grow forever. Retention is
+ * settings.scratchRetentionDays (default 7).
  *
- * Conservative scope: only sweeps PLAIN FILES at the top level of scratch/.
- * - Skips dotfiles (.mcp.json, .claude/, .forge/) — Forge/Claude project state
- * - Skips CLAUDE.md — scratch project marker
- * - Skips subdirectories — could be user-created project trees we don't own
+ * Conservative scope: only top-level files. Skips dotfiles, the
+ * scratch-project marker CLAUDE.md, and subdirs (could be user-created
+ * project trees we don't own).
  */
 
 import { readdirSync, statSync, unlinkSync } from 'node:fs';
@@ -29,16 +29,13 @@ function retentionMs(): number {
   return days * ONE_DAY_MS;
 }
 
-export function cleanupScratch(): { scanned: number; deleted: number; freedBytes: number } {
-  const root = join(getDataDir(), 'scratch');
+function sweepDir(root: string, cutoff: number, skipNames: Set<string>): { scanned: number; deleted: number; freedBytes: number } {
   let scanned = 0, deleted = 0, freedBytes = 0;
-  const maxAge = retentionMs();
-  const cutoff = Date.now() - maxAge;
   let entries: string[] = [];
   try { entries = readdirSync(root); } catch { return { scanned, deleted, freedBytes }; }
   for (const name of entries) {
     if (name.startsWith('.')) continue;
-    if (name === 'CLAUDE.md') continue;
+    if (skipNames.has(name)) continue;
     const p = join(root, name);
     let st;
     try { st = statSync(p); } catch { continue }
@@ -48,12 +45,24 @@ export function cleanupScratch(): { scanned: number; deleted: number; freedBytes
     try { unlinkSync(p); deleted++; freedBytes += st.size; }
     catch (e) { console.warn('[scratch-cleanup] unlink failed:', p, (e as Error).message); }
   }
-  if (deleted > 0) {
-    console.log(`[scratch-cleanup] deleted ${deleted}/${scanned} files, freed ${freedBytes} bytes`);
-  }
   return { scanned, deleted, freedBytes };
 }
 
+export function cleanupScratch(): { scanned: number; deleted: number; freedBytes: number } {
+  const cutoff = Date.now() - retentionMs();
+  const tmp = sweepDir(join(getDataDir(), 'tmp'), cutoff, new Set());
+  const scratch = sweepDir(join(getDataDir(), 'scratch'), cutoff, new Set(['CLAUDE.md']));
+  const total = {
+    scanned: tmp.scanned + scratch.scanned,
+    deleted: tmp.deleted + scratch.deleted,
+    freedBytes: tmp.freedBytes + scratch.freedBytes,
+  };
+  if (total.deleted > 0) {
+    console.log(`[scratch-cleanup] deleted ${total.deleted}/${total.scanned} files (tmp=${tmp.deleted}, scratch=${scratch.deleted}), freed ${total.freedBytes} bytes`);
+  }
+  return total;
+}
+
 let started = false;
 export function startScratchCleanup(): void {
   if (started) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.10.53",
+  "version": "0.10.55",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {