@alexeiled/pi-fusion 0.2.2 → 0.3.0

package/docs/user-guide.md

@@ -110,7 +110,8 @@ Panel member:
 - `id`: stable machine name
 - `label`: human-readable report label
 - `agent`: subagent name
-- `model`: optional model override; often the main source of panel diversity
+- `model`: optional model override; often the main source of panel diversity. Supports normal Pi model ids, and if `pi-claude-alias` is configured, Claude alias shorthand like `claude-work/opus-4.8`
+- Claude alias handles must be unique across global and project alias files; duplicate handles are rejected.
 - `thinking`: optional `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`
 - `role`: optional perspective hint layered on top of the model
 
@@ -162,7 +163,7 @@ Deliberate review:
           "id": "architect",
           "label": "Architect",
           "agent": "pi-fusion.fusion-panelist",
-          "model": "anthropic/claude-sonnet-4",
+          "model": "claude-work/sonnet-4.6",
           "thinking": "high",
           "role": "architecture and failure modes"
         },
@@ -177,7 +178,7 @@ Deliberate review:
       ],
       "judge": {
         "agent": "pi-fusion.fusion-judge",
-        "model": "anthropic/claude-sonnet-4",
+        "model": "claude-work/sonnet-4.6",
         "thinking": "high"
       },
       "concurrency": 2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Stronger answers for hard Pi questions via a parallel model panel + judge, built on pi-subagents",
   "type": "module",
   "main": "./src/index.ts",
@@ -21,6 +21,7 @@
   ],
   "files": [
     "agents/*.md",
+    "skills/**/*.md",
     "src/*.ts",
     "docs/user-guide.md"
   ],
@@ -39,6 +40,9 @@
     "extensions": [
       "./src/index.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "subagents": {
       "agents": [
         "./agents"

package/skills/fusion-review/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: fusion-review
+description: >
+  Trigger a pi-fusion multi-model panel review implicitly. Use when the user asks to
+  "invoke fusion", "run a fusion panel", "discuss this through fusion", "get multi-model
+  opinions", "panel review", or any phrasing that implies running a parallel model review.
+  Call the start_fusion_review tool with the user's topic or prompt.
+---
+
+# Fusion Review
+
+Use the `start_fusion_review` tool to launch a fusion panel without the user needing to type `/fusion`.
+
+## When to use
+
+- "invoke fusion panel to discuss this"
+- "run fusion on this"
+- "get a panel review of …"
+- "use multi-model review for …"
+- "discuss this through fusion"
+- Any prompt that implies parallel model review or multi-perspective analysis
+
+## How to use
+
+Call `start_fusion_review` with:
+
+- `prompt` — the topic, question, or code excerpt to review (required)
+- `profile` — a named fusion profile (optional; omit to use the default)
+
+The tool queues a `/fusion` command as a follow-up, so the panel starts immediately after the current turn.

package/src/claude-aliases.ts

@@ -0,0 +1,255 @@
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { FusionConfig } from "./types.js";
+import { FusionConfigError } from "./errors.js";
+import { isNodeErrorCode, isNonEmptyString, isRecord } from "./utils.js";
+import type { FusionConfigLoadContext } from "./config.js";
+
+const CLAUDE_ALIAS_CONFIG_FILE = "claude-alias.json";
+
+interface ClaudeAliasDefinition {
+  slug: string;
+  providerId: string;
+  handle: string;
+}
+
+interface AliasFileDeps {
+  readTextFile?: (path: string) => Promise<string>;
+  agentDir?: string;
+}
+
+interface RawAliasConfig {
+  aliases?: unknown;
+}
+
+interface RawAliasEntry {
+  slug?: unknown;
+  handle?: unknown;
+}
+
+export async function applyClaudeAliasShorthand(
+  config: FusionConfig,
+  ctx: FusionConfigLoadContext,
+  deps: AliasFileDeps = {},
+): Promise<FusionConfig> {
+  const aliases = await loadClaudeAliases(ctx, deps);
+  if (aliases.length === 0) return config;
+
+  return {
+    ...config,
+    profiles: Object.fromEntries(
+      Object.entries(config.profiles).map(([name, profile]) => [
+        name,
+        {
+          ...profile,
+          panel: profile.panel.map((member) => ({
+            ...member,
+            ...(member.model
+              ? { model: resolveClaudeAliasModelSpec(member.model, aliases) }
+              : {}),
+          })),
+          judge: {
+            ...profile.judge,
+            ...(profile.judge.model
+              ? { model: resolveClaudeAliasModelSpec(profile.judge.model, aliases) }
+              : {}),
+          },
+        },
+      ]),
+    ),
+  };
+}
+
+export function resolveClaudeAliasModelSpec(
+  model: string,
+  aliases: readonly ClaudeAliasDefinition[],
+): string {
+  const trimmed = model.trim();
+  const slashIndex = trimmed.indexOf("/");
+  if (slashIndex <= 0 || slashIndex === trimmed.length - 1) return trimmed;
+
+  const handle = trimmed.slice(0, slashIndex).trim().toLowerCase();
+  const modelRef = trimmed.slice(slashIndex + 1).trim();
+  const alias = aliases.find((item) => item.handle === handle);
+  if (!alias) return trimmed;
+
+  return `${alias.providerId}/${normalizeAnthropicModelRef(modelRef)}`;
+}
+
+export function normalizeAnthropicModelRef(modelRef: string): string {
+  const normalized = modelRef
+    .trim()
+    .toLowerCase()
+    .replace(/[._\s]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  if (!normalized) return modelRef.trim();
+  return normalized.startsWith("claude-") ? normalized : `claude-${normalized}`;
+}
+
+async function loadClaudeAliases(
+  ctx: FusionConfigLoadContext,
+  deps: AliasFileDeps,
+): Promise<ClaudeAliasDefinition[]> {
+  const readTextFile = deps.readTextFile ?? readUtf8File;
+  const global = await readOptionalAliasFile(
+    getGlobalClaudeAliasConfigPath(deps.agentDir),
+    readTextFile,
+  );
+  const project = ctx.isProjectTrusted()
+    ? await readOptionalAliasFile(
+        getProjectClaudeAliasConfigPath(ctx.cwd),
+        readTextFile,
+      )
+    : undefined;
+
+  const merged = new Map<string, ClaudeAliasDefinition>();
+  for (const alias of global ?? []) {
+    merged.set(alias.slug, alias);
+  }
+  for (const alias of project ?? []) {
+    merged.set(alias.slug, alias);
+  }
+
+  const aliases = [...merged.values()];
+  validateUniqueHandles(aliases);
+  return aliases;
+}
+
+async function readOptionalAliasFile(
+  path: string,
+  readTextFile: (path: string) => Promise<string>,
+): Promise<ClaudeAliasDefinition[] | undefined> {
+  let raw: string;
+  try {
+    raw = await readTextFile(path);
+  } catch (error: unknown) {
+    if (isNodeErrorCode(error, "ENOENT")) return undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FusionConfigError(
+      `Could not read Claude alias config at ${path}: ${message}`,
+    );
+  }
+
+  return parseAliasFile(raw, path);
+}
+
+function parseAliasFile(raw: string, source: string): ClaudeAliasDefinition[] {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FusionConfigError(
+      `Invalid JSON in Claude alias config at ${source}: ${message}`,
+    );
+  }
+
+  if (!isRecord(value) || !Array.isArray((value as RawAliasConfig).aliases)) {
+    throw new FusionConfigError(
+      `Invalid Claude alias config at ${source}. Expected aliases array.`,
+    );
+  }
+
+  const aliasValues = (value as { aliases: unknown[] }).aliases;
+  const aliases: ClaudeAliasDefinition[] = [];
+  for (const [index, entry] of aliasValues.entries()) {
+    const parsed = parseAliasEntry(entry);
+    if (!parsed) {
+      throw new FusionConfigError(
+        `Invalid Claude alias entry at ${source} aliases[${index}].`,
+      );
+    }
+    aliases.push(parsed);
+  }
+
+  return dedupeAliases(aliases, source);
+}
+
+function parseAliasEntry(value: unknown): ClaudeAliasDefinition | undefined {
+  if (!isRecord(value)) return undefined;
+  const entry = value as RawAliasEntry;
+
+  const slug = normalizeSlug(entry.slug);
+  if (!slug) return undefined;
+
+  const handle = normalizeHandle(entry.handle) ?? `claude-${slug}`;
+  if (!handle) return undefined;
+
+  return {
+    slug,
+    providerId: `anthropic-${slug}`,
+    handle,
+  };
+}
+
+function dedupeAliases(
+  aliases: readonly ClaudeAliasDefinition[],
+  source: string,
+): ClaudeAliasDefinition[] {
+  const byHandle = new Set<string>();
+  const deduped: ClaudeAliasDefinition[] = [];
+
+  for (const alias of aliases) {
+    if (byHandle.has(alias.handle)) {
+      throw new FusionConfigError(
+        `Duplicate Claude alias handle "${alias.handle}" in ${source}.`,
+      );
+    }
+    byHandle.add(alias.handle);
+    deduped.push(alias);
+  }
+
+  return deduped;
+}
+
+function validateUniqueHandles(
+  aliases: readonly ClaudeAliasDefinition[],
+): void {
+  const seen = new Map<string, string>();
+
+  for (const alias of aliases) {
+    const existingSlug = seen.get(alias.handle);
+    if (existingSlug && existingSlug !== alias.slug) {
+      throw new FusionConfigError(
+        `Duplicate Claude alias handle "${alias.handle}" across merged config. Use a unique handle for each alias.`,
+      );
+    }
+    seen.set(alias.handle, alias.slug);
+  }
+}
+
+function normalizeSlug(value: unknown): string | undefined {
+  if (!isNonEmptyString(value)) return undefined;
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || undefined;
+}
+
+function normalizeHandle(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  if (!isNonEmptyString(value)) return undefined;
+  const handle = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return handle || undefined;
+}
+
+function getGlobalClaudeAliasConfigPath(agentDir = getAgentDir()): string {
+  return join(agentDir, CLAUDE_ALIAS_CONFIG_FILE);
+}
+
+function getProjectClaudeAliasConfigPath(cwd: string): string {
+  return join(cwd, CONFIG_DIR_NAME, CLAUDE_ALIAS_CONFIG_FILE);
+}
+
+async function readUtf8File(path: string): Promise<string> {
+  return readFile(path, "utf8");
+}

package/src/config.ts

@@ -1,6 +1,7 @@
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { applyClaudeAliasShorthand } from "./claude-aliases.js";
 import { FusionConfigError } from "./errors.js";
 import {
   THINKING_LEVELS,
@@ -104,12 +105,15 @@ export async function loadFusionConfig(
   if (ctx.isProjectTrusted()) {
     const projectPath = getProjectFusionConfigPath(ctx.cwd);
     const projectConfig = await readOptionalConfig(projectPath, readTextFile);
-    if (projectConfig) return projectConfig;
+    if (projectConfig) {
+      return applyClaudeAliasShorthand(projectConfig, ctx, deps);
+    }
   }
 
   const globalPath = getGlobalFusionConfigPath(deps.agentDir);
   const globalConfig = await readOptionalConfig(globalPath, readTextFile);
-  return globalConfig ?? createDefaultFusionConfig();
+  const config = globalConfig ?? createDefaultFusionConfig();
+  return applyClaudeAliasShorthand(config, ctx, deps);
 }
 
 export function resolveProfile(

package/src/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { registerFusionCommands } from "./commands.js";
 import {
   FusionOrchestrator,
@@ -7,6 +8,35 @@ import {
 import { FusionRunStore } from "./run-store.js";
 import { SubagentsRpcClient } from "./subagents-rpc.js";
 
+function registerFusionTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "start_fusion_review",
+    label: "Fusion Review",
+    description:
+      "Start a pi-fusion multi-model panel review. Use when the user asks to invoke fusion, run a panel review, get multi-model opinions, or discuss something through the fusion panel.",
+    promptSnippet: "Start a fusion panel review for a topic or code",
+    promptGuidelines: [
+      "Use start_fusion_review when the user says 'invoke fusion', 'run fusion', 'fusion panel', 'multi-model review', 'panel review', or similar.",
+    ],
+    parameters: Type.Object({
+      prompt: Type.String({ description: "What to review or discuss" }),
+      profile: Type.Optional(
+        Type.String({ description: "Fusion profile name (optional)" }),
+      ),
+    }),
+    execute(_toolCallId, params) {
+      const cmd = params.profile
+        ? `/fusion --profile ${params.profile} ${params.prompt}`
+        : `/fusion ${params.prompt}`;
+      pi.sendUserMessage(cmd, { deliverAs: "followUp" });
+      return Promise.resolve({
+        content: [{ type: "text", text: "Starting fusion panel review…" }],
+        details: { prompt: params.prompt, profile: params.profile },
+      });
+    },
+  });
+}
+
 export default function fusionExtension(pi: ExtensionAPI): void {
   const orchestrator = new FusionOrchestrator({
     rpc: new SubagentsRpcClient({ events: pi.events }),
@@ -15,6 +45,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   });
 
   registerFusionCommands(pi, orchestrator);
+  registerFusionTool(pi);
 
   const unsubscribeComplete = pi.events.on(
     SUBAGENT_ASYNC_COMPLETE_EVENT,