pi-fabric 0.22.2 → 0.22.4

package/skills/fabric-council/SKILL.md

@@ -1,28 +1,94 @@
 ---
 name: fabric-council
-description: Runs a bounded multi-perspective Pi Fabric council with independent reviewers and optional synthesis. Use for architecture choices, plans, reviews, and adversarial cross-checking.
+description: Runs a bounded multi-perspective Pi Fabric council with independent reviewers and best-effort synthesis. Use for architecture choices, plans, reviews, and adversarial cross-checking.
 disable-model-invocation: true
 ---
 
 # Fabric Council
 
-Use one `fabric_exec` call and `council.run()`. Choose three to five roles that disagree usefully rather than duplicating one another, such as correctness, security, operability, maintainability, and requirements skepticism.
+Use one `fabric_exec` call with bounded role fan-out. Choose three to five roles that disagree usefully rather than duplicating one another, such as correctness, security, operability, maintainability, and requirements skepticism.
 
 ```ts
-const roles = JSON.parse(π.roles) as string[];
+type CouncilOutcome =
+  | { role: string; status: "completed"; report: string }
+  | { role: string; status: "failed"; error: string };
+
+const roles = [...new Set(
+  (JSON.parse(π.roles) as string[]).map((role) => role.trim()).filter(Boolean),
+)];
+if (roles.length < 3 || roles.length > 5) {
+  throw new Error("Council requires 3–5 distinct non-empty roles.");
+}
 await workflow.configure({
   name: "Council review",
-  description: `${roles.length} independent perspectives with synthesis`,
-});
-await phase("Deliberate", { total: roles.length });
-return council.run({
-  task: π.task,
-  roles,
-  tools: ["read", "grep", "find", "ls"],
-  synthesize: true,
+  description: `${roles.length} independent perspectives with best-effort synthesis`,
 });
+await phase("Deliberate", { total: roles.length + 1 });
+const outcomes = await parallel(
+  roles.map((role) => async (): Promise<CouncilOutcome> => {
+    try {
+      const report = await agent(
+        `Act as the ${role} council member. Independently analyze this task:\n\n${π.task}`,
+        { label: role, tools: ["read", "grep", "find", "ls"] },
+      );
+      return { role, status: "completed", report };
+    } catch (error) {
+      return {
+        role,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }),
+  { concurrency: roles.length },
+);
+const completed = outcomes.filter(
+  (outcome): outcome is Extract<CouncilOutcome, { status: "completed" }> =>
+    outcome.status === "completed",
+);
+const failures = outcomes.filter(
+  (outcome): outcome is Extract<CouncilOutcome, { status: "failed" }> =>
+    outcome.status === "failed",
+);
+const coverage = { requested: roles.length, completed: completed.length };
+if (completed.length === 0) {
+  return { status: "failed", coverage, failures, result: null };
+}
+if (completed.length === 1) {
+  return {
+    status: "partial",
+    coverage,
+    failures,
+    result: completed[0].report,
+    synthesisSkipped: "Only one role completed; another agent would add no diversity.",
+  };
+}
+
+try {
+  const result = await agent(
+    `Synthesize these completed reports into one decision. Reject unsupported claims, preserve material disagreements, attribute each concern to its role. Do not infer the views of failed roles.\n\nTask:\n${π.task}\n\nReports:\n${JSON.stringify(completed)}`,
+    { label: "council synthesis", tools: ["read", "grep", "find", "ls"] },
+  );
+  return {
+    status: failures.length === 0 ? "success" : "partial",
+    coverage,
+    failures,
+    result,
+  };
+} catch (error) {
+  return {
+    status: "partial",
+    coverage,
+    failures,
+    result: null,
+    synthesisError: error instanceof Error ? error.message : String(error),
+    fallback: completed,
+  };
+}
 ```
 
-Pass the task as `strings.task` and the JSON role array as `strings.roles`. Members inspect evidence independently; synthesis must preserve material disagreement, reject unsupported claims, and make a concrete recommendation. Use `synthesize: false` only for raw opinions.
+Pass the task as `strings.task` and the JSON role array as `strings.roles`. Successful synthesis returns only the compact decision, coverage, and failures. Raw completed reports return only when synthesis fails; one surviving role returns directly without spending another agent call.
+
+Concurrent calls can overshoot an observational `tokenBudget` because usage settles afterward. Reserve at least `roles.length + 1` top-level agent calls when synthesis may run, and use a finite role set rather than relying on token accounting as a hard concurrent ceiling.
 
-A council costs N concurrent role agents plus one sequential synthesizer and must fit `executor.timeoutMs`; its usage counts toward the execution budget. Keep roles bounded and set top-level `agentBudget`/`tokenBudget` for large runs. Do not use a council for a simple lookup or a decision with no meaningful competing considerations.
+Status is `success`, `partial`, or `failed`. A partial result is usable evidence with named gaps and must not trigger an automatic whole-council rerun. If a missing perspective matters, retry that role with one plain agent using the original task and role; do not invoke a new council or rerun successful roles. Do not use a council for a lookup or a decision with no meaningful competing considerations.

package/skills/fabric-exec/SKILL.md

@@ -60,7 +60,7 @@ All calls return promises. Fields ending in `?` are optional; `unknown` marks pr
 
 ### Dynamic provider return shapes
 
-- `mcp.<sanitized_server>.<sanitized_tool>(args)` resolves to the server-defined result, commonly `{text:string,content:unknown[],structuredContent:unknown}`; for example `mcp.fal_ai.get_model_schema({ endpoint_id: "openai/gpt-image-2" })`. See `references/mcp.md`.
+- `mcp.<sanitized_server>.<sanitized_tool>(args)` resolves to the server-defined result, commonly `{text:string,content:unknown[],structuredContent:unknown}`; for example `mcp.fal_ai.get_model_schema({ endpoint_id: "openai/gpt-image-2" })`. `references/mcp.md` is a branch pointer for MCP naming and management only when the task needs MCP.
 - `extensions.<tool>(args)` in full code mode resolves to `{content:Array<{type,text?,...}>,text:string,details?,isError:boolean,terminate?,source:{path,source,scope,origin,baseDir?}}`.
 
 The guest TypeScript declarations contain the complete argument and return contracts. For a discovered or dynamic action, use `tools.describe({ref})`; inspect `outputSchema` when supplied, otherwise treat the result as `unknown`.
@@ -72,7 +72,7 @@ Refs are namespaced (`pi.grep`, `extensions.<tool>`, `mcp.<server>.<tool>`, `sch
 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`).
 
 ## Orchestration surfaces (opt-in)
-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`).
+Advanced workflow skills are user-invoked; never load them autonomously. When the user has explicitly invoked an agent or mesh workflow, `references/agents.md` and `references/mesh.md` are branch pointers for low-level API detail.
 
 `agents.main()` returns the dashboard-owning root Pi session; `agents.peers()` lists other live root sessions in the shared project mesh as `Peer <session-prefix>` targets. Peers support `agents.steer()` and `agents.followUp()` by exact id.
 

package/skills/fabric-exec/references/agents.md

@@ -118,4 +118,4 @@ Mailbox:
 return rlm.query({ task: "Decompose this repository and produce a compact architecture map.", transport: "process" });
 ```
 
-`council.run({ task, roles, synthesize?, ...agentOptions })` runs several `agents.run` calls concurrently under the subagent semaphore and optionally synthesizes them; load `/skill:fabric-council` for the pattern.
+`council.run({ task, roles, synthesize?, ...agentOptions })` runs several `agents.run` calls concurrently under the subagent semaphore and optionally synthesizes them. The full council pattern is user-invoked; never load `/skill:fabric-council` autonomously.

package/skills/fabric-fusion/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: fabric-fusion
-description: Multi-model deliberation. Up to 8 distinct models answer in parallel with web-capable tools, then a judge compares consensus, contradictions, coverage gaps, unique insights, and blind spots. Use when the cost of being wrong justifies multiple completions.
+description: Multi-model deliberation. Two to 8 distinct models answer in parallel with web-capable tools, then a judge compares consensus, contradictions, coverage gaps, unique insights, and blind spots. Use when the cost of being wrong justifies multiple completions.
 disable-model-invocation: true
 ---
 
 # Fabric Fusion
 
-Use one `fabric_exec` call for a 1–8 model panel followed by one judge. The judge compares rather than merges responses; return its structured analysis so the caller writes the final answer. Use fusion for model-diverse research or critique, not tactical work or a lookup.
+Use one `fabric_exec` call for a 2–8 model panel and a judge when at least two responses complete. The judge compares rather than merges responses; return a compact status/coverage/analysis envelope so the caller writes the final answer. Use fusion for model-diverse research or critique, not tactical work or a lookup.
 
 Pass every key: `strings.task`; JSON `strings.panel` as `Array<{ model, label? }>`; and optional `strings.judge`, `strings.tools`, and `strings.thinking` as empty strings when unset. Labels are attribution only. Tools default to `read`, `grep`, `find`, `ls`, and `bash`; thinking defaults to configured subagent thinking.
 
@@ -21,8 +21,8 @@ type FusionAnalysis = {
 
 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.");
+if (panel.length < 2 || panel.length > 8) {
+  throw new Error("Fusion panel (analysis_models) must have 2–8 members.");
 }
 const toolset = π.tools ? (JSON.parse(π.tools) as string[]) : ["read", "grep", "find", "ls", "bash"];
 const thinking = π.thinking ? (π.thinking as FabricThinking) : undefined;
@@ -53,83 +53,151 @@ try {
 }
 const resolve = (needle: string): RunnerModel => {
   const n = needle.toLowerCase();
-  const hit = models.find(
+  const exact = models.filter((entry) => entry.key.toLowerCase() === n);
+  if (exact.length === 1) return exact[0];
+  const fuzzy = models.filter(
     (entry) =>
-      entry.key.toLowerCase() === n ||
-      entry.id.toLowerCase().includes(n) ||
-      entry.name.toLowerCase().includes(n),
+      entry.id.toLowerCase().includes(n) || entry.name.toLowerCase().includes(n),
   );
-  if (!hit) {
+  if (fuzzy.length !== 1) {
     throw new Error(
-      `Fusion: model "${needle}" not found. Available: ${models.map((entry) => entry.key).join(", ")}`,
+      fuzzy.length === 0
+        ? `Fusion: model "${needle}" not found. Available: ${models.map((entry) => entry.key).join(", ")}`
+        : `Fusion: model "${needle}" is ambiguous. Matches: ${fuzzy.map((entry) => entry.key).join(", ")}`,
     );
   }
-  return hit;
+  return fuzzy[0];
 };
 const members = panel.map((member) => ({
   ...resolve(member.model),
-  label: member.label || member.model,
+  label: (member.label || member.model).trim(),
 }));
-const judgeModel = π.judge ? resolve(π.judge) : members[0];
+const modelIdentities = members.map((member) =>
+  `${member.runner}:${member.provider}:${member.resolvedModel ?? member.id}`
+);
+if (new Set(modelIdentities).size !== members.length) {
+  throw new Error("Fusion requires distinct resolved models, not aliases of the same model.");
+}
+if (members.some((member) => !member.label) ||
+    new Set(members.map((member) => member.label)).size !== members.length) {
+  throw new Error("Fusion requires distinct non-empty labels.");
+}
+const explicitJudge = π.judge ? resolve(π.judge) : undefined;
 
-// 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.
+type PanelOutcome =
+  | { label: string; model: string; runner: FabricAgentRunner; status: "completed"; response: string }
+  | { label: string; model: string; runner: FabricAgentRunner; status: "failed"; error: string };
+
+// Plain, non-recursive members preserve one level of deliberation.
 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),
-        runner: m.runner,
-        model: m.key,
-        tools: toolset,
-        ...(thinking ? { thinking } : {}),
-      },
-    ),
-  ),
+const outcomes = await parallel(
+  members.map((member) => async (): Promise<PanelOutcome> => {
+    try {
+      const response = await 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 · ${member.label}`.slice(0, 50),
+          runner: member.runner,
+          model: member.key,
+          tools: toolset,
+          ...(thinking ? { thinking } : {}),
+        },
+      );
+      return {
+        label: member.label, model: member.key, runner: member.runner,
+        status: "completed", response,
+      };
+    } catch (error) {
+      return {
+        label: member.label, model: member.key, runner: member.runner,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }),
   { concurrency: members.length },
 );
+const completed = outcomes.filter(
+  (outcome): outcome is Extract<PanelOutcome, { status: "completed" }> =>
+    outcome.status === "completed",
+);
+const failures = outcomes.filter(
+  (outcome): outcome is Extract<PanelOutcome, { status: "failed" }> =>
+    outcome.status === "failed",
+);
+const coverage = { requested: members.length, completed: completed.length };
+if (completed.length === 0) {
+  return { status: "failed", coverage, failures, analysis: null };
+}
+if (completed.length === 1) {
+  return {
+    status: "partial",
+    coverage,
+    failures,
+    analysis: null,
+    judgeSkipped: "At least two model responses are required for comparison.",
+    fallback: completed,
+  };
+}
 
-// Judge: compare, don't merge. Returns the structured analysis shape
-// OpenRouter's fusion judge returns; the caller writes the final answer.
+const judgeModel = explicitJudge ?? {
+  key: completed[0].model,
+  runner: completed[0].runner,
+};
 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",
-    runner: judgeModel.runner,
-    model: judgeModel.key,
-    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" } },
+try {
+  const analysis = await agent<FusionAnalysis>(
+    `You are the fusion judge. Compare these ${completed.length} completed panel responses — do NOT merge them into one answer or infer claims from failed models.\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(completed),
+    {
+      label: "fusion judge",
+      runner: judgeModel.runner,
+      model: judgeModel.key,
+      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,
       },
-      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;
+  );
+  await workflow.event({ message: `Fusion complete · ${completed.length}/${members.length} models judged`, level: "success" });
+  return {
+    status: failures.length === 0 ? "success" : "partial",
+    coverage,
+    failures,
+    analysis,
+  };
+} catch (error) {
+  return {
+    status: "partial",
+    coverage,
+    failures,
+    analysis: null,
+    judgeError: error instanceof Error ? error.message : String(error),
+    fallback: completed,
+  };
+}
 ```
 
-Choose distinct models by intent: strongest available, budget-balanced with a frontier judge, or similar-latency models for faster fan-out. The default panel size is three. Cost is N panel calls plus one judge; set top-level `agentBudget` and `tokenBudget`, while `subagents.budgetUsd` bounds spend.
+Choose distinct models by intent: strongest available, budget-balanced with a frontier judge, or similar-latency models for faster fan-out. The default panel size is three. Cost is N panel calls plus a judge when comparison is possible. Reserve `panel.length + 1` top-level agent calls. Concurrent calls can overshoot observational token/USD checks because usage settles afterward; those settings are not hard concurrent reservations.
 
 Panel members and the judge are plain, non-recursive agents, so deliberation is one level. `bash` enables web access through local search/fetch commands and requires execute approval. Concurrency is capped by `subagents.maxConcurrent`; inner calls otherwise inherit provider limits and use `thinking` for reasoning effort.
 
-Use `/skill:fabric-council` instead for same-model, role-diverse review. Use a plain agent when competing model perspectives do not justify the cost.
+For same-model role diversity, recommend `/skill:fabric-council` for the user to invoke; do not invoke another user-only skill yourself. Use a plain agent when competing model perspectives do not justify the cost.
+
+## Completion criterion
+
+Return `success`, `partial`, or `failed` with explicit panel coverage. Successful judging returns only the structured comparison; raw responses return only when judging fails or fewer than two models complete. A partial result is usable and must not trigger an automatic full-panel rerun. Failures retain label, canonical model key, and runner; retry only failed models or the judge when that missing coverage matters.

package/skills/fabric-guide/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: fabric-guide
+description: Recommends the right user-invoked Pi Fabric workflow without running it. Use when you want help choosing among workflow, council, fusion, RLM, Schema, ambient actors, or swarm.
+disable-model-invocation: true
+---
+
+# Fabric Guide
+
+Recommend the smallest sufficient path; do not invoke it. Core coding needs no advanced skill: answer `No advanced skill — use the core fabric_exec path.`
+
+| Need | Recommend |
+|---|---|
+| Finite discover → fan-out → verify work | `/skill:fabric-workflow` |
+| Same-model independent roles and synthesis | `/skill:fabric-council` |
+| Different models compared by a judge | `/skill:fabric-fusion` |
+| Work too large for one context window | `/skill:fabric-rlm` |
+| Evidence-gated or transactional local-file mutation | `/skill:fabric-schema` |
+| Persistent material peer advice | `/skill:fabric-advisor` |
+| Persistent progress toward one measurable goal | `/skill:fabric-supervisor` |
+| One command that infers advisor versus supervisor | `/skill:fabric-ambient` |
+| Durable actor team with mailboxes and CAS tasks | `/skill:fabric-swarm` |
+
+Prefer the smallest sufficient mechanism. Distinguish workflow/council/fusion by execution shape, RLM by context size, ambient roles by persistence, and swarm by durable multi-actor coordination.
+
+## Completion criterion
+
+Complete with one of three outputs: (1) `No advanced skill` plus one-sentence reasoning for core work; (2) one advanced recommendation, one-sentence reasoning, and an exact `/skill:...` command that preserves the user’s task as arguments; or (3) one discriminating question when two choices are genuinely tied. Never load or execute a recommended skill yourself.