pi-fabric 0.17.1 → 0.18.0

package/README.md

@@ -431,6 +431,7 @@ Pi discovers these package skills automatically:
 | `/skill:fabric-rlm <task>`        | Recursive self-delegation via `rlm.query()` for tasks too big for one context window |
 | `/skill:fabric-swarm <objective>`  | Persistent actors, durable topics, and CAS-based shared tasks           |
 | `/skill:fabric-council <decision>` | Bounded independent perspectives plus synthesis                         |
+| `/skill:fabric-fusion <task>`      | Multi-model deliberation: parallel panel plus a compare-not-merge judge |
 
 `fabric-exec` is the one discoverable reference skill: it holds the full `fabric_exec` API (core `pi.*` tools, `tools` discovery, `π` strings, error recovery) plus `references/` files for MCP, agents/rlm, and mesh loaded by relative path (not separate skills). It appears in `<available_skills>`; load it via `read` before your first `fabric_exec` call or when a call errors.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fabric",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "A programmable tool and agent runtime for Pi",
   "type": "module",
   "main": "./dist/index.js",

package/skills/fabric-exec/SKILL.md

@@ -36,4 +36,4 @@ Refs namespaced: `pi.grep`, `extensions.<tool>`, `mcp.<server>.<tool>`; bare nam
 Read the line-numbered error → `await tools.describe({ref})` for the schema → match `inputSchema`, rerun (don't guess). Common mistakes: bare ref (`grep`→`pi.grep`); 2 positional args on `read`/`bash`/`ls` (use an options object — positional is supported only for `grep`/`find`/`write`/`edit`).
 
 ## Other surfaces (opt-in)
-MCP tools are discoverable via `tools` (`mcp.<server>.<tool>`); see `references/mcp.md`. Multi-agent orchestration is opt-in: load `/skill:fabric-workflow`, `/skill:fabric-council`, or `/skill:fabric-rlm` (API detail in `references/agents.md`, `references/mesh.md`).
+MCP tools are discoverable via `tools` (`mcp.<server>.<tool>`); see `references/mcp.md`. Multi-agent orchestration is opt-in: load `/skill:fabric-workflow`, `/skill:fabric-council`, `/skill:fabric-rlm`, or `/skill:fabric-fusion` (API detail in `references/agents.md`, `references/mesh.md`).

package/skills/fabric-fusion/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: fabric-fusion
+description: Multi-model deliberation. A panel of up to 8 distinct models answers a task in parallel (each with web access), then a judge model compares their responses into structured analysis (consensus, contradictions, coverage gaps, unique insights, blind spots) that the caller turns into a better final answer. Use for research, expert critique, and compare-and-contrast where the cost of being wrong outweighs the cost of a few extra completions.
+disable-model-invocation: true
+---
+
+# Fabric Fusion
+
+Use one `fabric_exec` call. A panel of up to 8 distinct models answers the task in parallel, each with web access, then a judge model compares (does not merge) their responses and returns structured analysis: consensus, contradictions, partial coverage, unique insights, blind spots. Return that analysis; the caller writes the final answer from it. This mirrors OpenRouter's Fusion Router (`openrouter/fusion`): the panel and the judge are the inner deliberation, and the program hands back analysis rather than a merged answer.
+
+Use when a single model is not enough: research questions, expert critique, compare-and-contrast, or anything where the cost of being wrong outweighs the cost of a few extra completions. Do not use it for a short tactical prompt or a lookup with no meaningful competing considerations.
+
+Pass the task and panel through `strings` and reference them as `π.*`. `π.task` is the prompt. `π.panel` is OpenRouter's `analysis_models`, a JSON `Array<{ model, label? }>` of 1–8 models; `label` defaults to the model id and is used only for attribution in the judge's input and the dashboard, never injected into a member's prompt. `π.judge` is OpenRouter's judge `model` (defaults to the first panel model). `π.tools` is the panel+judge tool allowlist (defaults to read, grep, find, ls, and bash; `bash` is the `web_search`/`web_fetch` analog via `gsearch`/`curl`). `π.thinking` is the reasoning effort for panel+judge (maps to OpenRouter's `reasoning`; defaults to `subagents.thinking`, medium). Pass every referenced key, using empty string for the optionals (`judge`, `tools`, `thinking`) when not setting them.
+
+```ts
+type FusionAnalysis = {
+  consensus: string[];
+  contradictions: string[];
+  partial_coverage: string[];
+  unique_insights: string[];
+  blind_spots: string[];
+};
+
+const task = π.task;
+const panel = JSON.parse(π.panel) as Array<{ model: string; label?: string }>;
+if (panel.length < 1 || panel.length > 8) {
+  throw new Error("Fusion panel (analysis_models) must have 1–8 members.");
+}
+const toolset = π.tools ? (JSON.parse(π.tools) as string[]) : ["read", "grep", "find", "ls", "bash"];
+const thinking = π.thinking ? (π.thinking as FabricThinking) : undefined;
+
+await workflow.configure({
+  name: "Fusion deliberation",
+  description: `${panel.length}-model panel + judge (compare, don't merge)`,
+});
+
+// Resolve each model to its canonical provider/id key. A bare id may not
+// resolve, and silently inheriting the host model would defeat a multi-model
+// panel, so fail loudly with the available keys.
+const models = await tools.models();
+const resolve = (needle: string): string => {
+  const n = needle.toLowerCase();
+  const hit = models.find(
+    (m) => m.key === n || m.id.toLowerCase().includes(n) || m.name.toLowerCase().includes(n),
+  );
+  if (!hit) {
+    throw new Error(
+      `Fusion: model "${needle}" not found. Available: ${models.map((m) => m.key).join(", ")}`,
+    );
+  }
+  return hit.key;
+};
+const members = panel.map((m) => ({ key: resolve(m.model), label: m.label || m.model }));
+const judgeModel = π.judge ? resolve(π.judge) : members[0].key;
+
+// Panel: up to 8 distinct models answer the same task in parallel, each with
+// web access (bash → gsearch/curl is the web_search/web_fetch analog). Members
+// run as plain agents (no recursive:true), so they cannot launch their own
+// fusion panel — one level of deliberation, like x-openrouter-fusion-depth.
+await phase("Panel", { total: members.length });
+const responses = await parallel(
+  members.map((m) => () =>
+    agent<string>(
+      `Independently answer this task. Use web search (run gsearch or curl via bash) when fresh sources help, and cite them inline.\n\nTask:\n${task}`,
+      {
+        label: `panel · ${m.label}`.slice(0, 50),
+        model: m.key,
+        tools: toolset,
+        ...(thinking ? { thinking } : {}),
+      },
+    ),
+  ),
+  { concurrency: members.length },
+);
+
+// Judge: compare, don't merge. Returns the structured analysis shape
+// OpenRouter's fusion judge returns; the caller writes the final answer.
+await phase("Judge", { total: 1 });
+const analysis = await agent<FusionAnalysis>(
+  `You are the fusion judge. Compare these ${members.length} panel responses — do NOT merge them into one answer.\n` +
+    `Return structured analysis: consensus (points all or most agree on, higher-confidence), ` +
+    `contradictions (where they disagreed), partial_coverage (what only some covered), ` +
+    `unique_insights (insights from individual models), blind_spots (gaps none addressed). ` +
+    `You may search the web to verify claims.\n\nTask:\n${task}\n\nPanel responses:\n` +
+    JSON.stringify(members.map((m, i) => ({ model: m.label, response: responses[i] }))),
+  {
+    label: "fusion judge",
+    model: judgeModel,
+    tools: toolset,
+    ...(thinking ? { thinking } : {}),
+    schema: {
+      type: "object",
+      properties: {
+        consensus: { type: "array", items: { type: "string" } },
+        contradictions: { type: "array", items: { type: "string" } },
+        partial_coverage: { type: "array", items: { type: "string" } },
+        unique_insights: { type: "array", items: { type: "string" } },
+        blind_spots: { type: "array", items: { type: "string" } },
+      },
+      required: ["consensus", "contradictions", "partial_coverage", "unique_insights", "blind_spots"],
+      additionalProperties: false,
+    },
+  },
+);
+
+await workflow.event({ message: `Fusion complete · ${members.length}-model panel judged`, level: "success" });
+return analysis;
+```
+
+The default panel size is 3 (OpenRouter's Quality preset). Pick a panel by intent; these mirror OpenRouter's presets, which you encode directly since pi-fabric has no model catalog: the strongest all-round models you have (`general-high`), a cheaper panel with one frontier judge (`general-budget`), or a latency-homogeneous panel (models with similar TTFT, so none gates the fan-out) for fast agentic turns (`general-fast`).
+
+Cost is N panel + 1 judge: a 3-model panel is roughly 4× a single answer. The run counts toward `budget.spent()` and the `tokenBudget` guard; `subagents.budgetUsd` bounds total spend. Set `agentBudget` and `tokenBudget` on `fabric_exec` when the panel or per-member work is large.
+
+Deliberation is bounded to one level. Members and the judge run as plain `agent()` calls without `recursive: true`, so they do not receive `fabric_exec` and cannot launch their own fusion panel, the same invariant OpenRouter enforces with its `x-openrouter-fusion-depth` header. Unlike OpenRouter, where the outer model decides per request whether to call `openrouter:fusion`, here the caller decides by running this skill; once invoked, the panel + judge always run.
+
+Web access requires `bash`, which is gated by the `execute` approval policy; without it, members answer from their own knowledge (a panel without web tools). Members run concurrently up to `subagents.maxConcurrent` (default 4); raise it in `fabric.json` or `/fabric` settings to run larger panels fully in parallel. OpenRouter exposes `max_tool_calls`, `max_completion_tokens`, and `temperature` per inner call; pi-fabric has no per-call equivalents, so members and the judge inherit provider defaults, with `thinking` for reasoning effort.
+
+Do not use fusion for a single-model lookup, a simple edit, or a decision with no meaningful competing considerations; use a plain `agent()` or `council.run()` instead. For same-model, role-diverse review (one model, several perspectives), `/skill:fabric-council` is the closer match; fusion is for model-diverse deliberation.