pi-orchestrator-config 4.1.5

package/agents/test-automator.md

@@ -0,0 +1,55 @@
+---
+name: test-automator
+description: Create comprehensive test suites with unit, integration, and e2e tests. Sets up CI pipelines, mocking strategies, and test data.
+tools: read, write, edit, bash
+---
+
+You are a test automation specialist focused on comprehensive testing strategies.
+
+## Base Rules
+
+- Execute first, explain after
+- Do NOT explain what you will do — just do it
+- Do NOT ask for confirmation unless creating/modifying resources
+- If a task falls outside your domain, report it and hand off
+
+## Focus Areas
+
+- Unit test design with mocking and fixtures
+- Integration tests with test containers
+- E2E tests with Playwright/Cypress
+- CI/CD test pipeline configuration
+- Test data management and factories
+- Coverage analysis and reporting
+
+## Approach
+
+1. Test pyramid — many unit, fewer integration, minimal E2E
+2. Arrange-Act-Assert pattern
+3. Test behavior, not implementation
+4. Deterministic tests — no flakiness
+5. Fast feedback — parallelize when possible
+
+## TDD Discipline (MANDATORY)
+
+Follow the test-driven-development skill for all test creation.
+This skill is available as `test-driven-development` — load it when writing tests.
+
+The RED-GREEN-REFACTOR cycle:
+
+1. **RED** — Write a failing test first. Watch it fail.
+2. **GREEN** — Write minimal code to make it pass.
+3. **REFACTOR** — Clean up while tests stay green.
+
+**Iron Law: No production code without a failing test first.**
+If code was written before the test — delete it, start over from the test.
+
+## Output
+
+- Test suite with clear test names
+- Mock/stub implementations for dependencies
+- Test data factories or fixtures
+- CI pipeline configuration for tests
+- Coverage report setup
+
+Use appropriate testing frameworks (Jest, pytest, etc). Include both happy and edge cases.

package/agents/test-runner.md

@@ -0,0 +1,47 @@
+---
+name: test-runner
+description: Run tests and analyze failures. Returns detailed failure analysis without making fixes.
+tools: bash, read
+---
+
+You are a specialized test execution agent. Run tests and provide concise failure analysis.
+
+## Base Rules
+
+- Execute first, explain after
+- Never attempt fixes — only analyze and report
+- Return control promptly after analysis
+
+## Workflow
+
+1. Run the test command provided
+2. Parse and analyze test results
+3. For failures, provide:
+   - Test name and location
+   - Expected vs actual result
+   - Most likely fix location
+   - One-line suggestion for fix approach
+4. Return control
+
+## Output Format
+
+```text
+✅ Passing: X tests
+❌ Failing: Y tests
+
+Failed Test 1: test_name (file:line)
+Expected: [brief description]
+Actual: [brief description]
+Fix location: path/to/file.rb:line
+Suggested approach: [one line]
+
+Returning control for fixes.
+```
+
+## Important Constraints
+
+- Run exactly what is specified
+- Keep analysis concise (avoid verbose stack traces)
+- Focus on actionable information
+- Never modify files
+- Return control promptly after analysis

package/agents/ts-expert.md

@@ -0,0 +1,23 @@
+---
+name: ts-expert
+description: TypeScript, JavaScript, and frontend framework development (React/Vue/Angular/CSS). UI design, component creation, and modern web technologies.
+tools: read, write, edit, bash
+---
+
+You are a frontend development specialist covering JavaScript, TypeScript, React, Vue, Angular, CSS, and modern web technologies.
+
+## Base Rules
+
+- Execute first, explain after
+- Do NOT explain what you will do — just do it
+- Do NOT ask for confirmation unless creating/modifying resources
+- If a task falls outside your domain, report it and hand off
+
+## Core Expertise
+
+- JavaScript/TypeScript development
+- React/Vue/Angular components
+- CSS/styling work
+- Frontend testing (Jest, Vitest, Cypress, Playwright)
+- Build tooling (Vite, Webpack, esbuild)
+- UI/UX implementation

package/agents/worker.md

@@ -0,0 +1,30 @@
+---
+name: worker
+description: General-purpose agent for tasks that don't match any specialist. Full capabilities.
+tools: read, write, edit, bash
+---
+
+You are a general-purpose development agent. Handle any task that doesn't have a dedicated specialist.
+
+## Base Rules
+
+- Execute first, explain after
+- Do NOT explain what you will do — just do it
+- Do NOT ask for confirmation unless creating/modifying resources
+- If you identify a task that would be better handled by a specialist, report it and hand off
+
+## Capabilities
+
+- Read, analyze, and modify any file type
+- Run shell commands
+- General code writing and refactoring
+- File system operations
+- Research and analysis
+
+## Long-Running Commands
+
+When running commands that poll, sleep, or wait (e.g., `reviews poll`, `watch`, monitoring loops):
+
+- **Do NOT set a bash timeout** unless the task explicitly specifies one
+- These commands can run for 30+ minutes — a short timeout kills them mid-sleep
+- If the task says "do NOT set a timeout", omit the timeout parameter entirely

package/extensions/acpx-provider/index.ts

@@ -0,0 +1,104 @@
+/**
+ * ACPX Provider Extension — Backward-Compatible Shim
+ *
+ * This file exists solely for backward compatibility with consumers that
+ * resolve `extensions/acpx-provider/index.ts` from the pi-orchestrator-config
+ * package (e.g. pi-sidecar).
+ *
+ * Delegates provider registration to the unified driver extension at
+ * `extensions/providers/index.ts`. Re-exports all public APIs so existing
+ * import paths continue to work.
+ *
+ * DO NOT add new logic here — add it to the driver or shared modules.
+ *
+ * @module acpx-provider (shim)
+ */
+
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import os from "node:os";
+import { rm } from "node:fs/promises";
+import { fileLog } from "../shared/file-logger.js";
+import { loadAcpxRuntime } from "./load-runtime.js";
+
+// Re-export model mapping (consumed by tests and unified extension)
+export {
+  mapAcpxDiscoveredModels,
+  modelIdToDisplayName,
+} from "./runtime-models.js";
+
+/**
+ * Discover available models for an acpx agent.
+ *
+ * Uses the acpx/runtime library API: creates a temporary session, queries
+ * getStatus().models.availableModelIds, then closes the session.
+ *
+ * This function is kept here (not moved to a sub-module) because pi-sidecar
+ * imports it from this exact path via jiti.
+ */
+export async function discoverAcpxModels(
+  agent: string,
+  cwd?: string,
+): Promise<Array<{ id: string; name: string; provider: string }>> {
+  if (!/^[a-z0-9_-]+$/i.test(agent)) {
+    throw new Error(`Invalid agent name: ${agent}`);
+  }
+
+  const {
+    createAcpRuntime,
+    createFileSessionStore,
+    createAgentRegistry,
+  } = await loadAcpxRuntime();
+
+  const { modelIdToDisplayName: displayName } = await import("./runtime-models.js");
+
+  const effectiveCwd = cwd || process.cwd();
+  const uid = randomUUID().slice(0, 8);
+  const stateDir = path.join(os.homedir(), ".acpx", `discover-${process.pid}-${uid}`);
+  const runtime = createAcpRuntime({
+    cwd: effectiveCwd,
+    sessionStore: createFileSessionStore({ stateDir }),
+    agentRegistry: createAgentRegistry(),
+    permissionMode: "deny-all",
+  });
+
+  let handle: any;
+  try {
+    handle = await runtime.ensureSession({
+      sessionKey: `discover-${agent}-${uid}`,
+      agent,
+      mode: "oneshot",
+      cwd: effectiveCwd,
+    });
+
+    const status = await runtime.getStatus({ handle });
+    const modelIds: string[] = status.models?.availableModelIds || [];
+
+    return modelIds.map((modelId: string) => ({
+      id: `${agent}:${modelId}`,
+      name: `${displayName(modelId)} (${agent})`,
+      provider: `acpx-${agent}`,
+    }));
+  } catch (err) {
+    fileLog("acpx-provider", "debug", "acpx-provider", `model discovery failed for ${agent}:`, err);
+    return [];
+  } finally {
+    if (handle) {
+      await runtime.close({ handle, reason: "discovery complete" }).catch((err: any) => {
+        fileLog("acpx-provider", "debug", "acpx-provider", "failed to close discovery session:", err);
+      });
+    }
+    await rm(stateDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * No-op extension entry point.
+ *
+ * Registration is now handled by the unified provider extension at
+ * `extensions/providers/index.ts`. This default export exists only so
+ * pi's extension loader does not throw when loading this directory.
+ */
+export default async function (_pi: unknown) {
+  // Intentional no-op — registration moved to extensions/providers/index.ts
+}

package/extensions/acpx-provider/load-runtime.ts

@@ -0,0 +1,99 @@
+/**
+ * Load acpx/runtime: prefer a global `npm install -g acpx`, then fall back to the
+ * package-local `acpx` dependency (required for plain `pi` / ~/.pi package installs).
+ */
+
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+
+/** Minimal surface used by acpx-provider. */
+export type AcpxRuntimeModule = {
+  createAcpRuntime: (...args: any[]) => any;
+  createFileSessionStore: (...args: any[]) => any;
+  createAgentRegistry: (...args: any[]) => any;
+};
+
+let cachedRoots: string[] | null = null;
+let cachedRuntime: Promise<AcpxRuntimeModule> | null = null;
+
+function globalNodeModuleRoots(): string[] {
+  if (cachedRoots) return cachedRoots;
+  const roots: string[] = [];
+  try {
+    const root = execFileSync("npm", ["root", "-g"], {
+      encoding: "utf-8",
+      timeout: 15_000,
+    }).trim();
+    if (root) roots.push(root);
+  } catch {
+    /* ignore */
+  }
+  for (const candidate of [
+    "/usr/local/lib/node_modules",
+    join(homedir(), ".npm-global", "lib", "node_modules"),
+  ]) {
+    if (candidate && !roots.includes(candidate)) roots.push(candidate);
+  }
+  cachedRoots = roots;
+  return roots;
+}
+
+async function importFromPackageRoot(pkgRoot: string): Promise<AcpxRuntimeModule | null> {
+  const runtimeJs = join(pkgRoot, "dist", "runtime.js");
+  if (existsSync(runtimeJs)) {
+    return (await import(pathToFileURL(runtimeJs).href)) as AcpxRuntimeModule;
+  }
+  const pkgJson = join(pkgRoot, "package.json");
+  if (!existsSync(pkgJson)) return null;
+  try {
+    const req = createRequire(pkgJson);
+    const resolved = req.resolve("./dist/runtime.js");
+    return (await import(pathToFileURL(resolved).href)) as AcpxRuntimeModule;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveAcpxRuntime(): Promise<AcpxRuntimeModule> {
+  for (const root of globalNodeModuleRoots()) {
+    const mod = await importFromPackageRoot(join(root, "acpx"));
+    if (typeof mod?.createAcpRuntime === "function") return mod;
+  }
+
+  try {
+    const mod = (await import("acpx/runtime")) as AcpxRuntimeModule;
+    if (typeof mod?.createAcpRuntime === "function") return mod;
+  } catch {
+    /* ignore */
+  }
+
+  throw new Error(
+    "acpx/runtime not found. Install with: npm install -g acpx " +
+      "(or ensure the pi-config package dependency `acpx` is installed)",
+  );
+}
+
+/**
+ * Resolve acpx/runtime: global install first, then package dependency import.
+ * Memoized — concurrent/repeated calls share one resolution. Rejected loads
+ * clear the cache so a later install can succeed.
+ */
+export function loadAcpxRuntime(): Promise<AcpxRuntimeModule> {
+  if (!cachedRuntime) {
+    cachedRuntime = resolveAcpxRuntime().catch((err) => {
+      cachedRuntime = null;
+      throw err;
+    });
+  }
+  return cachedRuntime;
+}
+
+/** Test helper — clear memoization between cases. */
+export function clearAcpxRuntimeCache(): void {
+  cachedRoots = null;
+  cachedRuntime = null;
+}

package/extensions/acpx-provider/runtime-models.ts

@@ -0,0 +1,40 @@
+/**
+ * Map ACPX discovery results → full createProvider Model[].
+ * Kept separate from index.ts so unit tests do not load runtime/stream code.
+ */
+
+import { buildRuntimeModel } from "../shared/create-runtime-provider.js";
+
+export function modelIdToDisplayName(modelId: string): string {
+	// Strip bracket suffixes for display: gpt-5.4[context=272k,...] -> Gpt 5.4
+	const bracketIdx = modelId.indexOf("[");
+	const baseName = bracketIdx >= 0 ? modelId.substring(0, bracketIdx) : modelId;
+	return baseName
+		.replace(/-/g, " ")
+		.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export function mapAcpxDiscoveredModels(
+	agent: string,
+	modelIds: readonly string[],
+): ReturnType<typeof buildRuntimeModel>[] {
+	const provider = `acpx-${agent}`;
+	if (modelIds.length === 0) {
+		return [
+			buildRuntimeModel({
+				id: `${agent}:default`,
+				name: `${agent} (default)`,
+				api: "acpx",
+				provider,
+			}),
+		];
+	}
+	return modelIds.map((m) =>
+		buildRuntimeModel({
+			id: `${agent}:${m}`,
+			name: `${modelIdToDisplayName(m)} (${agent})`,
+			api: "acpx",
+			provider,
+		}),
+	);
+}

package/extensions/cli-provider/agents/claude.ts

@@ -0,0 +1,128 @@
+/**
+ * Claude Code CLI agent — flags + binary-catalog discovery.
+ */
+
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { cliProviderLog } from "../../shared/file-logger.js";
+import type { CliProviderDef, DiscoveredCliModel } from "../types.js";
+import {
+  cacheKeyForFile,
+  readModelCache,
+  resolveBinary,
+  writeModelCache,
+} from "../shared/discover-cache.js";
+
+/** Catalog entries embedded in the Claude Code binary (minified JS/strings). */
+const CATALOG_RE =
+  /\{id:"(claude-[^"]+)",family:"([^"]+)",display_name:"([^"]+)"/g;
+
+const DEFAULT_CHUNK_SIZE = 8 * 1024 * 1024;
+/** Enough overlap that a catalog match cannot split across chunks. */
+const DEFAULT_OVERLAP = 512;
+
+/** Parse selectable catalog from a string (tests / small fixtures). */
+export function parseClaudeBinaryCatalog(
+  binaryContents: string,
+): DiscoveredCliModel[] {
+  const models: DiscoveredCliModel[] = [];
+  const seen = new Set<string>();
+  CATALOG_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = CATALOG_RE.exec(binaryContents))) {
+    const id = m[1];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    models.push({ id, name: m[3] });
+  }
+  return models;
+}
+
+/**
+ * Scan a Claude binary for the embedded model catalog without loading the
+ * whole file into a JS string (binaries are ~250MB+ ELF).
+ */
+export function scanClaudeBinaryCatalog(
+  filePath: string,
+  opts?: { chunkSize?: number; overlap?: number },
+): DiscoveredCliModel[] {
+  const chunkSize = opts?.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  const overlap = Math.min(opts?.overlap ?? DEFAULT_OVERLAP, chunkSize - 1);
+  const size = statSync(filePath).size;
+  const fd = openSync(filePath, "r");
+  const readBuf = Buffer.alloc(chunkSize);
+  let prev = Buffer.alloc(0);
+  const models: DiscoveredCliModel[] = [];
+  const seen = new Set<string>();
+  let offset = 0;
+
+  try {
+    while (offset < size) {
+      const n = readSync(fd, readBuf, 0, chunkSize, offset);
+      if (n <= 0) break;
+
+      const chunk = Buffer.concat([prev, readBuf.subarray(0, n)]);
+      // latin1 = 1:1 byte mapping; catalog ids are ASCII
+      const text = chunk.toString("latin1");
+      CATALOG_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = CATALOG_RE.exec(text))) {
+        const id = m[1];
+        if (seen.has(id)) continue;
+        seen.add(id);
+        models.push({ id, name: m[3] });
+      }
+
+      prev =
+        overlap > 0
+          ? chunk.subarray(Math.max(0, chunk.length - overlap))
+          : Buffer.alloc(0);
+      offset += n;
+    }
+  } finally {
+    closeSync(fd);
+  }
+
+  return models;
+}
+
+function discoverClaudeModels(): DiscoveredCliModel[] {
+  const binary = resolveBinary("claude");
+  if (!binary) return [];
+  try {
+    const key = cacheKeyForFile("claude", binary);
+    const cached = readModelCache(key);
+    if (cached && cached.length > 0) return cached;
+
+    const models = scanClaudeBinaryCatalog(binary);
+    if (models.length > 0) writeModelCache(key, models);
+    return models;
+  } catch (err) {
+    cliProviderLog("error", "claude: binary catalog failed", err);
+    return [];
+  }
+}
+
+export const claudeProvider: CliProviderDef = {
+  name: "claude",
+  binary: "claude",
+  buildBaseArgs: (model) => {
+    // -p skips workspace trust; stream-json requires --verbose
+    const args = [
+      "-p",
+      "--verbose",
+      "--dangerously-skip-permissions",
+      "--output-format",
+      "stream-json",
+      "--include-partial-messages",
+    ];
+    if (model && model !== "default") {
+      args.unshift("--model", model);
+    }
+    return args;
+  },
+  resumeFlag: "--resume",
+  continueFlags: ["--continue"],
+  outputFormat: "stream-json",
+  promptOnStdin: true,
+  discoverModels: discoverClaudeModels,
+};

package/extensions/cli-provider/agents/cursor.ts

@@ -0,0 +1,84 @@
+/**
+ * Cursor CLI agent — flags, discovery, headless trust/force.
+ *
+ * Model ids from `agent --list-models` (CLI namespace, not acpx).
+ */
+
+import { spawnSync } from "node:child_process";
+import { cliProviderLog } from "../../shared/file-logger.js";
+import type { CliProviderDef, DiscoveredCliModel } from "../types.js";
+import { resolveBinary } from "../shared/discover-cache.js";
+
+/** Strip CSI / OSC ANSI sequences so colored CLI output still parses (#666). */
+export function stripAnsi(text: string): string {
+  return text
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "")
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
+    .replace(/\u001b[@-Z\\-_]/g, "");
+}
+
+/** Parse `agent --list-models` text output. */
+export function parseAgentListModels(stdout: string): DiscoveredCliModel[] {
+  const models: DiscoveredCliModel[] = [];
+  const seen = new Set<string>();
+  for (const line of stripAnsi(stdout).split(/\r?\n/)) {
+    const m = line.match(
+      /^([a-zA-Z0-9][a-zA-Z0-9._\[\]=,:-]*)\s+-\s+(.+?)\s*$/,
+    );
+    if (!m) continue;
+    const id = m[1];
+    const name = m[2].replace(/\s*\(default\)\s*$/i, "").trim();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    models.push({ id, name });
+  }
+  return models;
+}
+
+function discoverCursorModels(): DiscoveredCliModel[] {
+  const binary = resolveBinary("agent");
+  if (!binary) return [];
+
+  const r = spawnSync(binary, ["--list-models"], {
+    encoding: "utf-8",
+    timeout: 25_000,
+    // Prefer plain text; still strip ANSI in parser if CLI ignores NO_COLOR.
+    env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+  });
+  const out = `${r.stdout || ""}\n${r.stderr || ""}`;
+  const models = parseAgentListModels(out);
+  if (models.length === 0) {
+    cliProviderLog(
+      "warn",
+      `cursor: --list-models failed (status=${r.status}): ${out.slice(0, 200)}`,
+    );
+  }
+  return models;
+}
+
+export const cursorProvider: CliProviderDef = {
+  name: "cursor",
+  binary: "agent",
+  buildBaseArgs: (model, cwd) => {
+    // --trust: workspace; --force: auto-approve; stream-partial-output: live tokens
+    const args = [
+      "--print",
+      "--trust",
+      "--force",
+      "--output-format",
+      "stream-json",
+      "--stream-partial-output",
+      "--workspace",
+      cwd,
+    ];
+    if (model && model !== "default") {
+      args.unshift("--model", model);
+    }
+    return args;
+  },
+  resumeFlag: "--resume",
+  continueFlags: ["--continue"],
+  outputFormat: "stream-json",
+  promptOnStdin: true,
+  discoverModels: discoverCursorModels,
+};