pi-cockpit 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# pi-cockpit
+
+A list-mode **agent cockpit** for [Pi](https://pi.dev): a status stack pinned **above the editor** showing live teammates and the current todo plan, plus a Starship-style footer. Everything is drawn through Pi's public extension APIs only (`setWidget` / `setFooter`) — no core patches.
+
+```
+ ┌─ AGENTS · 2 running ─────────────────────────────┐   ← setWidget(aboveEditor)
+ │ ⠋ explorer  #a1f3c2  map auth   read routes.ts   │
+ │ ⠋ explorer  #b9e014  trace jwt  read jwt.ts      │
+ ├─ TODO · 1/4 ─────────────────────────────────────┤
+ │ 01 ✓ map auth entrypoints                        │
+ │ 02 ⠋ trace jwt verify                            │
+ │ 03 · implement refresh                           │
+ │ 04 · add tests                                   │
+ └──────────────────────────────────────────────────┘
+ >  dispatch a goal…                                  ← editor (Pi native)
+ pi/stream-70b · ctx [████░░░░] 42% · $0.52 · 01:23   ← setFooter
+```
+
+## Install
+
+```bash
+pi install <path-or-spec>     # or, for one run:
+pi -e ./extensions/pi-cockpit
+```
+
+## What it shows
+
+- **AGENTS** — every running teammate as a table row (status spinner · role · id · label · live tail), sorted running-first. Collapses to a one-line `N agents running` summary in compact mode.
+- **TODO** — the active plan as numbered rows with four states (done ✓ / in-progress spinner / blocked ! / pending ·). Collapses to a segmented progress bar + current step + percent.
+- **Footer** — `provider/model · context gauge · ↑in ↓out · $cost · elapsed · git branch`.
+
+Toggle each block between list and compact with `/cockpit`.
+
+## Data sources (and the dependency this implies)
+
+| Block | Source | Available on bare Pi? |
+|-------|--------|------------------------|
+| AGENTS | `pi.events` channels `teammate:started` / `teammate:message` / `teammate:complete`, broadcast by **pi-maestro-teammate** | **No** — without that extension no events fire, the block stays hidden |
+| TODO | the `todo-state` snapshot the **pi-maestro-flow** `todo` tool persists after every mutation (re-read on each `tool_execution_end` and on `session_start`) | **No** — without the `todo` tool the block stays hidden |
+| Footer | `ctx.model`, `ctx.getContextUsage()`, session usage totals, `footerData.getGitBranch()` | **Yes** |
+
+So on a stock Pi (no teammate / no todo tool) the extension loads without error, the status stack renders nothing, and only the footer appears. The roster is **self-accumulated from event deltas** — teammates already running before the extension loads are not back-filled (the teammate extension broadcasts deltas, never a full roster). The todo list **is** back-filled on `session_start` from the persisted snapshot.
+
+## Configuration
+
+`~/.pi/agent/cockpit.json` (created on first run):
+
+```json
+{
+  "enabled": true,
+  "agentsMode": "list",
+  "todoMode": "list",
+  "hideNativeAgents": false
+}
+```
+
+- `agentsMode` / `todoMode`: `"list"` or `"compact"`.
+- `hideNativeAgents`: when `true`, clears the teammate extension's own `teammate-agents` widget (it draws a similar list *below* the editor) so the two don't duplicate. Off by default — the two widgets use different keys and placements and can coexist.
+
+## Command
+
+`/cockpit` opens an overlay to toggle `enabled`, `agentsMode`, `todoMode`, and `hideNativeAgents` (`e` / `a` / `t` / `n`, `Esc` to close). Changes persist immediately.
+
+## Terminal feasibility — what this design deliberately does NOT do
+
+The original mockup was a browser page; a terminal is an ANSI stream with no DOM, no CSS, no focus, no hover. Four mockup effects are **out of scope** here, with replacements:
+
+| Mockup effect | Why it can't work in a TUI | Replacement |
+|---------------|----------------------------|-------------|
+| Input-focus "power-up" glow (`:has(:focus)`) | no focus pseudo-class; `render(width)` can't see focus | the stack's header dot turns accent-green while an agent is running |
+| Hover-to-expand chips/rows | no hover in a terminal | list mode shows everything; compact mode is one line; `/cockpit` toggles |
+| Scanlines / logo light-up animation | no overlay/animation layer | a braille spinner frame, advanced on each redraw |
+| In-stream thinking-collapse / edit progress bar / colored bash stdout | built-in message & built-in tool rendering is **not** replaceable by extensions (`renderCall`/`renderResult` only apply to tools *you* register) | the conversation stream is left to Pi's native renderer — it is context, not a cockpit deliverable |
+
+## Local development
+
+```bash
+cd extensions/pi-cockpit
+node --test --experimental-transform-types tests/agents-store.test.ts tests/todo-store.test.ts tests/render.test.ts tests/footer.test.ts
+../../node_modules/.bin/tsc -p tsconfig.json     # type-check (uses the monorepo root's tsc + types)
+```
+
+The package lives inside the `pi-maestro-flow` tree so it resolves `@earendil-works/*` types from the root `node_modules`, but it is **not** part of the `packages/*` workspace — it neither pollutes the lockfile nor gets swept by monorepo builds.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pi-cockpit",
+  "version": "0.1.0",
+  "description": "Agent cockpit for Pi: a list-mode status stack (live teammates + todo plan) pinned above the editor, plus a Starship-style footer. Renders only via public extension APIs (setWidget/setFooter).",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "tui",
+    "teammate",
+    "todo"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "themes/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-transform-types tests/agents-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/settings-view.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "pi-maestro-teammate": "^0.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "pi-maestro-teammate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.82.1",
+    "@earendil-works/pi-ai": "0.82.1",
+    "@earendil-works/pi-coding-agent": "0.82.1",
+    "@earendil-works/pi-tui": "0.82.1",
+    "@types/node": "^22.0.0",
+    "pi-maestro-teammate": "0.6.0",
+    "typescript": "^5.5.0"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./src/*": "./src/*"
+  }
+}

package/src/agents-store.ts

@@ -0,0 +1,270 @@
+import type { TeammateCompleteEvent } from "pi-maestro-teammate/v1/events";
+import { sanitizeExtensionStatusText } from "./extension-status.ts";
+import type { AgentRow, AgentStatus } from "./types.ts";
+
+const TAIL_MAX = 48;
+
+// Every string here originates in an LLM-authored teammate event. A raw newline
+// would split one widget row into several physical terminal rows and a raw escape
+// (e.g. ESC[2J) would clear or recolor the whole screen — and neither is caught by
+// width checks, because both measure as zero columns. Sanitize on ingest so no
+// renderer has to remember to.
+function clean(raw: string | undefined): string {
+	return raw === undefined ? "" : sanitizeExtensionStatusText(raw);
+}
+
+function truncateTail(raw: string): string {
+	const flat = clean(raw);
+	if (flat.length === 0) return "";
+	return flat.length > TAIL_MAX ? flat.slice(0, TAIL_MAX - 1) + "…" : flat;
+}
+
+// Shapes mirror what pi-maestro-teammate emits on pi.events (teammate/.../index.ts:378/1636/3420).
+export interface StartedPayload {
+	correlationId: string;
+	agent: string;
+	name?: string;
+	spawnedBy?: string;
+	startedAt?: number | string;
+	lastActivityAt?: number | string;
+	status?: string;
+}
+export interface ProgressPayload {
+	agent: string;
+	name?: string;
+	correlationId: string;
+	taskIndex: number;
+	dependencies?: number[];
+	status?: string;
+	startedAt?: number | string;
+	lastActivityAt?: number | string;
+	recentTools?: Array<string | { name?: string; status?: string }>;
+	toolCount?: number;
+	tokens?: number;
+	lastMessage?: string;
+}
+export interface MessagePayload {
+	correlationId: string;
+	taskCorrelationId?: string;
+	taskIndex?: number;
+	dependencies?: number[];
+	message?: string;
+	lastMessage?: string;
+	recentTools?: Array<string | { name?: string; status?: string }>;
+	toolCount?: number;
+	tokens?: number;
+	status?: string;
+	lastActivityAt?: number | string;
+	progress?: ProgressPayload[];
+}
+export type CompletePayload = Pick<TeammateCompleteEvent, "correlationId" | "exitCode">;
+
+/**
+ * How long a failed agent stays on screen after it completes.
+ *
+ * Long enough to read the role and the tail that explains it; short enough that
+ * the panel still empties itself without the user clearing anything.
+ */
+export const FAILED_LINGER_MS = 30_000;
+
+function deriveRole(agent: string | undefined, name: string | undefined): string {
+	if (agent && !agent.startsWith("graph(")) return clean(agent);
+	return clean(name) || "agent";
+}
+
+export function mapAgentStatus(status: unknown): AgentStatus {
+	switch (status) {
+		case "pending":
+			return "pending";
+		case "retrying":
+			return "retrying";
+		case "sleeping":
+			return "sleeping";
+		case "completed":
+		case "complete":
+		case "done":
+			return "done";
+		case "failed":
+			return "failed";
+		case "running":
+		default:
+			return "running";
+	}
+}
+
+function normalizeStartedAt(value: number | string | undefined, fallback: number): number {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Date.parse(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+
+function latestTool(tools: MessagePayload["recentTools"]): string | undefined {
+	if (!tools?.length) return undefined;
+	const tool = tools.find((candidate) => typeof candidate === "object" && candidate?.status === "running")
+		?? tools.at(-1);
+	if (!tool) return undefined;
+	if (typeof tool === "string") return truncateTail(tool);
+	const name = tool?.name?.trim();
+	if (!name) return undefined;
+	const status = tool.status?.trim();
+	return truncateTail(status && status !== "completed" ? `${name} (${status})` : name);
+}
+
+// Self-accumulating roster. The teammate extension only broadcasts deltas
+// (started/message/complete), never a full snapshot, so we rebuild the list here.
+// Cold start is empty by design — we only reflect activity observed after load.
+export class AgentsStore {
+	private readonly roster = new Map<string, AgentRow>();
+
+	applyStarted(p: StartedPayload, now: number = Date.now()): void {
+		const id = p.correlationId;
+		const prev = this.roster.get(id);
+		this.roster.set(id, {
+			...prev,
+			correlationId: id,
+			agent: clean(p.agent) || prev?.agent || "",
+			name: p.name === undefined ? prev?.name : clean(p.name),
+			role: deriveRole(p.agent, p.name),
+			task: prev?.task ?? clean(p.name),
+			status: p.status === undefined ? prev?.status ?? "running" : mapAgentStatus(p.status),
+			tail: prev?.tail ?? "",
+			startedAt: prev?.startedAt ?? normalizeStartedAt(p.startedAt, now),
+			lastActivityAt: normalizeStartedAt(p.lastActivityAt, now),
+			...(p.spawnedBy && p.spawnedBy !== id
+				? { parentCorrelationId: p.spawnedBy }
+				: prev?.parentCorrelationId
+					? { parentCorrelationId: prev.parentCorrelationId }
+					: {}),
+		});
+	}
+
+	applyMessage(p: MessagePayload, now = Date.now()): void {
+		if (p.progress) {
+			for (const progress of p.progress) this.applyProgress(p.correlationId, progress, now);
+		}
+		const targetId = p.taskCorrelationId ?? p.correlationId;
+		const row = this.roster.get(targetId);
+		if (!row) return;
+		const progressActivity = p.progress?.find((progress) => progress.correlationId === targetId)?.lastActivityAt;
+		row.lastActivityAt = normalizeStartedAt(p.lastActivityAt ?? progressActivity, now);
+		const tail = p.message ?? p.lastMessage;
+		if (typeof tail === "string" && tail.length > 0) row.tail = truncateTail(tail);
+		if (p.recentTools) {
+			const tool = latestTool(p.recentTools);
+			if (tool) row.activeTool = tool;
+			else delete row.activeTool;
+		}
+		if (typeof p.toolCount === "number") row.toolCount = p.toolCount;
+		if (typeof p.tokens === "number") row.tokens = p.tokens;
+		if (typeof p.status === "string") {
+			row.taskStatus = p.status;
+			row.status = mapAgentStatus(p.status);
+		}
+		if (typeof p.taskIndex === "number") row.taskIndex = p.taskIndex;
+		if (Array.isArray(p.dependencies)) row.dependencies = [...p.dependencies];
+	}
+
+	applyComplete(p: CompletePayload, now = Date.now()): void {
+		const pending = [p.correlationId];
+		const visited = new Set<string>();
+		while (pending.length > 0) {
+			const id = pending.pop()!;
+			if (visited.has(id)) continue;
+			visited.add(id);
+			for (const row of this.roster.values()) {
+				if (row.parentCorrelationId === id) pending.push(row.correlationId);
+			}
+			// A failed agent used to be deleted the moment its result arrived, so the
+			// only evidence of the failure disappeared in the same frame it appeared.
+			// Successes still vanish immediately — the work has simply moved on.
+			const row = this.roster.get(id);
+			const failedByExitCode = id === p.correlationId
+				&& Number.isFinite(p.exitCode)
+				&& p.exitCode !== 0;
+			if (row && (row.status === "failed" || failedByExitCode)) {
+				row.status = "failed";
+				row.taskStatus = "failed";
+				row.failedAt = now;
+				row.lastActivityAt = now;
+				delete row.activeTool;
+			} else {
+				this.roster.delete(id);
+			}
+		}
+	}
+
+	/** Drop failed rows that have had their time on screen. Returns true if any went. */
+	prune(now = Date.now()): boolean {
+		let changed = false;
+		for (const [id, row] of this.roster) {
+			if (row.failedAt !== undefined && now - row.failedAt >= FAILED_LINGER_MS) {
+				this.roster.delete(id);
+				changed = true;
+			}
+		}
+		return changed;
+	}
+
+	/** True while a failed row is still counting down, so the redraw loop must run. */
+	hasLingering(): boolean {
+		for (const row of this.roster.values()) {
+			if (row.failedAt !== undefined) return true;
+		}
+		return false;
+	}
+
+	private applyProgress(parentCorrelationId: string, p: ProgressPayload, now: number): void {
+		const row = this.roster.get(p.correlationId);
+		if (!row) return;
+		row.parentCorrelationId = parentCorrelationId === p.correlationId
+			? row.parentCorrelationId
+			: parentCorrelationId;
+		row.agent = clean(p.agent) || row.agent;
+		row.name = p.name === undefined ? row.name : clean(p.name);
+		row.role = deriveRole(p.agent, p.name);
+		row.task = p.name === undefined ? row.task : clean(p.name);
+		if (typeof p.status === "string") {
+			row.taskStatus = p.status;
+			row.status = mapAgentStatus(p.status);
+		}
+		row.taskIndex = p.taskIndex;
+		row.dependencies = Array.isArray(p.dependencies) ? [...p.dependencies] : [];
+		if (p.startedAt !== undefined) row.startedAt = normalizeStartedAt(p.startedAt, row.startedAt);
+		row.lastActivityAt = normalizeStartedAt(p.lastActivityAt, now);
+		if (p.recentTools) {
+			const tool = latestTool(p.recentTools);
+			if (tool) row.activeTool = tool;
+			else delete row.activeTool;
+		}
+		if (typeof p.toolCount === "number") row.toolCount = p.toolCount;
+		if (typeof p.tokens === "number") row.tokens = p.tokens;
+		if (typeof p.lastMessage === "string" && p.lastMessage.length > 0) {
+			row.tail = truncateTail(p.lastMessage);
+		}
+	}
+
+	snapshot(now = Date.now()): AgentRow[] {
+		// Expiry is driven by reads rather than a dedicated timer: the panel is
+		// already redrawn while anything is lingering, and nothing else has to know.
+		this.prune(now);
+		return [...this.roster.values()].sort((a, b) => {
+			const activity = b.lastActivityAt - a.lastActivityAt;
+			return activity || a.correlationId.localeCompare(b.correlationId);
+		});
+	}
+
+	get size(): number {
+		return this.roster.size;
+	}
+
+	has(correlationId: string): boolean {
+		return this.roster.has(correlationId);
+	}
+
+	clear(): void {
+		this.roster.clear();
+	}
+}

package/src/ambient.ts

@@ -0,0 +1,72 @@
+// Ambient surfaces: the streaming working line, the terminal tab title, and the
+// footer status slot.
+//
+// Cockpit already knows the in-progress task, the live agent roster and the
+// background jobs, but it only ever painted them into its own widgets. Meanwhile
+// the host's streaming loader said "Working…", the tab title said nothing, and a
+// config error scrolled away as a one-shot toast. These are pure composers for
+// those three surfaces — they add information without costing a single row.
+
+import type { AgentRow, BashBgJob, TodoItem } from "./types.ts";
+
+export interface AmbientState {
+	todos: readonly TodoItem[];
+	agents: readonly AgentRow[];
+	jobs: readonly BashBgJob[];
+	running: boolean;
+	cwd?: string;
+	activeTool?: string;
+}
+
+function liveAgents(agents: readonly AgentRow[]): AgentRow[] {
+	return agents.filter((a) => a.status === "running" || a.status === "retrying");
+}
+
+function failedAgents(agents: readonly AgentRow[]): AgentRow[] {
+	return agents.filter((a) => a.status === "failed");
+}
+
+function failedJobs(jobs: readonly BashBgJob[]): BashBgJob[] {
+	return jobs.filter((job) => job.status === "failed" || (job.exitCode !== null && job.exitCode !== 0));
+}
+
+/**
+ * The streaming loader line.
+ *
+ * Keep the host's default "Working" label, elapsed time and interrupt hint.
+ * Only replace the label while a foreground tool is actively executing.
+ */
+export function workingMessage(state: AmbientState): string | undefined {
+	return state.activeTool;
+}
+
+/**
+ * The terminal tab title.
+ *
+ * A developer with several tabs open cannot otherwise tell which run finished and
+ * which one needs them. Failure outranks progress, because that is the state that
+ * actually requires a human.
+ */
+export function titleFor(state: AmbientState, marks: { ok: string; fail: string }): string {
+	const base = state.cwd ? `pi · ${state.cwd}` : "pi";
+	const broken = failedAgents(state.agents).length + failedJobs(state.jobs).length;
+	if (broken > 0) return `${marks.fail} ${base} · ${broken} failed`;
+	if (state.running) {
+		const live = liveAgents(state.agents).length;
+		return live > 0 ? `${base} · ${live} agents` : `${base} · working`;
+	}
+	const jobs = state.jobs.filter((job) => job.status === "running").length;
+	if (jobs > 0) return `${base} · ${jobs} bg`;
+	return base;
+}
+
+/**
+ * The footer status slot.
+ *
+ * Reserved for conditions that must persist rather than scroll away — a config
+ * that failed to load is the motivating case, since the session then silently
+ * runs on defaults.
+ */
+export function statusText(problem: string | undefined, mark: string): string | undefined {
+	return problem ? `${mark} cockpit: ${problem}` : undefined;
+}