@diousk/pi-subagents-fast 0.20.0

package/examples/workflows/lib/count-child.js

@@ -0,0 +1,27 @@
+/**
+ * lib/count-child.js — a nested workflow, invoked by compose.js.
+ *
+ * A child is an ordinary workflow: it needs its own `export const meta =`
+ * declaration, which is exactly what marks a file in a workflows directory as
+ * runnable rather than as some unrelated script that happens to live there.
+ *
+ * args: { root?: string }
+ */
+export const meta = {
+  name: 'count-child',
+  description: 'Count the source files under a directory',
+}
+
+const root = args?.root ?? 'src/'
+
+const found = await agent(`List every source file under ${root}. One path per line, nothing else.`, {
+  label: 'scan',
+  schema: {
+    type: 'object',
+    properties: { files: { type: 'array', items: { type: 'string' } } },
+    required: ['files'],
+  },
+})
+
+// A schema call can still return null if the child never complied.
+return found === null ? 0 : found.files.length

package/examples/workflows/review-panel.js

@@ -0,0 +1,63 @@
+/**
+ * review-panel.js — the case where a barrier is actually earned.
+ *
+ * Demonstrates: `parallel` used correctly, `effort` tiering (cheap reviewers,
+ * an expensive judge), and a `model` override.
+ *
+ * Most of the time `pipeline` beats `parallel`, because a barrier idles every
+ * fast agent until the slowest finishes. This is the exception: the synthesis
+ * prompt interpolates ALL of the reviews, so it genuinely cannot start until
+ * every one of them is in. That — a prompt that compares results against each
+ * other — is what justifies a barrier.
+ *
+ * args: { target?: string, lenses?: string[] }
+ *
+ * Run: ask the model — "run the workflow at examples/workflows/review-panel.js
+ * against src/auth.ts".
+ */
+export const meta = {
+  name: 'review-panel',
+  description: 'Review one thing from several angles, then reconcile the verdicts',
+  phases: [{ title: 'Review' }, { title: 'Synthesize' }],
+}
+
+const target = args?.target ?? 'the changed files'
+const lenses = args?.lenses ?? ['correctness', 'security', 'performance']
+
+phase('Review')
+
+// Perspective diversity, not redundancy: three reviewers with DIFFERENT briefs
+// catch failure modes that three identical ones cannot.
+const reviews = await parallel(
+  lenses.map(lens => () =>
+    agent(`Review ${target} through the lens of ${lens} alone. Be specific and brief.`, {
+      label: `review:${lens}`,
+      // Cheap for the survey work; the judge below gets the depth.
+      effort: 'low',
+    }),
+  ),
+)
+
+// A thunk that throws becomes null without taking its siblings down.
+const usable = reviews
+  .map((text, i) => ({ lens: lenses[i], text }))
+  .filter(r => r.text !== null)
+
+if (usable.length === 0) {
+  log('every reviewer failed — nothing to synthesize')
+  return { reviewed: 0, verdict: null }
+}
+
+phase('Synthesize')
+
+// This is the barrier's payoff: one prompt that sees all of them at once and can
+// weigh them against each other.
+const verdict = await agent(
+  [
+    `Reconcile these reviews of ${target}. Where they disagree, say which is right and why.`,
+    ...usable.map(r => `\n## ${r.lens}\n${r.text}`),
+  ].join('\n'),
+  { label: 'synthesize', effort: 'high', agentType: 'Plan' },
+)
+
+return { reviewed: usable.length, verdict }

package/examples/workflows/structured-findings.js

@@ -0,0 +1,78 @@
+/**
+ * structured-findings.js — get objects back, not prose.
+ *
+ * Demonstrates: `schema` on every agent call, so the script manipulates
+ * validated objects instead of parsing text it hopes is well-formed.
+ *
+ * Reach for this whenever the script has to *do* something with the results —
+ * sort, count, filter, compare — rather than hand them straight to you.
+ *
+ * args: { dimensions?: string[] }  — review angles, default bugs + perf
+ *
+ * Run: ask the model — "run the workflow at
+ * examples/workflows/structured-findings.js".
+ */
+export const meta = {
+  name: 'structured-findings',
+  description: 'Review changed files across dimensions and verify each finding',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+
+const FINDINGS = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          file: { type: 'string' },
+          severity: { type: 'string' },
+        },
+        required: ['title', 'file'],
+      },
+    },
+  },
+  required: ['findings'],
+}
+
+const VERDICT = {
+  type: 'object',
+  properties: { isReal: { type: 'boolean' }, why: { type: 'string' } },
+  required: ['isReal'],
+}
+
+const dimensions = args?.dimensions ?? ['bugs', 'performance']
+
+const reviewed = await pipeline(
+  dimensions,
+  dim => agent(`Review the changed files for ${dim}. Report every finding.`, {
+    label: `review:${dim}`,
+    phase: 'Review',
+    // With a schema the call resolves to the validated object, so `.findings`
+    // below is a real array rather than something scraped out of prose.
+    schema: FINDINGS,
+  }),
+  // A barrier is earned here only per-dimension: each dimension's findings are
+  // verified concurrently, but dimensions never wait for each other.
+  review => parallel(
+    review.findings.map(f => () =>
+      agent(`Try to REFUTE this finding: ${f.title} (${f.file})`, {
+        label: `verify:${f.file}`,
+        phase: 'Verify',
+        schema: VERDICT,
+      }).then(verdict => ({ ...f, verdict })),
+    ),
+  ),
+)
+
+// filter(Boolean) twice: once for a whole dimension that failed, once for an
+// individual verification that did. A schema call can still return null.
+const confirmed = reviewed
+  .filter(Boolean)
+  .flat()
+  .filter(Boolean)
+  .filter(f => f.verdict?.isReal)
+
+return { confirmed: confirmed.length, findings: confirmed }

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@diousk/pi-subagents-fast",
+  "version": "0.20.0",
+  "description": "A pi extension that brings Claude Code-like sub-agents and workflow orchestration to pi — parallel execution, live widget, fleet view, custom agent types, mid-run steering, dynamic workflows, Claude Code compatibility, look and feel.",
+  "author": "tintinweb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diousk/pi-subagents.git"
+  },
+  "homepage": "https://github.com/diousk/pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/diousk/pi-subagents/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
+    "@earendil-works/pi-tui": ">=0.84.0"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "croner": "^10.0.1",
+    "nanoid": "^5.1.16",
+    "typebox": "^1.3.7"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run e2e --reporter=verbose",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --fix src/ test/",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "test:coverage": "vitest run --coverage",
+    "bench": "vitest bench",
+    "bench:ab": "node test/perf/ab.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@earendil-works/pi-ai": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-istanbul": "^4.1.10",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "video": "https://github.com/diousk/pi-subagents/raw/master/media/demo.mp4",
+    "image": "https://github.com/diousk/pi-subagents/raw/master/media/screenshot.png"
+  }
+}

package/src/abortable.ts

@@ -0,0 +1,43 @@
+/**
+ * abortable.ts — race a promise against an AbortSignal without cancelling the
+ * underlying work.
+ *
+ * Used by the `get_subagent_result` wait paths (top-level and nested): pressing
+ * Esc cancels only the caller's wait; the background child keeps running and its
+ * result stays unconsumed. The listener is removed on every settle path so the
+ * signal accumulates no handlers, and a late settlement of the wrapped promise
+ * after an abort is absorbed as a no-op (no unhandled rejection).
+ */
+
+/** Await a promise until it settles or the caller cancels, without aborting the underlying work. */
+export function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(signal.reason);
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}

package/src/agent-color.ts

@@ -0,0 +1,161 @@
+/**
+ * agent-color.ts — Claude Code-compatible agent name badges.
+ *
+ * Claude Code renders a subagent's name as a badge: the configured color is the
+ * background, the text an inverse foreground. Its eight named colors are
+ * reproduced here, along with six-digit hex and the extra palette names Agency
+ * Agents uses, so those definitions render as written.
+ */
+
+import { getConfig } from "./agent-types.js";
+
+const NAMED_AGENT_COLORS: Readonly<Record<string, string>> = {
+  // Claude Code's eight subagent colors, as its default theme renders them.
+  red: "#DC2626",
+  blue: "#6A9BCC",
+  green: "#16A34A",
+  yellow: "#CA8A04",
+  purple: "#827DBD",
+  orange: "#D97757",
+  pink: "#C46686",
+  cyan: "#0891B2",
+  // Agency Agents palette aliases.
+  amber: "#F59E0B",
+  teal: "#008080",
+  indigo: "#6366F1",
+  gold: "#EAB308",
+  "neon-green": "#10B981",
+  "neon-cyan": "#06B6D4",
+  "metallic-blue": "#3B82F6",
+  violet: "#8B5CF6",
+  rose: "#F43F5E",
+  lime: "#84CC16",
+  gray: "#6B7280",
+  grey: "#6B7280",
+  fuchsia: "#D946EF",
+  slate: "#64748B",
+  navy: "#1E3A8A",
+};
+
+const CUBE_VALUES = [0, 95, 135, 175, 215, 255];
+const GRAY_VALUES = Array.from({ length: 24 }, (_, i) => 8 + i * 10);
+const BLACK = { r: 0, g: 0, b: 0 };
+const WHITE = { r: 255, g: 255, b: 255 };
+
+type Rgb = { r: number; g: number; b: number };
+type ColorMode = "truecolor" | "256color";
+
+export interface AgentNameTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+  getColorMode?(): ColorMode;
+}
+
+export interface AgentNameStyle {
+  /** Existing theme foreground used when no valid agent color is configured. */
+  fallbackColor?: string;
+  /** Reapply an enclosing background after the badge instead of resetting it. */
+  restoreBackground?: string;
+  bold?: boolean;
+}
+
+/** Resolve Claude Code/Agency Agents color syntax to normalized #RRGGBB. */
+export function resolveAgentColor(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  const resolved = NAMED_AGENT_COLORS[normalized] ?? normalized;
+  return /^#[0-9a-f]{6}$/i.test(resolved) ? resolved.toUpperCase() : undefined;
+}
+
+function parseHex(hex: string): Rgb {
+  return {
+    r: Number.parseInt(hex.slice(1, 3), 16),
+    g: Number.parseInt(hex.slice(3, 5), 16),
+    b: Number.parseInt(hex.slice(5, 7), 16),
+  };
+}
+
+/** Index of the entry in `values` closest to `value`. */
+function nearest(values: readonly number[], value: number): number {
+  return values.reduce((best, v, i) => (Math.abs(value - v) < Math.abs(value - values[best]) ? i : best), 0);
+}
+
+/**
+ * Quantize to the xterm-256 palette the way pi's own theme does, returning both
+ * the index to emit and the color the terminal will actually show — badge
+ * contrast is judged against the latter.
+ */
+function rgbTo256({ r, g, b }: Rgb): { index: number; rgb: Rgb } {
+  const [rIndex, gIndex, bIndex] = [r, g, b].map((channel) => nearest(CUBE_VALUES, channel));
+  const distance = ({ r: cr, g: cg, b: cb }: Rgb) => 0.299 * (r - cr) ** 2 + 0.587 * (g - cg) ** 2 + 0.114 * (b - cb) ** 2;
+  const grayIndex = nearest(GRAY_VALUES, Math.round(0.299 * r + 0.587 * g + 0.114 * b));
+  const gray = { r: GRAY_VALUES[grayIndex], g: GRAY_VALUES[grayIndex], b: GRAY_VALUES[grayIndex] };
+  const cube = { r: CUBE_VALUES[rIndex], g: CUBE_VALUES[gIndex], b: CUBE_VALUES[bIndex] };
+  // Only near-neutral colors may take the gray ramp; anything else keeps its tint.
+  if (Math.max(r, g, b) - Math.min(r, g, b) < 10 && distance(gray) < distance(cube)) {
+    return { index: 232 + grayIndex, rgb: gray };
+  }
+  return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cube };
+}
+
+function ansiColor(layer: "foreground" | "background", color: Rgb | number): string {
+  const code = layer === "foreground" ? 38 : 48;
+  return typeof color === "number"
+    ? `\u001b[${code};5;${color}m`
+    : `\u001b[${code};2;${color.r};${color.g};${color.b}m`;
+}
+
+function relativeLuminance({ r, g, b }: Rgb): number {
+  const linear = (value: number) => {
+    const channel = value / 255;
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/**
+ * Render one name as a padded background badge when `color` is valid. Claude
+ * Code uses one inverse color for every badge's text; black or white is picked
+ * by WCAG contrast here instead, so each palette entry stays readable. Invalid
+ * or omitted colors preserve the caller's existing theme styling.
+ */
+export function renderAgentNameLabel(
+  name: string,
+  color: string | undefined,
+  theme: AgentNameTheme,
+  style: AgentNameStyle = {},
+): string {
+  const resolved = resolveAgentColor(color);
+  if (!resolved) {
+    const text = style.bold ? theme.bold(name) : name;
+    return style.fallbackColor ? theme.fg(style.fallbackColor, text) : text;
+  }
+
+  const rgb = parseHex(resolved);
+  const quantized = (theme.getColorMode?.() ?? "truecolor") === "256color" ? rgbTo256(rgb) : undefined;
+  const shown = quantized?.rgb ?? rgb;
+  const contrasting = relativeLuminance(shown) > 0.179 ? BLACK : WHITE;
+  const label = style.bold ? theme.bold(` ${name} `) : ` ${name} `;
+
+  return ansiColor("background", quantized?.index ?? rgb)
+    + ansiColor("foreground", quantized ? rgbTo256(contrasting).index : contrasting)
+    + label
+    + "\u001b[39m"
+    + (style.restoreBackground ?? "\u001b[49m");
+}
+
+/** Whether an agent renders as a badge — i.e. it has a valid configured color. */
+export function hasAgentBadge(type: string | undefined): boolean {
+  return type !== undefined && resolveAgentColor(getConfig(type).color) !== undefined;
+}
+
+/** Render a registered agent's display name with its configured color. */
+export function renderAgentName(
+  type: string | undefined,
+  theme: AgentNameTheme,
+  style: AgentNameStyle = {},
+): string {
+  if (!type) return renderAgentNameLabel("Agent", undefined, theme, style);
+  const config = getConfig(type);
+  return renderAgentNameLabel(config.displayName, config.color, theme, style);
+}