@kata-sh/pi-symphony-extension 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @kata-sh/pi-symphony-extension
+
+Pi extension for initializing, launching, attaching to, and monitoring Kata Symphony.
+
+## Local development
+
+```sh
+pnpm --dir apps/symphony/pi-extension test
+pnpm --dir apps/symphony/pi-extension typecheck
+```
+
+Run it locally with `pi -e ./apps/symphony/pi-extension`.
+
+## Commands through Wave 3
+
+- `/symphony:help`
+- `/symphony:init [--force]`
+- `/symphony:doctor [workflow]`
+- `/symphony:start [workflow]`
+- `/symphony:attach [url]`
+- `/symphony:detach`
+- `/symphony:console`
+- `/symphony:status`
+- `/symphony:refresh`
+- `/symphony:steer <ISSUE> <instruction>`
+- `/symphony:stop`
+
+## Console keys through Wave 3
+
+- `↑` / `↓` selects running workers, retry entries, blocked issues, completed issues, and pending escalations.
+- `r` requests an immediate Symphony refresh and reloads state.
+- `s` prompts for a steer instruction when the selected item is a running worker.
+- `e` prompts for a response when the selected item is a pending escalation. Valid JSON is sent as JSON; other input is sent as a string response.
+- `d` toggles selected-item details.
+- `q` or Escape closes the console and leaves Symphony running.
+
+## Progress feedback
+
+Commands that can take a few seconds show Pi-native progress feedback while they run:
+
+- `/symphony:refresh`, `/symphony:attach [url]`, and `/symphony:stop` use inline working text plus the Symphony footer status.
+- `/symphony:start`, `/symphony:init`, and `/symphony:doctor` use a blocking loader panel.
+- Symphony tools emit partial progress updates before returning their final result.
+
+## Slice 1 verification
+
+Verified commands:
+
+```text
+/symphony:help
+/symphony:status
+```
+
+Package checks:
+
+```sh
+pnpm --dir apps/symphony/pi-extension test
+pnpm --dir apps/symphony/pi-extension typecheck
+```
+
+## Wave 3 manual verification
+
+1. Start Pi with the local extension:
+
+   ```sh
+   pi -e ./apps/symphony/pi-extension
+   ```
+
+   Expected: Pi starts with Symphony commands available.
+
+2. Start or attach to a Symphony server:
+
+   Start path:
+
+   ```text
+   /symphony:start .symphony/WORKFLOW.md
+   ```
+
+   Expected: Symphony starts, the console opens, and the status block shows the attached base URL.
+
+   Attach path:
+
+   ```text
+   /symphony:attach http://127.0.0.1:<port>
+   /symphony:console
+   ```
+
+   Expected: attach updates the Symphony attachment, then `/symphony:console` opens the console with the attached base URL in the status block.
+
+3. Create or use a Symphony state with at least one retry entry, blocked issue, completed issue, and pending escalation.
+
+   For deterministic local testing, start the Wave 3 mock server in another terminal:
+
+   ```sh
+   pnpm --dir apps/symphony/pi-extension run mock:wave3
+   ```
+
+   Then attach Pi to the printed URL:
+
+   ```text
+   /symphony:attach http://127.0.0.1:8787
+   /symphony:console
+   ```
+
+   Expected: the console shows `Retry Queue`, `Blocked Issues`, `Completed Issues`, and `Pending Escalations` sections.
+
+4. Use `↑` / `↓` to select each Wave 3 item type.
+
+   Expected: the detail panel shows running, retry, blocked, completed, and escalation-specific fields.
+
+5. Select a pending escalation, press `e`, and enter `{"approved":true}`.
+
+   Expected: Pi reports `Escalation response sent for <request_id>` and the console refreshes.
+
+6. Watch recent events after escalation creation and response.
+
+   Expected with a real or event-capable Symphony server: escalation lifecycle events appear in the `Events` section. The Wave 3 mock server supports state, refresh, steer, and escalation response checks, but it does not expose `/api/v1/events`.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@kata-sh/pi-symphony-extension",
+  "version": "0.1.0",
+  "description": "Pi extension for launching, attaching to, and monitoring Kata Symphony",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "keywords": ["pi-package", "symphony", "kata"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gannonh/kata.git",
+    "directory": "apps/symphony/pi-extension"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": ["src", "scripts", "README.md", "package.json"],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm exec vitest run",
+    "test:watch": "pnpm exec vitest",
+    "mock:wave3": "node scripts/wave3-mock-server.mjs",
+    "lint": "eslint src/ --max-warnings=0"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "ws": "^8.20.1"
+  }
+}

package/scripts/wave3-mock-server.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+
+const options = parseArgs(process.argv.slice(2));
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const state = createInitialState();
+const responses = [];
+
+const server = createServer((req, res) => {
+  let body = "";
+  req.on("data", (chunk) => {
+    body += String(chunk);
+  });
+  req.on("end", () => {
+    handleRequest(req, res, body);
+  });
+});
+
+server.listen(options.port, options.host, () => {
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("Expected TCP server address");
+  }
+  const baseUrl = `http://${options.host}:${address.port}`;
+  console.log(`Mock Symphony server: ${baseUrl}`);
+  console.log("");
+  console.log("Attach from Pi:");
+  console.log(`/symphony:attach ${baseUrl}`);
+  console.log("/symphony:console");
+  console.log("");
+  console.log("Seeded state: running SIM-123, retry SIM-200, blocked SIM-300, completed SIM-400, escalation esc-1");
+});
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+function handleRequest(req, res, body) {
+  setJson(res);
+
+  if (req.method === "GET" && req.url === "/api/v1/state") {
+    res.end(JSON.stringify(state));
+    return;
+  }
+
+  if (req.method === "GET" && req.url === "/api/v1/escalations") {
+    res.end(JSON.stringify({ pending: state.pending_escalations }));
+    return;
+  }
+
+  if (req.method === "POST" && req.url === "/api/v1/refresh") {
+    res.statusCode = 202;
+    res.end(JSON.stringify({ queued: true, coalesced: false, pending_requests: 1 }));
+    return;
+  }
+
+  if (req.method === "POST" && req.url === "/api/v1/steer") {
+    const payload = parseJsonBody(body);
+    const instruction = typeof payload?.instruction === "string" ? payload.instruction : "";
+    res.end(JSON.stringify({
+      ok: true,
+      issue_id: "issue-123",
+      issue_identifier: "SIM-123",
+      delivered: true,
+      instruction_preview: instruction.slice(0, 120),
+    }));
+    return;
+  }
+
+  const escalationMatch = req.url?.match(/^\/api\/v1\/escalations\/([^/]+)\/respond$/);
+  if (req.method === "POST" && escalationMatch) {
+    let requestId;
+    try {
+      requestId = decodeURIComponent(escalationMatch[1]);
+    } catch {
+      res.statusCode = 400;
+      res.end(JSON.stringify({ error: "invalid_escalation_id" }));
+      return;
+    }
+    const escalation = state.pending_escalations.find((entry) => entry.request_id === requestId);
+    if (!escalation) {
+      res.statusCode = 404;
+      res.end(JSON.stringify({ error: "escalation_not_found" }));
+      return;
+    }
+
+    responses.push({ request_id: requestId, body: parseJsonBody(body), received_at: new Date().toISOString() });
+    state.pending_escalations = state.pending_escalations.filter((entry) => entry.request_id !== requestId);
+    state.supervisor.escalations_created = state.pending_escalations.length;
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+
+  if (req.method === "GET" && req.url === "/debug/responses") {
+    res.end(JSON.stringify({ responses }));
+    return;
+  }
+
+  res.statusCode = 404;
+  res.end(JSON.stringify({ error: "not_found" }));
+}
+
+function createInitialState() {
+  return {
+    poll_interval_ms: 30000,
+    max_concurrent_agents: 2,
+    tracker_project_url: "https://linear.app/kata-sh/project/symphony",
+    running: {
+      "issue-123": {
+        issue_id: "issue-123",
+        issue_identifier: "SIM-123",
+        issue_title: "Running worker",
+        attempt: 1,
+        workspace_path: "/tmp/symphony/issue-123",
+        started_at: "2026-05-14T12:00:00Z",
+        status: "running",
+        tracker_state: "In Progress",
+        worker_host: "local",
+        model: "test-model",
+        issue_url: "https://linear.app/kata-sh/issue/SIM-123/running-worker",
+      },
+    },
+    running_sessions: {
+      "issue-123": {
+        turn_count: 3,
+        last_activity_at: "2026-05-14T12:04:00Z",
+        total_tokens: 1200,
+        last_event: "tool_call_completed",
+        last_event_message: "running cargo test",
+        session_id: "session-123",
+      },
+    },
+    running_session_info: {
+      "issue-123": {
+        turn_count: 3,
+        max_turns: 20,
+        last_activity_ms: Date.parse("2026-05-14T12:04:00Z"),
+        session_tokens: { input_tokens: 800, output_tokens: 400, total_tokens: 1200 },
+        last_error: null,
+      },
+    },
+    claimed: [],
+    retry_queue: [
+      {
+        issue_id: "issue-retry",
+        identifier: "SIM-200",
+        attempt: 3,
+        due_in_ms: 90000,
+        error: "rate limit",
+        worker_host: "host-b",
+        workspace_path: "/tmp/retry",
+      },
+    ],
+    blocked: [
+      {
+        issue_id: "issue-blocked",
+        identifier: "SIM-300",
+        title: "Blocked work",
+        state: "Todo",
+        blocker_identifiers: ["SIM-100", "SIM-101"],
+      },
+    ],
+    completed: [
+      {
+        issue_id: "issue-done",
+        identifier: "SIM-400",
+        title: "Done work",
+        completed_at: "2026-05-14T13:00:00Z",
+      },
+    ],
+    pending_escalations: [
+      {
+        request_id: "esc-1",
+        issue_id: "issue-123",
+        issue_identifier: "SIM-123",
+        method: "approval",
+        preview: "Approve cargo test?",
+        created_at: "2026-05-14T12:06:00Z",
+        timeout_ms: 600000,
+      },
+    ],
+    shared_context: { total_entries: 0, entries_by_scope: {}, oldest_entry_at: null, newest_entry_at: null },
+    supervisor: { active: true, steers_issued: 0, conflicts_detected: 0, patterns_detected: 0, escalations_created: 1 },
+    codex_totals: { input_tokens: 800, output_tokens: 400, total_tokens: 1200, event_count: 2, seconds_running: 60 },
+    codex_rate_limits: null,
+    polling: { checking: false, next_poll_in_ms: 1000, poll_interval_ms: 30000, poll_count: 1, last_poll_at: "2026-05-14T12:05:00Z" },
+  };
+}
+
+function parseArgs(args) {
+  const parsed = { host: "127.0.0.1", port: 8787, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--") {
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--host") {
+      parsed.host = readValue(args, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--port") {
+      const rawPort = readValue(args, index, arg);
+      const port = Number(rawPort);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid --port value: ${rawPort}`);
+      }
+      parsed.port = port;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return parsed;
+}
+
+function readValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parseJsonBody(body) {
+  if (!body.trim()) return null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return { raw: body };
+  }
+}
+
+function setJson(res) {
+  res.setHeader("content-type", "application/json");
+}
+
+function shutdown() {
+  server.close(() => process.exit(0));
+}
+
+function printHelp() {
+  console.log(`Usage: node apps/symphony/pi-extension/scripts/wave3-mock-server.mjs [--host 127.0.0.1] [--port 8787]\n\nStarts a local mock Symphony HTTP API seeded with Wave 3 dashboard state.\n\nEndpoints:\n  GET  /api/v1/state\n  GET  /api/v1/escalations\n  POST /api/v1/escalations/esc-1/respond\n  POST /api/v1/refresh\n  POST /api/v1/steer\n\nAttach from Pi with /symphony:attach http://127.0.0.1:<port>.`);
+}

package/src/attach-url-policy.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { resolveAttachUrl } from "./attach-url-policy.ts";
+
+const ownedProcess = {
+  pid: 123,
+  command: "symphony --no-tui",
+  cwd: "/repo",
+  baseUrl: "http://127.0.0.1:8080",
+  startedAt: "2026-05-14T00:00:00.000Z",
+};
+
+describe("resolveAttachUrl", () => {
+  it("treats whitespace-only URLs as absent so owned process fallback is preserved", () => {
+    expect(resolveAttachUrl("   ", ownedProcess)).toBe("http://127.0.0.1:8080");
+  });
+
+  it("returns trimmed explicit URLs", () => {
+    expect(resolveAttachUrl(" http://localhost:8080 ", ownedProcess)).toBe("http://localhost:8080");
+  });
+});

package/src/attach-url-policy.ts

@@ -0,0 +1,24 @@
+import { SymphonyExtensionError } from "./errors.ts";
+import type { OwnedProcessMetadata } from "./state.ts";
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+
+export function resolveAttachUrl(url: string | undefined, ownedProcess: OwnedProcessMetadata | undefined): string {
+  const trimmedUrl = url?.trim();
+  if (trimmedUrl) return trimmedUrl;
+  if (ownedProcess?.baseUrl) return ownedProcess.baseUrl;
+  throw new SymphonyExtensionError(
+    "no_attachment",
+    "No Symphony URL provided and no Pi-owned Symphony server is running. Use /symphony:start or /symphony:attach <url>.",
+  );
+}
+
+export function assertLoopbackAttachUrl(url: string): void {
+  const parsed = new URL(url.trim());
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+  if ((parsed.protocol === "http:" || parsed.protocol === "https:") && LOOPBACK_HOSTS.has(hostname)) {
+    return;
+  }
+
+  throw new Error("Symphony attach URL must use http or https on a loopback host: 127.0.0.1, localhost, or ::1");
+}

package/src/binary-resolver.test.ts

@@ -0,0 +1,114 @@
+import { chmod, mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveSymphonyBinary, validateBinaryPath } from "./binary-resolver.ts";
+import { createDefaultState } from "./state.ts";
+
+const symphonyBinaryName = process.platform === "win32" ? "symphony.exe" : "symphony";
+
+async function executable(path: string): Promise<string> {
+  await mkdir(resolve(path, ".."), { recursive: true });
+  await writeFile(path, "#!/bin/sh\necho symphony\n", "utf8");
+  await chmod(path, 0o755);
+  return path;
+}
+
+describe("Symphony binary resolver", () => {
+  it("uses SYMPHONY_BIN first", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-bin-"));
+    const binary = await executable(join(dir, "custom-symphony"));
+    const state = createDefaultState();
+
+    const resolved = await resolveSymphonyBinary({
+      cwd: dir,
+      state,
+      env: { SYMPHONY_BIN: binary, PATH: "" },
+      promptForPath: async () => undefined,
+    });
+
+    expect(resolved).toBe(binary);
+  });
+
+  it("finds repo-local target release binary by walking upward", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-symphony-repo-"));
+    const nested = join(root, "packages", "x");
+    const binary = await executable(join(root, "apps", "symphony", "target", "release", symphonyBinaryName));
+    await mkdir(nested, { recursive: true });
+
+    const resolved = await resolveSymphonyBinary({
+      cwd: nested,
+      state: createDefaultState(),
+      env: { PATH: "" },
+      promptForPath: async () => undefined,
+    });
+
+    expect(resolved).toBe(binary);
+  });
+
+  it("falls back to PATH when SYMPHONY_BIN is invalid", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-fallback-"));
+    const invalid = join(dir, "missing-symphony");
+    const binary = await executable(join(dir, symphonyBinaryName));
+
+    await expect(
+      resolveSymphonyBinary({
+        cwd: dir,
+        state: createDefaultState(),
+        env: { SYMPHONY_BIN: invalid, PATH: dir },
+        promptForPath: async () => undefined,
+      }),
+    ).resolves.toBe(binary);
+  });
+
+  it("uses persisted user path after built-in checks fail", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-persisted-"));
+    const binary = await executable(join(dir, "persisted"));
+    const state = createDefaultState();
+    state.binaryPath = binary;
+
+    await expect(resolveSymphonyBinary({ cwd: dir, state, env: { PATH: "" }, promptForPath: async () => undefined })).resolves.toBe(binary);
+  });
+
+  it("prompts for an absolute path and persists it", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-prompt-"));
+    const binary = await executable(join(dir, "prompted"));
+    const state = createDefaultState();
+
+    const resolved = await resolveSymphonyBinary({
+      cwd: dir,
+      state,
+      env: { PATH: "" },
+      promptForPath: async () => binary,
+    });
+
+    expect(resolved).toBe(binary);
+    expect(state.binaryPath).toBe(binary);
+  });
+
+  it("rejects relative binary paths", async () => {
+    await expect(validateBinaryPath("relative/symphony")).rejects.toThrow("Symphony binary path must be absolute");
+  });
+
+  it("rejects directories", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-dir-"));
+
+    await expect(validateBinaryPath(dir)).rejects.toThrow("Symphony binary path is not a file");
+  });
+
+  it("reports a missing binary when no candidate is valid", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-missing-"));
+
+    await expect(
+      resolveSymphonyBinary({
+        cwd: dir,
+        state: createDefaultState(),
+        env: { PATH: "" },
+        promptForPath: async () => undefined,
+      }),
+    ).rejects.toMatchObject({
+      kind: "missing_binary",
+      message: expect.stringContaining("Could not find Symphony binary"),
+    });
+  });
+});

package/src/binary-resolver.ts

@@ -0,0 +1,115 @@
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { SymphonyExtensionError } from "./errors.ts";
+import type { ExtensionState } from "./state.ts";
+
+export interface ResolveBinaryOptions {
+  cwd: string;
+  state: ExtensionState;
+  env?: NodeJS.ProcessEnv;
+  promptForPath?: () => Promise<string | undefined>;
+}
+
+export async function resolveSymphonyBinary(options: ResolveBinaryOptions): Promise<string> {
+  const env = options.env ?? process.env;
+  const candidates: string[] = [];
+
+  if (env.SYMPHONY_BIN) candidates.push(env.SYMPHONY_BIN);
+
+  const repoLocal = await findRepoLocalBinary(options.cwd);
+  if (repoLocal) candidates.push(repoLocal);
+
+  const pathBinary = await findOnPath("symphony", env);
+  if (pathBinary) candidates.push(pathBinary);
+
+  if (options.state.binaryPath) candidates.push(options.state.binaryPath);
+
+  for (const candidate of candidates) {
+    try {
+      return await validateBinaryPath(candidate);
+    } catch {
+      continue;
+    }
+  }
+
+  const prompted = await options.promptForPath?.();
+  if (prompted) {
+    const validated = await validateBinaryPath(prompted);
+    options.state.binaryPath = validated;
+    return validated;
+  }
+
+  throw new SymphonyExtensionError(
+    "missing_binary",
+    "Could not find Symphony binary. Set SYMPHONY_BIN, build apps/symphony/target/release/symphony, add symphony to PATH, or provide an absolute path.",
+  );
+}
+
+export async function validateBinaryPath(path: string): Promise<string> {
+  if (!isAbsolute(path)) {
+    throw new SymphonyExtensionError("invalid_binary", "Symphony binary path must be absolute", { path });
+  }
+  let isFile: boolean;
+  try {
+    isFile = (await stat(path)).isFile();
+  } catch (error) {
+    throw new SymphonyExtensionError("invalid_binary", "Symphony binary path is not executable", {
+      path,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  if (!isFile) {
+    throw new SymphonyExtensionError("invalid_binary", "Symphony binary path is not a file", { path });
+  }
+  try {
+    await access(path, constants.X_OK);
+  } catch (error) {
+    throw new SymphonyExtensionError("invalid_binary", "Symphony binary path is not executable", {
+      path,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return path;
+}
+
+async function findRepoLocalBinary(cwd: string): Promise<string | undefined> {
+  let current = cwd;
+  while (true) {
+    const candidate = join(current, "apps", "symphony", "target", "release", process.platform === "win32" ? "symphony.exe" : "symphony");
+    try {
+      await validateBinaryPath(candidate);
+      return candidate;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return undefined;
+      current = parent;
+    }
+  }
+}
+
+async function findOnPath(command: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  const commandNames = pathCommandNames(command, env);
+  for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    for (const commandName of commandNames) {
+      const candidate = join(dir, commandName);
+      try {
+        await validateBinaryPath(candidate);
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return undefined;
+}
+
+function pathCommandNames(command: string, env: NodeJS.ProcessEnv): string[] {
+  if (process.platform !== "win32") return [command];
+
+  const extensions = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .filter(Boolean)
+    .map((extension) => (extension.startsWith(".") ? extension : `.${extension}`));
+  return [command, ...extensions.map((extension) => `${command}${extension}`)];
+}