@aion0/forge 0.10.31 → 0.10.32

package/RELEASE_NOTES.md

@@ -1,11 +1,11 @@
-# Forge v0.10.31
+# Forge v0.10.32
 
 Released: 2026-06-02
 
-## Changes since v0.10.30
+## Changes since v0.10.31
 
 ### Other
-- fix(watch): allow builtin tool names (no connector prefix) in start_watch
+- fix(watch): builtin pollers return JSON + add get_task_status
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.30...v0.10.31
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.31...v0.10.32

package/lib/chat/tool-dispatcher.ts

@@ -163,50 +163,61 @@ const BUILTINS: Record<string, BuiltinHandler> = {
     }
 
     const pipeline = startPipeline(params.workflow, stringInput, { skills: skills.length ? skills : undefined });
-    let line = `Pipeline started: ${pipeline.id} (workflow: ${params.workflow}, status: ${pipeline.status})`;
+    const fresh = getPipeline(pipeline.id) || pipeline;
+    const errors: string[] = [];
     if (pipeline.status === 'failed') {
-      const fresh = getPipeline(pipeline.id) || pipeline;
-      const errs: string[] = [];
       for (const [nid, n] of Object.entries(fresh.nodes || {})) {
-        if ((n as any).error) errs.push(`${nid}: ${(n as any).error}`);
+        if ((n as any).error) errors.push(`${nid}: ${(n as any).error}`);
       }
-      if (errs.length > 0) line += `\nFailure(s): ${errs.join(' | ').slice(0, 500)}`;
-    } else if (pipeline.status === 'done') {
-      // For for_each workflows, a "done" with zero iterations is the silent
-      // failure mode (empty source). Warn the LLM explicitly so it doesn't
-      // claim success.
-      const fresh = getPipeline(pipeline.id) || pipeline;
+    }
+    let warning: string | undefined;
+    if (pipeline.status === 'done') {
       const forEach = (fresh as any).forEach;
       if (forEach && typeof forEach === 'object') {
         const iters = Array.isArray(forEach.iterations) ? forEach.iterations.length : 0;
         const total = typeof forEach.total === 'number' ? forEach.total : iters;
         if (total === 0) {
-          line += '\n⚠ Pipeline finished with 0 iterations — likely empty source list. This is NOT a success; the work the user asked for did NOT happen. Re-check input fields (especially the one feeding for_each.source) and retry.';
+          warning = 'Pipeline finished with 0 iterations — likely empty source list. This is NOT a success; the work the user asked for did NOT happen. Re-check input fields (especially the one feeding for_each.source) and retry.';
         }
       }
-    } else {
-      line += '. Watch progress in the Pipelines view.';
     }
-    return line;
+    return JSON.stringify({
+      ok: pipeline.status !== 'failed',
+      pipeline_id: pipeline.id,
+      workflow: params.workflow,
+      status: pipeline.status,
+      terminal: pipeline.status !== 'running',
+      ...(errors.length ? { errors: errors.join(' | ').slice(0, 500) } : {}),
+      ...(warning ? { warning } : {}),
+      hint: pipeline.status === 'running'
+        ? 'To wait for completion: start_watch poll="get_pipeline_status" poll_args={pipeline_id:"' + pipeline.id + '"} done_match={path:"status",equals:"done"} fail_path="status==failed". Do NOT poll get_pipeline_status in this conversation.'
+        : undefined,
+    });
   },
 
   // Query a pipeline run's status + per-node results by id (pairs with
-  // trigger_pipeline's returned id). Mirrors the MCP get_pipeline_status tool.
+  // trigger_pipeline's returned id). Returns JSON so start_watch's
+  // done_match={path:"status",equals:"done"} can resolve — a string-shaped
+  // response leaves watches polling forever.
   get_pipeline_status: async (input) => {
     const params = (input as { pipeline_id?: string } | undefined) || {};
-    if (!params.pipeline_id) return 'get_pipeline_status failed: pipeline_id is required (returned by trigger_pipeline).';
+    if (!params.pipeline_id) return JSON.stringify({ ok: false, error: 'pipeline_id is required (returned by trigger_pipeline)' });
     const { getPipeline } = await import('../pipeline');
     const pipeline = getPipeline(params.pipeline_id);
-    if (!pipeline) return `Pipeline "${params.pipeline_id}" not found.`;
-    const nodes = Object.entries(pipeline.nodes || {}).map(([id, n]) => {
-      let line = `  ${id}: ${n.status}`;
-      if (n.error) line += ` — ${n.error}`;
-      for (const [k, v] of Object.entries(n.outputs || {})) {
-        line += `\n    ${k}: ${String(v).slice(0, 200)}`;
-      }
-      return line;
-    }).join('\n');
-    return `Pipeline ${pipeline.id} [${pipeline.status}] (${pipeline.workflowName})\n${nodes}`;
+    if (!pipeline) return JSON.stringify({ ok: false, error: `Pipeline "${params.pipeline_id}" not found` });
+    const nodes = Object.entries(pipeline.nodes || {}).map(([id, n]) => ({
+      id,
+      status: n.status,
+      ...(n.error ? { error: n.error } : {}),
+      outputs: Object.fromEntries(Object.entries(n.outputs || {}).map(([k, v]) => [k, String(v).slice(0, 500)])),
+    }));
+    return JSON.stringify({
+      id: pipeline.id,
+      status: pipeline.status,
+      terminal: pipeline.status !== 'running',
+      workflowName: pipeline.workflowName,
+      nodes,
+    });
   },
 
   // Surface Forge's local context (projects + agents + skills) so the chat
@@ -260,11 +271,11 @@ const BUILTINS: Record<string, BuiltinHandler> = {
   // caller can ask "what's the status of task <id>?" later — we don't block.
   dispatch_task: async (input) => {
     const params = (input as { project?: string; prompt?: string; agent?: string } | undefined) || {};
-    if (!params.prompt) return 'dispatch_task failed: prompt is required';
+    if (!params.prompt) return JSON.stringify({ ok: false, error: 'prompt is required' });
     const { getProjectInfo, SCRATCH_PROJECT_NAME } = await import('../projects');
     const projectName = params.project?.trim() || SCRATCH_PROJECT_NAME;
     const project = getProjectInfo(projectName);
-    if (!project) return `dispatch_task failed: project "${projectName}" not found`;
+    if (!project) return JSON.stringify({ ok: false, error: `project "${projectName}" not found` });
     const { createTask } = await import('../task-manager');
     const task = createTask({
       projectName: project.name,
@@ -273,7 +284,33 @@ const BUILTINS: Record<string, BuiltinHandler> = {
       conversationId: '',
       agent: params.agent || undefined,
     });
-    return `Task dispatched: ${task.id} (project: ${project.name}, status: ${task.status}). Watch in the Tasks view.`;
+    return JSON.stringify({
+      ok: true,
+      task_id: task.id,
+      project: project.name,
+      status: task.status,
+      hint: 'To wait for completion: start_watch poll="get_task_status" poll_args={task_id:"' + task.id + '"} done_path="terminal". Do NOT poll get_task_status in this conversation.',
+    });
+  },
+
+  // 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"}.
+  get_task_status: async (input) => {
+    const params = (input as { task_id?: string } | undefined) || {};
+    if (!params.task_id) return JSON.stringify({ ok: false, error: 'task_id is required (returned by dispatch_task)' });
+    const { getTask } = await import('../task-manager');
+    const task = getTask(params.task_id);
+    if (!task) return JSON.stringify({ ok: false, error: `Task "${params.task_id}" not found` });
+    return JSON.stringify({
+      id: task.id,
+      status: task.status,
+      terminal: task.status === 'done' || task.status === 'failed' || task.status === 'cancelled',
+      project: task.projectName,
+      ...(task.resultSummary ? { result_summary: String(task.resultSummary).slice(0, 1000) } : {}),
+      ...(task.error ? { error: String(task.error).slice(0, 500) } : {}),
+      ...(task.completedAt ? { completed_at: task.completedAt } : {}),
+    });
   },
 
   // List Forge's own help/documentation files so the chat agent can answer
@@ -315,7 +352,7 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
   },
   {
     name: 'trigger_pipeline',
-    description: 'Trigger a Forge pipeline workflow (YAML under flows/). Two-step usage: (1) call with NO args first — returns every workflow + its input schema (which fields are required vs have defaults). (2) call again with workflow=<name> and input={...} passing ONLY required fields and any optional fields the user explicitly specified. NEVER pass invented placeholder values for optional fields with defaults — omit them and the default is used. If the pipeline fails immediately, the response includes the validation error so you can fix the inputs and retry.',
+    description: 'Trigger a Forge pipeline workflow (YAML under flows/). Two-step usage: (1) call with NO args first — returns every workflow + its input schema (which fields are required vs have defaults). (2) call again with workflow=<name> and input={...} passing ONLY required fields and any optional fields the user explicitly specified. NEVER pass invented placeholder values for optional fields with defaults — omit them and the default is used. On success returns JSON: {ok, pipeline_id, workflow, status, terminal, errors?, warning?, hint?}. If the run is still running, follow the hint — call start_watch on get_pipeline_status and STOP polling in this conversation.',
     input_schema: {
       type: 'object',
       properties: {
@@ -337,7 +374,7 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
   },
   {
     name: 'get_pipeline_status',
-    description: "Check a Forge pipeline run's live status + per-node results by id. Pass pipeline_id (returned by trigger_pipeline) to get the run's overall status + each node's status / error / outputs. Use whenever the user asks how a running or finished pipeline is doing.",
+    description: "Check a Forge pipeline run's live status + per-node results by id. Pass pipeline_id (returned by trigger_pipeline) to get a JSON object: {id, status: 'running'|'done'|'failed'|'cancelled', terminal: bool, workflowName, nodes: [{id, status, error?, outputs}]}. Use whenever the user asks how a running or finished pipeline is doing. For start_watch, pair this with done_match={path:\"status\",equals:\"done\"} (or done_path=\"terminal\" to fire on ANY terminal state) and fail_path=... per your needs.",
     input_schema: {
       type: 'object',
       properties: {
@@ -356,7 +393,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 immediately with the task id; the task runs in the background and the user can check the Tasks view for output.',
+    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.',
     input_schema: {
       type: 'object',
       properties: {
@@ -376,6 +413,20 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
       required: ['prompt'],
     },
   },
+  {
+    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\"}.",
+    input_schema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'Task id (returned by dispatch_task).',
+        },
+      },
+      required: ['task_id'],
+    },
+  },
   {
     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.",

package/lib/watch/start-watch-tool.ts

@@ -36,11 +36,13 @@ export function buildStartWatchTool(sessionId: string | null): StartWatchTool {
     name: 'start_watch',
     description:
       'Register a BACKGROUND WATCH that polls a tool until done, then posts the result back here — for long-running jobs you just kicked off (a Forge pipeline, a Jenkins build, a test run, a device upgrade). Use this INSTEAD of polling in conversation: call the trigger tool, then call start_watch and STOP — Forge polls in the background and a completion message arrives in this chat. ' +
-      'Pick `poll` = the read tool that reports status. Two forms accepted: (a) connector tool "<connector>.<tool>" e.g. "jenkins.get_build", "gitlab.get_pipeline"; (b) BARE builtin name e.g. "get_pipeline_status" (Forge pipelines — pair with poll_args={pipeline_id} and done_match={path:"status",equals:"done"}). Set `poll_args` to call it with (e.g. the build number you predicted via get_next_build_number). Give a done condition: `done_match` {path, equals} on the poll result (e.g. path "result" equals "SUCCESS"), or `done_path` (a result path that becomes truthy). You usually already saw the poll tool\'s output once, so you know the right field. Optional `fail_path` (truthy = failed). Tune `interval_sec`/`timeout_sec` to the job (pipeline ≈ 30s / 1800s, build ≈ 60s / 1800s).',
+      'Pick `poll` = the read tool that reports status. Two forms accepted: (a) connector tool "<connector>.<tool>" e.g. "jenkins.get_build", "gitlab.get_pipeline"; (b) BARE builtin name — "get_pipeline_status" (pair with poll_args={pipeline_id} and done_match={path:"status",equals:"done"}) or "get_task_status" (pair with poll_args={task_id} and done_path="terminal"). Set `poll_args` to call it with (e.g. the build number you predicted via get_next_build_number). ' +
+      'Give a done condition: `done_match` {path, equals} on the poll result (e.g. path "result" equals "SUCCESS"), or `done_path` (a result path that becomes truthy). You usually already saw the poll tool\'s output once, so you know the right field. Optional `fail_path` (truthy = failed). ' +
+      'If the poll tool returns NON-JSON text (e.g. some shell-protocol tools), the result is wrapped as {_raw: "...full output..."}, so use done_match={path:"_raw",contains:"DONE"} to grep markers in the output. Tune `interval_sec`/`timeout_sec` to the job (pipeline ≈ 30s / 1800s, build ≈ 60s / 1800s).',
     input_schema: {
       type: 'object',
       properties: {
-        poll: { type: 'string', description: 'Tool to poll. Either "<connector>.<tool>" e.g. "jenkins.get_build", OR a bare builtin name e.g. "get_pipeline_status" (for Forge pipelines). Must be a read/status tool.' },
+        poll: { type: 'string', description: 'Tool to poll. Either "<connector>.<tool>" e.g. "jenkins.get_build", OR a bare builtin name — "get_pipeline_status" (Forge pipelines) or "get_task_status" (dispatched tasks). Must be a read/status tool.' },
         poll_args: { type: 'object', description: 'Args to call the poll tool with each tick, e.g. {"job_path":"job/foo","build_number":18}. Concrete values, not templates.' },
         done_match: {
           type: 'object',

package/package.json

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