@dieulc/pi-office-bridge 0.1.0 → 0.2.0

package/README.md

@@ -1,97 +1,120 @@
-# @dieulc/pi-office-bridge
-
-Native Pi extension that lets a local Pi process drive **Excel**, **Word**, and
-**PowerPoint** through the [pi-for-office](../add-in/README.md) task-pane
-add-in.
-
-Pure extension — it only uses Pi's public extension API, so **Pi core is never
-touched** and Pi can be updated freely.
-
-## How it works
-
-```
-Excel / Word / PowerPoint  (pi-for-office task pane)
-        │  WebSocket  ws://127.0.0.1:38617
-        ▼
-local Pi process  (this extension)
-   • registers office_<host>_<op> tools
-   • proxies Office.js calls back to the pane
-   • injects pane prompts into the Pi session
-```
-
-Two flows:
-
-1. **Tool proxy (Pi → pane):** the Pi agent calls `office_excel_read_range`,
-   `office_word_insert_text`, …; the extension forwards a `tool_call` to the
-   attached pane; the pane runs the Office.js op and answers with a
-   `tool_result`. The LLM then sees the document content **and** has Pi's full
-   system tools (bash, git, files).
-
-2. **Pane-driven chat (pane → Pi):** the user types in the add-in sidebar; the
-   pane forwards a `user_message`; the extension injects it into the Pi session
-   and streams the assistant's final reply back to the pane.
-
-## Install
-
-```bash
-pi install npm:@dieulc/pi-office-bridge
-```
-
-Or from the monorepo (development):
-
-```bash
-cd packages/bridge-extension
-npm install
-# then load it in pi for a quick test:
-pi -e ./src/index.ts
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `/office` | Show bridge status: port + attached apps (Excel/Word/PowerPoint) |
-| `/office-tools` | List every `office_*` tool registered |
-
-## Configuration
-
-- **Port** — flag `--office-bridge-port <port>` or env `PI_OFFICE_BRIDGE_PORT`
-  (default `38617`). The add-in connects to the same default; change both if you
-  override it.
-
-## Office tools
-
-The extension registers a `office_<host>_<op>` tool per op in the shared
-catalog. The catalog lives in
-[`src/office-tools.ts`](./src/office-tools.ts); op ids are namespaced by host:
-
-| Host | Ops |
-|------|-----|
-| Excel | `get_overview`, `read_range`, `write_cells`, `fill_formula`, `search_workbook` |
-| Word | `get_overview`, `read_document`, `insert_text`, `replace_text` |
-| PowerPoint | `get_overview`, `read_slide`, `add_slide`, `add_text_box` |
-
-The pane-side executors are the counterpart contract — see
-`packages/add-in/src/bridge/` (same repo). **When adding an op, update both
-sides** (see "Bridge contract" in the add-in README).
-
-## Development
-
-```bash
-npm run typecheck     # typecheck against @earendil-works/pi-coding-agent 0.85.x
-npm run build         # emit dist/ (for the node smoke tests)
-npm test              # smoke test + end-to-end interop test (real client ↔ real server)
-```
-
-`tests/pane-interop.mjs` wires the **real** add-in `PaneBridgeClient` to the
-**real** bridge server through the shared `@dieulc/pi-office-protocol` package —
-the strongest proof the two halves agree on the wire format.
-
-## Protocol
-
-The wire protocol is shared in `@dieulc/pi-office-protocol`
-(`packages/protocol`). Bump `BRIDGE_PROTOCOL_VERSION` on breaking changes.
-
-## License
-
-MIT
+# @dieulc/pi-office-bridge
+
+Native Pi extension that lets a local Pi process drive **Excel**, **Word**, and
+**PowerPoint** through the [pi-for-office](../add-in/README.md) task-pane
+add-in.
+
+Pure extension — it only uses Pi's public extension API, so **Pi core is never
+touched** and Pi can be updated freely.
+
+## How it works
+
+```
+Excel / Word / PowerPoint  (pi-for-office task pane)
+        │  WebSocket  ws://127.0.0.1:38617
+        ▼
+local Pi process  (this extension)
+   • registers office_<host>_<op> tools
+   • proxies Office.js calls back to the pane
+   • injects pane prompts into the Pi session
+```
+
+Two flows:
+
+1. **Tool proxy (Pi → pane):** the Pi agent calls `office_excel_read_range`,
+   `office_word_insert_text`, …; the extension forwards a `tool_call` to the
+   attached pane; the pane runs the Office.js op and answers with a
+   `tool_result`. The LLM then sees the document content **and** has Pi's full
+   system tools (bash, git, files).
+
+2. **Pane-driven chat (pane → Pi):** the user types in the add-in sidebar; the
+   pane forwards a `user_message`; the extension injects it into the Pi session
+   and streams the assistant's final reply back to the pane.
+
+## Install
+
+```bash
+pi install npm:@dieulc/pi-office-bridge
+```
+
+Or from the monorepo (development):
+
+```bash
+cd packages/bridge-extension
+npm install
+# then load it in pi for a quick test:
+pi -e ./src/index.ts
+```
+
+## Enable in the add-in
+
+1. Install/run the bridge so a Pi process with this extension is listening
+   (see above). Keep that Pi process running in the background.
+2. Open pi-for-office in Excel / Word / PowerPoint.
+3. Go to **Settings → Connections → Local Pi agent (advanced)** and flip the
+   **Enable local Pi agent** toggle on. The card shows the live connection
+   state (Connecting… → Connected); no taskpane reload is needed.
+4. Verify with the card's **Test connection** button, or from a terminal:
+
+```bash
+curl http://127.0.0.1:38617/health
+# → { "ok": true, "service": "pi-office-bridge", "panes": [ … ] }
+```
+
+`/health` lists the attached pane(s) and their host app (excel / word /
+powerpoint), so it doubles as a quick host-detection check.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/office` | Show bridge status: port + attached apps (Excel/Word/PowerPoint) |
+| `/office-tools` | List every `office_*` tool registered |
+
+## Configuration
+
+- **Port** — flag `--office-bridge-port <port>` or env `PI_OFFICE_BRIDGE_PORT`
+  (default `38617`). The add-in connects to the same default; change both if you
+  override it.
+- **Allowed origins** — env `PI_OFFICE_BRIDGE_ALLOWED_ORIGINS` (comma-separated)
+  extends the browser origins allowed to read `GET /health`. Defaults cover the
+  dev Vite server (`https://localhost:3141`) and the hosted GitHub Pages add-in
+  (`https://dieuluucanh.github.io`). The pane's WebSocket connection is
+  loopback-only and is not restricted by this list.
+
+## Office tools
+
+The extension registers a `office_<host>_<op>` tool per op in the shared
+catalog. The catalog lives in
+[`src/office-tools.ts`](./src/office-tools.ts); op ids are namespaced by host:
+
+| Host | Ops |
+|------|-----|
+| Excel | `get_overview`, `read_range`, `write_cells`, `fill_formula`, `search_workbook` |
+| Word | `get_overview`, `read_document`, `insert_text`, `replace_text` |
+| PowerPoint | `get_overview`, `read_slide`, `add_slide`, `add_text_box` |
+
+The pane-side executors are the counterpart contract — see
+`packages/add-in/src/bridge/` (same repo). **When adding an op, update both
+sides** (see "Bridge contract" in the add-in README).
+
+## Development
+
+```bash
+npm run typecheck     # typecheck against @earendil-works/pi-coding-agent 0.85.x
+npm run build         # emit dist/ (for the node smoke tests)
+npm test              # smoke test + end-to-end interop test (real client ↔ real server)
+```
+
+`tests/pane-interop.mjs` wires the **real** add-in `PaneBridgeClient` to the
+**real** bridge server through the shared `@dieulc/pi-office-protocol` package —
+the strongest proof the two halves agree on the wire format.
+
+## Protocol
+
+The wire protocol is shared in `@dieulc/pi-office-protocol`
+(`packages/protocol`). Bump `BRIDGE_PROTOCOL_VERSION` on breaking changes.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dieulc/pi-office-bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Native Pi extension — WebSocket bridge + Office tool proxy so Pi can drive Excel, Word, and PowerPoint through the pi-for-office add-in.",
   "type": "module",
   "license": "MIT",

package/src/bridge-server.ts

@@ -8,7 +8,11 @@
  */
 
 import { WebSocketServer, WebSocket } from "ws";
-import type { Server as HttpServer } from "node:http";
+import type {
+  IncomingMessage,
+  Server as HttpServer,
+  ServerResponse,
+} from "node:http";
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 
@@ -16,6 +20,7 @@ import {
   BRIDGE_PROTOCOL_VERSION,
   nextCallId,
   parseClientMessage,
+  type BridgeCapability,
   type ClientMessage,
   type OfficeHostApp,
   type ServerMessage,
@@ -36,6 +41,11 @@ export interface AttachedPane {
 export interface BridgeServerHandlers {
   /** A user typed a prompt in the add-in sidebar. */
   onUserMessage(text: string, pane: AttachedPane): void;
+  /**
+   * A pane attached or detached. Lets the host (Pi) refresh its status line
+   * immediately instead of waiting for the next session event.
+   */
+  onPanesChanged?(panes: readonly AttachedPane[]): void;
 }
 
 export interface CallOfficeToolResult {
@@ -49,6 +59,16 @@ const HEARTBEAT_INTERVAL_MS = 30_000;
 const MAX_TEXT_CHARS = 50_000;
 const MAX_DETAILS_BYTES = 1_000_000;
 
+/** Extra browser origins for the /health CORS gate, from env (comma-separated). */
+function parseExtraOrigins(): string[] {
+  const raw = process.env.PI_OFFICE_BRIDGE_ALLOWED_ORIGINS;
+  if (!raw) return [];
+  return raw
+    .split(/[,\s]+/u)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 interface PendingCall {
   resolve(result: CallOfficeToolResult): void;
   reject(error: Error): void;
@@ -56,10 +76,15 @@ interface PendingCall {
 }
 
 export class OfficeBridgeServer {
+  /** Capabilities advertised in `welcome` and `GET /health`. */
+  static readonly CAPABILITIES: readonly BridgeCapability[] = ["http-health"];
+
   private readonly port: number;
   private readonly handlers: BridgeServerHandlers;
   private readonly serverName: string;
+  private readonly serverVersion: string;
   private readonly piVersion: string | null;
+  private readonly startedAt = Date.now();
 
   private httpServer: HttpServer | null = null;
   private wss: WebSocketServer | null = null;
@@ -71,11 +96,13 @@ export class OfficeBridgeServer {
   constructor(options: {
     port: number;
     serverName?: string;
+    serverVersion?: string;
     piVersion?: string | null;
     handlers: BridgeServerHandlers;
   }) {
     this.port = options.port;
     this.serverName = options.serverName ?? "pi-office-bridge";
+    this.serverVersion = options.serverVersion ?? "unknown";
     this.piVersion = options.piVersion ?? null;
     this.handlers = options.handlers;
   }
@@ -86,7 +113,9 @@ export class OfficeBridgeServer {
 
   get actualPort(): number | null {
     const addr = this.httpServer?.address();
-    return typeof addr === "object" && addr !== null ? (addr as AddressInfo).port : null;
+    return typeof addr === "object" && addr !== null
+      ? (addr as AddressInfo).port
+      : null;
   }
 
   /** Pane list copy (ordered by most recent connection first). */
@@ -98,8 +127,13 @@ export class OfficeBridgeServer {
   start(): Promise<void> {
     if (this.wss) return Promise.resolve();
 
-    const httpServer = createServer();
-    const wss = new WebSocketServer({ server: httpServer, maxPayload: 16 * 1024 * 1024 });
+    const httpServer = createServer((req, res) =>
+      this.handleHttpRequest(req, res),
+    );
+    const wss = new WebSocketServer({
+      server: httpServer,
+      maxPayload: 16 * 1024 * 1024,
+    });
 
     this.httpServer = httpServer;
     this.wss = wss;
@@ -153,6 +187,7 @@ export class OfficeBridgeServer {
       pane.ws.close(1001, "bridge shutting down");
     }
     this.panes.length = 0;
+    this.notifyPanesChanged();
 
     return new Promise((resolve) => {
       wss.close(() => resolve());
@@ -195,7 +230,11 @@ export class OfficeBridgeServer {
     return new Promise<CallOfficeToolResult>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`office-bridge: ${op} timed out after ${timeoutMs / 1000}s`));
+        reject(
+          new Error(
+            `office-bridge: ${op} timed out after ${timeoutMs / 1000}s`,
+          ),
+        );
       }, timeoutMs);
 
       this.pending.set(id, { resolve, reject, timer });
@@ -217,7 +256,11 @@ export class OfficeBridgeServer {
       if (!this.sendToPane(pane, message)) {
         clearTimeout(timer);
         this.pending.delete(id);
-        reject(new Error("office-bridge: pane disconnected before the tool call was sent"));
+        reject(
+          new Error(
+            "office-bridge: pane disconnected before the tool call was sent",
+          ),
+        );
       }
     });
   }
@@ -229,10 +272,127 @@ export class OfficeBridgeServer {
     }
   }
 
+  /* ── HTTP (health/diagnostics, loopback-only) ─────────────────────── */
+
+  /**
+   * Browser origins allowed to read this loopback HTTP surface. The add-in
+   * task pane runs at these origins (dev Vite server + hosted GitHub Pages).
+   * Extend with the PI_OFFICE_BRIDGE_ALLOWED_ORIGINS env var
+   * (comma-separated) when the add-in is hosted elsewhere.
+   */
+  private static readonly ALLOWED_ORIGINS: ReadonlySet<string> = new Set([
+    "https://localhost:3141",
+    "https://pi-excel.localhost",
+    "https://dieuluucanh.github.io",
+    ...parseExtraOrigins(),
+  ]);
+
+  private static resolveAllowOrigin(req: IncomingMessage): string | null {
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || origin.trim().length === 0) {
+      // Non-browser client (curl / tests / server tooling) — no CORS gate.
+      return "*";
+    }
+    if (OfficeBridgeServer.ALLOWED_ORIGINS.has(origin)) return origin;
+    return null; // Unknown browser origin → omit header; browser blocks.
+  }
+
+  /**
+   * Minimal loopback HTTP surface used by the add-in's "Test connection"
+   * probe and by curl. WebSocket upgrades are handled by `ws` at the server
+   * level; ordinary requests (GET /health, OPTIONS preflight) land here.
+   * The endpoint is unauthenticated but exposes only bridge metadata.
+   */
+  private handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
+    const urlRaw = req.url ?? "/";
+    let url: URL;
+    try {
+      url = new URL(urlRaw, "http://127.0.0.1");
+    } catch {
+      this.writeHttp(res, 400, { ok: false, error: "bad_request" }, req);
+      return;
+    }
+    const allowOrigin = OfficeBridgeServer.resolveAllowOrigin(req);
+
+    if (req.method === "OPTIONS") {
+      this.writeHttp(res, 204, null, req, allowOrigin);
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/health") {
+      const panes = this.attachedPanes().map((p) => ({
+        host: p.host,
+        paneId: p.paneId,
+        clientName: p.clientName,
+        connectedAt: p.connectedAt,
+        lastSeen: p.lastSeen,
+        model: p.model,
+        provider: p.provider,
+      }));
+
+          this.writeHttp(
+            res,
+            200,
+            {
+              ok: true,
+              service: this.serverName,
+              serverVersion: this.serverVersion,
+              capabilities: OfficeBridgeServer.CAPABILITIES,
+              protocolVersion: BRIDGE_PROTOCOL_VERSION,
+              piVersion: this.piVersion,
+              port: this.actualPort,
+              uptimeMs: Date.now() - this.startedAt,
+              panes,
+            },
+            req,
+            allowOrigin,
+          );
+      return;
+    }
+
+    this.writeHttp(
+      res,
+      404,
+      { ok: false, error: "not_found" },
+      req,
+      allowOrigin,
+    );
+  }
+
+  private writeHttp(
+    res: ServerResponse,
+    status: number,
+    body: unknown,
+    _req?: IncomingMessage,
+    allowOrigin: string | null = "*",
+  ): void {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+      // Loopback-only server. The Private-Network header keeps the probe
+      // working from the hosted GitHub Pages origin (public → localhost).
+      "Access-Control-Allow-Methods": "GET, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+      "Access-Control-Allow-Private-Network": "true",
+    };
+    if (allowOrigin !== null) {
+      headers["Access-Control-Allow-Origin"] = allowOrigin;
+      headers["Vary"] = "Origin";
+    }
+    res.writeHead(status, headers);
+    if (status === 204 || body === null) {
+      res.end();
+      return;
+    }
+    res.end(JSON.stringify(body));
+  }
+
   /* ── Internals ─────────────────────────────────────────────────────── */
 
   private findPane(host: OfficeHostApp): AttachedPane | null {
-    const sorted = [...this.panes].sort((a, b) => b.connectedAt - a.connectedAt);
+    const sorted = [...this.panes].sort(
+      (a, b) => b.connectedAt - a.connectedAt,
+    );
     return sorted.find((p) => p.host === host) ?? null;
   }
 
@@ -286,7 +446,10 @@ export class OfficeBridgeServer {
             protocolVersion: BRIDGE_PROTOCOL_VERSION,
             piVersion: this.piVersion,
             serverName: this.serverName,
+            serverVersion: this.serverVersion,
+            capabilities: [...OfficeBridgeServer.CAPABILITIES],
           });
+          this.notifyPanesChanged();
           break;
         }
         case "ping": {
@@ -333,7 +496,9 @@ export class OfficeBridgeServer {
     // Only the pane that received the call may answer it.
     const pane = this.panes.find((p) => p.ws === ws);
     if (!pane) {
-      call.reject(new Error("office-bridge: pane disconnected before answering"));
+      call.reject(
+        new Error("office-bridge: pane disconnected before answering"),
+      );
       return;
     }
 
@@ -341,25 +506,42 @@ export class OfficeBridgeServer {
     this.pending.delete(msg.id);
 
     if (!msg.ok) {
-      call.reject(new Error(`office-bridge: ${msg.error ?? "office tool failed"}`));
+      call.reject(
+        new Error(`office-bridge: ${msg.error ?? "office tool failed"}`),
+      );
       return;
     }
 
-    const text = msg.text.length > MAX_TEXT_CHARS
-      ? `${msg.text.slice(0, MAX_TEXT_CHARS)}\n…[truncated: ${msg.text.length - MAX_TEXT_CHARS} chars]`
-      : msg.text;
+    const text =
+      msg.text.length > MAX_TEXT_CHARS
+        ? `${msg.text.slice(0, MAX_TEXT_CHARS)}\n…[truncated: ${msg.text.length - MAX_TEXT_CHARS} chars]`
+        : msg.text;
 
     let details: unknown = msg.details;
     if (details !== undefined) {
       const bytes = Buffer.byteLength(JSON.stringify(details));
       if (bytes > MAX_DETAILS_BYTES) {
-        details = { truncated: true, note: `details exceeded ${MAX_DETAILS_BYTES} bytes` };
+        details = {
+          truncated: true,
+          note: `details exceeded ${MAX_DETAILS_BYTES} bytes`,
+        };
       }
     }
 
     call.resolve({ text, details });
   }
 
+  /** Notify the host that the attached-pane set changed. Never throws. */
+  private notifyPanesChanged(): void {
+    try {
+      this.handlers.onPanesChanged?.(this.attachedPanes());
+    } catch (error) {
+      console.error(
+        `[office-bridge] onPanesChanged handler failed: ${String(error)}`,
+      );
+    }
+  }
+
   private detachPane(pane: AttachedPane): void {
     const idx = this.panes.findIndex((p) => p === pane);
     if (idx >= 0) this.panes.splice(idx, 1);
@@ -368,9 +550,15 @@ export class OfficeBridgeServer {
     // reject them — tracked separately so we sweep all on disconnect).
     for (const [id, call] of this.pending) {
       clearTimeout(call.timer);
-      call.reject(new Error("office-bridge: pane disconnected while the tool was running"));
+      call.reject(
+        new Error(
+          "office-bridge: pane disconnected while the tool was running",
+        ),
+      );
       this.pending.delete(id);
     }
+
+    this.notifyPanesChanged();
   }
 
   private startHeartbeat(): void {
@@ -387,7 +575,10 @@ export class OfficeBridgeServer {
     }, HEARTBEAT_INTERVAL_MS);
   }
 
-  private sendToPane(pane: WebSocket | AttachedPane, message: ServerMessage): boolean {
+  private sendToPane(
+    pane: WebSocket | AttachedPane,
+    message: ServerMessage,
+  ): boolean {
     const ws = pane instanceof WebSocket ? pane : pane.ws;
     if (ws.readyState !== WebSocket.OPEN) return false;
     try {

package/src/index.ts

@@ -21,6 +21,9 @@ import type {
   RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { BRIDGE_DEFAULT_PORT } from "./protocol.js";
 import type { AttachedPane } from "./bridge-server.js";
@@ -46,6 +49,24 @@ function piVersion(): string | null {
   }
 }
 
+/**
+ * The bridge extension's own package version, read from the `package.json`
+ * that ships next to this module. Falls back to `"unknown"` so a bundled or
+ * relocated install never breaks the `welcome` frame.
+ */
+function serverVersion(): string {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const raw = readFileSync(resolve(here, "..", "package.json"), "utf8");
+    const pkg = JSON.parse(raw) as { version?: unknown };
+    return typeof pkg.version === "string" && pkg.version.length > 0
+      ? pkg.version
+      : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 export default function (pi: ExtensionAPI): void {
   let server: OfficeBridgeServer | null = null;
   let currentCtx: ExtensionContext | null = null;
@@ -89,6 +110,17 @@ export default function (pi: ExtensionAPI): void {
     ui.setStatus("office-bridge", `office: ${labels} attached (bridge :${port})`);
   }
 
+  let panesChangedTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /** Debounced status refresh triggered by pane attach/detach (~100 ms). */
+  function scheduleStatusUpdate(): void {
+    if (panesChangedTimer !== null) clearTimeout(panesChangedTimer);
+    panesChangedTimer = setTimeout(() => {
+      panesChangedTimer = null;
+      updateStatus();
+    }, 100);
+  }
+
   /** Extract display text from an assistant message content payload. */
   function flattenAssistantText(content: unknown): string {
     if (typeof content === "string") return content;
@@ -120,6 +152,9 @@ export default function (pi: ExtensionAPI): void {
         _onUpdate,
         _ctx,
       ): Promise<AgentToolResult<unknown>> {
+        // SAFETY: `Params` is the TypeBox-derived shape of
+        // `descriptor.parameters` (always an object); the bridge forwards it
+        // verbatim as the Office.js args record, so this widening is sound.
         const args = params as unknown as Record<string, unknown>;
         const active = server;
         if (!active?.isRunning) {
@@ -154,6 +189,7 @@ export default function (pi: ExtensionAPI): void {
     const bridge = new OfficeBridgeServer({
       port,
       serverName: "pi-office-bridge",
+      serverVersion: serverVersion(),
       piVersion: piVersion(),
       handlers: {
         onUserMessage: (text, pane) => {
@@ -163,6 +199,9 @@ export default function (pi: ExtensionAPI): void {
           // triggers a turn; if a turn is running it is queued until it settles.
           pi.sendUserMessage(text, { deliverAs: "followUp" });
         },
+        // Keep the TUI status line live: flip to "Excel attached" the moment
+        // the pane connects instead of waiting for the next message.
+        onPanesChanged: () => scheduleStatusUpdate(),
       },
     });
 
@@ -172,7 +211,17 @@ export default function (pi: ExtensionAPI): void {
       ctx.ui.notify(`Office bridge listening on ws://127.0.0.1:${port}`, "info");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      ctx.ui.notify(`Office bridge failed to start: ${message}`, "error");
+      const code = (error as NodeJS.ErrnoException | null)?.code;
+      if (code === "EADDRINUSE") {
+        ctx.ui.notify(
+          `Office bridge: port ${port} is already in use — another Pi process ` +
+            `is running the bridge. Start this one on a free port with ` +
+            `--${FLAG_PORT} <port> or PI_OFFICE_BRIDGE_PORT=<port>.`,
+          "error",
+        );
+      } else {
+        ctx.ui.notify(`Office bridge failed to start: ${message}`, "error");
+      }
       console.error(`[office-bridge] start failed: ${message}`);
     }
     updateStatus();
@@ -181,6 +230,10 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_shutdown", async () => {
     currentCtx = null;
     pendingReplyTargets.length = 0;
+    if (panesChangedTimer !== null) {
+      clearTimeout(panesChangedTimer);
+      panesChangedTimer = null;
+    }
     const active = server;
     server = null;
     if (active) {
@@ -199,6 +252,8 @@ export default function (pi: ExtensionAPI): void {
 
     const text = flattenAssistantText(event.message.content);
     if (!text) return;
+    // SAFETY: assistant messages may carry an id that the Pi event type does
+    // not surface; read it through a narrow shape check before using it.
     const maybeId = (event.message as unknown as { id?: unknown }).id;
     server.broadcast({
       type: "agent_message",