@runfusion/fusion 0.22.0 → 0.24.0

package/dist/plugins/fusion-plugin-whatsapp-chat/src/connection.ts

@@ -0,0 +1,253 @@
+import { DisconnectReason, makeWASocket, type ConnectionState, type WAMessage, type WAMessageContent, type WASocket } from "@whiskeysockets/baileys";
+import type { PluginContext } from "@fusion/plugin-sdk";
+import pino from "pino";
+import qrcode from "qrcode";
+import { clearAuthState, createPluginDbAuthState } from "./auth-state.js";
+import {
+  getAllowedSenders,
+  getDedupeRetentionDays,
+  getHistoryTurnLimit,
+  loadHistory,
+  markProcessed,
+  saveHistory,
+  wasProcessed,
+  type ChatTurn,
+  type PluginDb,
+} from "./index.js";
+
+export type ConnectionStatus = {
+  state: "starting" | "awaiting-qr" | "awaiting-code" | "connected" | "disconnected" | "error";
+  qr?: string;
+  qrDataUrl?: string;
+  pairingCode?: string;
+  lastError?: string;
+  jid?: string;
+};
+
+export type ReplyGenerator = (ctx: PluginContext, sender: string, text: string, history: ChatTurn[]) => Promise<string>;
+
+const BACKOFF_MS = [1000, 2000, 5000, 15000, 30000];
+const FALLBACK_TEXT = "Sorry, I hit an internal error while processing that message.";
+const MAX_WHATSAPP_MESSAGE_CHARS = 4096;
+
+function extractText(message?: WAMessageContent | null): string | null {
+  const text = message?.conversation ?? message?.extendedTextMessage?.text;
+  if (!text || !text.trim()) return null;
+  return text.trim();
+}
+
+function normalizeSender(jid: string): string {
+  return jid.split("@")[0]?.replace(/\D+/g, "") ?? "";
+}
+
+function isLoggedOutDisconnect(error: unknown): boolean {
+  const statusCode = (error as { output?: { statusCode?: unknown } })?.output?.statusCode;
+  return statusCode === DisconnectReason.loggedOut;
+}
+
+function splitMessageForWhatsapp(text: string): string[] {
+  if (text.length <= MAX_WHATSAPP_MESSAGE_CHARS) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= MAX_WHATSAPP_MESSAGE_CHARS) {
+      chunks.push(remaining);
+      break;
+    }
+    const candidate = remaining.slice(0, MAX_WHATSAPP_MESSAGE_CHARS);
+    const splitAt = Math.max(candidate.lastIndexOf("\n"), candidate.lastIndexOf(" "));
+    const breakpoint = splitAt > 0 ? splitAt : MAX_WHATSAPP_MESSAGE_CHARS;
+    chunks.push(remaining.slice(0, breakpoint).trim());
+    remaining = remaining.slice(breakpoint).trimStart();
+  }
+
+  return chunks.filter(Boolean);
+}
+
+export class WhatsAppConnection {
+  private sock: WASocket | null = null;
+  private status: ConnectionStatus = { state: "disconnected" };
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempt = 0;
+  private stopped = true;
+  private authState: ReturnType<typeof createPluginDbAuthState>;
+
+  public constructor(
+    private readonly ctx: PluginContext,
+    private readonly fusionVersion: string,
+    private readonly generateReply: ReplyGenerator,
+    private readonly db: PluginDb,
+  ) {
+    this.authState = createPluginDbAuthState(this.db);
+  }
+
+  public async start(): Promise<void> {
+    this.stopped = false;
+    this.status = { state: "starting" };
+    await this.connect();
+  }
+
+  public async stop(): Promise<void> {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.clearReconnectTimer();
+
+    const socket = this.sock;
+    this.sock = null;
+    this.status = { state: "disconnected" };
+
+    if (socket) {
+      socket.ev.off("creds.update", this.authState.saveCreds);
+      socket.ev.off("connection.update", this.onConnectionUpdate);
+      socket.ev.off("messages.upsert", this.onMessagesUpsert);
+      await socket.end(undefined);
+    }
+  }
+
+  public getStatus(): ConnectionStatus {
+    return { ...this.status };
+  }
+
+  public async requestPairingCode(phoneNumberE164: string): Promise<string> {
+    if (!this.sock) throw new Error("WhatsApp socket not initialized");
+    const pairingCode = await this.sock.requestPairingCode(phoneNumberE164);
+    this.status = { ...this.status, state: "awaiting-code", pairingCode };
+    return pairingCode;
+  }
+
+  public async logout(): Promise<void> {
+    try {
+      await this.sock?.logout();
+    } finally {
+      clearAuthState(this.db);
+      this.authState = createPluginDbAuthState(this.db);
+      this.status = { state: "disconnected" };
+    }
+  }
+
+  private async connect(): Promise<void> {
+    if (this.stopped) return;
+
+    this.status = { state: "starting" };
+    const socket = makeWASocket({
+      auth: this.authState.state,
+      printQRInTerminal: false,
+      browser: ["Fusion", "Chrome", this.fusionVersion],
+      logger: pino({ level: "silent" }),
+    });
+
+    this.sock = socket;
+    socket.ev.on("creds.update", this.authState.saveCreds);
+    socket.ev.on("connection.update", this.onConnectionUpdate);
+    socket.ev.on("messages.upsert", this.onMessagesUpsert);
+  }
+
+  private readonly onConnectionUpdate = async (update: Partial<ConnectionState>): Promise<void> => {
+    if (update.qr) {
+      const qrDataUrl = await qrcode.toDataURL(update.qr);
+      this.ctx.logger.info("WhatsApp pairing QR updated", update.qr);
+      this.status = { state: "awaiting-qr", qr: update.qr, qrDataUrl };
+    }
+
+    if (update.connection === "open") {
+      this.reconnectAttempt = 0;
+      this.status = { state: "connected", jid: this.sock?.user?.id };
+      return;
+    }
+
+    if (update.connection === "close") {
+      if (isLoggedOutDisconnect(update.lastDisconnect?.error)) {
+        clearAuthState(this.db);
+        this.authState = createPluginDbAuthState(this.db);
+        this.status = { state: "disconnected", lastError: "loggedOut" };
+        return;
+      }
+
+      const closeError = update.lastDisconnect?.error;
+      this.status = {
+        state: "disconnected",
+        lastError: closeError instanceof Error ? closeError.message : "connection closed",
+      };
+      this.scheduleReconnect();
+    }
+  };
+
+  private readonly onMessagesUpsert = async (upsert: { type?: string; messages?: WAMessage[] }): Promise<void> => {
+    if (upsert.type !== "notify") return;
+
+    for (const message of upsert.messages ?? []) {
+      const jid = message.key.remoteJid;
+      const messageId = message.key.id;
+      if (!jid || !messageId) continue;
+      if (jid.endsWith("@g.us") || jid.endsWith("@broadcast") || jid === "status@broadcast") continue;
+      if (message.key.fromMe) continue;
+
+      const text = extractText(message.message);
+      if (!text) continue;
+
+      const sender = normalizeSender(jid);
+      const allowedSenders = getAllowedSenders(this.ctx.settings);
+      if (allowedSenders.size === 0 || (!allowedSenders.has(sender) && !allowedSenders.has(jid))) continue;
+      if (wasProcessed(this.db, messageId)) continue;
+
+      markProcessed(this.db, messageId, sender, getDedupeRetentionDays(this.ctx.settings));
+
+      try {
+        const history = loadHistory(this.db, sender);
+        const reply = await this.generateReply(this.ctx, sender, text, history);
+        const now = new Date().toISOString();
+        const nextHistory: ChatTurn[] = [
+          ...history,
+          { role: "user" as const, text, createdAt: now },
+          { role: "assistant" as const, text: reply, createdAt: now },
+        ].slice(-getHistoryTurnLimit(this.ctx.settings));
+        saveHistory(this.db, sender, nextHistory);
+
+        for (const chunk of splitMessageForWhatsapp(reply)) {
+          await this.sock?.sendMessage(jid, { text: chunk });
+        }
+      } catch (error) {
+        this.ctx.logger.error("WhatsApp chat processing failed", error);
+        try {
+          await this.sock?.sendMessage(jid, { text: FALLBACK_TEXT });
+        } catch {
+          // no-op
+        }
+      }
+    }
+  };
+
+  private scheduleReconnect(): void {
+    if (this.stopped || this.reconnectTimer) return;
+    const delay = BACKOFF_MS[Math.min(this.reconnectAttempt, BACKOFF_MS.length - 1)] ?? 30000;
+    this.reconnectAttempt += 1;
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      await this.connect();
+    }, delay);
+  }
+
+  private clearReconnectTimer(): void {
+    if (!this.reconnectTimer) return;
+    clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+
+  public static splitMessageForWhatsapp(text: string, max = 4096): string[] {
+    const chunks = splitMessageForWhatsapp(text);
+    if (max === 4096) return chunks;
+    return chunks.flatMap((chunk) => {
+      if (chunk.length <= max) return [chunk];
+      const split: string[] = [];
+      let remaining = chunk;
+      while (remaining.length > max) {
+        split.push(remaining.slice(0, max));
+        remaining = remaining.slice(max);
+      }
+      if (remaining.length) split.push(remaining);
+      return split;
+    });
+  }
+}

package/dist/plugins/fusion-plugin-whatsapp-chat/src/index.ts

@@ -0,0 +1,262 @@
+import { definePlugin } from "@fusion/plugin-sdk";
+import type { FusionPlugin, PluginContext, PluginRouteDefinition, PluginRouteResponse, PluginSettingSchema } from "@fusion/plugin-sdk";
+import { WhatsAppConnection } from "./connection.js";
+import { generateReply } from "./reply.js";
+
+const DEFAULT_HISTORY_TURN_LIMIT = 40;
+const DEFAULT_DEDUPE_RETENTION_DAYS = 7;
+
+export type ChatTurn = { role: "user" | "assistant"; text: string; createdAt: string };
+
+export type PluginDb = {
+  exec(sql: string): void;
+  prepare(sql: string): {
+    get(...args: unknown[]): unknown;
+    run(...args: unknown[]): unknown;
+  };
+};
+
+const settingsSchema: Record<string, PluginSettingSchema> = {
+  pairingMode: {
+    type: "enum",
+    label: "Pairing Mode",
+    enumValues: ["qr", "code"],
+    defaultValue: "qr",
+  },
+  pairingPhoneNumber: {
+    type: "string",
+    label: "Pairing Phone Number",
+    description: "E.164 digits without + (required when pairingMode is code)",
+  },
+  allowedSenders: { type: "array", label: "Allowed WhatsApp Senders", itemType: "string" },
+  agentSystemPrompt: {
+    type: "string",
+    label: "Agent System Prompt",
+    multiline: true,
+    defaultValue: "You are a helpful assistant replying in WhatsApp chats.",
+  },
+  historyTurnLimit: {
+    type: "number",
+    label: "History Turn Limit",
+    defaultValue: DEFAULT_HISTORY_TURN_LIMIT,
+  },
+  dedupeRetentionDays: {
+    type: "number",
+    label: "Dedupe Retention (days)",
+    description: "How long inbound message IDs are kept for replay protection. Older rows are pruned on each inbound message.",
+    defaultValue: DEFAULT_DEDUPE_RETENTION_DAYS,
+  },
+};
+
+const connections = new Map<string, WhatsAppConnection>();
+
+function getConnectionKey(ctx: PluginContext): string {
+  return `${ctx.taskStore.getRootDir()}::${ctx.pluginId}`;
+}
+
+export function getSettingString(settings: Record<string, unknown>, key: string): string | undefined {
+  const value = settings[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function getAllowedSenders(settings: Record<string, unknown>): Set<string> {
+  const senders = settings.allowedSenders;
+  if (!Array.isArray(senders)) return new Set<string>();
+  return new Set(senders.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim()));
+}
+
+export function getHistoryTurnLimit(settings: Record<string, unknown>): number {
+  const value = settings.historyTurnLimit;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_HISTORY_TURN_LIMIT;
+  }
+  return Math.floor(value);
+}
+
+export function getDedupeRetentionDays(settings: Record<string, unknown>): number {
+  const value = settings.dedupeRetentionDays;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_DEDUPE_RETENTION_DAYS;
+  }
+  return Math.floor(value);
+}
+
+export function splitMessageForWhatsapp(text: string): string[] {
+  return WhatsAppConnection.splitMessageForWhatsapp(text);
+}
+
+export function ensureSchema(db: PluginDb): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS whatsapp_chat_sessions (
+      sender TEXT PRIMARY KEY,
+      history TEXT NOT NULL,
+      updatedAt TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS whatsapp_chat_dedupe (
+      messageId TEXT PRIMARY KEY,
+      sender TEXT NOT NULL,
+      receivedAt TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS whatsapp_auth_creds (
+      id TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updatedAt TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS whatsapp_auth_keys (
+      category TEXT NOT NULL,
+      keyId TEXT NOT NULL,
+      value TEXT NOT NULL,
+      updatedAt TEXT NOT NULL,
+      PRIMARY KEY (category, keyId)
+    );
+  `);
+}
+
+export function loadHistory(db: PluginDb, sender: string): ChatTurn[] {
+  const row = db.prepare("SELECT history FROM whatsapp_chat_sessions WHERE sender = ?").get(sender) as { history: string } | undefined;
+  if (!row) return [];
+  try {
+    const parsed = JSON.parse(row.history) as ChatTurn[];
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+export function saveHistory(db: PluginDb, sender: string, history: ChatTurn[]): void {
+  const now = new Date().toISOString();
+  db.prepare(`
+    INSERT INTO whatsapp_chat_sessions(sender, history, updatedAt)
+    VALUES(?, ?, ?)
+    ON CONFLICT(sender) DO UPDATE SET history = excluded.history, updatedAt = excluded.updatedAt
+  `).run(sender, JSON.stringify(history), now);
+}
+
+export function wasProcessed(db: PluginDb, messageId: string): boolean {
+  const row = db.prepare("SELECT 1 as found FROM whatsapp_chat_dedupe WHERE messageId = ?").get(messageId) as { found: number } | undefined;
+  return Boolean(row?.found);
+}
+
+export function markProcessed(
+  db: PluginDb,
+  messageId: string,
+  sender: string,
+  retentionDays: number = DEFAULT_DEDUPE_RETENTION_DAYS,
+): void {
+  const now = new Date().toISOString();
+  const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
+  db.prepare("DELETE FROM whatsapp_chat_dedupe WHERE receivedAt < ?").run(cutoff);
+  db.prepare("INSERT INTO whatsapp_chat_dedupe(messageId, sender, receivedAt) VALUES(?, ?, ?)").run(messageId, sender, now);
+}
+
+
+function getDbFromTaskStore(ctx: PluginContext): PluginDb {
+  const pluginStore = ctx.taskStore.getPluginStore();
+  const db = (pluginStore as unknown as { db?: PluginDb }).db;
+  if (!db) {
+    throw new Error("Plugin database unavailable");
+  }
+  return db;
+}
+
+function getConnectionOrResponse(ctx: PluginContext): { connection?: WhatsAppConnection; error?: PluginRouteResponse } {
+  const connection = connections.get(getConnectionKey(ctx));
+  if (!connection) {
+    return { error: { status: 503, body: { error: "WhatsApp connection is not initialized" } } };
+  }
+  return { connection };
+}
+
+const routes: PluginRouteDefinition[] = [
+  {
+    method: "GET",
+    path: "/status",
+    handler: async (_req, ctx) => {
+      const { connection, error } = getConnectionOrResponse(ctx);
+      if (!connection) return error as PluginRouteResponse;
+      const status = connection.getStatus();
+      return {
+        status: 200,
+        body: {
+          status: status.state,
+          jid: status.jid,
+          allowedSenders: Array.from(getAllowedSenders(ctx.settings)),
+        },
+      };
+    },
+  },
+  {
+    method: "GET",
+    path: "/qr",
+    handler: async (_req, ctx) => {
+      const { connection, error } = getConnectionOrResponse(ctx);
+      if (!connection) return error as PluginRouteResponse;
+      const status = connection.getStatus();
+      if (status.state !== "awaiting-qr" || !status.qrDataUrl || !status.qr) {
+        return { status: 409, body: { error: "QR is not currently available" } };
+      }
+      return { status: 200, body: { qrDataUrl: status.qrDataUrl, qr: status.qr } };
+    },
+  },
+  {
+    method: "POST",
+    path: "/pair-code",
+    handler: async (req, ctx) => {
+      const { connection, error } = getConnectionOrResponse(ctx);
+      if (!connection) return error as PluginRouteResponse;
+      const body = (req as { body?: { phoneNumber?: unknown } })?.body;
+      const phoneNumber = typeof body?.phoneNumber === "string" ? body.phoneNumber.trim() : "";
+      if (!phoneNumber) {
+        return { status: 400, body: { error: "phoneNumber is required" } };
+      }
+      const pairingCode = await connection.requestPairingCode(phoneNumber);
+      return { status: 200, body: { pairingCode } };
+    },
+  },
+  {
+    method: "POST",
+    path: "/logout",
+    handler: async (_req, ctx) => {
+      const { connection, error } = getConnectionOrResponse(ctx);
+      if (!connection) return error as PluginRouteResponse;
+      await connection.logout();
+      return { status: 200, body: { ok: true } };
+    },
+  },
+];
+
+const plugin: FusionPlugin = definePlugin({
+  manifest: {
+    id: "fusion-plugin-whatsapp-chat",
+    name: "WhatsApp Chat",
+    version: "0.1.0",
+    description: "WhatsApp Web (multi-device) bridge that pairs via QR/code and forwards messages to Fusion AI",
+    author: "Fusion Team",
+    settingsSchema,
+  },
+  state: "installed",
+  routes,
+  hooks: {
+    onSchemaInit: (db) => {
+      ensureSchema(db as PluginDb);
+    },
+    onLoad: async (ctx) => {
+      const db = getDbFromTaskStore(ctx);
+      const connection = new WhatsAppConnection(ctx, plugin.manifest.version, generateReply, db);
+      connections.set(getConnectionKey(ctx), connection);
+      await connection.start();
+    },
+    onUnload: async (ctx) => {
+      const connectionKey = getConnectionKey(ctx);
+      const connection = connections.get(connectionKey);
+      if (!connection) return;
+      await connection.stop();
+      connections.delete(connectionKey);
+    },
+  },
+});
+
+export default plugin;

package/dist/plugins/fusion-plugin-whatsapp-chat/src/qrcode.d.ts

@@ -0,0 +1 @@
+declare module "qrcode";

package/dist/plugins/fusion-plugin-whatsapp-chat/src/reply.ts

@@ -0,0 +1,37 @@
+import type { PluginContext } from "@fusion/plugin-sdk";
+import { getSettingString, type ChatTurn } from "./index.js";
+
+export async function generateReply(ctx: PluginContext, _sender: string, text: string, history: ChatTurn[]): Promise<string> {
+  if (!ctx.createAiSession) {
+    throw new Error("AI session factory unavailable: engine not registered");
+  }
+
+  const systemPrompt = getSettingString(ctx.settings, "agentSystemPrompt") ?? "You are a helpful assistant replying in WhatsApp chats.";
+  const sessionResult = await ctx.createAiSession({
+    cwd: ctx.taskStore.getRootDir(),
+    systemPrompt,
+    tools: "readonly",
+  });
+
+  const promptLines = [
+    "Continue this WhatsApp conversation.",
+    ...history.map((turn) => `${turn.role === "user" ? "User" : "Assistant"}: ${turn.text}`),
+    `User: ${text}`,
+    "Assistant:",
+  ];
+
+  await sessionResult.session.prompt(promptLines.join("\n"));
+  const assistantMessages = sessionResult.session.state.messages.filter((message) => message.role === "assistant");
+  const latest = assistantMessages[assistantMessages.length - 1];
+  const content = latest?.content;
+
+  if (typeof content === "string" && content.trim()) return content.trim();
+  if (Array.isArray(content)) {
+    const textParts = content
+      .map((part) => (part && typeof part === "object" && "text" in part && typeof (part as { text?: unknown }).text === "string") ? (part as { text: string }).text : "")
+      .filter(Boolean);
+    if (textParts.length > 0) return textParts.join("\n").trim();
+  }
+
+  throw new Error("AI session returned no assistant text");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runfusion/fusion",
-  "version": "0.22.0",
+  "version": "0.24.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",
@@ -96,7 +96,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --silent=passed-only --reporter=dot",
     "test:slow-cli": "cross-env FUSION_TEST_SLOW_CLI=1 vitest run src/commands/__tests__/agent-export.test.ts --silent=passed-only --reporter=dot",
-    "test:extension-integration": "cross-env FUSION_TEST_EXTENSION_INTEGRATION=1 vitest run src/__tests__/extension.test.ts --silent=passed-only --reporter=dot",
+    "test:extension-integration": "cross-env FUSION_TEST_EXTENSION_INTEGRATION=1 vitest run src/__tests__/extension-integration.test.ts --silent=passed-only --reporter=dot",
     "test:build-exe": "cross-env FUSION_TEST_BUILD_EXE=1 vitest run --config vitest.build-exe.config.ts --silent=passed-only --reporter=dot",
     "test:pre-release": "pnpm test:slow-cli && pnpm test:build-exe"
   }

package/skill/fusion/SKILL.md

@@ -30,10 +30,10 @@ Mission → Milestone → Slice → Feature → Task
 - **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`, `fn_list_agents`, `fn_delegate_task`, `fn_agent_show`, `fn_agent_org_chart`
+- **Agent tools** — `fn_agent_stop`, `fn_agent_start`, `fn_agent_create`, `fn_agent_delete`, `fn_list_agents`, `fn_delegate_task`, `fn_agent_show`, `fn_agent_org_chart`
 - **Skills tools** — `fn_skills_search`, `fn_skills_install`
 - **Insight tools** — `fn_insight_list`, `fn_insight_show`, `fn_insight_run_list`, `fn_insight_run_show`
-- **Other tools** — `fn_research_run`, `fn_research_list`, `fn_research_get`, `fn_research_cancel`, `fn_research_retry`
+- **Other tools** — `fn_web_fetch`, `fn_research_run`, `fn_research_list`, `fn_research_get`, `fn_research_cancel`, `fn_research_retry`
 <!-- END: tool-categories -->
 - **Dashboard** — Use `/fn` command to start/stop the dashboard
 

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

@@ -4,6 +4,7 @@ These tools are **not** part of the user-invokable extension surface. They are i
 
 - 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
+- Runtime contract: engine sessions now forward requested skill names (`skillSelection.requestedSkillNames`) into the generic runtime `skills` field so non-pi runtimes can still receive Fusion skill intent.
 - Important: do not tell users to call these directly from the generic extension tool list
 
 ## Shared runtime tools (`agent-tools.ts`)
@@ -17,6 +18,7 @@ These tools are **not** part of the user-invokable extension surface. They are i
 | `fn_memory_search` | triage, executor, heartbeat | Search project memory plus per-agent layered memory snippets | `query` (string), `limit?` (number) |
 | `fn_memory_get` | triage, executor, heartbeat | Read a bounded memory file window (including bounded per-agent layered paths) | `path` (string), `startLine?` (number), `lineCount?` (number) |
 | `fn_memory_append` | executor, heartbeat (when writable backend enabled) | Append memory notes with explicit scope: `scope="agent"` for private operating context, `scope="project"` for workspace-wide durable knowledge | `scope?` (`project` \| `agent`), `layer` (`long-term` \| `daily`), `content` (string) |
+| `fn_web_fetch` | executor, step-session, reviewer, merger, triage, heartbeat | Lightweight HTTP fetch with HTML→text extraction, timeout/size caps, and SSRF guard (no JS rendering) | `url` (string), `prompt?` (string), `timeoutMs?` (number), `maxBytes?` (number) |
 | `fn_research_run` | triage, executor | Start a bounded research run (optionally wait for completion) and return structured findings metadata | `query` (string), `wait_for_completion?` (boolean), `max_wait_ms?` (number) |
 | `fn_research_list` | triage, executor | List recent research runs with status/summary metadata | `status?` (`pending` \| `running` \| `completed` \| `failed` \| `cancelled`), `limit?` (number) |
 | `fn_research_get` | triage, executor | Read one research run's structured findings/citations payload | `id` (string) |
@@ -28,8 +30,10 @@ These tools are **not** part of the user-invokable extension surface. They are i
 | `fn_delegate_task` | triage, executor, heartbeat | Create and assign a new task to a specific agent | `agent_id` (string), `description` (string), `dependencies?` (string[]) |
 | `fn_get_agent_config` | executor, heartbeat | Read full config for a direct-report agent | `agent_id` (string) |
 | `fn_update_agent_config` | executor, heartbeat | Update config fields for a direct-report, non-ephemeral agent | `agent_id` (string), optional: `soul`, `instructions_text`, `instructions_path`, `heartbeat_procedure_path`, `heartbeat_interval_ms`, `heartbeat_timeout_ms`, `max_concurrent_runs`, `message_response_mode` |
-| `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) |
+| `fn_agent_create` | executor, heartbeat | Create a non-ephemeral direct-report agent | `name` (string), `role` (string), optional: `soul`, `instructions_text`, `instructions_path`, `reportsTo`, `heartbeat_interval_ms`, `heartbeat_timeout_ms`, `max_concurrent_runs`, `message_response_mode` |
+| `fn_agent_delete` | executor, heartbeat | Delete a non-ephemeral direct-report agent | `agent_id` (string), optional: `force` (boolean), `reassign_to` (string) |
+| `fn_send_message` | executor, step-session, 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, step-session, heartbeat | Read inbox messages | `unread_only?` (boolean), `limit?` (number) |
 
 ## Triage-only runtime tools (`triage.ts`)
 
@@ -41,6 +45,8 @@ These tools are **not** part of the user-invokable extension surface. They are i
 
 ## Executor-only runtime tools (`executor.ts`)
 
+Note: step-session execution (`step-session-executor.ts`) reuses executor coordination tools (`fn_send_message`, `fn_read_messages`, `fn_list_agents`, `fn_delegate_task`, task-document tools, and memory tools) so spawned/session-sliced execution keeps parity with main executor runs.
+
 | Tool | Purpose | Parameters |
 |---|---|---|
 | `fn_task_update` | Update a spec step status (`pending`/`in-progress`/`done`/`skipped`) | `step` (number), `status` (enum) |

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

@@ -263,6 +263,33 @@ Start a stopped agent — resumes its execution. Transitions the agent from paus
 |-----------|------|----------|-------------|
 | `id` | string | ✓ | Agent ID to start (e.g., agent-abc123) |
 
+### fn_agent_create
+
+Create a new non-ephemeral agent.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | ✓ | Agent name |
+| `role` | string | ✓ | Agent role/capability |
+| `soul` | string | — | Agent personality/identity text |
+| `instructions_text` | string | — | Inline custom instructions |
+| `instructions_path` | string | — | Path to instructions markdown |
+| `reportsTo` | string | — | Manager agent ID |
+| `heartbeat_interval_ms` | number | — |  |
+| `heartbeat_timeout_ms` | number | — |  |
+| `max_concurrent_runs` | number | — |  |
+| `message_response_mode` | union | — |  |
+
+### fn_agent_delete
+
+Delete a non-ephemeral agent.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Agent ID to delete |
+| `force` | boolean | — | Force delete when holding checkout |
+| `reassign_to` | string | — | Optional replacement agent for assigned tasks |
+
 ### fn_list_agents
 
 List all available agents in the system. Shows each agent's name, role, state, personality (soul), and current assignment. Use this to discover which agents exist and what they specialize in before delegating work.
@@ -282,6 +309,7 @@ Create a new task and assign it to a specific agent for execution. The task goes
 | `agent_id` | string | ✓ | The agent ID to delegate work to |
 | `description` | string | ✓ | What needs to be done |
 | `dependencies` | array | — | Task IDs this new task depends on (e.g. [\"KB-001\"] |
+| `override` | boolean | — | Set true to bypass executor-role assignment policy |
 
 ### fn_agent_show
 
@@ -363,6 +391,17 @@ Show a single insight-generation run by ID.
 
 ## Other Tools
 
+### fn_web_fetch
+
+Lightweight URL fetch (no JS rendering). Use agent-browser skill for JS-heavy pages. URL to fetch (http/https) Optional extraction hint for downstream summarization Timeout in milliseconds (default: 30000) Max bytes to return (default: 512000)
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | ✓ | URL to fetch (http/https) |
+| `prompt` | string | — | Optional extraction hint for downstream summarization |
+| `timeoutMs` | number | — | Timeout in milliseconds (default: 30000) |
+| `maxBytes` | number | — | Max bytes to return (default: 512000) |
+
 ### fn_research_run
 
 Start a bounded research run and optionally wait for findings.