@kata-sh/pi-symphony-extension 0.1.2 → 2.3.1

package/README.md

@@ -1,6 +1,8 @@
 # @kata-sh/pi-symphony-extension
 
-Pi extension for initializing, launching, attaching to, and monitoring Kata Symphony.
+Pi extension for initializing, launching, attaching to, and monitoring Kata Symphony from Pi Coding Agent. It adds `/symphony:*` commands plus a live console for active workers, retry queue entries, blocked issues, completed issues, and pending escalations.
+
+![Symphony console in Pi Coding Agent](assets/symphony-console.png)
 
 ## Requirements
 
@@ -40,6 +42,49 @@ pnpm --dir apps/symphony/pi-extension typecheck
 
 Run it locally with `pi -e ./apps/symphony/pi-extension`.
 
+## Screenshot demo with mock data
+
+Use the mock server to show an active Symphony session without tracker credentials or real workers.
+
+1. Start the seeded mock Symphony API:
+
+   ```sh
+   pnpm --dir apps/symphony/pi-extension run mock:wave3
+   ```
+
+   If port `8787` is already in use, choose another port:
+
+   ```sh
+   pnpm --dir apps/symphony/pi-extension run mock:wave3 -- --port 8788
+   ```
+
+   Expected output includes:
+
+   ```text
+   Mock Symphony server: http://127.0.0.1:8787
+   /symphony:attach http://127.0.0.1:8787
+   /symphony:console
+   ```
+
+   Use the printed port in the attach command when you override `--port`.
+
+2. Start Pi with the local extension:
+
+   ```sh
+   pi -e ./apps/symphony/pi-extension
+   ```
+
+3. In Pi, run:
+
+   ```text
+   /symphony:attach http://127.0.0.1:8787
+   /symphony:console
+   ```
+
+4. Use `↑` / `↓` to select the running worker, retry queue, blocked issue, completed issue, or pending escalation. Capture the screenshot when the console shows the seeded `SIM-*` items.
+
+   Suggested screenshot path for this README: `apps/symphony/pi-extension/assets/symphony-console.png`.
+
 ## Commands through Wave 3
 
 - `/symphony:help`

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@kata-sh/pi-symphony-extension",
-  "version": "0.1.2",
+  "version": "2.3.1",
   "description": "Pi extension for launching, attaching to, and monitoring Kata Symphony",
   "license": "MIT",
   "private": false,
   "type": "module",
-  "keywords": ["pi-package", "symphony", "kata"],
+  "keywords": [
+    "pi-package",
+    "symphony",
+    "kata"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gannonh/kata.git",
@@ -15,7 +19,12 @@
     ".": "./src/index.ts",
     "./package.json": "./package.json"
   },
-  "files": ["src", "scripts", "README.md", "package.json"],
+  "files": [
+    "src",
+    "scripts",
+    "README.md",
+    "package.json"
+  ],
   "scripts": {
     "build": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
@@ -25,7 +34,9 @@
     "lint": "eslint src/ --max-warnings=0"
   },
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": [
+      "./src/index.ts"
+    ]
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/scripts/wave3-mock-server.mjs

@@ -20,6 +20,16 @@ const server = createServer((req, res) => {
   });
 });
 
+server.on("error", (error) => {
+  if (error?.code === "EADDRINUSE") {
+    console.error(`Port ${options.port} is already in use on ${options.host}.`);
+    console.error("Try another port, for example:");
+    console.error("pnpm --dir apps/symphony/pi-extension run mock:wave3 -- --port 8788");
+    process.exit(1);
+  }
+  throw error;
+});
+
 server.listen(options.port, options.host, () => {
   const address = server.address();
   if (!address || typeof address === "string") {

package/src/console-model.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { buildEscalationRows, buildIssueRows, buildWorkerRows, formatEventRows } from "./console-model.ts";
+import { buildEscalationRows, buildIssueRows, buildTriageRows, buildWorkerRows, formatEventRows } from "./console-model.ts";
 import type { SymphonyEventEnvelope, SymphonyStateResponse } from "./http-client.ts";
 
 function stateFixture(): SymphonyStateResponse {
@@ -126,6 +126,50 @@ describe("console model", () => {
     });
   });
 
+  it("includes triage sessions between running and retry rows", () => {
+    const state = stateFixture();
+    state.triage_sessions = [
+      {
+        issue_identifier: "#1",
+        run_id: "run-1",
+        stage_run_id: "stage-1",
+        attempt: 2,
+        harness: "pi",
+        model: "openai-codex/gpt-5.6-luna",
+        started_at: "2026-05-14T12:00:00Z",
+        last_activity_at: "2026-05-14T12:00:05Z",
+        last_event: "tool_execution_start",
+        last_event_message: "running read",
+        current_tool_name: "read",
+        current_tool_args_preview: "README.md",
+        total_tokens: 12,
+      },
+    ];
+
+    const issueRows = buildIssueRows(state);
+    const triageRows = buildTriageRows(state);
+
+    expect(issueRows.map((row) => `${row.kind}:${row.issueIdentifier}`)).toEqual([
+      "running:SIM-123",
+      "running:SIM-777",
+      "triage:#1",
+    ]);
+    expect(triageRows).toEqual([
+      {
+        issueIdentifier: "#1",
+        stageRunId: "stage-1",
+        attempt: "2",
+        harness: "pi",
+        model: "openai-codex/gpt-5.6-luna",
+        status: "triage#2",
+        lastEvent: "tool_execution_start",
+        message: "read: README.md",
+        lastActivity: "2026-05-14T12:00:05Z",
+        tokens: "12",
+      },
+    ]);
+  });
+
   it("rounds retry wait times up to the next second", () => {
     const state = stateFixture();
     state.retry_queue = [

package/src/console-model.ts

@@ -6,6 +6,7 @@ import type {
   RunAttemptResponse,
   SymphonyEventEnvelope,
   SymphonyStateResponse,
+  TriageSessionResponse,
 } from "./http-client.ts";
 
 export interface WorkerRow {
@@ -23,7 +24,7 @@ export interface WorkerRow {
   errorPreview: string;
 }
 
-export type IssueRowKind = "running" | "retry" | "blocked" | "completed";
+export type IssueRowKind = "running" | "triage" | "retry" | "blocked" | "completed";
 
 export interface IssueRow {
   kind: IssueRowKind;
@@ -43,6 +44,19 @@ export interface IssueRow {
   completedAt: string;
 }
 
+export interface TriageRow {
+  issueIdentifier: string;
+  stageRunId: string;
+  attempt: string;
+  harness: string;
+  model: string;
+  status: string;
+  lastEvent: string;
+  message: string;
+  lastActivity: string;
+  tokens: string;
+}
+
 export interface EscalationRow {
   requestId: string;
   issueId: string;
@@ -66,12 +80,31 @@ export function buildIssueRows(state: SymphonyStateResponse | undefined): IssueR
     ...Object.entries(state.running ?? {})
       .map(([issueId, attempt]) => workerToIssueRow(issueId, attempt, state))
       .sort(compareIssueRows),
+    ...(state.triage_sessions ?? []).map(triageToIssueRow).sort(compareIssueRows),
     ...(state.retry_queue ?? []).map(retryToIssueRow).sort(compareIssueRows),
     ...(state.blocked ?? []).map(blockedToIssueRow).sort(compareIssueRows),
     ...(state.completed ?? []).map(completedToIssueRow).sort(compareIssueRows),
   ];
 }
 
+export function buildTriageRows(state: SymphonyStateResponse | undefined): TriageRow[] {
+  return (state?.triage_sessions ?? [])
+    .slice()
+    .sort((left, right) => left.issue_identifier.localeCompare(right.issue_identifier))
+    .map((session) => ({
+      issueIdentifier: session.issue_identifier,
+      stageRunId: session.stage_run_id,
+      attempt: String(session.attempt),
+      harness: session.harness,
+      model: session.model?.trim() || "-",
+      status: `triage#${session.attempt}`,
+      lastEvent: session.last_event?.trim() || "-",
+      message: triageMessage(session),
+      lastActivity: session.last_activity_at ?? session.started_at,
+      tokens: session.total_tokens === undefined ? "-" : String(session.total_tokens),
+    }));
+}
+
 export function buildEscalationRows(state: SymphonyStateResponse | undefined): EscalationRow[] {
   return (state?.pending_escalations ?? [])
     .slice()
@@ -89,12 +122,47 @@ export function buildEscalationRows(state: SymphonyStateResponse | undefined): E
 
 export function formatEventRows(events: SymphonyEventEnvelope[], limit = 8): string[] {
   return events
-    .filter((event) => event.kind === "worker" || event.kind === "runtime" || event.kind.startsWith("escalation_"))
+    .filter(
+      (event) =>
+        event.kind === "worker" ||
+        event.kind === "runtime" ||
+        event.kind === "triage" ||
+        event.kind.startsWith("escalation_") ||
+        event.event.startsWith("triage_"),
+    )
     .slice(-limit)
     .reverse()
     .map((event) => [event.timestamp, event.severity, event.kind, event.issue ?? "-", event.event, eventSummary(event)].filter(Boolean).join(" "));
 }
 
+function triageToIssueRow(session: TriageSessionResponse): IssueRow {
+  return {
+    kind: "triage",
+    issueId: session.stage_run_id,
+    issueIdentifier: session.issue_identifier,
+    title: triageMessage(session),
+    status: `triage#${session.attempt}`,
+    trackerState: "triage",
+    attempt: String(session.attempt),
+    turnCount: "1",
+    maxTurns: "1",
+    lastActivity: session.last_activity_at ?? session.started_at,
+    workerHost: session.harness,
+    workspacePath: session.session_id ?? "-",
+    errorPreview: "-",
+    blockers: "-",
+    completedAt: "-",
+  };
+}
+
+function triageMessage(session: TriageSessionResponse): string {
+  if (session.current_tool_name) {
+    const args = session.current_tool_args_preview?.trim();
+    return args ? `${session.current_tool_name}: ${truncateText(args, 80)}` : session.current_tool_name;
+  }
+  return session.last_event_message?.trim() || session.last_event?.trim() || "running";
+}
+
 function workerToIssueRow(issueId: string, attempt: RunAttemptResponse, state: SymphonyStateResponse | undefined): IssueRow {
   return {
     kind: "running",

package/src/console.ts

@@ -1,6 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import { buildEscalationRows, buildIssueRows, buildWorkerRows, formatEventRows, type EscalationRow, type IssueRow, type WorkerRow } from "./console-model.ts";
+import { buildEscalationRows, buildIssueRows, buildTriageRows, buildWorkerRows, formatEventRows, type EscalationRow, type IssueRow, type TriageRow, type WorkerRow } from "./console-model.ts";
 import { startSymphonyEventStream, type EventStreamHandle } from "./event-stream.ts";
 import type { SymphonyEventEnvelope, SymphonyStateResponse } from "./http-client.ts";
 import type { SymphonyRuntime } from "./runtime.ts";
@@ -124,6 +124,8 @@ export class SymphonyConsoleComponent {
     const escalationRows: EscalationRow[] = buildEscalationRows(symphonyState);
     this.clampSelection(issueRows.length + escalationRows.length);
     const runningRows = issueRows.filter((row) => row.kind === "running");
+    const triageRows = issueRows.filter((row) => row.kind === "triage");
+    const triageDetailRows: TriageRow[] = buildTriageRows(symphonyState);
     const retryRows = issueRows.filter((row) => row.kind === "retry");
     const blockedRows = issueRows.filter((row) => row.kind === "blocked");
     const completedRows = issueRows.filter((row) => row.kind === "completed");
@@ -132,6 +134,10 @@ export class SymphonyConsoleComponent {
     const connection = state.attachedBaseUrl ? color(theme, "success", "attached") : color(theme, "error", "detached");
     const polling = health?.pollingChecking ? color(theme, "warning", "checking") : color(theme, "success", "idle");
     const consoleWidth = Math.max(44, width);
+    const triageOffset = runningRows.length;
+    const retryOffset = triageOffset + triageRows.length;
+    const blockedOffset = retryOffset + retryRows.length;
+    const completedOffset = blockedOffset + blockedRows.length;
     const lines = [
       color(theme, "accent", bold(theme, "Symphony Console")),
       "",
@@ -145,13 +151,14 @@ export class SymphonyConsoleComponent {
       ], consoleWidth, theme),
       "",
       ...boxLines("Worker Summary", [
-        `workers: ${color(theme, "success", `running: ${health?.runningCount ?? workers.length}`)} | ${color(theme, "warning", `retry: ${health?.retryCount ?? retryRows.length}`)} | ${color(theme, "error", `blocked: ${health?.blockedCount ?? blockedRows.length}`)} | ${color(theme, "accent", `completed: ${health?.completedCount ?? completedRows.length}`)}`,
+        `workers: ${color(theme, "success", `running: ${health?.runningCount ?? workers.length}`)} | ${color(theme, "accent", `triage: ${triageRows.length}`)} | ${color(theme, "warning", `retry: ${health?.retryCount ?? retryRows.length}`)} | ${color(theme, "error", `blocked: ${health?.blockedCount ?? blockedRows.length}`)} | ${color(theme, "accent", `completed: ${health?.completedCount ?? completedRows.length}`)}`,
       ], consoleWidth, theme),
       "",
       ...boxLines("Running Workers", renderIssueTable(runningRows, this.selectedIndex, 0, theme), consoleWidth, theme),
-      ...boxLines("Retry Queue", renderIssueTable(retryRows, this.selectedIndex, runningRows.length, theme), consoleWidth, theme),
-      ...boxLines("Blocked Issues", renderIssueTable(blockedRows, this.selectedIndex, runningRows.length + retryRows.length, theme), consoleWidth, theme),
-      ...boxLines("Completed Issues", renderIssueTable(completedRows, this.selectedIndex, runningRows.length + retryRows.length + blockedRows.length, theme), consoleWidth, theme),
+      ...boxLines("Triage", renderTriageTable(triageDetailRows, this.selectedIndex, triageOffset, theme), consoleWidth, theme),
+      ...boxLines("Retry Queue", renderIssueTable(retryRows, this.selectedIndex, retryOffset, theme), consoleWidth, theme),
+      ...boxLines("Blocked Issues", renderIssueTable(blockedRows, this.selectedIndex, blockedOffset, theme), consoleWidth, theme),
+      ...boxLines("Completed Issues", renderIssueTable(completedRows, this.selectedIndex, completedOffset, theme), consoleWidth, theme),
       ...boxLines("Selected Issue", renderSelectedIssueDetails(selectedIssue, state.console.showDetails, theme), consoleWidth, theme),
       ...boxLines("Pending Escalations", renderEscalationTable(escalationRows, this.selectedIndex - issueRows.length, theme), consoleWidth, theme),
       ...boxLines("Selected Escalation", renderSelectedEscalationDetails(escalationRows[this.selectedIndex - issueRows.length], state.console.showDetails, theme), consoleWidth, theme),
@@ -295,6 +302,27 @@ function renderIssueTable(rows: IssueRow[], selectedIndex: number, selectedOffse
   return lines;
 }
 
+function renderTriageTable(rows: TriageRow[], selectedIndex: number, selectedOffset: number, theme?: ConsoleTheme): string[] {
+  const lines = [color(theme, "dim", "sel issue    attempt harness  model                 event            message")];
+  if (rows.length === 0) return [...lines, color(theme, "dim", "-   none")];
+
+  for (const [index, row] of rows.entries()) {
+    const rowIndex = selectedOffset + index;
+    const selected = rowIndex === selectedIndex ? ">" : " ";
+    const line = [
+      selected,
+      pad(row.issueIdentifier, 8),
+      pad(row.attempt, 7),
+      pad(row.harness, 8),
+      pad(row.model, 21),
+      pad(row.lastEvent, 16),
+      row.message,
+    ].join(" ");
+    lines.push(rowIndex === selectedIndex ? selectedLine(theme, line) : line);
+  }
+  return lines;
+}
+
 function renderSelectedIssueDetails(issue: IssueRow | undefined, showDetails: boolean, theme?: ConsoleTheme): string[] {
   if (!showDetails) return [];
   if (!issue) return [color(theme, "dim", "none")];
@@ -315,6 +343,15 @@ function renderSelectedIssueDetails(issue: IssueRow | undefined, showDetails: bo
       `workspace: ${color(theme, "dim", issue.workspacePath)}`,
       `error: ${issue.errorPreview === "-" ? color(theme, "dim", issue.errorPreview) : color(theme, "error", issue.errorPreview)}`,
     );
+  } else if (issue.kind === "triage") {
+    lines.push(
+      `stage: triage`,
+      `attempt: ${issue.attempt}`,
+      `harness: ${issue.workerHost}`,
+      `last activity: ${color(theme, "dim", issue.lastActivity)}`,
+      `session: ${color(theme, "dim", issue.workspacePath)}`,
+      `detail: ${issue.title}`,
+    );
   } else if (issue.kind === "retry") {
     lines.push(
       `attempt: ${issue.attempt}`,

package/src/http-client.ts

@@ -145,6 +145,23 @@ export interface CodexTotalsResponse {
   seconds_running: number;
 }
 
+export interface TriageSessionResponse {
+  issue_identifier: string;
+  run_id: string;
+  stage_run_id: string;
+  attempt: number;
+  harness: string;
+  model?: string | null;
+  started_at: string;
+  last_activity_at?: string | null;
+  last_event?: string | null;
+  last_event_message?: string | null;
+  session_id?: string | null;
+  current_tool_name?: string | null;
+  current_tool_args_preview?: string | null;
+  total_tokens?: number;
+}
+
 export interface SymphonyStateResponse {
   tracker_project_url?: string | null;
   running?: Record<string, RunAttemptResponse>;
@@ -154,6 +171,8 @@ export interface SymphonyStateResponse {
   blocked: BlockedIssueResponse[];
   pending_escalations?: PendingEscalationResponse[];
   completed: CompletedIssueResponse[];
+  /** In-flight A1 triage attempts (optional for older Symphony builds). */
+  triage_sessions?: TriageSessionResponse[];
   polling?: {
     checking?: boolean;
     next_poll_in_ms?: number;
@@ -406,6 +425,7 @@ function validateSymphonyStateResponse(value: unknown, details: Record<string, u
   validateOptionalRecord(value, "running_sessions", details);
   validateOptionalRecord(value, "running_session_info", details);
   validateOptionalArray(value, "claimed", details);
+  validateOptionalTriageSessions(value, details);
   validatePendingEscalations(value, "pending_escalations", details);
   validateSharedContextSummary(value.shared_context, details, "shared_context", throwNonSymphonyState);
   validateSupervisorSnapshot(value.supervisor, details, "supervisor", throwNonSymphonyState);
@@ -748,6 +768,31 @@ function validateOptionalArray(value: Record<string, unknown>, field: string, de
   }
 }
 
+function validateOptionalTriageSessions(value: Record<string, unknown>, details: Record<string, unknown>): void {
+  const fieldValue = value.triage_sessions;
+  if (fieldValue === undefined) return;
+  if (!Array.isArray(fieldValue)) {
+    throwNonSymphonyState(details, "state response field had an invalid shape", {
+      field: "triage_sessions",
+      expected: "array",
+    });
+  }
+  fieldValue.forEach((entry, index) => {
+    if (!isRecord(entry)) {
+      throwNonSymphonyState(details, "state response field had an invalid shape", {
+        field: `triage_sessions.${index}`,
+        expected: "object",
+      });
+    }
+    validateRequiredString(entry, "issue_identifier", details, `triage_sessions.${index}.issue_identifier`);
+    validateRequiredString(entry, "run_id", details, `triage_sessions.${index}.run_id`);
+    validateRequiredString(entry, "stage_run_id", details, `triage_sessions.${index}.stage_run_id`);
+    validateRequiredNumber(entry, "attempt", details, `triage_sessions.${index}.attempt`);
+    validateRequiredString(entry, "harness", details, `triage_sessions.${index}.harness`);
+    validateRequiredString(entry, "started_at", details, `triage_sessions.${index}.started_at`);
+  });
+}
+
 function validateOptionalRecord(value: Record<string, unknown>, field: string, details: Record<string, unknown>, detailField = field): void {
   const fieldValue = value[field];
   if (fieldValue === undefined) return;