@aion0/forge 0.10.18 → 0.10.20

package/RELEASE_NOTES.md

@@ -1,8 +1,8 @@
-# Forge v0.10.18
+# Forge v0.10.20
 
-Released: 2026-05-30
+Released: 2026-05-31
 
-## Changes since v0.10.17
+## Changes since v0.10.19
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.17...v0.10.18
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.19...v0.10.20

package/app/api/agents/route.ts

@@ -6,9 +6,11 @@ export async function GET(req: Request) {
   const url = new URL(req.url);
   const resolve = url.searchParams.get('resolve');
 
-  // GET /api/agents?resolve=claude → resolve terminal launch info for an agent
+  // GET /api/agents?resolve=claude[&scene=help] → resolve launch info for an
+  // agent in a given scene (terminal default; help/task/etc. pick models[scene]).
   if (resolve) {
-    const info = resolveTerminalLaunch(resolve);
+    const scene = url.searchParams.get('scene') as 'terminal' | 'task' | 'telegram' | 'help' | 'mobile' | null;
+    const info = resolveTerminalLaunch(resolve, scene || undefined);
     return NextResponse.json(info);
   }
 

package/components/HelpTerminal.tsx

@@ -27,7 +27,10 @@ export default function HelpTerminal() {
 
     let disposed = false;
     let dataDir = '~/.forge/data';
-    let agentCmd = 'claude';
+    // Full launch command for the Help AI: resolved from the DEFAULT agent's
+    // `help` scene (binary path + --model models.help + env exports). Falls back
+    // to bare `claude` if resolution fails.
+    let launchCmd = 'claude';
 
     const cs = getComputedStyle(document.documentElement);
     const tv = (name: string) => cs.getPropertyValue(name).trim();
@@ -76,7 +79,7 @@ export default function HelpTerminal() {
               isNewSession = false;
               setTimeout(() => {
                 if (socket.readyState === WebSocket.OPEN) {
-                  socket.send(JSON.stringify({ type: 'input', data: `cd "${dataDir}" 2>/dev/null && ${agentCmd}\n` }));
+                  socket.send(JSON.stringify({ type: 'input', data: `cd "${dataDir}" 2>/dev/null && ${launchCmd}\n` }));
                 }
               }, 300);
             }
@@ -97,13 +100,27 @@ export default function HelpTerminal() {
       socket.onerror = () => {};
     }
 
-    // Fetch data dir + default agent then connect
+    // Fetch data dir + default agent, then resolve that agent's `help`-scene
+    // launch info (path + model + env) so Help runs the configured binary/model.
     Promise.all([
       fetch('/api/help?action=status').then(r => r.json()).then(data => { if (data.dataDir) dataDir = data.dataDir; }).catch(() => {}),
-      fetch('/api/agents').then(r => r.json()).then(data => {
+      fetch('/api/agents').then(r => r.json()).then(async (data) => {
         const defaultId = data.defaultAgent || 'claude';
-        const agent = (data.agents || []).find((a: any) => a.id === defaultId);
-        if (agent?.path) agentCmd = agent.path;
+        try {
+          const info = await fetch(`/api/agents?resolve=${encodeURIComponent(defaultId)}&scene=help`).then(r => r.json());
+          const bin = info?.cliCmd || 'claude';
+          const modelFlag = info?.model ? ` --model ${info.model}` : '';
+          const envPrefix = info?.env
+            ? Object.entries(info.env as Record<string, string>)
+                .map(([k, v]) => `export ${k}=${JSON.stringify(v)}`)
+                .join(' && ') + ' && '
+            : '';
+          launchCmd = `${envPrefix}${bin}${modelFlag}`;
+        } catch {
+          // Fallback to bare path from the agent list if resolve fails.
+          const agent = (data.agents || []).find((a: any) => a.id === defaultId);
+          if (agent?.path) launchCmd = agent.path;
+        }
       }).catch(() => {}),
     ]).finally(() => { if (!disposed) connect(); });
 

package/components/SettingsModal.tsx

@@ -901,7 +901,6 @@ interface AgentEntry {
   enabled: boolean;
   type: string;
   taskFlags: string;
-  interactiveCmd: string;
   resumeFlag: string;
   outputFormat: string;
   models: { terminal: string; task: string; telegram: string; help: string; mobile: string };
@@ -1334,7 +1333,7 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
     'generic': { taskFlags: '', resumeFlag: '', outputFormat: 'text', skipPermissionsFlag: '' },
   };
   const makeNewAgent = (cliType = 'claude-code') => ({
-    id: '', name: '', path: '', interactiveCmd: '',
+    id: '', name: '', path: '',
     models: { terminal: 'default', task: 'default', telegram: 'default', help: 'default', mobile: 'default' },
     requiresTTY: false, cliType,
     ...cliDefaults[cliType],
@@ -1369,7 +1368,6 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
             enabled: cfg.enabled !== false,
             type: a.type || 'generic',
             taskFlags: cfg.taskFlags ?? (a.id === 'claude' ? '-p --verbose --output-format stream-json --dangerously-skip-permissions' : cfg.flags?.join(' ') ?? ''),
-            interactiveCmd: cfg.interactiveCmd ?? a.path,
             resumeFlag: cfg.resumeFlag ?? (a.capabilities?.supportsResume ? '-c' : ''),
             outputFormat: cfg.outputFormat ?? (a.capabilities?.supportsStreamJson ? 'stream-json' : 'text'),
             models: cfg.models ?? { terminal: "default", task: "default", telegram: "default", help: "default", mobile: "default" },
@@ -1395,7 +1393,6 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
             enabled: cfg.enabled !== false,
             type: 'generic',
             taskFlags: cfg.taskFlags ?? cfg.flags?.join(' ') ?? '',
-            interactiveCmd: cfg.interactiveCmd ?? cfg.path ?? '',
             resumeFlag: cfg.resumeFlag ?? '',
             outputFormat: cfg.outputFormat ?? 'text',
             models: cfg.models ?? { terminal: "default", task: "default", telegram: "default", help: "default", mobile: "default" },
@@ -1434,7 +1431,6 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
           path: a.path,
           enabled: a.enabled,
           taskFlags: a.taskFlags,
-          interactiveCmd: a.interactiveCmd,
           resumeFlag: a.resumeFlag,
           outputFormat: a.outputFormat,
           models: a.models,
@@ -1527,7 +1523,7 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
           onClick={() => {
             // Auto-fill path from detected claude agent when opening Add form
             const claude = agents.find(a => a.id === 'claude');
-            if (claude?.path && !newAgent.path) setNewAgent((prev: any) => ({ ...prev, path: claude.path, interactiveCmd: claude.path }));
+            if (claude?.path && !newAgent.path) setNewAgent((prev: any) => ({ ...prev, path: claude.path }));
             setShowAdd(v => !v);
           }}
           className="text-[9px] px-2 py-0.5 border border-[var(--border)] text-[var(--text-secondary)] rounded hover:text-[var(--text-primary)]"
@@ -1614,10 +1610,6 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
                     <label className="text-[9px] text-[var(--text-secondary)]">Task Flags <span className="text-[8px]">(non-interactive mode, e.g. -p --output-format json)</span></label>
                     <input value={a.taskFlags} onChange={e => updateAgent(a.id, 'taskFlags', e.target.value)} placeholder="-p --verbose" className={inputClass} />
                   </div>
-                  <div>
-                    <label className="text-[9px] text-[var(--text-secondary)]">Interactive Command <span className="text-[8px]">(terminal startup)</span></label>
-                    <input value={a.interactiveCmd} onChange={e => updateAgent(a.id, 'interactiveCmd', e.target.value)} placeholder="claude" className={inputClass} />
-                  </div>
                   <div className="flex gap-3">
                     <div className="flex-1">
                       <label className="text-[9px] text-[var(--text-secondary)]">Resume Flag <span className="text-[8px]">(empty = no resume)</span></label>
@@ -1770,7 +1762,7 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
                 // Auto-fill path from detected agent if available
                 const baseId = ct === 'claude-code' ? 'claude' : ct;
                 const detected = agents.find(a => a.id === baseId);
-                setNewAgent({ ...newAgent, cliType: ct, ...(cliDefaults[ct] || {}), path: detected?.path || newAgent.path, interactiveCmd: detected?.path || newAgent.interactiveCmd });
+                setNewAgent({ ...newAgent, cliType: ct, ...(cliDefaults[ct] || {}), path: detected?.path || newAgent.path });
               }} className={inputClass}>
                 <option value="claude-code">Claude Code</option>
                 <option value="codex">Codex</option>

package/lib/agents/index.ts

@@ -240,7 +240,7 @@ export interface TerminalLaunchInfo {
   model?: string;              // profile model override (--model flag)
 }
 
-export function resolveTerminalLaunch(agentId?: string): TerminalLaunchInfo {
+export function resolveTerminalLaunch(agentId?: string, scene: 'terminal' | 'task' | 'telegram' | 'help' | 'mobile' = 'terminal'): TerminalLaunchInfo {
   const settings = loadSettings();
   const agentCfg = settings.agents?.[agentId || 'claude'] || {};
   // Resolve cliType: own cliType → base agent's cliType → base agent name guessing → agentId name guessing
@@ -263,18 +263,19 @@ export function resolveTerminalLaunch(agentId?: string): TerminalLaunchInfo {
     || undefined;
 
   // Resolve env/model from this agent's per-use models sub-table.
-  // 顶层 model 字段已在 0.10 起被 migrate.ts 清理,这里只读 models.terminal。
+  // 顶层 model 字段已在 0.10 起被 migrate.ts 清理,这里按 scene 读 models[scene]
+  // (默认 terminal;Help 传 'help' 等)。models[scene] === 'default' → 不加 --model。
   let env: Record<string, string> | undefined;
   let model: string | undefined;
   if (agentCfg.base || agentCfg.env || agentCfg.models) {
     if (agentCfg.env) env = { ...agentCfg.env };
-    model = agentCfg.models?.terminal;
+    model = agentCfg.models?.[scene];
     if (model === 'default') model = undefined; // 'default' = 不加 --model
   } else if (agentCfg.profile) {
     const profileCfg = settings.agents?.[agentCfg.profile];
     if (profileCfg) {
       if (profileCfg.env) env = { ...profileCfg.env };
-      model = profileCfg.models?.terminal;
+      model = profileCfg.models?.[scene];
       if (model === 'default') model = undefined;
     }
   }

package/lib/agents/migrate.ts

@@ -89,6 +89,14 @@ export function migrateAgentsFlatten(settings: Settings): boolean {
       delete raw.model;
       mutated = true;
     }
+
+    // ── interactiveCmd 字段清理 ──────────────────────────
+    // 终端启动统一走 resolveTerminalLaunch(cliCmd = agentCfg.path),
+    // interactiveCmd 从未被后端读取,已从 UI / 类型移除。清掉残留死数据。
+    if (raw.interactiveCmd !== undefined) {
+      delete raw.interactiveCmd;
+      mutated = true;
+    }
   }
 
   // === 兜底校验 defaultAgent / chatAgent ===

package/lib/chat/tool-dispatcher.ts

@@ -274,6 +274,30 @@ const BUILTINS: Record<string, BuiltinHandler> = {
     });
     return `Task dispatched: ${task.id} (project: ${project.name}, status: ${task.status}). Watch in the Tasks view.`;
   },
+
+  // List Forge's own help/documentation files so the chat agent can answer
+  // questions about Forge itself (features, config, troubleshooting) without
+  // the user opening the separate Help AI. Pair with read_help_doc.
+  list_help_docs: async () => {
+    const { listHelpDocs } = await import('../help-content');
+    const docs = listHelpDocs();
+    if (docs.length === 0) return 'No Forge help docs found.';
+    return 'Forge help docs (read one with read_help_doc):\n' + docs.map((d) => `- ${d}`).join('\n');
+  },
+
+  // Read one Forge help doc in full. Use to answer questions about Forge's
+  // own features / settings / troubleshooting.
+  read_help_doc: async (input) => {
+    const { doc } = (input as { doc?: string } | undefined) || {};
+    if (!doc) return 'read_help_doc failed: doc is required (a filename from list_help_docs, e.g. "05-pipelines.md").';
+    const { readHelpDoc } = await import('../help-content');
+    const content = readHelpDoc(doc);
+    if (content == null) return `Help doc "${doc}" not found. Call list_help_docs to see available filenames.`;
+    const MAX = 30000;
+    return content.length > MAX
+      ? content.slice(0, MAX) + `\n\n…[truncated — doc is ${content.length} chars]`
+      : content;
+  },
 };
 
 export interface BuiltinToolDef {
@@ -351,6 +375,25 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
       required: ['prompt'],
     },
   },
+  {
+    name: 'list_help_docs',
+    description: "List Forge's own documentation files. Call this FIRST whenever the user asks how Forge itself works — its features, settings/config, setup, or troubleshooting (e.g. pipelines, schedules, connectors, telegram, tunnel, workspace/smiths, skills, crafts, usage/cost, agents/models). Returns doc filenames; then read the relevant one(s) with read_help_doc and answer from their content. No arguments.",
+    input_schema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'read_help_doc',
+    description: 'Read one Forge help doc in full (filename from list_help_docs, e.g. "05-pipelines.md"). Use its content to answer the user\'s question about Forge. Read more than one doc if the question spans topics.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        doc: {
+          type: 'string',
+          description: 'Help doc filename, e.g. "05-pipelines.md" or "10-troubleshooting.md". Get exact names from list_help_docs.',
+        },
+      },
+      required: ['doc'],
+    },
+  },
 ];
 
 // ─── Connector dispatch ──────────────────────────────────

package/lib/help-content.ts

@@ -0,0 +1,51 @@
+/**
+ * Help-doc reader for the chat agent's read_help_doc / list_help_docs tools.
+ *
+ * Reads the markdown docs that ship under lib/help-docs/ (same set the Help AI
+ * terminal uses). Resolved relative to this module so it works regardless of
+ * whether the on-disk sync (ensureHelpDocs → <config>/help) has run yet, then
+ * falls back to the synced copy if the source tree isn't present (installed
+ * tarball layouts).
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfigDir } from './dirs';
+
+// Candidate dirs, in priority order: source tree next to this module, then the
+// synced runtime copy under ~/.forge/help.
+function helpDirs(): string[] {
+  const dirs: string[] = [];
+  try {
+    const here = fileURLToPath(new URL('./help-docs', import.meta.url));
+    dirs.push(here);
+  } catch { /* import.meta.url unavailable (CJS bundle) — skip */ }
+  dirs.push(join(getConfigDir(), 'help'));
+  return dirs;
+}
+
+/** List available help-doc filenames (e.g. ["00-overview.md", ...]), sorted. */
+export function listHelpDocs(): string[] {
+  for (const dir of helpDirs()) {
+    try {
+      if (!existsSync(dir)) continue;
+      const files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+      if (files.length) return files;
+    } catch { /* try next dir */ }
+  }
+  return [];
+}
+
+/** Read one help doc by filename. Returns null if not found. Path-traversal safe. */
+export function readHelpDoc(name: string): string | null {
+  const base = (name || '').split(/[\\/]/).pop() || '';
+  if (!base.endsWith('.md')) return null;
+  for (const dir of helpDirs()) {
+    try {
+      const file = join(dir, base);
+      if (existsSync(file)) return readFileSync(file, 'utf-8');
+    } catch { /* try next dir */ }
+  }
+  return null;
+}

package/lib/help-docs/01-settings.md

@@ -46,7 +46,6 @@ Each agent entry in `settings.agents` supports:
 | `enabled` | boolean | Whether this agent is available |
 | `cliType` | string | CLI tool type: `claude-code`, `codex`, `aider`, `generic` |
 | `taskFlags` | string | Flags for headless task execution (e.g. `-p --verbose`) |
-| `interactiveCmd` | string | Command for interactive terminal sessions |
 | `resumeFlag` | string | Flag to resume sessions (e.g. `-c` for claude) |
 | `outputFormat` | string | Output format: `stream-json`, `text` |
 | `skipPermissionsFlag` | string | Flag to skip permissions (e.g. `--dangerously-skip-permissions`) |

package/lib/settings.ts

@@ -23,7 +23,7 @@ const SETTINGS_FILE = join(DATA_DIR, 'settings.yaml');
 export interface AgentEntry {
   tool?: 'claude' | 'codex' | 'aider' | 'opencode';   // which CLI binary
   path?: string; name?: string; enabled?: boolean;
-  flags?: string[]; taskFlags?: string; interactiveCmd?: string; resumeFlag?: string; outputFormat?: string;
+  flags?: string[]; taskFlags?: string; resumeFlag?: string; outputFormat?: string;
   models?: { terminal?: string; task?: string; telegram?: string; help?: string; mobile?: string };
   skipPermissionsFlag?: string;
   requiresTTY?: boolean;

package/lib/telegram-bot.ts

@@ -1086,7 +1086,7 @@ function getSessionPreview(sessionName: string, maxLines: number = 1): string {
   try {
     const { execSync } = require('node:child_process');
     // Capture last screen, strip ANSI escapes, find last non-empty lines
-    const out = execSync(`tmux capture-pane -t "${sessionName}" -p -S -50 2>/dev/null`, {
+    const out = execSync(`tmux capture-pane -t "${sessionName}" -p -S -100 2>/dev/null`, {
       encoding: 'utf-8',
       timeout: 2000,
     }) as string;
@@ -1101,8 +1101,8 @@ function getSessionPreview(sessionName: string, maxLines: number = 1): string {
       const last = tail[0];
       return last.length > 30 ? last.slice(0, 30) + '…' : last;
     }
-    // Multi-line: truncate each line to 80 chars
-    return tail.map(l => l.length > 80 ? l.slice(0, 80) + '…' : l).join('\n');
+    // Multi-line: truncate each line to 160 chars
+    return tail.map(l => l.length > 160 ? l.slice(0, 160) + '…' : l).join('\n');
   } catch {
     return '';
   }
@@ -1185,8 +1185,8 @@ async function pickInjectTarget(chatId: number, numStr: string) {
   scheduleInjectAutoClear(chatId);
   const labelMap = getSessionLabels();
   const display = labelMap[sessionName] || sessionName.replace(/^mw-?/, '');
-  // Show last 8 lines of context so user knows what's in the terminal
-  const context = getSessionPreview(sessionName, 8);
+  // Show last 16 lines of context so user knows what's in the terminal
+  const context = getSessionPreview(sessionName, 16);
   const contextBlock = context ? `\n\n📺 Last output:\n\`\`\`\n${context}\n\`\`\`` : '';
   await send(chatId,
     `🎯 Target: ${display}${contextBlock}\n\n` +

package/package.json

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