@runfusion/fusion 0.2.6 → 0.3.0

package/dist/pi-claude-cli/src/prompt-builder.ts

@@ -23,7 +23,20 @@ export interface PiMessage {
   content: string | unknown[];
   toolName?: string;
 }
-export type PiContext = { systemPrompt?: string; messages: PiMessage[] };
+/**
+ * Minimal pi-ai Tool shape — the subset we read from `Context.tools` to build
+ * the deferred-tools system-prompt addendum.
+ */
+export interface PiToolLike {
+  name: string;
+  description?: string;
+}
+
+export type PiContext = {
+  systemPrompt?: string;
+  messages: PiMessage[];
+  tools?: ReadonlyArray<PiToolLike>;
+};
 import {
   mapPiToolNameToClaude,
   translatePiArgsToClaude,
@@ -49,7 +62,7 @@ type AnthropicContentBlock =
  * Each message is labeled with its role:
  * - USER: for user messages
  * - ASSISTANT: for assistant messages
- * - TOOL RESULT (historical {toolName}): for tool result messages
+ * - TOOL RESULT ({toolName}): for tool result messages
  */
 /** Module-level counter for placeholder images, reset per buildPrompt call. */
 let placeholderImageCount = 0;
@@ -200,7 +213,7 @@ export function buildResumePrompt(context: PiContext): string | AnthropicContent
         const claudeToolName = msg.toolName
           ? mapPiToolNameToClaude(msg.toolName)
           : "unknown";
-        parts.push(`TOOL RESULT (historical ${claudeToolName}):`);
+        parts.push(`TOOL RESULT (${claudeToolName}):`);
       }
       parts.push(toolResultContentToText(msg.content));
     } else if (msg.role === "user") {
@@ -270,7 +283,7 @@ export function buildPrompt(context: PiContext): string | AnthropicContentBlock[
           const claudeToolName = message.toolName
             ? mapPiToolNameToClaude(message.toolName)
             : "unknown";
-          historyParts.push(`TOOL RESULT (historical ${claudeToolName}):`);
+          historyParts.push(`TOOL RESULT (${claudeToolName}):`);
         }
         // Extract text portion of tool result
         historyParts.push(toolResultContentToText(message.content));
@@ -334,7 +347,7 @@ export function buildPrompt(context: PiContext): string | AnthropicContentBlock[
         const claudeToolName = message.toolName
           ? mapPiToolNameToClaude(message.toolName)
           : "unknown";
-        parts.push(`TOOL RESULT (historical ${claudeToolName}):`);
+        parts.push(`TOOL RESULT (${claudeToolName}):`);
       }
       parts.push(toolResultContentToText(message.content));
     }
@@ -372,7 +385,7 @@ export function buildSystemPrompt(
   const parts: string[] = [];
 
   if (context.systemPrompt) {
-    parts.push(context.systemPrompt);
+    parts.push(rewriteCustomToolReferences(context.systemPrompt, context.tools));
   }
 
   // Look for AGENTS.md
@@ -396,9 +409,100 @@ export function buildSystemPrompt(
     );
   }
 
+  const customToolsAddendum = buildCustomToolsAddendum(context.tools);
+  if (customToolsAddendum) {
+    parts.push(customToolsAddendum);
+  }
+
   return parts.join("\n\n");
 }
 
+/** Pi built-in tool names — these go through pi's wrapped built-ins, not MCP. */
+const BUILT_IN_PI_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "bash",
+  "grep",
+  "find",
+  "ls",
+]);
+
+/**
+ * Rewrite bare references to custom pi tool names (e.g. `fn_review_spec`,
+ * `fn_review_spec()`) in the system prompt so they appear as their
+ * MCP-prefixed names (`mcp__custom-tools__fn_review_spec`). Engine prompts are
+ * written for direct API tool calls; under pi-claude-cli the same tools are
+ * reachable only through the MCP shim. Without this rewrite, models like
+ * Sonnet 4.6 inconsistently translate the names — sometimes calling MCP
+ * variants, sometimes silently skipping the call (observed in triage where
+ * `fn_review_spec` was never invoked even though the prompt said "MUST call").
+ *
+ * Only rewrites whole-word matches anchored to a non-identifier boundary, so
+ * substrings inside other identifiers stay intact. Skips already-prefixed
+ * occurrences (`mcp__custom-tools__fn_review_spec`) and pi built-ins.
+ */
+function rewriteCustomToolReferences(
+  prompt: string,
+  tools: ReadonlyArray<PiToolLike> | undefined,
+): string {
+  if (!prompt || !tools || tools.length === 0) {
+    return prompt;
+  }
+
+  let result = prompt;
+  for (const tool of tools) {
+    if (BUILT_IN_PI_TOOLS.has(tool.name)) continue;
+    // \b doesn't treat `_` as a word boundary the way we want here, so anchor
+    // the match between either start-of-string/non-identifier-char and either
+    // end-of-string/non-identifier-char. Also negative-lookbehind for
+    // `mcp__custom-tools__` so we don't double-prefix.
+    const escaped = tool.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(
+      `(?<![A-Za-z0-9_])(?<!mcp__custom-tools__)${escaped}(?![A-Za-z0-9_])`,
+      "g",
+    );
+    result = result.replace(pattern, `mcp__custom-tools__${tool.name}`);
+  }
+  return result;
+}
+
+/**
+ * Build a system-prompt addendum that maps each custom pi tool to its
+ * MCP-exposed name (`mcp__custom-tools__<name>`) and explains Claude Code's
+ * deferred-tool protocol. Without this, the model sees instructions like
+ * "call fn_review_spec()" but only finds `mcp__custom-tools__fn_review_spec`
+ * via ToolSearch — and may report "tool not found" or skip the call.
+ *
+ * Returns an empty string when there are no custom tools so the addendum
+ * doesn't pollute prompts on plain chat sessions with only built-ins.
+ */
+function buildCustomToolsAddendum(
+  tools: ReadonlyArray<PiToolLike> | undefined,
+): string {
+  if (!tools || tools.length === 0) return "";
+  const customNames = tools
+    .map((t) => t.name)
+    .filter((name) => !BUILT_IN_PI_TOOLS.has(name));
+  if (customNames.length === 0) return "";
+
+  const lines = customNames
+    .sort()
+    .map((name) => `- \`${name}\` is exposed as \`mcp__custom-tools__${name}\``);
+
+  return [
+    "## Custom tool naming (Claude Code deferred-tools protocol)",
+    "",
+    "The following pi extension tools are available, but Claude Code exposes",
+    "them under MCP-prefixed names. When a system prompt or task instruction",
+    "asks you to call one of these by its short name, use the MCP-prefixed",
+    "name instead. Their schemas are deferred — call `ToolSearch` with",
+    '`select:mcp__custom-tools__<name>` first, then call the tool directly.',
+    "",
+    ...lines,
+  ].join("\n");
+}
+
 /**
  * Converts user message content to text.
  * Handles string content and array of content blocks.
@@ -462,7 +566,7 @@ function contentToText(content: string | unknown[]): string {
           : typeof rawArgs === "string"
             ? JSON.stringify(rawArgs)
             : "{}";
-        return `Historical tool call (non-executable): ${claudeName} args=${argsStr}`;
+        return `[Prior tool call — already executed; result follows in TOOL RESULT (${claudeName}):] args=${argsStr}`;
       }
       // Unknown block types are represented as a placeholder
       return `[${String(block.type)}]`;

package/dist/pi-claude-cli/src/provider.ts

@@ -44,8 +44,23 @@ import { createEventBridge } from "./event-bridge.js";
 import { handleControlRequest } from "./control-handler.js";
 import { mapThinkingEffort } from "./thinking-config.js";
 import { isPiKnownClaudeTool } from "./tool-mapping.js";
-/** Inactivity timeout: kill subprocess if no stdout for 180 seconds (3 minutes). */
-const INACTIVITY_TIMEOUT_MS = 180_000;
+/**
+ * Inactivity safety net for the Claude CLI subprocess.
+ *
+ * Set very high (30 minutes) because the caller is the authoritative source of
+ * truth for "this session is stuck": Fusion's engine runs a `StuckTaskDetector`
+ * with a configurable heartbeat (default 1 hour) and aborts the session via
+ * `AbortSignal` when it decides the agent has gone quiet. pi-claude-cli already
+ * forwards that signal to the subprocess (`forceKillProcess` on `signal.abort`).
+ *
+ * A short timeout here was racing the engine: Sonnet 4.6 with extended thinking
+ * on the triage prompt (~40k chars) routinely goes >3 minutes between thinking
+ * deltas, and we were killing those subprocesses before they could write
+ * PROMPT.md and call `fn_review_spec`. The half-hour ceiling is just a
+ * last-resort guard for catastrophically hung processes when no abort signal
+ * arrives (e.g. someone embeds pi-claude-cli without a stuck detector).
+ */
+const INACTIVITY_TIMEOUT_MS = 30 * 60_000;
 
 /** Extended stream options: pi's SimpleStreamOptions plus optional cwd and mcpConfigPath */
 type StreamViaCLiOptions = SimpleStreamOptions & {
@@ -120,6 +135,7 @@ export function streamViaCli(
         newSessionId: !resumeSessionId ? options?.sessionId : undefined,
       });
       const getStderr = captureStderr(proc);
+      const spawnTime = Date.now();
 
       // Register in global process registry for teardown cleanup
       registerProcess(proc);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runfusion/fusion",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Fusion CLI: HTTP API server, daemon, dashboard launcher, and task tooling for the Fusion AI coding agent.",
   "homepage": "https://github.com/Runfusion/Fusion#readme",
@@ -75,10 +75,10 @@
     "typescript": "^5.7.0",
     "vitest": "^3.1.0",
     "yaml": "^2.8.3",
-    "@fusion/core": "0.2.6",
-    "@fusion/dashboard": "0.2.6",
-    "@fusion/engine": "0.2.6",
-    "@fusion/pi-claude-cli": "0.2.6"
+    "@fusion/core": "0.3.0",
+    "@fusion/engine": "0.3.0",
+    "@fusion/dashboard": "0.3.0",
+    "@fusion/pi-claude-cli": "0.3.0"
   },
   "repository": {
     "type": "git",
@@ -86,6 +86,7 @@
   },
   "scripts": {
     "dev": "tsx src/bin.ts",
+    "prebuild": "node ../../scripts/sync-fusion-skill-tools.mjs",
     "build": "tsup",
     "build:exe": "bun run build.ts",
     "build:exe:all": "bun run build.ts --all",

package/skill/fusion/SKILL.md

@@ -21,14 +21,18 @@ Mission → Milestone → Slice → Feature → Task
 
 **Available tools:** Fusion registers tools via the pi extension (prefixed `fn_*`). No CLI commands or Bash needed — use the registered tools directly.
 
-**Naming boundary:** The published skill surface always uses `fn_*` tool names (for example `fn_task_create`, `fn_mission_create`). Internal engine runtime tools like `task_create`, `task_update`, `task_log`, and `task_done` are intentionally unprefixed and not part of this skill.
+**Naming boundary:** The published pi-extension skill surface uses `fn_*` tool names (for example `fn_task_create`, `fn_mission_create`). Engine runtime sessions also inject additional `fn_*` tools (for example `fn_review_spec`, `fn_review_step`, `fn_spawn_agent`) that are not user-invokable extension tools.
+
+**Engine runtime tools:** Triage/executor/merger/heartbeat sessions include auto-injected engine tools that do not come from the pi extension registration list. See `references/engine-tools.md` for the canonical runtime-only catalog and usage boundaries.
 
 **Tool categories:**
+<!-- BEGIN: tool-categories (auto-generated by scripts/sync-fusion-skill-tools.mjs — do not edit by hand) -->
 - **Task tools** — `fn_task_create`, `fn_task_update`, `fn_task_list`, `fn_task_show`, `fn_task_attach`, `fn_task_pause`, `fn_task_unpause`, `fn_task_retry`, `fn_task_duplicate`, `fn_task_refine`, `fn_task_archive`, `fn_task_unarchive`, `fn_task_delete`, `fn_task_plan`
 - **GitHub tools** — `fn_task_import_github`, `fn_task_import_github_issue`, `fn_task_browse_github_issues`
 - **Mission tools** — `fn_mission_create`, `fn_mission_list`, `fn_mission_show`, `fn_mission_delete`, `fn_milestone_add`, `fn_slice_add`, `fn_feature_add`, `fn_slice_activate`, `fn_feature_link_task`
 - **Agent tools** — `fn_agent_stop`, `fn_agent_start`
 - **Skills tools** — `fn_skills_search`, `fn_skills_install`
+<!-- END: tool-categories -->
 - **Dashboard** — Use `/fn` command to start/stop the dashboard
 
 </essential_principles>
@@ -100,6 +104,7 @@ For these operations, guide the user to the dashboard (`/fn`) or CLI commands do
 | references/extension-tools.md | All pi extension tools with parameters |
 | references/best-practices.md | Tips for effective Fusion usage |
 | references/fusion-capabilities.md | Complete feature catalog |
+| references/engine-tools.md | Engine session-scoped runtime tools (not extension-invokable) |
 | references/skill-patterns.md | Patterns used in this skill's design |
 
 </reference_index>

package/skill/fusion/references/engine-tools.md

@@ -0,0 +1,54 @@
+# Engine Session-Scoped Tools
+
+These tools are **not** part of the pi extension's user-invokable `extension.ts` surface. They are injected by the engine at runtime for specific agent session types.
+
+- Source files: `packages/engine/src/agent-tools.ts`, `triage.ts`, `executor.ts`, `merger.ts`, `agent-heartbeat.ts`
+- Availability: only when the engine creates a session for the matching agent role
+- Important: do not tell users to call these directly from the generic pi extension tool list
+
+## Shared runtime tools (`agent-tools.ts`)
+
+| Tool | Agent Types | Purpose | Parameters |
+|---|---|---|---|
+| `fn_task_create` | triage, executor, heartbeat | Create a follow-up task from within an agent run | `description` (string), `dependencies?` (string[]) |
+| `fn_task_log` | executor, heartbeat | Write significant task log entries | `message` (string), `outcome?` (string) |
+| `fn_task_document_write` | triage, executor, heartbeat | Save/update a named task document revision | `key` (string), `content` (string), `author?` (string) |
+| `fn_task_document_read` | triage, executor, heartbeat | Read one task document or list all | `key?` (string) |
+| `fn_memory_search` | triage, executor, heartbeat | Search project/agent memory snippets | `query` (string), `limit?` (number) |
+| `fn_memory_get` | triage, executor, heartbeat | Read a bounded memory file window | `path` (string), `startLine?` (number), `lineCount?` (number) |
+| `fn_memory_append` | executor, heartbeat (when writable backend enabled) | Append long-term/daily memory notes | `scope?` (`project` \| `agent`), `layer` (`long-term` \| `daily`), `content` (string) |
+| `fn_reflect_on_performance` | executor | Generate reflection insights from prior runs | `focus_area?` (string) |
+| `fn_list_agents` | triage, executor, heartbeat | List agents (optionally filtered) | `role?` (string), `state?` (string), `includeEphemeral?` (boolean) |
+| `fn_delegate_task` | triage, executor, heartbeat | Create and assign a new task to a specific agent | `agent_id` (string), `description` (string), `dependencies?` (string[]) |
+| `fn_send_message` | executor, heartbeat | Send inbox messages to agents/users | `to_id` (string), `content` (string), `type?` (`agent-to-agent` \| `agent-to-user`), `reply_to_message_id?` (string) |
+| `fn_read_messages` | executor, heartbeat | Read inbox messages | `unread_only?` (boolean), `limit?` (number) |
+
+## Triage-only runtime tools (`triage.ts`)
+
+| Tool | Purpose | Parameters |
+|---|---|---|
+| `fn_task_list` | List active tasks during specification (duplicate check, discovery) | none |
+| `fn_task_get` | Fetch full task detail including PROMPT.md | `id` (string) |
+| `fn_review_spec` | Spawn spec reviewer and return `APPROVE`/`REVISE`/`RETHINK`/`UNAVAILABLE` | none |
+
+## Executor-only runtime tools (`executor.ts`)
+
+| Tool | Purpose | Parameters |
+|---|---|---|
+| `fn_task_update` | Update a spec step status (`pending`/`in-progress`/`done`/`skipped`) | `step` (number), `status` (enum) |
+| `fn_task_add_dep` | Add a dependency to current task (confirmation-gated) | `task_id` (string), `confirm?` (boolean) |
+| `fn_task_done` | Mark task complete and optionally store summary | `summary?` (string) |
+| `fn_review_step` | Spawn step plan/code reviewer | `step` (number), `type` (`plan` \| `code`), `step_name` (string), `baseline?` (string) |
+| `fn_spawn_agent` | Spawn child agent in separate worktree | `name` (string), `role` (enum), `task` (string) |
+
+## Merger-only runtime tools (`merger.ts`)
+
+| Tool | Purpose | Parameters |
+|---|---|---|
+| `fn_report_build_failure` | Explicitly signal merge-time build verification failure | `message` (string) |
+
+## Heartbeat-only runtime tools (`agent-heartbeat.ts`)
+
+| Tool | Purpose | Parameters |
+|---|---|---|
+| `fn_heartbeat_done` | Signal end of heartbeat run with optional summary | `summary?` (string) |