@dieulc/pi-office-bridge 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @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

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@dieulc/pi-office-bridge",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dieuluucanh/pi-for-office"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "office",
+    "excel",
+    "word",
+    "powerpoint",
+    "bridge",
+    "extension"
+  ],
+  "dependencies": {
+    "@dieulc/pi-office-protocol": "*",
+    "typebox": "^1.3.10",
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.0",
+    "@earendil-works/pi-ai": ">=0.83.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "^22.20.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.9.0"
+  },
+  "files": [
+    "src/index.ts",
+    "src/bridge-server.ts",
+    "src/office-tools.ts",
+    "src/protocol.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test:smoke": "npm run build && node tests/smoke.mjs",
+    "test:interop": "npm run build && node tests/pane-interop.mjs",
+    "test": "npm run test:smoke && npm run test:interop"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/bridge-server.ts

@@ -0,0 +1,404 @@
+/**
+ * Bridge server — a loopback-only WebSocket server inside the Pi process.
+ *
+ * The pi-for-office task pane connects here. This module owns the socket
+ * lifecycle, the attached-pane registry, and the pending tool-call correlation
+ * map. It has no Pi knowledge; the extension entry point (`index.ts`) wires it
+ * to the Pi session.
+ */
+
+import { WebSocketServer, WebSocket } from "ws";
+import type { Server as HttpServer } from "node:http";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+import {
+  BRIDGE_PROTOCOL_VERSION,
+  nextCallId,
+  parseClientMessage,
+  type ClientMessage,
+  type OfficeHostApp,
+  type ServerMessage,
+  type ToolResultMessage,
+} from "./protocol.js";
+
+export interface AttachedPane {
+  ws: WebSocket;
+  host: OfficeHostApp;
+  paneId: string;
+  clientName: string;
+  connectedAt: number;
+  lastSeen: number;
+  model?: string;
+  provider?: string;
+}
+
+export interface BridgeServerHandlers {
+  /** A user typed a prompt in the add-in sidebar. */
+  onUserMessage(text: string, pane: AttachedPane): void;
+}
+
+export interface CallOfficeToolResult {
+  text: string;
+  details?: unknown;
+}
+
+const HELLO_TIMEOUT_MS = 10_000;
+const TOOL_CALL_TIMEOUT_MS = 120_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const MAX_TEXT_CHARS = 50_000;
+const MAX_DETAILS_BYTES = 1_000_000;
+
+interface PendingCall {
+  resolve(result: CallOfficeToolResult): void;
+  reject(error: Error): void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class OfficeBridgeServer {
+  private readonly port: number;
+  private readonly handlers: BridgeServerHandlers;
+  private readonly serverName: string;
+  private readonly piVersion: string | null;
+
+  private httpServer: HttpServer | null = null;
+  private wss: WebSocketServer | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  private readonly panes: AttachedPane[] = [];
+  private readonly pending = new Map<string, PendingCall>();
+
+  constructor(options: {
+    port: number;
+    serverName?: string;
+    piVersion?: string | null;
+    handlers: BridgeServerHandlers;
+  }) {
+    this.port = options.port;
+    this.serverName = options.serverName ?? "pi-office-bridge";
+    this.piVersion = options.piVersion ?? null;
+    this.handlers = options.handlers;
+  }
+
+  get isRunning(): boolean {
+    return this.wss !== null;
+  }
+
+  get actualPort(): number | null {
+    const addr = this.httpServer?.address();
+    return typeof addr === "object" && addr !== null ? (addr as AddressInfo).port : null;
+  }
+
+  /** Pane list copy (ordered by most recent connection first). */
+  attachedPanes(): readonly AttachedPane[] {
+    return [...this.panes].sort((a, b) => b.connectedAt - a.connectedAt);
+  }
+
+  /** Start listening. Idempotent. Resolves once the socket is bound. */
+  start(): Promise<void> {
+    if (this.wss) return Promise.resolve();
+
+    const httpServer = createServer();
+    const wss = new WebSocketServer({ server: httpServer, maxPayload: 16 * 1024 * 1024 });
+
+    this.httpServer = httpServer;
+    this.wss = wss;
+
+    wss.on("connection", (ws) => this.handleConnection(ws));
+    wss.on("error", (error) => {
+      console.error(`[office-bridge] server error: ${String(error)}`);
+    });
+
+    return new Promise((resolve, reject) => {
+      const onError = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      const cleanup = () => {
+        httpServer.off("listening", onListening);
+        httpServer.off("error", onError);
+      };
+      const onListening = () => {
+        cleanup();
+        this.startHeartbeat();
+        resolve();
+      };
+      httpServer.once("listening", onListening);
+      httpServer.once("error", onError);
+      httpServer.listen(this.port, "127.0.0.1");
+    });
+  }
+
+  /** Close the server and drop all panes. Idempotent. */
+  stop(): Promise<void> {
+    if (!this.wss) return Promise.resolve();
+
+    const wss = this.wss;
+    const httpServer = this.httpServer;
+    this.wss = null;
+    this.httpServer = null;
+
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
+    for (const call of this.pending.values()) {
+      clearTimeout(call.timer);
+      call.reject(new Error("office-bridge: server stopped"));
+    }
+    this.pending.clear();
+
+    for (const pane of this.panes) {
+      pane.ws.close(1001, "bridge shutting down");
+    }
+    this.panes.length = 0;
+
+    return new Promise((resolve) => {
+      wss.close(() => resolve());
+      if (httpServer) {
+        httpServer.close(() => resolve());
+      }
+    });
+  }
+
+  /**
+   * Proxy one Office.js operation to the most recent pane attached for `host`.
+   * Resolves with the pane's tool_result, rejects when no pane is attached, the
+   * call times out, the pane disconnects, or the caller's signal aborts.
+   */
+  callOfficeTool(
+    host: OfficeHostApp,
+    op: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+    timeoutMs: number = TOOL_CALL_TIMEOUT_MS,
+  ): Promise<CallOfficeToolResult> {
+    const pane = this.findPane(host);
+    if (!pane) {
+      return Promise.reject(
+        new Error(
+          `office-bridge: no ${host} workbook/document is attached. ` +
+            "Open the document in the Office add-in (pi-for-office) to enable this tool.",
+        ),
+      );
+    }
+
+    const id = nextCallId("tool");
+    const message: ServerMessage = {
+      type: "tool_call",
+      id,
+      tool: `${host}.${op}`,
+      args,
+    };
+
+    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`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const onAbort = () => {
+        const call = this.pending.get(id);
+        if (!call) return;
+        clearTimeout(call.timer);
+        this.pending.delete(id);
+        reject(new Error("office-bridge: tool call aborted by the agent"));
+      };
+
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      signal?.addEventListener("abort", onAbort, { once: true });
+
+      if (!this.sendToPane(pane, message)) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(new Error("office-bridge: pane disconnected before the tool call was sent"));
+      }
+    });
+  }
+
+  /** Push a message to every attached pane. */
+  broadcast(message: ServerMessage): void {
+    for (const pane of this.panes) {
+      this.sendToPane(pane, message);
+    }
+  }
+
+  /* ── Internals ─────────────────────────────────────────────────────── */
+
+  private findPane(host: OfficeHostApp): AttachedPane | null {
+    const sorted = [...this.panes].sort((a, b) => b.connectedAt - a.connectedAt);
+    return sorted.find((p) => p.host === host) ?? null;
+  }
+
+  private handleConnection(ws: WebSocket): void {
+    let pane: AttachedPane | null = null;
+
+    const helloTimer = setTimeout(() => {
+      if (!pane) {
+        ws.close(1008, "bridge: hello not received in time");
+      }
+    }, HELLO_TIMEOUT_MS);
+
+    ws.on("message", (raw) => {
+      let msg: ClientMessage;
+      try {
+        msg = parseClientMessage(raw.toString());
+      } catch (error) {
+        this.sendError(ws, "bad_message", String(error));
+        return;
+      }
+
+      switch (msg.type) {
+        case "hello": {
+          if (msg.protocolVersion !== BRIDGE_PROTOCOL_VERSION) {
+            this.sendError(
+              ws,
+              "protocol_mismatch",
+              `bridge: client protocol v${msg.protocolVersion} does not match server v${BRIDGE_PROTOCOL_VERSION}`,
+            );
+            ws.close(1008, "protocol mismatch");
+            return;
+          }
+          pane = {
+            ws,
+            host: msg.host,
+            paneId: msg.paneId,
+            clientName: msg.clientName,
+            connectedAt: Date.now(),
+            lastSeen: Date.now(),
+          };
+          // A pane reconnecting replaces any older pane with the same paneId.
+          this.panes.splice(
+            0,
+            this.panes.length,
+            ...this.panes.filter((p) => p.paneId !== pane!.paneId),
+            pane,
+          );
+          clearTimeout(helloTimer);
+          this.sendToPane(ws, {
+            type: "welcome",
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            piVersion: this.piVersion,
+            serverName: this.serverName,
+          });
+          break;
+        }
+        case "ping": {
+          this.sendToPane(ws, { type: "pong", ts: msg.ts });
+          break;
+        }
+        case "tool_result": {
+          if (pane) pane.lastSeen = Date.now();
+          this.handleToolResult(msg, ws);
+          break;
+        }
+        case "user_message": {
+          if (!pane) return;
+          pane.lastSeen = Date.now();
+          const text = msg.text?.trim();
+          if (text) this.handlers.onUserMessage(text, pane);
+          break;
+        }
+        case "status": {
+          if (!pane) return;
+          pane.lastSeen = Date.now();
+          if (msg.model !== undefined) pane.model = msg.model;
+          if (msg.provider !== undefined) pane.provider = msg.provider;
+          break;
+        }
+      }
+    });
+
+    ws.on("close", () => {
+      clearTimeout(helloTimer);
+      if (pane) this.detachPane(pane);
+    });
+
+    ws.on("error", () => {
+      clearTimeout(helloTimer);
+      if (pane) this.detachPane(pane);
+    });
+  }
+
+  private handleToolResult(msg: ToolResultMessage, ws: WebSocket): void {
+    const call = this.pending.get(msg.id);
+    if (!call) return;
+
+    // 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"));
+      return;
+    }
+
+    clearTimeout(call.timer);
+    this.pending.delete(msg.id);
+
+    if (!msg.ok) {
+      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;
+
+    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` };
+      }
+    }
+
+    call.resolve({ text, details });
+  }
+
+  private detachPane(pane: AttachedPane): void {
+    const idx = this.panes.findIndex((p) => p === pane);
+    if (idx >= 0) this.panes.splice(idx, 1);
+
+    // Reject any pending calls owned by this pane (best-effort: find calls and
+    // 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"));
+      this.pending.delete(id);
+    }
+  }
+
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(() => {
+      for (const pane of this.panes) {
+        const alive = pane.ws.readyState === WebSocket.OPEN;
+        if (!alive) {
+          pane.ws.terminate();
+          this.detachPane(pane);
+        } else if (Date.now() - pane.lastSeen > HEARTBEAT_INTERVAL_MS * 3) {
+          pane.ws.ping();
+        }
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private sendToPane(pane: WebSocket | AttachedPane, message: ServerMessage): boolean {
+    const ws = pane instanceof WebSocket ? pane : pane.ws;
+    if (ws.readyState !== WebSocket.OPEN) return false;
+    try {
+      ws.send(JSON.stringify(message));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private sendError(ws: WebSocket, code: string, message: string): void {
+    this.sendToPane(ws, { type: "error", code, message });
+  }
+}

package/src/index.ts

@@ -0,0 +1,292 @@
+/**
+ * pi-office-bridge — native Pi extension.
+ *
+ * Runs a loopback WebSocket server inside the local Pi process so the
+ * pi-for-office task-pane add-in (Excel / Word / PowerPoint) can attach.
+ *
+ *  - Registers `office_<host>_<op>` tools the Pi agent can call; each call is
+ *    proxied to the attached pane, which executes the Office.js operation.
+ *  - Injects pane-typed prompts into the Pi session and streams the assistant
+ *    reply back to the pane.
+ *
+ * Pure extension: uses only the public extension API — Pi core is never
+ * touched, so Pi can be updated freely.
+ */
+
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  RegisteredCommand,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+import { BRIDGE_DEFAULT_PORT } from "./protocol.js";
+import type { AttachedPane } from "./bridge-server.js";
+import { OfficeBridgeServer } from "./bridge-server.js";
+import {
+  OFFICE_TOOL_DESCRIPTORS,
+  hostForToolName,
+  OFFICE_TOOL_NAMES,
+  HOST_APP_LABEL,
+} from "./office-tools.js";
+import type { OfficeToolDescriptor } from "./office-tools.js";
+
+const FLAG_PORT = "office-bridge-port";
+
+/** Which Pi version we run inside (shown in the pane's welcome frame). */
+function piVersion(): string | null {
+  try {
+    // The coding-agent package exposes its version via package.json at runtime.
+    // Fall back to process env when unavailable.
+    return process.env.PI_VERSION ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export default function (pi: ExtensionAPI): void {
+  let server: OfficeBridgeServer | null = null;
+  let currentCtx: ExtensionContext | null = null;
+
+  /** Panes awaiting the assistant reply to their injected prompt. */
+  const pendingReplyTargets: AttachedPane[] = [];
+
+  pi.registerFlag(FLAG_PORT, {
+    description: `Port for the pi-office bridge server (default ${BRIDGE_DEFAULT_PORT})`,
+    type: "string",
+  });
+
+  function resolvePort(): number {
+    const raw = pi.getFlag(FLAG_PORT);
+    if (typeof raw === "string" && raw.trim() !== "") {
+      const parsed = Number.parseInt(raw.trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0 && parsed < 65536) return parsed;
+    }
+    const env = process.env.PI_OFFICE_BRIDGE_PORT;
+    if (env) {
+      const parsed = Number.parseInt(env, 10);
+      if (Number.isFinite(parsed) && parsed > 0 && parsed < 65536) return parsed;
+    }
+    return BRIDGE_DEFAULT_PORT;
+  }
+
+  function updateStatus(): void {
+    const ui = currentCtx?.ui;
+    if (!ui) return;
+    const panes = server?.attachedPanes() ?? [];
+    if (!server?.isRunning) {
+      ui.setStatus("office-bridge", undefined);
+      return;
+    }
+    const port = server.actualPort ?? resolvePort();
+    if (panes.length === 0) {
+      ui.setStatus("office-bridge", `office bridge on :${port} — no app attached`);
+      return;
+    }
+    const labels = panes.map((p) => HOST_APP_LABEL[p.host]).join(", ");
+    ui.setStatus("office-bridge", `office: ${labels} attached (bridge :${port})`);
+  }
+
+  /** Extract display text from an assistant message content payload. */
+  function flattenAssistantText(content: unknown): string {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    const parts: string[] = [];
+    for (const part of content) {
+      if (typeof part !== "object" || part === null) continue;
+      const p = part as { type?: unknown; text?: unknown };
+      if (p.type === "text" && typeof p.text === "string") parts.push(p.text);
+      if (p.type === "thinking" && typeof p.text === "string") parts.push(p.text);
+    }
+    return parts.join("\n").trim();
+  }
+
+  function registerOfficeTool(descriptor: OfficeToolDescriptor): void {
+    type Params = Static<typeof descriptor.parameters>;
+
+    pi.registerTool({
+      name: descriptor.name,
+      label: descriptor.label,
+      description: descriptor.description,
+      promptGuidelines: descriptor.promptGuidelines,
+      parameters: descriptor.parameters,
+      executionMode: "sequential",
+      async execute(
+        _toolCallId: string,
+        params: Params,
+        signal: AbortSignal | undefined,
+        _onUpdate,
+        _ctx,
+      ): Promise<AgentToolResult<unknown>> {
+        const args = params as unknown as Record<string, unknown>;
+        const active = server;
+        if (!active?.isRunning) {
+          throw new Error(
+            `office-bridge: server is not running. Check the Pi extension loaded, then open the add-in.`,
+          );
+        }
+        const result = await active.callOfficeTool(descriptor.host, descriptor.op, args, signal);
+        return { content: [{ type: "text", text: result.text }], details: result.details };
+      },
+    });
+  }
+
+  function registerAllOfficeTools(): void {
+    for (const descriptor of OFFICE_TOOL_DESCRIPTORS) {
+      registerOfficeTool(descriptor);
+    }
+  }
+
+  /* ── lifecycle ─────────────────────────────────────────────────────── */
+
+  pi.on("session_start", async (_event, ctx) => {
+    currentCtx = ctx;
+    registerAllOfficeTools();
+
+    if (server?.isRunning) {
+      updateStatus();
+      return;
+    }
+
+    const port = resolvePort();
+    const bridge = new OfficeBridgeServer({
+      port,
+      serverName: "pi-office-bridge",
+      piVersion: piVersion(),
+      handlers: {
+        onUserMessage: (text, pane) => {
+          pendingReplyTargets.push(pane);
+          updateStatus();
+          // followUp: if Pi is idle the message is delivered immediately and
+          // triggers a turn; if a turn is running it is queued until it settles.
+          pi.sendUserMessage(text, { deliverAs: "followUp" });
+        },
+      },
+    });
+
+    try {
+      await bridge.start();
+      server = bridge;
+      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");
+      console.error(`[office-bridge] start failed: ${message}`);
+    }
+    updateStatus();
+  });
+
+  pi.on("session_shutdown", async () => {
+    currentCtx = null;
+    pendingReplyTargets.length = 0;
+    const active = server;
+    server = null;
+    if (active) {
+      await active.stop();
+    }
+  });
+
+  /* ── agent → pane forwarding ───────────────────────────────────────── */
+
+  // Forward the final assistant reply to the pane that prompted it.
+  pi.on("message_end", async (event, _ctx) => {
+    if (event.message.role !== "assistant") return;
+    if (!server?.isRunning) return;
+    const target = pendingReplyTargets.shift();
+    if (!target) return;
+
+    const text = flattenAssistantText(event.message.content);
+    if (!text) return;
+    const maybeId = (event.message as unknown as { id?: unknown }).id;
+    server.broadcast({
+      type: "agent_message",
+      kind: "final",
+      text,
+      messageId: typeof maybeId === "string" ? maybeId : undefined,
+    });
+    updateStatus();
+  });
+
+  // Forward progress of non-office tools while a pane is awaiting a reply.
+  pi.on("tool_execution_start", async (event) => {
+    if (!server?.isRunning) return;
+    if (pendingReplyTargets.length === 0) return;
+    if (hostForToolName(event.toolName) !== null) return;
+    server.broadcast({
+      type: "tool_activity",
+      tool: event.toolName,
+      status: "start",
+      summary: summarizeArgs(event.toolName, event.args),
+    });
+  });
+
+  pi.on("tool_execution_end", async (event) => {
+    if (!server?.isRunning) return;
+    if (pendingReplyTargets.length === 0) return;
+    if (hostForToolName(event.toolName) !== null) return;
+    server.broadcast({
+      type: "tool_activity",
+      tool: event.toolName,
+      status: event.isError ? "error" : "end",
+      summary: event.isError ? String(event.result ?? "tool failed") : undefined,
+    });
+  });
+
+  /* ── commands ──────────────────────────────────────────────────────── */
+
+  const officeCommand: Omit<RegisteredCommand, "name" | "sourceInfo"> = {
+    description:
+      "Show the pi-office bridge status: server port and attached Office apps (Excel/Word/PowerPoint).",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      const active = server;
+      if (!active?.isRunning) {
+        ctx.ui.notify("Office bridge is not running.", "warning");
+        return;
+      }
+      const port = active.actualPort ?? resolvePort();
+      const panes = active.attachedPanes();
+      if (panes.length === 0) {
+        ctx.ui.notify(`Office bridge is listening on :${port} — no app attached yet.`, "info");
+        return;
+      }
+      const lines = panes.map((p) => {
+        const model = p.model ? `, model=${p.model}` : "";
+        const provider = p.provider ? `, provider=${p.provider}` : "";
+        const ago = Math.max(0, Math.round((Date.now() - p.lastSeen) / 1000));
+        return `- ${HOST_APP_LABEL[p.host]} (${p.clientName}, pane ${p.paneId.slice(0, 8)})${model}${provider}, seen ${ago}s ago`;
+      });
+      ctx.ui.notify(`Office bridge on :${port}\n${lines.join("\n")}`, "info");
+    },
+  };
+
+  pi.registerCommand("office", officeCommand);
+
+  // Also list every office tool we exposed so users can confirm them:
+  pi.registerCommand("office-tools", {
+    description: "List the office tools registered by the pi-office bridge extension.",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      ctx.ui.notify(
+        `Office tools (${OFFICE_TOOL_NAMES.length}):\n${OFFICE_TOOL_NAMES.join("\n")}`,
+        "info",
+      );
+    },
+  });
+}
+
+/** Compact one-line summary of a non-office tool call for the pane UI. */
+function summarizeArgs(tool: string, args: unknown): string {
+  if (tool === "bash" || tool === "powershell") {
+    const command = (args as { command?: unknown })?.command;
+    if (typeof command === "string") {
+      const oneLine = command.replace(/\s+/g, " ").trim();
+      return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
+    }
+  }
+  if (tool === "read" || tool === "write" || tool === "edit") {
+    const path = (args as { path?: unknown })?.path;
+    if (typeof path === "string") return path;
+  }
+  return tool;
+}

package/src/office-tools.ts

@@ -0,0 +1,262 @@
+/**
+ * Office tool catalog — the Office.js operations the Pi agent can drive
+ * through the bridge.
+ *
+ * Each descriptor is host-scoped (excel / word / powerpoint). The task-pane
+ * add-in executes the actual Office.js call; this extension only describes the
+ * tool to the LLM and routes the call over the bridge.
+ *
+ * Keep `op` values in sync with the add-in's `bridge/tool-registry.ts` (same
+ * repository, `packages/add-in`). The pane validates args again at runtime, so
+ * this file is the *contract*, not the enforcement point.
+ */
+
+import { Type, type TSchema } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { OfficeHostApp } from "./protocol.js";
+
+export interface OfficeToolDescriptor {
+  /** Host app that can execute this op. */
+  host: OfficeHostApp;
+  /** Payload op id, namespaced by host: "excel.read_range". */
+  op: string;
+  /** Pi-registered tool name, e.g. "office_excel_read_range". */
+  name: string;
+  label: string;
+  description: string;
+  promptGuidelines?: string[];
+  parameters: TSchema;
+}
+
+/** Office apps we currently expose tools for (map host → tool prefix). */
+export const HOST_APP_LABEL: Record<OfficeHostApp, string> = {
+  excel: "Excel",
+  word: "Word",
+  powerpoint: "PowerPoint",
+};
+
+function officeToolName(host: OfficeHostApp, op: string): string {
+  return `office_${host}_${op}`;
+}
+
+/* ── Excel ───────────────────────────────────────────────────────────── */
+
+const EXCEL_READ_RANGE_SCHEMA = Type.Object({
+  range: Type.String({
+    description:
+      'Cell range in A1 notation, e.g. "A1:D10" or "Sheet2!A1:B5". ' +
+      "Uses the active sheet when no sheet is specified.",
+  }),
+  mode: Type.Optional(
+    StringEnum(["compact", "csv", "detailed"], {
+      description:
+        '"compact" (default): markdown table. "csv": raw values. "detailed": with formulas/formats.',
+    }),
+  ),
+});
+
+/* ── Word ────────────────────────────────────────────────────────────── */
+
+const WORD_READ_SCOPE = StringEnum(["all", "selection"], {
+  description: '"all": whole document. "selection": currently selected text only.',
+});
+
+/* ── PowerPoint ──────────────────────────────────────────────────────── */
+
+const PPT_SLIDE_INDEX = Type.Integer({
+  minimum: 1,
+  description: "1-based slide index.",
+});
+
+/* ── Catalog ─────────────────────────────────────────────────────────── */
+
+export const OFFICE_TOOL_DESCRIPTORS: OfficeToolDescriptor[] = [
+  /* Excel */
+  {
+    host: "excel",
+    op: "get_overview",
+    name: officeToolName("excel", "get_overview"),
+    label: "Excel Workbook Overview",
+    description:
+      "Read a compact overview of the attached Excel workbook: sheet names, used ranges, " +
+      "table names, and named ranges. Call this first before any range operation.",
+    promptGuidelines: [
+      "Call office_excel_get_overview before office_excel_read_range to learn the workbook structure.",
+    ],
+    parameters: Type.Object({}),
+  },
+  {
+    host: "excel",
+    op: "read_range",
+    name: officeToolName("excel", "read_range"),
+    label: "Excel Read Range",
+    description:
+      "Read cell values (and optionally formulas/formatting) from a range in the attached Excel workbook.",
+    parameters: EXCEL_READ_RANGE_SCHEMA,
+  },
+  {
+    host: "excel",
+    op: "write_cells",
+    name: officeToolName("excel", "write_cells"),
+    label: "Excel Write Cells",
+    description:
+      "Write a 2D array of values into the attached Excel workbook, starting at a top-left cell. " +
+      "values[row][col]; the array is written down and to the right from start_cell.",
+    promptGuidelines: [
+      "Prefer office_excel_write_cells in a single batched call instead of many small edits.",
+      "Always verify with office_excel_read_range after office_excel_write_cells when the change is user-visible.",
+    ],
+    parameters: Type.Object({
+      start_cell: Type.String({
+        description: 'Top-left cell to write from, e.g. "A1" or "Sheet2!B3".',
+      }),
+      values: Type.Array(Type.Array(Type.Any()), {
+        description: "2D array of cell values (rows × cols).",
+      }),
+    }),
+  },
+  {
+    host: "excel",
+    op: "fill_formula",
+    name: officeToolName("excel", "fill_formula"),
+    label: "Excel Fill Formula",
+    description:
+      "Write a formula into a single contiguous range of the attached Excel workbook. " +
+      "Relative references adjust as the formula fills.",
+    parameters: Type.Object({
+      range: Type.String({ description: 'Target range, e.g. "B2:B20" or "Sheet1!C3:F20".' }),
+      formula: Type.String({
+        description: 'Formula starting with "=", e.g. "=SUM(B2:B10)".',
+      }),
+    }),
+  },
+
+  /* Word */
+  {
+    host: "word",
+    op: "get_overview",
+    name: officeToolName("word", "get_overview"),
+    label: "Word Document Overview",
+    description:
+      "Read a compact overview of the attached Word document: heading outline, paragraph count, " +
+      "table count, and word count. Call this first before editing.",
+    promptGuidelines: [
+      "Call office_word_get_overview before office_word_insert_text or office_word_replace_text.",
+    ],
+    parameters: Type.Object({}),
+  },
+  {
+    host: "word",
+    op: "read_document",
+    name: officeToolName("word", "read_document"),
+    label: "Word Read Document",
+    description:
+      "Read text from the attached Word document: the whole body or the current selection.",
+    parameters: Type.Object({
+      scope: Type.Optional(WORD_READ_SCOPE),
+      maxChars: Type.Optional(
+        Type.Integer({
+          minimum: 100,
+          maximum: 200000,
+          description: "Cap on characters returned (default 20000).",
+        }),
+      ),
+    }),
+  },
+  {
+    host: "word",
+    op: "insert_text",
+    name: officeToolName("word", "insert_text"),
+    label: "Word Insert Text",
+    description:
+      "Insert text at the start or end of the attached Word document, or replace the current selection.",
+    parameters: Type.Object({
+      text: Type.String({ description: "Text to insert." }),
+      location: Type.Optional(
+        StringEnum(["start", "end", "replace_selection"], {
+          description: '"end" (default) appends to the document. "replace_selection" overwrites the selection.',
+        }),
+      ),
+    }),
+  },
+  {
+    host: "word",
+    op: "replace_text",
+    name: officeToolName("word", "replace_text"),
+    label: "Word Replace Text",
+    description:
+      "Find and replace literal text in the attached Word document. Returns how many occurrences were replaced.",
+    parameters: Type.Object({
+      find: Type.String({ description: "Literal text to find." }),
+      replace: Type.String({ description: "Replacement text." }),
+      matchCase: Type.Optional(Type.Boolean({ description: "Case-sensitive match (default false)." })),
+    }),
+  },
+
+  /* PowerPoint */
+  {
+    host: "powerpoint",
+    op: "get_overview",
+    name: officeToolName("powerpoint", "get_overview"),
+    label: "PowerPoint Overview",
+    description:
+      "Read a compact overview of the attached presentation: slide count, each slide's title and " +
+      "shape count. Call this first before any slide operation.",
+    promptGuidelines: [
+      "Call office_powerpoint_get_overview before office_powerpoint_read_slide or office_powerpoint_add_slide.",
+    ],
+    parameters: Type.Object({}),
+  },
+  {
+    host: "powerpoint",
+    op: "read_slide",
+    name: officeToolName("powerpoint", "read_slide"),
+    label: "PowerPoint Read Slide",
+    description:
+      "Read all text content of one slide in the attached presentation (shapes, text frames, notes).",
+    parameters: Type.Object({
+      slideIndex: PPT_SLIDE_INDEX,
+    }),
+  },
+  {
+    host: "powerpoint",
+    op: "add_slide",
+    name: officeToolName("powerpoint", "add_slide"),
+    label: "PowerPoint Add Slide",
+    description:
+      "Append a new slide to the attached presentation and navigate to it. Uses the default layout.",
+    parameters: Type.Object({}),
+  },
+  {
+    host: "powerpoint",
+    op: "add_text_box",
+    name: officeToolName("powerpoint", "add_text_box"),
+    label: "PowerPoint Add Text Box",
+    description:
+      "Add a text box with the given text to a slide. Coordinates/geometry are in points.",
+    parameters: Type.Object({
+      slideIndex: PPT_SLIDE_INDEX,
+      text: Type.String({ description: "Text box content." }),
+      x: Type.Optional(Type.Number({ description: "Left edge in points (default centered)." })),
+      y: Type.Optional(Type.Number({ description: "Top edge in points (default centered)." })),
+      width: Type.Optional(Type.Number({ description: "Width in points (default 400)." })),
+      height: Type.Optional(Type.Number({ description: "Height in points (default 60)." })),
+    }),
+  },
+];
+
+/** Index by op id for fast lookup. */
+export const OFFICE_TOOL_BY_OP: ReadonlyMap<string, OfficeToolDescriptor> = new Map(
+  OFFICE_TOOL_DESCRIPTORS.map((d) => [`${d.host}.${d.op}`, d]),
+);
+
+/** All tool names registered by this extension. */
+export const OFFICE_TOOL_NAMES: readonly string[] = OFFICE_TOOL_DESCRIPTORS.map((d) => d.name);
+
+/** The office host this tool name drives, or null when unknown. */
+export function hostForToolName(name: string): OfficeHostApp | null {
+  for (const d of OFFICE_TOOL_DESCRIPTORS) {
+    if (d.name === name) return d.host;
+  }
+  return null;
+}

package/src/protocol.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-export of the shared bridge protocol.
+ *
+ * The single source of truth lives in `@dieulc/pi-office-protocol` so the Pi
+ * extension (server) and the add-in task pane (client) stay in lockstep.
+ */
+export * from "@dieulc/pi-office-protocol";