@agnishc/edb-bridge 0.12.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `@agnishc/edb-bridge` will be documented in this file.
+
+## [0.12.0] - 2026-05-22
+
+### Added
+
+- Initial release
+- Unix socket broker with auto-spawn
+- `ask_supervisor` tool for sub-agents (blocking question to orchestrator)
+- `notify_parent` tool for sub-agents (fire-and-forget progress updates)
+- `answer_subagent` tool for orchestrators (reply to pending sub-agent questions)
+- Internal `pi.events` API: `bridge:ready`, `bridge:task_updated`
+- `PI_BRIDGE_PARENT_SESSION` / `PI_BRIDGE_AGENT_ID` env var support
+
+## [0.10.9] - 2026-05-18

package/README.md

@@ -0,0 +1,39 @@
+# @agnishc/edb-bridge
+
+A Pi CLI extension providing a lightweight inter-session message bus for orchestrator/sub-agent workflows.
+
+## Features
+
+- **Unix socket broker** — auto-spawned, zero config
+- **ask_supervisor** — sub-agent blocks until orchestrator answers (10-min timeout)
+- **notify_parent** — sub-agent sends fire-and-forget progress updates to orchestrator
+- **answer_subagent** — orchestrator replies to a pending sub-agent question
+- **Internal pi.events API** — other extensions coordinate via `bridge:ready`, `bridge:task_updated`
+
+## How it works
+
+When edb-bridge is installed, each pi session connects to a shared broker process at startup. Sub-agents get `ask_supervisor` and `notify_parent` tools when `PI_BRIDGE_PARENT_SESSION` is set in their environment. The orchestrator uses `answer_subagent` to respond.
+
+## Environment variables (injected by edb-subagents)
+
+| Variable | Description |
+|---|---|
+| `PI_BRIDGE_PARENT_SESSION` | Broker session ID of the parent orchestrator |
+| `PI_BRIDGE_AGENT_ID` | edb-subagents agent ID (for routing) |
+
+## Internal pi.events API
+
+| Event | Emitted by | Payload |
+|---|---|---|
+| `bridge:ready` | edb-bridge | `{ sessionId: string }` |
+| `bridge:task_updated` | edb-todo | `{ storePath: string }` |
+
+## Install
+
+```bash
+pi install npm:@agnishc/edb-bridge
+```
+
+## License
+
+MIT © Agnish Chakraborty

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@agnishc/edb-bridge",
+	"version": "0.12.0",
+	"description": "Pi extension: lightweight inter-session message bus for orchestrator/sub-agent workflows",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"edb",
+		"bridge",
+		"ipc"
+	],
+	"type": "module",
+	"license": "MIT",
+	"author": "Agnish Chakraborty",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agnishcc/pi-extention-monorepo.git",
+		"directory": "packages/edb-bridge"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "vitest run"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	}
+}

package/src/broker.ts

@@ -0,0 +1,180 @@
+/**
+ * edb-bridge broker process.
+ *
+ * Spawned as a detached child by the first connecting session.
+ * Routes messages between connected sessions by broker session ID.
+ * Shuts itself down 5s after the last session disconnects.
+ *
+ * Run: node broker.ts  (or tsx broker.ts for development)
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import { createMessageReader, writeMessage } from "./framing.js";
+import { BRIDGE_DIR, getBrokerPidPath, getBrokerSocketPath } from "./paths.js";
+import type { BridgeMessage, ClientMessage, SessionInfo } from "./types.js";
+
+const SOCKET_PATH = getBrokerSocketPath();
+const PID_PATH = getBrokerPidPath();
+const SHUTDOWN_IDLE_MS = 5_000;
+
+interface ConnectedSession {
+	socket: net.Socket;
+	info: SessionInfo;
+}
+
+class EdbBridgeBroker {
+	private sessions = new Map<string, ConnectedSession>();
+	private server: net.Server;
+	private shutdownTimer: ReturnType<typeof setTimeout> | null = null;
+
+	constructor() {
+		mkdirSync(BRIDGE_DIR, { recursive: true });
+		if (process.platform !== "win32") {
+			try {
+				unlinkSync(SOCKET_PATH);
+			} catch {
+				/* stale socket */
+			}
+		}
+		this.server = net.createServer(this.handleConnection.bind(this));
+	}
+
+	start(): void {
+		this.server.listen(SOCKET_PATH, () => {
+			writeFileSync(PID_PATH, String(process.pid));
+			console.log(`edb-bridge broker started (pid: ${process.pid})`);
+		});
+		process.on("SIGTERM", () => this.shutdown());
+		process.on("SIGINT", () => this.shutdown());
+	}
+
+	private handleConnection(socket: net.Socket): void {
+		let sessionId: string | null = null;
+
+		const reader = createMessageReader(
+			(msg) =>
+				this.handleMessage(socket, msg as ClientMessage, sessionId, (id) => {
+					sessionId = id;
+				}),
+			(err) => socket.destroy(err),
+		);
+
+		socket.on("data", reader);
+		socket.on("close", () => {
+			if (sessionId) {
+				this.sessions.delete(sessionId);
+				this.scheduleIdleShutdown();
+			}
+		});
+		socket.on("error", () => {
+			/* ignore */
+		});
+	}
+
+	private handleMessage(
+		socket: net.Socket,
+		msg: ClientMessage,
+		currentId: string | null,
+		setId: (id: string) => void,
+	): void {
+		if (!msg || typeof msg !== "object" || !("type" in msg)) {
+			throw new Error("invalid message");
+		}
+
+		if (currentId === null && msg.type !== "register") {
+			throw new Error(`received '${msg.type}' before register`);
+		}
+
+		switch (msg.type) {
+			case "register": {
+				if (currentId) throw new Error("duplicate register");
+				const id = randomUUID();
+				setId(id);
+				const info: SessionInfo = { ...msg.session, id };
+				this.sessions.set(id, { socket, info });
+				if (this.shutdownTimer) {
+					clearTimeout(this.shutdownTimer);
+					this.shutdownTimer = null;
+				}
+				writeMessage(socket, { type: "registered", sessionId: id });
+				break;
+			}
+
+			case "unregister": {
+				if (currentId) {
+					this.sessions.delete(currentId);
+					this.scheduleIdleShutdown();
+				}
+				break;
+			}
+
+			case "list": {
+				if (typeof msg.requestId !== "string") throw new Error("invalid list");
+				const sessions = Array.from(this.sessions.values()).map((s) => s.info);
+				writeMessage(socket, { type: "sessions", requestId: msg.requestId, sessions });
+				break;
+			}
+
+			case "send": {
+				const message = msg.message as BridgeMessage;
+				if (!message?.id || typeof msg.to !== "string") {
+					writeMessage(socket, {
+						type: "delivery_failed",
+						messageId: message?.id ?? "",
+						reason: "invalid message",
+					});
+					break;
+				}
+				const target = this.sessions.get(msg.to);
+				if (!target) {
+					writeMessage(socket, { type: "delivery_failed", messageId: message.id, reason: "session not found" });
+					break;
+				}
+				const fromSession = this.sessions.get(currentId!);
+				if (!fromSession) {
+					writeMessage(socket, { type: "delivery_failed", messageId: message.id, reason: "sender not found" });
+					break;
+				}
+				writeMessage(target.socket, { type: "message", from: fromSession.info, message });
+				writeMessage(socket, { type: "delivered", messageId: message.id });
+				break;
+			}
+
+			default:
+				throw new Error(`unknown message type: ${(msg as any).type}`);
+		}
+	}
+
+	private scheduleIdleShutdown(): void {
+		if (this.shutdownTimer) return;
+		this.shutdownTimer = setTimeout(() => {
+			this.shutdownTimer = null;
+			if (this.sessions.size === 0) {
+				console.log("edb-bridge: no sessions, shutting down");
+				this.shutdown();
+			}
+		}, SHUTDOWN_IDLE_MS);
+	}
+
+	private shutdown(): void {
+		for (const s of this.sessions.values()) s.socket.end();
+		this.sessions.clear();
+		if (process.platform !== "win32") {
+			try {
+				unlinkSync(SOCKET_PATH);
+			} catch {
+				/* ignore */
+			}
+		}
+		try {
+			unlinkSync(PID_PATH);
+		} catch {
+			/* ignore */
+		}
+		this.server.close(() => process.exit(0));
+	}
+}
+
+new EdbBridgeBroker().start();

package/src/client.ts

@@ -0,0 +1,368 @@
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import net from "node:net";
+import { createMessageReader, writeMessage } from "./framing.js";
+import { getBrokerSocketPath } from "./paths.js";
+import type { BridgeMessage, BrokerMessage, SessionInfo } from "./types.js";
+
+const SOCKET_PATH = getBrokerSocketPath();
+
+export interface SendOptions {
+	text: string;
+	data?: Record<string, unknown>;
+	type?: string;
+	replyTo?: string;
+	expectsReply?: boolean;
+	messageId?: string;
+}
+
+export interface SendResult {
+	id: string;
+	delivered: boolean;
+	reason?: string;
+}
+
+interface PendingSend {
+	resolve: (r: SendResult) => void;
+	reject: (e: Error) => void;
+}
+
+interface PendingList {
+	resolve: (sessions: SessionInfo[]) => void;
+	reject: (e: Error) => void;
+}
+
+function toError(e: unknown): Error {
+	return e instanceof Error ? e : new Error(String(e));
+}
+
+function isSessionInfo(v: unknown): v is SessionInfo {
+	if (!v || typeof v !== "object") return false;
+	const s = v as Record<string, unknown>;
+	return typeof s.id === "string" && typeof s.cwd === "string";
+}
+
+function isBridgeMessage(v: unknown): v is BridgeMessage {
+	if (!v || typeof v !== "object") return false;
+	const m = v as Record<string, unknown>;
+	return (
+		typeof m.id === "string" &&
+		typeof m.timestamp === "number" &&
+		m.content !== null &&
+		typeof m.content === "object" &&
+		typeof (m.content as any).text === "string"
+	);
+}
+
+export class BridgeClient extends EventEmitter {
+	private socket: net.Socket | null = null;
+	private _sessionId: string | null = null;
+	private pendingSends = new Map<string, PendingSend>();
+	private pendingLists = new Map<string, PendingList>();
+	private disconnecting = false;
+	private disconnectError: Error | null = null;
+
+	get sessionId(): string | null {
+		return this._sessionId;
+	}
+
+	isConnected(): boolean {
+		const s = this.socket;
+		return Boolean(s && this._sessionId && !this.disconnecting && !s.destroyed && !s.writableEnded && s.writable);
+	}
+
+	private requireSocket(): net.Socket {
+		if (this.disconnecting) throw new Error("disconnecting");
+		const s = this.socket;
+		if (!s || !this._sessionId) throw new Error("not connected");
+		if (s.destroyed || s.writableEnded || !s.writable) throw new Error("disconnected");
+		return s;
+	}
+
+	private failPending(err: Error): void {
+		for (const p of this.pendingSends.values()) p.reject(err);
+		this.pendingSends.clear();
+		for (const p of this.pendingLists.values()) p.reject(err);
+		this.pendingLists.clear();
+	}
+
+	connect(session: Omit<SessionInfo, "id">): Promise<void> {
+		if (this.socket) return Promise.reject(new Error("already connected"));
+
+		return new Promise((resolve, reject) => {
+			const socket = net.connect(SOCKET_PATH);
+			this.socket = socket;
+			this.disconnectError = null;
+			let settled = false;
+			let connected = false;
+
+			const timeout = setTimeout(() => {
+				if (!this._sessionId) {
+					cleanupAttempt();
+					cleanupSocket();
+					if (this.socket === socket) this.socket = null;
+					socket.destroy();
+					reject(new Error("edb-bridge: connection timeout"));
+				}
+			}, 10_000);
+
+			const onRegistered = () => {
+				settled = true;
+				connected = true;
+				cleanupAttempt();
+				resolve();
+			};
+
+			const onError = (err: Error) => {
+				settled = true;
+				cleanupAttempt();
+				cleanupSocket();
+				if (this.socket === socket) this.socket = null;
+				socket.destroy();
+				reject(err);
+			};
+
+			const onClose = () => {
+				const wasConnecting = !settled && !this._sessionId;
+				const wasDisconnecting = this.disconnecting;
+				const err = this.disconnectError ?? new Error("edb-bridge: disconnected");
+				this.disconnecting = false;
+				cleanupAttempt();
+				cleanupSocket();
+				this.failPending(err);
+				if (this.socket === socket) this.socket = null;
+				this._sessionId = null;
+				this.disconnectError = null;
+				if (connected && !wasDisconnecting) this.emit("disconnected", err);
+				if (wasConnecting) reject(new Error("edb-bridge: connection closed before registration"));
+			};
+
+			const onSocketError = (err: Error) => {
+				if (connected) {
+					this.disconnectError = err;
+					this.emit("error", err);
+				}
+			};
+
+			const onReaderError = (err: Error) => {
+				if (!connected) {
+					onError(err);
+					return;
+				}
+				this.disconnectError = err;
+				this.emit("error", err);
+				socket.destroy();
+			};
+
+			const reader = createMessageReader((msg) => this.handleBrokerMessage(msg as BrokerMessage), onReaderError);
+
+			const cleanupAttempt = () => {
+				this.off("_registered", onRegistered);
+				socket.off("error", onError);
+				clearTimeout(timeout);
+			};
+
+			const cleanupSocket = () => {
+				socket.off("data", reader);
+				socket.off("error", onSocketError);
+				socket.off("close", onClose);
+			};
+
+			socket.on("data", reader);
+			socket.on("error", onError);
+			socket.on("close", onClose);
+			socket.on("error", onSocketError);
+			this.once("_registered", onRegistered);
+
+			try {
+				writeMessage(socket, { type: "register", session });
+			} catch (err) {
+				cleanupAttempt();
+				cleanupSocket();
+				if (this.socket === socket) this.socket = null;
+				socket.destroy();
+				reject(toError(err));
+			}
+		});
+	}
+
+	private handleBrokerMessage(msg: BrokerMessage): void {
+		if (!msg || typeof msg !== "object" || !("type" in msg)) {
+			throw new Error("invalid broker message");
+		}
+
+		switch (msg.type) {
+			case "registered": {
+				if (this._sessionId !== null) throw new Error("duplicate registered");
+				this._sessionId = msg.sessionId;
+				this.emit("_registered");
+				break;
+			}
+
+			case "sessions": {
+				const p = this.pendingLists.get(msg.requestId);
+				if (!p) return;
+				this.pendingLists.delete(msg.requestId);
+				p.resolve(msg.sessions as SessionInfo[]);
+				break;
+			}
+
+			case "message": {
+				if (!isSessionInfo(msg.from) || !isBridgeMessage(msg.message)) {
+					throw new Error("invalid message event");
+				}
+				this.emit("message", msg.from, msg.message);
+				break;
+			}
+
+			case "delivered": {
+				const p = this.pendingSends.get(msg.messageId);
+				if (!p) return;
+				this.pendingSends.delete(msg.messageId);
+				p.resolve({ id: msg.messageId, delivered: true });
+				break;
+			}
+
+			case "delivery_failed": {
+				const p = this.pendingSends.get(msg.messageId);
+				if (!p) return;
+				this.pendingSends.delete(msg.messageId);
+				p.resolve({ id: msg.messageId, delivered: false, reason: msg.reason });
+				break;
+			}
+
+			case "session_joined":
+			case "session_left":
+				// broadcast events — not used currently
+				break;
+
+			default:
+				throw new Error(`unknown broker message type: ${(msg as any).type}`);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		const socket = this.socket;
+		if (!socket) return;
+
+		this.disconnecting = true;
+		this.disconnectError = null;
+		this.failPending(new Error("edb-bridge: disconnected"));
+
+		await new Promise<void>((resolve) => {
+			let done = false;
+			const finish = () => {
+				if (done) return;
+				done = true;
+				clearTimeout(t);
+				socket.off("close", onClose);
+				socket.off("error", onError);
+				resolve();
+			};
+			const onClose = () => finish();
+			const onError = () => {
+				socket.destroy();
+			};
+			const t = setTimeout(() => {
+				socket.destroy();
+			}, 2000);
+			socket.once("close", onClose);
+			socket.once("error", onError);
+			try {
+				writeMessage(socket, { type: "unregister" });
+				socket.end();
+			} catch {
+				socket.destroy();
+			}
+		});
+	}
+
+	listSessions(): Promise<SessionInfo[]> {
+		let socket: net.Socket;
+		try {
+			socket = this.requireSocket();
+		} catch (e) {
+			return Promise.reject(toError(e));
+		}
+
+		return new Promise((resolve, reject) => {
+			const requestId = randomUUID();
+			let done = false;
+			const timeout = setTimeout(() => {
+				if (!done) {
+					done = true;
+					this.pendingLists.delete(requestId);
+					reject(new Error("edb-bridge: list sessions timeout"));
+				}
+			}, 5000);
+			this.pendingLists.set(requestId, {
+				resolve: (sessions) => {
+					clearTimeout(timeout);
+					done = true;
+					resolve(sessions);
+				},
+				reject: (err) => {
+					clearTimeout(timeout);
+					done = true;
+					reject(err);
+				},
+			});
+			try {
+				writeMessage(socket, { type: "list", requestId });
+			} catch (err) {
+				clearTimeout(timeout);
+				this.pendingLists.delete(requestId);
+				reject(toError(err));
+			}
+		});
+	}
+
+	send(to: string, options: SendOptions): Promise<SendResult> {
+		let socket: net.Socket;
+		try {
+			socket = this.requireSocket();
+		} catch (e) {
+			return Promise.reject(toError(e));
+		}
+
+		const messageId = options.messageId ?? randomUUID();
+		const message: BridgeMessage = {
+			id: messageId,
+			timestamp: Date.now(),
+			replyTo: options.replyTo,
+			expectsReply: options.expectsReply,
+			type: options.type,
+			content: { text: options.text, data: options.data },
+		};
+
+		return new Promise((resolve, reject) => {
+			let done = false;
+			const timeout = setTimeout(() => {
+				if (!done) {
+					done = true;
+					this.pendingSends.delete(messageId);
+					reject(new Error("edb-bridge: send timeout"));
+				}
+			}, 10_000);
+			this.pendingSends.set(messageId, {
+				resolve: (r) => {
+					clearTimeout(timeout);
+					done = true;
+					resolve(r);
+				},
+				reject: (err) => {
+					clearTimeout(timeout);
+					done = true;
+					reject(err);
+				},
+			});
+			try {
+				writeMessage(socket, { type: "send", to, message });
+			} catch (err) {
+				clearTimeout(timeout);
+				this.pendingSends.delete(messageId);
+				reject(toError(err));
+			}
+		});
+	}
+}

package/src/framing.ts

@@ -0,0 +1,49 @@
+import type { Socket } from "node:net";
+
+/**
+ * Write a length-prefixed JSON message to a socket.
+ * Format: 4-byte big-endian uint32 length + UTF-8 JSON payload.
+ */
+export function writeMessage(socket: Socket, msg: unknown): void {
+	const json = JSON.stringify(msg);
+	const payload = Buffer.from(json, "utf-8");
+	const header = Buffer.alloc(4);
+	header.writeUInt32BE(payload.length, 0);
+	socket.write(Buffer.concat([header, payload]));
+}
+
+/**
+ * Create a streaming message reader that handles partial TCP reads.
+ * Calls onMessage for each complete framed message.
+ * Protocol errors are reported to onError — caller should close the socket.
+ */
+export function createMessageReader(onMessage: (msg: unknown) => void, onError: (error: Error) => void) {
+	let buffer = Buffer.alloc(0);
+
+	return (data: Buffer) => {
+		buffer = Buffer.concat([buffer, data]);
+
+		while (buffer.length >= 4) {
+			const length = buffer.readUInt32BE(0);
+			if (buffer.length < 4 + length) break;
+
+			const payload = buffer.subarray(4, 4 + length);
+			buffer = buffer.subarray(4 + length);
+
+			let msg: unknown;
+			try {
+				msg = JSON.parse(payload.toString("utf-8"));
+			} catch (err) {
+				onError(new Error(`edb-bridge: failed to parse message: ${err}`, { cause: err }));
+				return;
+			}
+
+			try {
+				onMessage(msg);
+			} catch (err) {
+				onError(new Error(`edb-bridge: failed to handle message: ${err}`, { cause: err }));
+				return;
+			}
+		}
+	};
+}