@weshipwork/pi-herd 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @weshipwork/pi-herd
+
+Read-only Transcript mirror plumbing for Pi Subagents in Herdr.
+
+This package is the v1 mirror-mode tracer bullet from the project ADRs:
+
+- Subagents still run in the Delegator Pi process.
+- A Delegator-side bridge serves structured mirror events over one Unix socket.
+- `pi-herd-viewer` connects from a Herdr pane and renders a read-only transcript/status stream.
+
+## Viewer
+
+```sh
+pi-herd-viewer --socket /path/to/pi-herd.sock --agent-id <subagent-id>
+```
+
+The current tracer bullet supports:
+
+- a read-only observation-source interface for Subagent snapshots and live updates;
+- a forked `pi-subagents` mirror-service adapter shape;
+- a Delegator-side `MirrorBridge` that forwards those updates to `MirrorServer`;
+- initial snapshots, assistant text deltas, and status updates in the viewer stream.
+- a Pi extension entrypoint that starts a session-scoped mirror runtime when an observation source is installed;
+- Herdr pane launch for `pi-herd-viewer` mirrors.
+
+Full chronological transcripts, tool folding, and scroll/focus keybindings are later slices.
+
+## Pi extension integration
+
+`./extensions/herd.ts` starts only inside Herdr (`HERDR_ENV` and `HERDR_PANE_ID`) and requires a read-only observation source from the forked `pi-subagents` runtime:
+
+```ts
+import { installPiHerdObservationSource } from "@weshipwork/pi-herd/extensions/herd";
+
+installPiHerdObservationSource(source);
+```
+
+The expected fork seam is represented by `PiSubagentsMirrorService` in `src/pi-subagents-observation-source.ts`.

package/bin/pi-herd-viewer.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { streamMirrorEvents } from "../src/mirror-client.js";
+import { renderMirrorEvent } from "../src/viewer-render.js";
+
+interface ViewerArgs {
+	socketPath: string;
+	agentId: string;
+}
+
+function parseArgs(argv: string[]): ViewerArgs {
+	const socketIndex = argv.indexOf("--socket");
+	const agentIndex = argv.indexOf("--agent-id");
+	const socketPath = socketIndex === -1 ? undefined : argv[socketIndex + 1];
+	const agentId = agentIndex === -1 ? undefined : argv[agentIndex + 1];
+	if (!socketPath || !agentId) {
+		throw new Error("Usage: pi-herd-viewer --socket <path> --agent-id <id>");
+	}
+	return { socketPath, agentId };
+}
+
+try {
+	const args = parseArgs(process.argv.slice(2));
+	await streamMirrorEvents(args, (event) => process.stdout.write(renderMirrorEvent(event)));
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`${message}\n`);
+	process.exitCode = 1;
+}

package/extensions/herd.ts

@@ -0,0 +1,76 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HerdrMirrorPaneLauncher } from "../src/herdr-pane-launcher.js";
+import { MirrorRuntime } from "../src/mirror-runtime.js";
+import type { MirrorObservationSource } from "../src/mirror-observation.js";
+import { MirrorServer } from "../src/mirror-server.js";
+import { PiSubagentsObservationSource, type PiSubagentsMirrorService } from "../src/pi-subagents-observation-source.js";
+
+export const PI_HERD_OBSERVATION_SOURCE_KEY = "__piHerdObservationSource";
+export const PI_SUBAGENTS_MIRROR_SERVICE_KEY = "__piSubagentsMirrorService";
+
+export type MirrorObservationSourceResolver = () => MirrorObservationSource | undefined;
+
+export function installPiHerdObservationSource(source: MirrorObservationSource): void {
+	Reflect.set(globalThis, PI_HERD_OBSERVATION_SOURCE_KEY, source);
+}
+
+export function resolveGlobalObservationSource(): MirrorObservationSource | undefined {
+	const directSource = Reflect.get(globalThis, PI_HERD_OBSERVATION_SOURCE_KEY) as unknown;
+	if (isMirrorObservationSource(directSource)) return directSource;
+
+	const piSubagentsService = Reflect.get(globalThis, PI_SUBAGENTS_MIRROR_SERVICE_KEY) as unknown;
+	if (!isPiSubagentsMirrorService(piSubagentsService)) return undefined;
+	return new PiSubagentsObservationSource(piSubagentsService);
+}
+
+export function createPiHerdExtension(resolveSource: MirrorObservationSourceResolver = resolveGlobalObservationSource) {
+	return function piHerdExtension(pi: ExtensionAPI): void {
+		const herdrEnv = process.env.HERDR_ENV;
+		const currentPaneId = process.env.HERDR_PANE_ID;
+		if (!herdrEnv || !currentPaneId) return;
+
+		let runtime: MirrorRuntime | undefined;
+
+		pi.on("session_start", async () => {
+			const source = resolveSource();
+			if (!source || runtime) return;
+			const socketPath = join(tmpdir(), `pi-herd-${process.pid}-${Date.now()}.sock`);
+			const server = new MirrorServer({ socketPath });
+			const launcher = new HerdrMirrorPaneLauncher({ pi, currentPaneId });
+			runtime = new MirrorRuntime({ source, server, launcher, socketPath });
+			await runtime.start();
+		});
+
+		pi.on("session_shutdown", async () => {
+			const activeRuntime = runtime;
+			runtime = undefined;
+			await activeRuntime?.stop();
+		});
+	};
+}
+
+function isMirrorObservationSource(value: unknown): value is MirrorObservationSource {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"listAgents" in value &&
+		"subscribe" in value &&
+		typeof value.listAgents === "function" &&
+		typeof value.subscribe === "function"
+	);
+}
+
+function isPiSubagentsMirrorService(value: unknown): value is PiSubagentsMirrorService {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"listMirrorSnapshots" in value &&
+		"subscribeToMirrorEvents" in value &&
+		typeof value.listMirrorSnapshots === "function" &&
+		typeof value.subscribeToMirrorEvents === "function"
+	);
+}
+
+export default createPiHerdExtension();

package/package.json

@@ -0,0 +1,72 @@
+{
+    "name": "@weshipwork/pi-herd",
+    "version": "0.1.0",
+    "description": "Read-only Herdr transcript mirrors for Pi Subagents.",
+    "license": "MIT",
+    "type": "module",
+    "keywords": [
+        "pi-package",
+        "pi",
+        "pi-coding-agent",
+        "herdr",
+        "subagents",
+        "mirror"
+    ],
+    "pi": {
+        "extensions": [
+            "./extensions/herd.ts"
+        ]
+    },
+    "bin": {
+        "pi-herd-viewer": "./bin/pi-herd-viewer.ts"
+    },
+    "scripts": {
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "test": "node --import tsx --test \"tests/**/*.test.ts\"",
+        "check": "pnpm run typecheck && pnpm test"
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "*",
+        "@weshipwork/pi-subagents": "*"
+    },
+    "peerDependenciesMeta": {
+        "@earendil-works/pi-coding-agent": {
+            "optional": true
+        },
+        "@weshipwork/pi-subagents": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@earendil-works/pi-coding-agent": "^0.79.3",
+        "@weshipwork/pi-subagents": "workspace:*",
+        "@types/node": "^24.10.1",
+        "tsx": "^4.20.6",
+        "typescript": "^5.9.3"
+    },
+    "files": [
+        "src/",
+        "bin/",
+        "extensions/",
+        "README.md",
+        "package.json",
+        "tsconfig.json"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/weshipwork/threeonefour.git",
+        "directory": "packages/pi-herd"
+    },
+    "homepage": "https://github.com/weshipwork/threeonefour/tree/main/packages/pi-herd",
+    "bugs": {
+        "url": "https://github.com/weshipwork/threeonefour/issues"
+    },
+    "author": "brandon@weship.work",
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=22.19.0"
+    },
+    "packageManager": "pnpm@11.6.0"
+}

package/src/herdr-pane-launcher.ts

@@ -0,0 +1,203 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { MirrorAgentSnapshot } from "./mirror-types.js";
+
+export interface PiExecResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+	killed?: boolean;
+}
+
+export interface PiExecutor {
+	exec(command: string, args: readonly string[], options?: { signal?: AbortSignal }): Promise<PiExecResult>;
+}
+
+export interface HerdrMirrorPaneLauncherOptions {
+	pi: PiExecutor;
+	currentPaneId: string;
+	signal?: AbortSignal;
+}
+
+interface HerdrPaneEnvelope {
+	result?: HerdrPaneResult;
+	error?: HerdrErrorResult;
+}
+
+interface HerdrPaneResult {
+	pane?: HerdrPaneInfo;
+}
+
+interface HerdrTabEnvelope {
+	result?: HerdrTabResult;
+	error?: HerdrErrorResult;
+}
+
+interface HerdrTabResult {
+	tab?: HerdrTabInfo;
+	root_pane?: HerdrPaneInfo;
+}
+
+interface HerdrTabInfo {
+	tab_id?: string;
+}
+
+interface HerdrPaneInfo {
+	pane_id?: string;
+}
+
+interface HerdrErrorResult {
+	code?: string;
+	message?: string;
+}
+
+interface CategoryTab {
+	tabId: string;
+	rootPaneId: string;
+	paneIds: string[];
+}
+
+const AGENT_CATEGORY_RULES = [
+	{ pattern: /scout|explore|research|inspect|search|find/i, label: "scouts" },
+	{ pattern: /debug|diagnos|triage|bug|fix/i, label: "debuggers" },
+	{ pattern: /plan|architect|design/i, label: "planners" },
+	{ pattern: /review|audit|security/i, label: "reviewers" },
+	{ pattern: /test|qa|spec/i, label: "testers" },
+	{ pattern: /doc|write|readme/i, label: "documenters" },
+] as const;
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function viewerCommand(socketPath: string, agentId: string): string {
+	const sourceDir = dirname(fileURLToPath(import.meta.url));
+	const packageDir = dirname(sourceDir);
+	const viewerPath = fileURLToPath(new URL("../bin/pi-herd-viewer.ts", import.meta.url));
+	return [
+		"pnpm",
+		"--dir",
+		shellQuote(packageDir),
+		"exec",
+		"tsx",
+		shellQuote(viewerPath),
+		"--socket",
+		shellQuote(socketPath),
+		"--agent-id",
+		shellQuote(agentId),
+	].join(" ");
+}
+
+function parseSplitPaneId(stdout: string): string {
+	let envelope: HerdrPaneEnvelope;
+	try {
+		envelope = JSON.parse(stdout) as HerdrPaneEnvelope;
+	} catch {
+		throw new Error("Failed to parse Herdr pane split response.");
+	}
+	if (envelope.error) {
+		throw new Error(envelope.error.message || envelope.error.code || "Herdr pane split failed.");
+	}
+	const paneId = envelope.result?.pane?.pane_id;
+	if (!paneId) throw new Error("Herdr pane split response did not include a pane id.");
+	return paneId;
+}
+
+function parseCreatedTab(stdout: string): CategoryTab {
+	let envelope: HerdrTabEnvelope;
+	try {
+		envelope = JSON.parse(stdout) as HerdrTabEnvelope;
+	} catch {
+		throw new Error("Failed to parse Herdr tab create response.");
+	}
+	if (envelope.error) {
+		throw new Error(envelope.error.message || envelope.error.code || "Herdr tab create failed.");
+	}
+	const tabId = envelope.result?.tab?.tab_id;
+	const paneId = envelope.result?.root_pane?.pane_id;
+	if (!tabId) throw new Error("Herdr tab create response did not include a tab id.");
+	if (!paneId) throw new Error("Herdr tab create response did not include a root pane id.");
+	return { tabId, rootPaneId: paneId, paneIds: [] };
+}
+
+function normalizeCategoryFallback(type: string): string {
+	const words = type
+		.trim()
+		.toLowerCase()
+		.replaceAll(/[^a-z0-9]+/g, " ")
+		.trim()
+		.split(/\s+/)
+		.filter(Boolean);
+	const base = words.at(-1) ?? "agents";
+	if (base.endsWith("s")) return base;
+	if (base.endsWith("y")) return `${base.slice(0, -1)}ies`;
+	return `${base}s`;
+}
+
+export function agentCategoryLabel(agent: MirrorAgentSnapshot): string {
+	for (const rule of AGENT_CATEGORY_RULES) {
+		if (rule.pattern.test(agent.type)) return rule.label;
+	}
+	for (const rule of AGENT_CATEGORY_RULES) {
+		if (rule.pattern.test(agent.description)) return rule.label;
+	}
+	return normalizeCategoryFallback(agent.type);
+}
+
+export class HerdrMirrorPaneLauncher {
+	private readonly paneIdsByAgentId = new Map<string, string>();
+	private readonly tabsByCategory = new Map<string, CategoryTab>();
+
+	constructor(private readonly options: HerdrMirrorPaneLauncherOptions) {}
+
+	async launch(agent: MirrorAgentSnapshot, socketPath: string): Promise<string> {
+		const existingPaneId = this.paneIdsByAgentId.get(agent.id);
+		if (existingPaneId) return existingPaneId;
+
+		const category = agentCategoryLabel(agent);
+		const categoryTab = await this.getOrCreateCategoryTab(category);
+		const paneId = await this.allocatePane(categoryTab);
+		await this.execHerdr(["pane", "run", paneId, viewerCommand(socketPath, agent.id)]);
+		this.paneIdsByAgentId.set(agent.id, paneId);
+		return paneId;
+	}
+
+	async closeAll(): Promise<void> {
+		const tabIds = [...this.tabsByCategory.values()].map((tab) => tab.tabId);
+		this.paneIdsByAgentId.clear();
+		this.tabsByCategory.clear();
+		await Promise.all(tabIds.map((tabId) => this.execHerdr(["tab", "close", tabId]).catch(() => undefined)));
+	}
+
+	private async getOrCreateCategoryTab(category: string): Promise<CategoryTab> {
+		const existing = this.tabsByCategory.get(category);
+		if (existing) return existing;
+
+		const created = await this.execHerdr(["tab", "create", "--label", `herd: ${category}`, "--no-focus"]);
+		const tab = parseCreatedTab(created.stdout.trim());
+		this.tabsByCategory.set(category, tab);
+		return tab;
+	}
+
+	private async allocatePane(tab: CategoryTab): Promise<string> {
+		if (tab.paneIds.length === 0) {
+			tab.paneIds.push(tab.rootPaneId);
+			return tab.rootPaneId;
+		}
+
+		const split = await this.execHerdr(["pane", "split", tab.rootPaneId, "--direction", "right", "--no-focus"]);
+		const paneId = parseSplitPaneId(split.stdout.trim());
+		tab.paneIds.push(paneId);
+		return paneId;
+	}
+
+	private async execHerdr(args: readonly string[]): Promise<PiExecResult> {
+		const result = await this.options.pi.exec("herdr", args, { signal: this.options.signal });
+		if (this.options.signal?.aborted || result.killed) throw new Error("Aborted");
+		if (result.code !== 0) {
+			const message = result.stderr.trim() || result.stdout.trim() || `herdr ${args.join(" ")} failed with exit code ${result.code}`;
+			throw new Error(message);
+		}
+		return result;
+	}
+}

package/src/mirror-bridge.ts

@@ -0,0 +1,54 @@
+import { MIRROR_EVENT_TYPE, type MirrorEvent } from "./mirror-types.js";
+import type { MirrorObservationEvent, MirrorObservationSource, MirrorObservationUnsubscribe } from "./mirror-observation.js";
+import { MIRROR_OBSERVATION_EVENT_TYPE } from "./mirror-observation.js";
+import type { MirrorServer } from "./mirror-server.js";
+
+export interface MirrorBridgeOptions {
+	source: MirrorObservationSource;
+	server: MirrorServer;
+}
+
+export class MirrorBridge {
+	private unsubscribe: MirrorObservationUnsubscribe | undefined;
+	private sequence = 1;
+	private started = false;
+
+	constructor(private readonly options: MirrorBridgeOptions) {}
+
+	async start(): Promise<void> {
+		if (this.started) return;
+		this.started = true;
+		await this.options.server.start();
+		this.unsubscribe = this.options.source.subscribe((event) => this.handleObservation(event));
+		const agents = await this.options.source.listAgents();
+		for (const agent of agents) {
+			this.options.server.upsertSnapshot(agent);
+		}
+	}
+
+	async stop(): Promise<void> {
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		this.started = false;
+		await this.options.server.stop();
+	}
+
+	private async handleObservation(event: MirrorObservationEvent): Promise<void> {
+		if (event.type === MIRROR_OBSERVATION_EVENT_TYPE.SNAPSHOT) {
+			this.options.server.upsertSnapshot(event.agent);
+			return;
+		}
+		await this.options.server.publish(this.toMirrorEvent(event));
+	}
+
+	private toMirrorEvent(event: Exclude<MirrorObservationEvent, { type: typeof MIRROR_OBSERVATION_EVENT_TYPE.SNAPSHOT }>): MirrorEvent {
+		const sequence = this.sequence;
+		this.sequence += 1;
+		switch (event.type) {
+			case MIRROR_OBSERVATION_EVENT_TYPE.STATUS:
+				return { type: MIRROR_EVENT_TYPE.STATUS, agentId: event.agentId, status: event.status, sequence };
+			case MIRROR_OBSERVATION_EVENT_TYPE.ASSISTANT_TEXT_DELTA:
+				return { type: MIRROR_EVENT_TYPE.ASSISTANT_TEXT_DELTA, agentId: event.agentId, delta: event.delta, sequence };
+		}
+	}
+}

package/src/mirror-client.ts

@@ -0,0 +1,33 @@
+import { connect, type Socket } from "node:net";
+import type { MirrorEvent } from "./mirror-types.js";
+
+export interface MirrorClientOptions {
+	socketPath: string;
+	agentId: string;
+}
+
+export async function streamMirrorEvents(
+	options: MirrorClientOptions,
+	onEvent: (event: MirrorEvent) => void,
+): Promise<Socket> {
+	const socket = connect(options.socketPath);
+	let buffer = "";
+	socket.setEncoding("utf8");
+	socket.on("data", (chunk) => {
+		buffer += chunk;
+		for (;;) {
+			const newline = buffer.indexOf("\n");
+			if (newline === -1) break;
+			const line = buffer.slice(0, newline);
+			buffer = buffer.slice(newline + 1);
+			if (!line.trim()) continue;
+			onEvent(JSON.parse(line) as MirrorEvent);
+		}
+	});
+	await new Promise<void>((resolve, reject) => {
+		socket.once("connect", resolve);
+		socket.once("error", reject);
+	});
+	socket.write(`${JSON.stringify({ agentId: options.agentId })}\n`);
+	return socket;
+}

package/src/mirror-observation.ts

@@ -0,0 +1,40 @@
+import type { MirrorAgentSnapshot, SubagentStatus } from "./mirror-types.js";
+
+export const MIRROR_OBSERVATION_EVENT_TYPE = {
+	SNAPSHOT: "snapshot",
+	STATUS: "status",
+	ASSISTANT_TEXT_DELTA: "assistant_text_delta",
+} as const;
+
+export type MirrorObservationEventType = (typeof MIRROR_OBSERVATION_EVENT_TYPE)[keyof typeof MIRROR_OBSERVATION_EVENT_TYPE];
+
+export interface MirrorSnapshotObservationEvent {
+	type: typeof MIRROR_OBSERVATION_EVENT_TYPE.SNAPSHOT;
+	agent: MirrorAgentSnapshot;
+}
+
+export interface MirrorStatusObservationEvent {
+	type: typeof MIRROR_OBSERVATION_EVENT_TYPE.STATUS;
+	agentId: string;
+	status: SubagentStatus;
+}
+
+export interface MirrorAssistantTextDeltaObservationEvent {
+	type: typeof MIRROR_OBSERVATION_EVENT_TYPE.ASSISTANT_TEXT_DELTA;
+	agentId: string;
+	delta: string;
+}
+
+export type MirrorObservationEvent =
+	| MirrorSnapshotObservationEvent
+	| MirrorStatusObservationEvent
+	| MirrorAssistantTextDeltaObservationEvent;
+
+export type MirrorObservationListener = (event: MirrorObservationEvent) => void | Promise<void>;
+
+export type MirrorObservationUnsubscribe = () => void;
+
+export interface MirrorObservationSource {
+	listAgents(): readonly MirrorAgentSnapshot[] | Promise<readonly MirrorAgentSnapshot[]>;
+	subscribe(listener: MirrorObservationListener): MirrorObservationUnsubscribe;
+}

package/src/mirror-runtime.ts

@@ -0,0 +1,69 @@
+import type { HerdrMirrorPaneLauncher } from "./herdr-pane-launcher.js";
+import { MirrorBridge } from "./mirror-bridge.js";
+import {
+	MIRROR_OBSERVATION_EVENT_TYPE,
+	type MirrorObservationEvent,
+	type MirrorObservationSource,
+	type MirrorObservationUnsubscribe,
+} from "./mirror-observation.js";
+import type { MirrorServer } from "./mirror-server.js";
+import type { MirrorAgentSnapshot } from "./mirror-types.js";
+
+export interface MirrorPaneLauncher {
+	launch(agent: MirrorAgentSnapshot, socketPath: string): Promise<string>;
+	closeAll(): Promise<void>;
+}
+
+export interface MirrorRuntimeOptions {
+	source: MirrorObservationSource;
+	server: MirrorServer;
+	launcher: MirrorPaneLauncher | HerdrMirrorPaneLauncher;
+	socketPath: string;
+}
+
+export class MirrorRuntime {
+	private readonly bridge: MirrorBridge;
+	private readonly launchedAgentIds = new Set<string>();
+	private unsubscribe: MirrorObservationUnsubscribe | undefined;
+	private started = false;
+
+	constructor(private readonly options: MirrorRuntimeOptions) {
+		this.bridge = new MirrorBridge({ source: options.source, server: options.server });
+	}
+
+	async start(): Promise<void> {
+		if (this.started) return;
+		this.started = true;
+		this.unsubscribe = this.options.source.subscribe((event) => this.handleObservation(event));
+		await this.bridge.start();
+		const agents = await this.options.source.listAgents();
+		await Promise.all(agents.map((agent) => this.launchOnce(agent)));
+	}
+
+	async stop(): Promise<void> {
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		this.launchedAgentIds.clear();
+		this.started = false;
+		await Promise.all([
+			this.bridge.stop(),
+			this.options.launcher.closeAll(),
+		]);
+	}
+
+	private async handleObservation(event: MirrorObservationEvent): Promise<void> {
+		if (event.type !== MIRROR_OBSERVATION_EVENT_TYPE.SNAPSHOT) return;
+		await this.launchOnce(event.agent);
+	}
+
+	private async launchOnce(agent: MirrorAgentSnapshot): Promise<void> {
+		if (this.launchedAgentIds.has(agent.id)) return;
+		this.launchedAgentIds.add(agent.id);
+		try {
+			await this.options.launcher.launch(agent, this.options.socketPath);
+		} catch (error) {
+			this.launchedAgentIds.delete(agent.id);
+			throw error;
+		}
+	}
+}

package/src/mirror-server.ts

@@ -0,0 +1,119 @@
+import { createServer, type Server, type Socket } from "node:net";
+import { rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+import { MIRROR_EVENT_TYPE, type MirrorAgentSnapshot, type MirrorEvent, type MirrorSubscribeRequest } from "./mirror-types.js";
+
+export interface MirrorServerOptions {
+	socketPath: string;
+}
+
+interface MirrorClient {
+	socket: Socket;
+	agentId?: string;
+}
+
+function encodeEvent(event: MirrorEvent): string {
+	return `${JSON.stringify(event)}\n`;
+}
+
+function shouldSendToClient(event: MirrorEvent, agentId: string | undefined): boolean {
+	if (event.type === MIRROR_EVENT_TYPE.ERROR) return event.agentId == null || event.agentId === agentId;
+	if (event.type === MIRROR_EVENT_TYPE.SNAPSHOT) return event.agent.id === agentId;
+	return event.agentId === agentId;
+}
+
+function parseSubscribeRequest(line: string): MirrorSubscribeRequest {
+	const value = JSON.parse(line) as Partial<MirrorSubscribeRequest>;
+	if (typeof value.agentId !== "string" || value.agentId.length === 0) {
+		throw new Error("Mirror subscribe request requires agentId.");
+	}
+	return { agentId: value.agentId };
+}
+
+export class MirrorServer {
+	private server: Server | undefined;
+	private readonly clients = new Set<MirrorClient>();
+	private readonly snapshots = new Map<string, MirrorAgentSnapshot>();
+
+	constructor(private readonly options: MirrorServerOptions) {}
+
+	async start(): Promise<void> {
+		if (this.server) return;
+		mkdirSync(dirname(this.options.socketPath), { recursive: true });
+		await rm(this.options.socketPath, { force: true });
+		this.server = createServer((socket) => this.handleConnection(socket));
+		await new Promise<void>((resolve, reject) => {
+			this.server?.once("error", reject);
+			this.server?.listen(this.options.socketPath, () => {
+				this.server?.off("error", reject);
+				resolve();
+			});
+		});
+	}
+
+	async stop(): Promise<void> {
+		for (const client of this.clients) client.socket.destroy();
+		this.clients.clear();
+		const server = this.server;
+		this.server = undefined;
+		if (server) {
+			await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+		}
+		await rm(this.options.socketPath, { force: true });
+	}
+
+	upsertSnapshot(snapshot: MirrorAgentSnapshot): void {
+		this.snapshots.set(snapshot.id, snapshot);
+	}
+
+	async publish(event: MirrorEvent): Promise<void> {
+		if (event.type === MIRROR_EVENT_TYPE.ASSISTANT_TEXT_DELTA) {
+			const snapshot = this.snapshots.get(event.agentId);
+			if (snapshot) {
+				this.snapshots.set(event.agentId, {
+					...snapshot,
+					assistantText: snapshot.assistantText + event.delta,
+					updatedAt: Date.now(),
+				});
+			}
+		}
+		if (event.type === MIRROR_EVENT_TYPE.STATUS) {
+			const snapshot = this.snapshots.get(event.agentId);
+			if (snapshot) {
+				this.snapshots.set(event.agentId, { ...snapshot, status: event.status, updatedAt: Date.now() });
+			}
+		}
+		for (const client of this.clients) {
+			if (!shouldSendToClient(event, client.agentId)) continue;
+			client.socket.write(encodeEvent(event));
+		}
+	}
+
+	private handleConnection(socket: Socket): void {
+		const client: MirrorClient = { socket };
+		this.clients.add(client);
+		let buffer = "";
+		socket.setEncoding("utf8");
+		socket.on("data", (chunk) => {
+			buffer += chunk;
+			const newline = buffer.indexOf("\n");
+			if (newline === -1 || client.agentId) return;
+			const line = buffer.slice(0, newline);
+			try {
+				const request = parseSubscribeRequest(line);
+				client.agentId = request.agentId;
+				const snapshot = this.snapshots.get(request.agentId);
+				if (snapshot) {
+					socket.write(encodeEvent({ type: MIRROR_EVENT_TYPE.SNAPSHOT, agent: snapshot, sequence: 0 }));
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "Invalid mirror subscribe request.";
+				socket.write(encodeEvent({ type: MIRROR_EVENT_TYPE.ERROR, message, sequence: 0 }));
+				socket.end();
+			}
+		});
+		socket.on("close", () => this.clients.delete(client));
+		socket.on("error", () => this.clients.delete(client));
+	}
+}

package/src/mirror-types.ts

@@ -0,0 +1,64 @@
+export const SUBAGENT_STATUS = {
+	QUEUED: "queued",
+	RUNNING: "running",
+	COMPLETED: "completed",
+	ABORTED: "aborted",
+	STEERED: "steered",
+	ERROR: "error",
+	STOPPED: "stopped",
+} as const;
+
+export type SubagentStatus = (typeof SUBAGENT_STATUS)[keyof typeof SUBAGENT_STATUS];
+
+export const MIRROR_EVENT_TYPE = {
+	SNAPSHOT: "snapshot",
+	STATUS: "status",
+	ASSISTANT_TEXT_DELTA: "assistant_text_delta",
+	ERROR: "error",
+} as const;
+
+export type MirrorEventType = (typeof MIRROR_EVENT_TYPE)[keyof typeof MIRROR_EVENT_TYPE];
+
+export interface MirrorAgentSnapshot {
+	id: string;
+	type: string;
+	description: string;
+	status: SubagentStatus;
+	assistantText: string;
+	updatedAt: number;
+	result?: string;
+	error?: string;
+}
+
+export interface SnapshotMirrorEvent {
+	type: typeof MIRROR_EVENT_TYPE.SNAPSHOT;
+	agent: MirrorAgentSnapshot;
+	sequence: number;
+}
+
+export interface StatusMirrorEvent {
+	type: typeof MIRROR_EVENT_TYPE.STATUS;
+	agentId: string;
+	status: SubagentStatus;
+	sequence: number;
+}
+
+export interface AssistantTextDeltaMirrorEvent {
+	type: typeof MIRROR_EVENT_TYPE.ASSISTANT_TEXT_DELTA;
+	agentId: string;
+	delta: string;
+	sequence: number;
+}
+
+export interface ErrorMirrorEvent {
+	type: typeof MIRROR_EVENT_TYPE.ERROR;
+	agentId?: string;
+	message: string;
+	sequence: number;
+}
+
+export type MirrorEvent = SnapshotMirrorEvent | StatusMirrorEvent | AssistantTextDeltaMirrorEvent | ErrorMirrorEvent;
+
+export interface MirrorSubscribeRequest {
+	agentId: string;
+}

package/src/pi-subagents-observation-source.ts

@@ -0,0 +1,69 @@
+import {
+	MIRROR_OBSERVATION_EVENT_TYPE,
+	type MirrorObservationEvent,
+	type MirrorObservationListener,
+	type MirrorObservationSource,
+	type MirrorObservationUnsubscribe,
+} from "./mirror-observation.js";
+import type { MirrorAgentSnapshot, SubagentStatus } from "./mirror-types.js";
+
+export const PI_SUBAGENTS_MIRROR_EVENT_TYPE = {
+	AGENT_SNAPSHOT: "agent_snapshot",
+	STATUS: "status",
+	ASSISTANT_TEXT_DELTA: "assistant_text_delta",
+} as const;
+
+export type PiSubagentsMirrorEventType =
+	(typeof PI_SUBAGENTS_MIRROR_EVENT_TYPE)[keyof typeof PI_SUBAGENTS_MIRROR_EVENT_TYPE];
+
+export interface PiSubagentsAgentSnapshotEvent {
+	type: typeof PI_SUBAGENTS_MIRROR_EVENT_TYPE.AGENT_SNAPSHOT;
+	agent: MirrorAgentSnapshot;
+}
+
+export interface PiSubagentsStatusEvent {
+	type: typeof PI_SUBAGENTS_MIRROR_EVENT_TYPE.STATUS;
+	agentId: string;
+	status: SubagentStatus;
+}
+
+export interface PiSubagentsAssistantTextDeltaEvent {
+	type: typeof PI_SUBAGENTS_MIRROR_EVENT_TYPE.ASSISTANT_TEXT_DELTA;
+	agentId: string;
+	delta: string;
+}
+
+export type PiSubagentsMirrorEvent =
+	| PiSubagentsAgentSnapshotEvent
+	| PiSubagentsStatusEvent
+	| PiSubagentsAssistantTextDeltaEvent;
+
+export type PiSubagentsMirrorListener = (event: PiSubagentsMirrorEvent) => void | Promise<void>;
+
+export interface PiSubagentsMirrorService {
+	listMirrorSnapshots(): readonly MirrorAgentSnapshot[] | Promise<readonly MirrorAgentSnapshot[]>;
+	subscribeToMirrorEvents(listener: PiSubagentsMirrorListener): MirrorObservationUnsubscribe;
+}
+
+export class PiSubagentsObservationSource implements MirrorObservationSource {
+	constructor(private readonly service: PiSubagentsMirrorService) {}
+
+	listAgents(): readonly MirrorAgentSnapshot[] | Promise<readonly MirrorAgentSnapshot[]> {
+		return this.service.listMirrorSnapshots();
+	}
+
+	subscribe(listener: MirrorObservationListener): MirrorObservationUnsubscribe {
+		return this.service.subscribeToMirrorEvents((event) => listener(toMirrorObservation(event)));
+	}
+}
+
+function toMirrorObservation(event: PiSubagentsMirrorEvent): MirrorObservationEvent {
+	switch (event.type) {
+		case PI_SUBAGENTS_MIRROR_EVENT_TYPE.AGENT_SNAPSHOT:
+			return { type: MIRROR_OBSERVATION_EVENT_TYPE.SNAPSHOT, agent: event.agent };
+		case PI_SUBAGENTS_MIRROR_EVENT_TYPE.STATUS:
+			return { type: MIRROR_OBSERVATION_EVENT_TYPE.STATUS, agentId: event.agentId, status: event.status };
+		case PI_SUBAGENTS_MIRROR_EVENT_TYPE.ASSISTANT_TEXT_DELTA:
+			return { type: MIRROR_OBSERVATION_EVENT_TYPE.ASSISTANT_TEXT_DELTA, agentId: event.agentId, delta: event.delta };
+	}
+}

package/src/viewer-render.ts

@@ -0,0 +1,16 @@
+import { MIRROR_EVENT_TYPE, type MirrorEvent } from "./mirror-types.js";
+
+export function renderMirrorEvent(event: MirrorEvent): string {
+	switch (event.type) {
+		case MIRROR_EVENT_TYPE.SNAPSHOT: {
+			const header = `[${event.agent.status}] ${event.agent.type} — ${event.agent.description}`;
+			return event.agent.assistantText ? `${header}\n${event.agent.assistantText}` : header;
+		}
+		case MIRROR_EVENT_TYPE.STATUS:
+			return `\n[${event.status}]`;
+		case MIRROR_EVENT_TYPE.ASSISTANT_TEXT_DELTA:
+			return event.delta;
+		case MIRROR_EVENT_TYPE.ERROR:
+			return `\n[mirror error] ${event.message}\n`;
+	}
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts", "bin/**/*.ts", "extensions/**/*.ts", "tests/**/*.ts"]
+}