@aion0/forge 0.10.47 → 0.10.49

package/mcp/tools/logs.ts

@@ -0,0 +1,57 @@
+/** Log tools — read the Forge server log so a user can ask "what's up with
+ *  Forge?" without opening the UI. Reads <dataDir>/forge.log directly.
+ *  Real-time streaming is a v1b TODO (needs an SSE endpoint). */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from '@/lib/dirs';
+import { text, guard } from './_shared';
+
+/** Read the last `maxBytes` of a file, dropping a partial first line. */
+function tailBytes(file: string, maxBytes: number): string {
+  const size = statSync(file).size;
+  const readSize = Math.min(size, maxBytes);
+  const buf = Buffer.alloc(readSize);
+  const fd = openSync(file, 'r');
+  try { readSync(fd, buf, 0, readSize, size - readSize); }
+  finally { closeSync(fd); }
+  const str = buf.toString('utf-8');
+  const nl = str.indexOf('\n');
+  return nl > 0 && readSize < size ? str.slice(nl + 1) : str;
+}
+
+export function registerLogTools(server: McpServer): void {
+  server.tool(
+    'forge_tail_logs',
+    'Show the most recent Forge server log lines (the next-server process log). Optionally filter by a search term. Use this to diagnose "what is Forge doing / why did X fail".',
+    {
+      lines: z.number().int().positive().max(1000).optional().describe('How many recent lines to show (default 100, max 1000)'),
+      search: z.string().optional().describe('Only show lines containing this text (case-insensitive)'),
+    },
+    (params) => guard(() => {
+      const file = join(getDataDir(), 'forge.log');
+      if (!existsSync(file)) {
+        // forge.log is the next-server's redirected stdout — written when Forge is
+        // started via `forge server start` / `start.sh`, but NOT by a bare `next dev`
+        // (which logs to its own terminal). Point the caller at the records that DO
+        // carry per-step errors instead of dead-ending on "no log file".
+        return text(
+          `No server log file at ${file}.\n`
+          + `It's written only when Forge is started via \`forge server start\` or \`start.sh\` — a bare \`next dev\` logs to its own stdout/terminal.\n`
+          + `For why a task or pipeline failed, the error is on the record itself: forge_list_tasks status="failed", then forge_get_task id=…, or forge_get_pipeline id=… for per-node errors.`,
+        );
+      }
+      const n = params.lines ?? 100;
+      let all = tailBytes(file, 512 * 1024).split('\n').filter(Boolean);
+      if (params.search) {
+        const q = params.search.toLowerCase();
+        all = all.filter((l) => l.toLowerCase().includes(q));
+      }
+      const shown = all.slice(-n);
+      if (shown.length === 0) return text(params.search ? `No log lines match "${params.search}".` : 'Log is empty.');
+      return text(`Last ${shown.length} line(s)${params.search ? ` matching "${params.search}"` : ''} of ${file}:\n\n${shown.join('\n')}`);
+    }),
+  );
+}

package/mcp/tools/marketplace.ts

@@ -0,0 +1,75 @@
+/** Marketplace tools — search and install Forge extensions: connectors (tool
+ *  bundles for GitLab/Jenkins/…), skills, and workflow templates. All in-process
+ *  lib calls; each follows sync → list → install. Listing auto-syncs once if the
+ *  local cache is empty. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { listMarketplace as listConnectorMarket, syncRegistry, installFromRegistry } from '@/lib/connectors/sync';
+import { listSkills, syncSkills, installGlobal } from '@/lib/skills';
+import { listMarketplace as listWorkflowMarket, syncMarketplace, installFromMarketplace } from '@/lib/workflow-marketplace';
+import { text, fail, guard, skillInstalled } from './_shared';
+
+const KIND = ['connector', 'skill', 'workflow'] as const;
+
+function filterBy(query: string | undefined, hay: string): boolean {
+  return !query || hay.toLowerCase().includes(query.toLowerCase());
+}
+
+export function registerMarketplaceTools(server: McpServer): void {
+  server.tool(
+    'forge_marketplace_search',
+    'Search the Forge marketplace for extensions to install. kind="connector" (external-system tool bundles), "skill" (agent skills), or "workflow" (pipeline templates). Auto-syncs the catalog once if needed.',
+    {
+      kind: z.enum(KIND).describe('What to search for'),
+      query: z.string().optional().describe('Filter by name/description substring'),
+    },
+    (params) => guard(async () => {
+      if (params.kind === 'connector') {
+        let m = listConnectorMarket();
+        if (!m.entries?.length) { await syncRegistry(); m = listConnectorMarket(); }
+        const items = m.entries.filter((e) => filterBy(params.query, `${e.id} ${e.name} ${e.description || ''}`)).slice(0, 40);
+        if (!items.length) return text('No matching connectors (catalog may need a sync, or none match).');
+        return text(`Connectors:\n${items.map((e) => `• ${e.id} v${e.version}${e.installed_version ? ' (installed)' : ''} — ${e.description || e.name}`).join('\n')}\n\nInstall with forge_marketplace_install kind="connector" name="<id>".`);
+      }
+      if (params.kind === 'skill') {
+        let s = listSkills();
+        if (!s?.length) { await syncSkills(); s = listSkills(); }
+        const items = s.filter((e) => filterBy(params.query, `${e.name} ${e.description || ''}`)).slice(0, 40);
+        if (!items.length) return text('No matching skills.');
+        return text(`Skills:\n${items.map((e) => `• ${e.name}${skillInstalled(e) ? ' (installed)' : ''} — ${e.description || ''}`).join('\n')}\n\nInstall with forge_marketplace_install kind="skill" name="<name>".`);
+      }
+      // workflow
+      let w = listWorkflowMarket();
+      if (!w.recipes?.length && !w.pipelines?.length) { await syncMarketplace(); w = listWorkflowMarket(); }
+      const all = [
+        ...(w.pipelines || []).map((e) => ({ ...e, _kind: 'pipeline' })),
+        ...(w.recipes || []).map((e) => ({ ...e, _kind: 'recipe' })),
+      ].filter((e) => filterBy(params.query, `${e.name} ${e.description || ''}`)).slice(0, 40);
+      if (!all.length) return text('No matching workflow templates.');
+      return text(`Workflow templates:\n${all.map((e) => `• [${e._kind}] ${e.name} — ${e.description || ''}`).join('\n')}\n\nInstall with forge_marketplace_install kind="workflow" name="<name>" workflow_kind="<pipeline|recipe>".`);
+    }),
+  );
+
+  server.tool(
+    'forge_marketplace_install',
+    'Install a marketplace extension by kind and name (see forge_marketplace_search). For workflows, pass workflow_kind ("pipeline" or "recipe").',
+    {
+      kind: z.enum(KIND).describe('connector | skill | workflow'),
+      name: z.string().describe('The id/name from forge_marketplace_search'),
+      workflow_kind: z.enum(['pipeline', 'recipe']).optional().describe('For kind="workflow": which list it came from (default pipeline)'),
+    },
+    (params) => guard(async () => {
+      if (params.kind === 'connector') {
+        const r = await installFromRegistry(params.name);
+        return r.ok ? text(`Installed connector ${params.name}${r.version ? ` v${r.version}` : ''}. Configure it in Settings → Connectors.`) : fail(`Install failed: ${r.error || 'unknown error'}`);
+      }
+      if (params.kind === 'skill') {
+        await installGlobal(params.name); // throws on failure
+        return text(`Installed skill "${params.name}" globally.`);
+      }
+      const r = await installFromMarketplace(params.workflow_kind || 'pipeline', params.name);
+      return r.ok ? text(`Installed workflow "${params.name}". List it with forge_list_workflows.`) : fail(`Install failed: ${r.error || 'unknown error'}`);
+    }),
+  );
+}

package/mcp/tools/observability.ts

@@ -0,0 +1,96 @@
+/** Observability tools — "what is Forge doing, and what is it costing?". A live
+ *  status snapshot (tasks/pipelines/schedules/tools) and token/cost analytics.
+ *  All in-process lib reads; no mutations. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { listTasksLite } from '@/lib/task-manager';
+import { listPipelines } from '@/lib/pipeline';
+import { listSchedules } from '@/lib/schedules/store';
+import { checkTools } from '@/lib/health';
+import { queryUsage } from '@/lib/usage-scanner';
+import { text, guard, fmtTokens, summarizePipelines } from './_shared';
+
+const TASK_STATES = ['running', 'queued', 'done', 'failed', 'cancelled'] as const;
+
+// checkTools() spawns blocking `which`/`--version` subprocesses per CLI tool, so
+// memoize it behind a short TTL — forge_status shouldn't reprobe the PATH on every
+// call. The set of installed tools changes rarely. Stored on a globalThis Symbol so
+// the cache survives HMR / multiple module evaluations (same pattern as
+// app/api/mcp/route.ts), instead of resetting on every reload.
+type ToolsCache = { at: number; tools: ReturnType<typeof checkTools> };
+const TOOLS_CACHE_KEY = Symbol.for('forge-mcp-tools-cache');
+const _g = globalThis as unknown as Record<symbol, ToolsCache | undefined>;
+function checkToolsCached(): ReturnType<typeof checkTools> {
+  const now = Date.now();
+  const cached = _g[TOOLS_CACHE_KEY];
+  if (cached && now - cached.at < 60_000) return cached.tools;
+  const fresh: ToolsCache = { at: now, tools: checkTools() };
+  _g[TOOLS_CACHE_KEY] = fresh;
+  return fresh.tools;
+}
+
+export function registerObservabilityTools(server: McpServer): void {
+  server.tool(
+    'forge_status',
+    'A snapshot of what Forge is doing right now: background-task counts by status, in-flight and recent pipelines, schedules, and which CLI tools are installed. Use this to answer "is Forge healthy / what is running?".',
+    {},
+    () => guard(() => {
+      const tasks = listTasksLite();
+      const counts: Record<string, number> = {};
+      for (const t of tasks) counts[t.status] = (counts[t.status] || 0) + 1;
+      const taskLine = TASK_STATES.filter((s) => counts[s]).map((s) => `${counts[s]} ${s}`).join(', ') || 'none';
+
+      const { runningCount, recent } = summarizePipelines(listPipelines());
+
+      const schedules = listSchedules();
+      const enabled = schedules.filter((s) => s.enabled).length;
+
+      const tools = checkToolsCached();
+      const installed = tools.filter((t) => t.installed).map((t) => t.name);
+      const missing = tools.filter((t) => !t.installed).map((t) => t.name);
+
+      const lines = [
+        `Tasks: ${taskLine} (${tasks.length} total)`,
+        `Pipelines: ${runningCount} running${recent.length ? ` · recent: ${recent.join(' · ')}` : ''}`,
+        `Schedules: ${schedules.length} (${enabled} enabled)`,
+        `Tools installed: ${installed.join(', ') || 'none'}${missing.length ? ` · missing: ${missing.join(', ')}` : ''}`,
+      ];
+      return text(`Forge status:\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_get_usage',
+    'Token usage and cost analytics over a recent window, optionally filtered by project or model. Reads the usage store, which Forge rescans automatically about hourly, so figures may be up to an hour old.',
+    {
+      days: z.number().int().positive().max(365).optional().describe('Window in days (default 30)'),
+      project: z.string().optional().describe('Filter to one project name'),
+      model: z.string().optional().describe('Filter to one model family as shown in the "By model" output (e.g. claude-opus-4, claude-sonnet-4, claude-haiku-4). Usage is aggregated by family — full model ids do not match.'),
+    },
+    (params) => guard(() => {
+      const days = params.days ?? 30;
+      const d = queryUsage({ days, projectName: params.project, model: params.model });
+      const t = d.total;
+      const scope = `last ${days} day(s)${params.project ? `, project=${params.project}` : ''}${params.model ? `, model=${params.model}` : ''}`;
+      if (!t.messages && !t.cost) {
+        return text(`No usage recorded (${scope}). Usage is rescanned automatically about hourly.`);
+      }
+      const lines = [
+        `Usage (${scope}):`,
+        `Total: $${t.cost.toFixed(2)} · ${fmtTokens(t.input)} in / ${fmtTokens(t.output)} out · ${t.sessions} sessions · ${t.messages} messages`,
+      ];
+      const topProjects = [...d.byProject].sort((a, b) => b.cost - a.cost).slice(0, 5);
+      if (topProjects.length) {
+        lines.push('By project:');
+        for (const p of topProjects) lines.push(`  • ${p.name}  $${p.cost.toFixed(2)}  (${p.sessions} sessions)`);
+      }
+      const topModels = [...d.byModel].sort((a, b) => b.cost - a.cost).slice(0, 5);
+      if (topModels.length) {
+        lines.push('By model:');
+        for (const m of topModels) lines.push(`  • ${m.model}  $${m.cost.toFixed(2)}`);
+      }
+      return text(lines.join('\n'));
+    }),
+  );
+}

package/mcp/tools/pipelines.ts

@@ -0,0 +1,150 @@
+/** Pipeline tools — list/run/inspect workflow definitions and runs, and create a
+ *  new workflow from a high-level step list (binding each step to a CLI agent).
+ *
+ *  Vocabulary: a *workflow* is a YAML DAG definition; a *pipeline* is a run of one.
+ *  Both definitions live in <dataDir>/flows/*.yaml. lib/flows.ts is a separate
+ *  legacy fan-out system and is intentionally NOT used here. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import {
+  listWorkflows, getWorkflow, startPipeline, getPipeline, listPipelinesSummary, parseWorkflow, cancelPipeline,
+} from '@/lib/pipeline';
+import { getDataDir } from '@/lib/dirs';
+import { ensureInitialized } from '@/lib/init';
+import { getProjectInfo } from '@/lib/projects';
+import { listAgents } from '@/lib/agents';
+import { text, fail, guard } from './_shared';
+
+export function registerPipelineTools(server: McpServer): void {
+  server.tool(
+    'forge_list_workflows',
+    'List the available pipeline workflow definitions (reusable DAG templates). Use forge_run_pipeline to start one, or forge_help topic="pipelines" to learn what a pipeline is.',
+    {},
+    () => guard(() => {
+      const wfs = listWorkflows();
+      if (wfs.length === 0) return text('No workflows defined. Create one with forge_create_pipeline, or install from the marketplace.');
+      const lines = wfs.map((w) => {
+        const n = Object.keys(w.nodes || {}).length;
+        return `• ${w.name}${w.type && w.type !== 'dag' ? ` (${w.type})` : ''} — ${n} node(s)${w.description ? `: ${w.description}` : ''}`;
+      });
+      return text(`${wfs.length} workflow(s):\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_run_pipeline',
+    'Start a pipeline from a workflow definition. Provide any input variables the workflow declares.',
+    {
+      workflow: z.string().describe('Workflow name (from forge_list_workflows)'),
+      input: z.record(z.string(), z.string()).optional().describe('Input variables, e.g. { "project": "my-app" }'),
+    },
+    (params) => guard(() => {
+      if (!getWorkflow(params.workflow)) return fail(`Workflow not found: ${params.workflow}. Use forge_list_workflows.`);
+      ensureInitialized();
+      const pipeline = startPipeline(params.workflow, params.input || {});
+      return text(`Started pipeline ${pipeline.id} (workflow: ${params.workflow}, status: ${pipeline.status}).\nTrack it with forge_get_pipeline id=${pipeline.id}.`);
+    }),
+  );
+
+  server.tool(
+    'forge_get_pipeline',
+    'Show the status and per-node results of a pipeline run.',
+    { id: z.string().describe('Pipeline run id') },
+    (params) => guard(() => {
+      const p = getPipeline(params.id);
+      if (!p) return fail(`Pipeline not found: ${params.id}`);
+      const nodes = Object.entries(p.nodes).map(([id, n]) => {
+        let line = `  ${id}: ${n.status}`;
+        if (n.error) line += ` — ${n.error}`;
+        return line;
+      });
+      return text(`Pipeline ${p.id} [${p.status}] (workflow: ${p.workflowName})\n${nodes.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_cancel_pipeline',
+    'Cancel a running pipeline by id — stops its in-flight nodes. No-op if it already finished.',
+    { id: z.string().describe('Pipeline run id (from forge_run_pipeline / forge_list_pipeline_runs)') },
+    (params) => guard(() => {
+      const ok = cancelPipeline(params.id);
+      return text(ok ? `Cancelled pipeline ${params.id}.` : `Could not cancel ${params.id} (not found, or already finished).`);
+    }),
+  );
+
+  server.tool(
+    'forge_list_pipeline_runs',
+    'List recent pipeline runs (newest first) with their status.',
+    { limit: z.number().int().positive().max(100).optional().describe('Max runs to show (default 20)') },
+    (params) => guard(() => {
+      const runs = listPipelinesSummary({ limit: params.limit ?? 20 });
+      if (runs.length === 0) return text('No pipeline runs yet.');
+      const lines = runs.map((r) => `• ${r.id}  [${r.status}]  ${r.workflowName}  (${r.createdAt})`);
+      return text(`${runs.length} run(s):\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_create_pipeline',
+    'Create a new pipeline workflow from an ordered list of steps. Each step runs an agent in a project; steps run in sequence (each depends on the previous). Bind a step to a specific CLI agent via its "agent" field (defaults to "claude"). Saves a reusable workflow you can then forge_run_pipeline.',
+    {
+      name: z.string().describe('Workflow name (used as the file name)'),
+      description: z.string().optional().describe('What the pipeline does'),
+      steps: z.array(z.object({
+        project: z.string().describe('Project name or {{vars}} template the step runs in'),
+        prompt: z.string().describe('What the agent should do in this step'),
+        agent: z.string().optional().describe('CLI agent id for this step (default "claude")'),
+      })).min(1).describe('Ordered steps; each runs after the previous one'),
+    },
+    (params) => guard(() => {
+      // Catch typo'd project names at create time rather than letting every node
+      // fail at run with "Project not found". Templated ({{var}}) projects are
+      // resolved per-run, so they can't be checked here — skip them.
+      const unknown = [...new Set(
+        params.steps.map((s) => s.project).filter((p) => !p.includes('{{') && !getProjectInfo(p)),
+      )];
+      if (unknown.length) {
+        return fail(`Unknown project(s): ${unknown.join(', ')}. Use forge_list_projects, or pass a {{var}} template resolved at run time.`);
+      }
+
+      // Validate explicit agent ids too, so a typo fails at create time rather than
+      // at the node that uses it. (Omitted agent defaults to "claude" below.)
+      const validAgents = new Set(listAgents().map((a) => a.id));
+      const badAgents = [...new Set(
+        params.steps.map((s) => s.agent).filter((a): a is string => !!a && !a.includes('{{') && !validAgents.has(a)),
+      )];
+      if (badAgents.length) {
+        return fail(`Unknown agent id(s): ${badAgents.join(', ')}. Use forge_list_agents, or omit to default to "claude".`);
+      }
+
+      const safeName = params.name.replace(/[^a-zA-Z0-9_-]/g, '-');
+      const nodes: Record<string, unknown> = {};
+      params.steps.forEach((st, i) => {
+        const id = `s${i + 1}`;
+        nodes[id] = {
+          project: st.project,
+          prompt: st.prompt,
+          agent: st.agent || 'claude',
+          ...(i > 0 ? { depends_on: [`s${i}`] } : {}),
+        };
+      });
+      const wf = { name: safeName, ...(params.description ? { description: params.description } : {}), nodes };
+      const yaml = YAML.stringify(wf);
+
+      // Validate against the engine's own parser before writing.
+      try { parseWorkflow(yaml); }
+      catch (e) { return fail(`Generated workflow is invalid: ${(e as Error).message}`); }
+
+      const dir = join(getDataDir(), 'flows');
+      mkdirSync(dir, { recursive: true });
+      const file = join(dir, `${safeName}.yaml`);
+      if (existsSync(file)) return fail(`A workflow named "${safeName}" already exists. Pick another name.`);
+      writeFileSync(file, yaml, 'utf-8');
+      return text(`Created workflow "${safeName}" with ${params.steps.length} step(s).\nRun it with forge_run_pipeline workflow="${safeName}".`);
+    }),
+  );
+}

package/mcp/tools/projects.ts

@@ -0,0 +1,54 @@
+/** Project tools — discover, register, and inspect the projects Forge manages.
+ *  Management-only: metadata (roots, git, language, rules-presence, sessions),
+ *  never project file contents. All in-process lib calls. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { scanProjects, addProjectRoot, removeProjectRoot, SCRATCH_PROJECT_NAME } from '@/lib/projects';
+import { text, fail, guard } from './_shared';
+
+export function registerProjectTools(server: McpServer): void {
+  server.tool(
+    'forge_list_projects',
+    'List the projects Forge can run tasks against (auto-discovered from the configured project roots). Each line shows name, language, whether it is a git repo, whether it has agent rules (CLAUDE.md), and last-modified date. Use a name with forge_create_task or forge_get_project. If none are registered, use forge_register_project.',
+    {},
+    () => guard(() => {
+      const projects = scanProjects();
+      const real = projects.filter((p) => p.name !== SCRATCH_PROJECT_NAME);
+      if (real.length === 0) {
+        return text('No projects registered yet (only the built-in "scratch" project exists). Register a folder that contains your projects with forge_register_project path="/path/to/code".');
+      }
+      const lines = projects.map((p) =>
+        `• ${p.name}${p.language ? ` [${p.language}]` : ''}${p.hasGit ? ' (git)' : ''}${p.hasClaudeMd ? ' (rules)' : ''}`
+        + ` — ${p.path}${p.lastModified ? ` · ${p.lastModified.slice(0, 10)}` : ''}`,
+      );
+      return text(`${projects.length} project(s):\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_register_project',
+    'Register a project root with Forge: a directory whose immediate subdirectories Forge will list as projects (e.g. "/Users/me/code", which contains your repos). Idempotent; validates the path exists. This is how you make new projects visible to forge_list_projects / forge_create_task.',
+    { path: z.string().min(1).describe('Absolute path to a folder that CONTAINS your projects (not a single repo)') },
+    (params) => guard(() => {
+      const r = addProjectRoot(params.path);
+      if (!r.ok) return fail(`Could not register "${params.path}": ${r.error}.`);
+      if (r.alreadyRegistered) return text(`Already registered: ${r.root}.`);
+      const added = scanProjects().filter((p) => p.root === r.root).map((p) => p.name);
+      const found = added.length ? `\nProjects now visible from it: ${added.join(', ')}.` : '\n(No subdirectories found yet — add projects under it, then forge_list_projects.)';
+      return text(`Registered project root ${r.root}.${found}`);
+    }),
+  );
+
+  server.tool(
+    'forge_unregister_project',
+    'Unregister a project root (does NOT delete files — only stops Forge from listing its subdirectories as projects). Pass the root path exactly as shown in forge_get_project (root: …).',
+    { path: z.string().min(1).describe('Absolute path of the root to unregister') },
+    (params) => guard(() => {
+      const r = removeProjectRoot(params.path);
+      if (!r.ok) return fail(`Could not unregister "${params.path}": ${r.error}.`);
+      return text(`Unregistered project root ${r.root}. Its subdirectories no longer appear in forge_list_projects.`);
+    }),
+  );
+
+}

package/mcp/tools/tasks.ts

@@ -0,0 +1,93 @@
+/** Task tools — the background-task lifecycle (list / inspect / create / cancel /
+ *  delete). Calls lib/task-manager in-process. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  listTasksLite, getTask, createTask, cancelTask,
+} from '@/lib/task-manager';
+import { getProjectInfo } from '@/lib/projects';
+import { ensureInitialized } from '@/lib/init';
+import type { TaskStatus } from '@/src/types';
+import { text, fail, guard, describeSession } from './_shared';
+
+const STATUS = ['queued', 'running', 'done', 'failed', 'cancelled'] as const;
+const ICON: Record<string, string> = { queued: '⏳', running: '🔄', done: '✅', failed: '❌', cancelled: '⚪' };
+
+export function registerTaskTools(server: McpServer): void {
+  server.tool(
+    'forge_list_tasks',
+    'List background tasks, newest first. Optionally filter by status. Returns id, status, project, prompt, and cost — use forge_get_task for full detail.',
+    { status: z.enum(STATUS).optional().describe('Filter by status') },
+    (params) => guard(() => {
+      const tasks = listTasksLite(params.status as TaskStatus | undefined);
+      if (tasks.length === 0) return text(params.status ? `No ${params.status} tasks.` : 'No tasks.');
+      const lines = tasks.slice(0, 50).map((t) => {
+        const cost = t.costUSD != null ? ` $${t.costUSD.toFixed(3)}` : '';
+        return `${ICON[t.status] || '?'} ${t.id}  ${t.status.padEnd(9)} ${t.projectName}  ${t.prompt.slice(0, 60)}${cost}`;
+      });
+      const more = tasks.length > 50 ? `\n… ${tasks.length - 50} more` : '';
+      return text(`${tasks.length} task(s):\n${lines.join('\n')}${more}`);
+    }),
+  );
+
+  server.tool(
+    'forge_get_task',
+    'Get full detail for one task: status, prompt, cost, result summary, error, and git branch.',
+    { id: z.string().describe('Task id') },
+    (params) => guard(() => {
+      const t = getTask(params.id);
+      if (!t) return fail(`Task not found: ${params.id}`);
+      const lines = [
+        `${ICON[t.status] || '?'} Task ${t.id} [${t.status}]`,
+        `Project: ${t.projectName} (${t.projectPath})`,
+        `Prompt: ${t.prompt}`,
+      ];
+      if (t.agent) lines.push(`Agent: ${t.agent}`);
+      if (t.gitBranch) lines.push(`Branch: ${t.gitBranch}`);
+      if (t.costUSD != null) lines.push(`Cost: $${t.costUSD.toFixed(4)}`);
+      if (t.startedAt) lines.push(`Started: ${t.startedAt}`);
+      if (t.completedAt) lines.push(`Completed: ${t.completedAt}`);
+      if (t.error) lines.push(`\nError: ${t.error}`);
+      if (t.resultSummary) lines.push(`\nResult:\n${t.resultSummary.slice(0, 1500)}`);
+      return text(lines.join('\n'));
+    }),
+  );
+
+  server.tool(
+    'forge_create_task',
+    'Submit a background task to run an agent in a project. Resolves the project by name (see forge_list_projects). By default it continues the project\'s existing session; set new_session to start fresh.',
+    {
+      project: z.string().describe('Project name (from forge_list_projects)'),
+      prompt: z.string().describe('What the agent should do'),
+      new_session: z.boolean().optional().describe('Start a fresh session instead of continuing the project\'s last one'),
+      agent: z.string().optional().describe('Agent/CLI to use (e.g. "claude", "codex"); defaults to the configured agent'),
+    },
+    (params) => guard(() => {
+      const project = getProjectInfo(params.project);
+      if (!project) return fail(`Project not found: ${params.project}. Use forge_list_projects to see valid names.`);
+      ensureInitialized(); // make sure the task runner is up so the task actually executes
+      const task = createTask({
+        projectName: project.name,
+        projectPath: project.path,
+        prompt: params.prompt,
+        priority: 0,
+        conversationId: params.new_session ? '' : undefined,
+        mode: 'prompt',
+        agent: params.agent || undefined,
+      });
+      const session = describeSession(params.new_session, task.conversationId);
+      return text(`Created task ${task.id} in ${task.projectName} (${session}).\nPrompt: ${params.prompt}\nInspect with forge_get_task id=${task.id}.`);
+    }),
+  );
+
+  server.tool(
+    'forge_cancel_task',
+    'Cancel a queued or running task. Does not delete it — its record and partial output remain.',
+    { id: z.string().describe('Task id') },
+    (params) => guard(() => {
+      const ok = cancelTask(params.id);
+      return text(ok ? `Cancelled task ${params.id}.` : `Could not cancel ${params.id} (not found, or already finished).`);
+    }),
+  );
+}

package/mcp/tools/workspace.ts

@@ -0,0 +1,94 @@
+/** Workspace-agent tools — add/list the agents ("smiths") in a project's
+ *  multi-agent workspace (e.g. add a code reviewer). These are DISTINCT from CLI
+ *  agents (see integrations.ts).
+ *
+ *  Per the single-writer rule, workspace mutations go through the workspace daemon
+ *  HTTP API (never direct state.json writes). Reads use in-process lib. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { getProjectInfo } from '@/lib/projects';
+import { findWorkspaceByProject } from '@/lib/workspace';
+import { createFromPreset, AGENT_PRESETS } from '@/lib/workspace/presets';
+import { text, fail, guard } from './_shared';
+
+const DAEMON = `http://localhost:${Number(process.env.WORKSPACE_PORT) || 8405}`;
+
+/** Map a natural-language role to a preset key (presets: pm, architect, engineer, qa, reviewer, lead). */
+function resolveRole(input: string): string | undefined {
+  const q = input.toLowerCase().replace(/[\s_-]+/g, '');
+  const alias: Record<string, string> = {
+    codereviewer: 'reviewer', reviewer: 'reviewer', review: 'reviewer',
+    engineer: 'engineer', dev: 'engineer', developer: 'engineer', coder: 'engineer',
+    qa: 'qa', tester: 'qa', test: 'qa',
+    pm: 'pm', productmanager: 'pm', product: 'pm',
+    architect: 'architect', arch: 'architect',
+    lead: 'lead', techlead: 'lead',
+  };
+  const key = alias[q] || q;
+  return AGENT_PRESETS[key] ? key : undefined;
+}
+
+async function daemon(path: string, body: unknown): Promise<{ ok: boolean; data?: any; error?: string }> {
+  try {
+    const res = await fetch(`${DAEMON}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) return { ok: false, error: data?.error || `daemon returned ${res.status}` };
+    return { ok: true, data };
+  } catch (e) {
+    return { ok: false, error: `workspace daemon unreachable at ${DAEMON} (${(e as Error).message}). Is Forge fully started?` };
+  }
+}
+
+export function registerWorkspaceTools(server: McpServer): void {
+  server.tool(
+    'forge_list_workspace_agents',
+    'List the agents (smiths) in a project\'s multi-agent workspace and their roles.',
+    { project: z.string().describe('Project name') },
+    (params) => guard(() => {
+      const project = getProjectInfo(params.project);
+      if (!project) return fail(`Project not found: ${params.project}. Use forge_list_projects.`);
+      const ws = findWorkspaceByProject(project.path);
+      if (!ws) return text(`No workspace exists for ${project.name} yet. Add an agent with forge_add_workspace_agent to create one.`);
+      const agents = (ws.agents || []).filter((a) => a.type !== 'input');
+      if (agents.length === 0) return text(`${project.name}'s workspace has no agents yet.`);
+      const lines = agents.map((a) => `• ${a.label} (${a.role ? a.role.slice(0, 60) : a.backend})${a.primary ? ' [primary]' : ''}`);
+      return text(`${agents.length} workspace agent(s) in ${project.name}:\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_add_workspace_agent',
+    'Add an agent to a project\'s multi-agent workspace by role (e.g. "code reviewer", "engineer", "qa", "architect", "pm", "lead"). Creates the workspace if needed. Goes through the workspace daemon.',
+    {
+      project: z.string().describe('Project name (from forge_list_projects)'),
+      role: z.string().describe('Role to add, e.g. "code reviewer", "engineer", "qa"'),
+    },
+    (params) => guard(async () => {
+      const project = getProjectInfo(params.project);
+      if (!project) return fail(`Project not found: ${params.project}. Use forge_list_projects.`);
+      const roleKey = resolveRole(params.role);
+      if (!roleKey) return fail(`Unknown role "${params.role}". Available: ${Object.keys(AGENT_PRESETS).join(', ')}.`);
+
+      // Find or create the workspace (create goes through the daemon — single writer).
+      // findWorkspaceByProject is typed (WorkspaceState.id); the daemon response is
+      // untrusted HTTP, so narrow it to the one field we use rather than `any`.
+      let wsId = findWorkspaceByProject(project.path)?.id;
+      if (!wsId) {
+        const created = await daemon('/workspace/create', { projectPath: project.path, projectName: project.name });
+        if (!created.ok) return fail(created.error || 'Could not create workspace.');
+        wsId = (created.data as { id?: string } | undefined)?.id;
+      }
+      if (!wsId) return fail('Could not resolve workspace id.');
+
+      const config = createFromPreset(roleKey);
+      const added = await daemon(`/workspace/${wsId}/agents`, { action: 'add', config });
+      if (!added.ok) return fail(added.error || 'Could not add agent.');
+      return text(`Added ${config.label} (${roleKey}) to ${project.name}'s workspace.`);
+    }),
+  );
+}

package/package.json

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