@dieulc/pi-office-bridge 0.2.0 → 0.3.0

package/README.md

@@ -37,6 +37,17 @@ Two flows:
 pi install npm:@dieulc/pi-office-bridge
 ```
 
+**Update to the latest** (the add-in's `/health` probe and version display
+require ≥ 0.2.0):
+
+```bash
+pi install npm:@dieulc/pi-office-bridge@latest
+```
+
+Then restart Pi. Note that `pi install` pins the version it fetched into
+`~/.pi/agent/npm/package.json`, so Pi will **not** auto-upgrade — re-run the
+command above to get the newest bridge.
+
 Or from the monorepo (development):
 
 ```bash
@@ -58,11 +69,29 @@ pi -e ./src/index.ts
 
 ```bash
 curl http://127.0.0.1:38617/health
-# → { "ok": true, "service": "pi-office-bridge", "panes": [ … ] }
+# → { "ok": true, "service": "pi-office-bridge", "serverVersion": "0.2.0",
+#     "capabilities": ["http-health"], "panes": [ … ] }
 ```
 
 `/health` lists the attached pane(s) and their host app (excel / word /
-powerpoint), so it doubles as a quick host-detection check.
+powerpoint), so it doubles as a quick host-detection check. The add-in's
+probe classifies the response (current / older bridge / timeout / browser
+blocked) instead of reporting a bare failure — see
+[`docs/local-development.md`](../../docs/local-development.md).
+
+## Version & capabilities
+
+Every `welcome` frame (and `GET /health`) advertises additive server
+metadata:
+
+- `serverVersion` — this package's version (e.g. `"0.2.0"`).
+- `capabilities` — `["http-health"]` means the HTTP `/health` surface is
+  served.
+
+Clients (the add-in card) treat an absent `capabilities` as “legacy bridge
+(< 0.2.0)” and tell the user to update instead of claiming the bridge is
+down. The connection state is surfaced live to the Pi TUI as soon as a pane
+attaches or detaches (`onPanesChanged`).
 
 ## Commands
 
@@ -75,7 +104,9 @@ powerpoint), so it doubles as a quick host-detection check.
 
 - **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.
+  override it (the add-in's bridge card has a **Bridge URL** row that both the
+  WebSocket client and the probe use). If the port is already taken by another
+  Pi process, the extension reports `EADDRINUSE` with the override hint.
 - **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
@@ -85,18 +116,47 @@ powerpoint), so it doubles as a quick host-detection check.
 ## 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:
+catalog. The catalog is the single source of truth: it lives in
+`@dieulc/pi-office-protocol` (`office-catalog.ts`) and BOTH the Pi extension
+and the add-in derive from it — the Pi side here, and the pane's bridge op
+registry (`packages/add-in/src/bridge/`) there. 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).
+| --- | --- |
+| Excel | `get_overview`, `read_range`, `write_cells`, `fill_formula`, `search_workbook`, `modify_structure`, `format_cells`, `conditional_format`, `charts`, `trace_dependencies`, `explain_formula`, `view_settings`, `comments`, `workbook_history` |
+| Word | `get_overview`, `read_document`, `insert_text`, `replace_text`, `format_range`, `insert_blocks`, `insert_table`, `insert_page_break`, `insert_image`, `insert_hyperlink` |
+| PowerPoint | `get_overview`, `read_slide`, `add_slide`, `add_text_box`, `format_slide` |
+
+### Active-tool reconciliation
+
+The office tools are registered at `session_start` from the catalog, but only
+**the ops the currently attached pane advertises are kept active** in the Pi
+session (`pi.setActiveTools()`). Opening an app activates that host's tools;
+closing it deactivates them; everything else stays untouched. Panes that don't
+advertise an `ops` list (legacy 0.2.x clients) are given only the v1 op set.
+This keeps the agent's prompt small and focused on the app actually open.
+
+### Capability handshake
+
+Panes send `hello.ops` + `hello.catalogVersion` with the op ids they can
+execute. The server validates them against its own catalog (entries that don't
+belong to the pane's host, or that the server doesn't know, are dropped and
+counted). `callOfficeTool` then rejects any op the pane did not advertise with
+an actionable message, so a mismatched add-in/bridge pair fails loudly instead
+of silently.
+
+- `/office` shows each attached pane's host, op count, catalog version, and any
+  ignored-op count.
+- `/office-tools` lists every registered tool + catalog version.
+- `GET /health` exposes `catalogVersion` and per-pane `ops` / `catalogVersion`.
+- `before_agent_start` appends a pane-context block (attached host, "the
+  office_* tools edit the live document; formatting is fully supported; never
+  emit HTML for Word") so the agent uses the tools directly.
+
+The pane-side executors are thin delegates to the same local tool factories the
+browser-only path uses (see `packages/add-in/src/bridge/`), and a parity test
+(`packages/add-in/tests/bridge-catalog-parity.test.ts`) fails CI if the pane
+registry ever drifts from the shared catalog.
 
 ## Development
 

package/package.json

@@ -1,60 +1,64 @@
-{
-  "name": "@dieulc/pi-office-bridge",
-  "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",
-  "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"
-  }
-}
+{
+  "name": "@dieulc/pi-office-bridge",
+  "version": "0.3.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": "^0.3.0",
+    "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/active-tools.ts",
+    "src/protocol.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test:active": "node --test tests/active-tools.test.mjs",
+    "test:smoke": "npm run build && node tests/smoke.mjs",
+    "test:interop": "npm run build && node --import ./tests/register-ts-loader.mjs tests/pane-interop.mjs",
+    "test": "npm run test:active && npm run test:smoke && npm run test:interop"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/active-tools.ts

@@ -0,0 +1,79 @@
+/**
+ * Active office tool reconciliation — pure functions that decide which
+ * `office_<host>_<op>` tools Pi exposes based on the currently attached panes.
+ *
+ * Kept free of Pi API calls so it is unit-testable without a live Pi session.
+ *
+ * Rules:
+ *  - Office tool names are identified from the shared catalog.
+ *  - A pane advertising `ops` exposes exactly those ops' tools.
+ *  - A legacy pane (no `ops`) exposes only the v1 op set.
+ *  - Tools for hosts that are no longer attached are deactivated.
+ *  - Non-office tools in the current active set are preserved untouched.
+ */
+
+import {
+ CATALOG_VERSION,
+ LEGACY_V1_OPS,
+ OFFICE_CATALOG_BY_OP,
+ OFFICE_TOOL_NAMES,
+ officeToolName,
+} from "./protocol.js";
+import type { OfficeHostApp } from "./protocol.js";
+
+/** What Pi knows about a pane's capabilities (server-normalized). */
+export interface PaneCapability {
+ host: OfficeHostApp;
+ /** Ops this pane advertises, or null for legacy panes (v1 set only). */
+ ops: readonly string[] | null;
+}
+
+/** The catalog version the pane's ops were derived from, when advertised. */
+export type { CATALOG_VERSION };
+
+/** Office tool names from the catalog, as a set for O(1) membership. */
+const OFFICE_TOOL_NAME_SET: ReadonlySet<string> = new Set(OFFICE_TOOL_NAMES);
+
+/** True when the name is one of the catalog's office_* tools. */
+export function isOfficeToolName(name: string): boolean {
+ return OFFICE_TOOL_NAME_SET.has(name);
+}
+
+/**
+ * The pi tool names enabled by the given panes (host-scoped, deterministic
+ * order). Legacy panes without an `ops` list get the v1 op set only.
+ */
+export function activeOfficeToolNames(
+ panes: readonly PaneCapability[],
+): string[] {
+ const names = new Set<string>();
+ for (const pane of panes) {
+  const ops = pane.ops ?? LEGACY_V1_OPS;
+  for (const op of ops) {
+   const entry = OFFICE_CATALOG_BY_OP.get(op);
+   if (entry && entry.host === pane.host) {
+    names.add(officeToolName(entry.host, entry.op));
+   }
+  }
+ }
+ return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Compute the next active tool list: drop all office tools, then re-add the
+ * office tools for the currently attached panes, preserving the caller's
+ * existing non-office tools. Deterministic and idempotent.
+ */
+export function reconcileOfficeToolActivation(
+ currentActive: readonly string[],
+ panes: readonly PaneCapability[],
+): string[] {
+ const next = currentActive.filter((name) => !isOfficeToolName(name));
+ const toAdd = activeOfficeToolNames(panes);
+ return [...new Set([...next, ...toAdd])].sort((a, b) => {
+  const aOffice = isOfficeToolName(a) ? 1 : 0;
+  const bOffice = isOfficeToolName(b) ? 1 : 0;
+  if (aOffice !== bOffice) return aOffice - bOffice;
+  return a.localeCompare(b);
+ });
+}

package/src/bridge-server.ts

@@ -18,6 +18,9 @@ import type { AddressInfo } from "node:net";
 
 import {
   BRIDGE_PROTOCOL_VERSION,
+  CATALOG_VERSION,
+  LEGACY_V1_OPS,
+  OFFICE_CATALOG_BY_OP,
   nextCallId,
   parseClientMessage,
   type BridgeCapability,
@@ -36,6 +39,16 @@ export interface AttachedPane {
   lastSeen: number;
   model?: string;
   provider?: string;
+  /**
+   * Ops this pane advertised in `hello` (validated against the server catalog
+   * and normalized to `<host>.<op>` ids). `null` means a legacy pane that did
+   * not advertise an `ops` list — only the v1 op set is allowed for it.
+   */
+  ops: readonly string[] | null;
+  /** Catalog version the pane derived its ops from, when advertised. */
+  catalogVersion: number | null;
+  /** Count of advertised ops dropped because they are unknown to this server. */
+  opsIgnoredCount: number;
 }
 
 export interface BridgeServerHandlers {
@@ -219,11 +232,34 @@ export class OfficeBridgeServer {
       );
     }
 
+    const opId = `${host}.${op}`;
+    // Capability gate: a pane may only execute ops it advertised (or, for
+    // legacy panes that advertise nothing, only the v1 op set).
+    if (pane.ops !== null) {
+      if (!pane.ops.includes(opId)) {
+        return Promise.reject(
+          new Error(
+            `office-bridge: the attached ${host} pane does not advertise "${opId}" ` +
+              `(it supports ${pane.ops.length} ops). ` +
+              "Reload the pi-for-office add-in to enable this tool.",
+          ),
+        );
+      }
+    } else if (!LEGACY_V1_OPS.includes(opId)) {
+      return Promise.reject(
+        new Error(
+          `office-bridge: "${opId}" requires a newer add-in. ` +
+            "The attached pane is a legacy client (no capability list); update " +
+            "pi-for-office and reload the document to enable this tool.",
+        ),
+      );
+    }
+
     const id = nextCallId("tool");
     const message: ServerMessage = {
       type: "tool_call",
       id,
-      tool: `${host}.${op}`,
+      tool: opId,
       args,
     };
 
@@ -328,25 +364,29 @@ export class OfficeBridgeServer {
         lastSeen: p.lastSeen,
         model: p.model,
         provider: p.provider,
+        ops: p.ops,
+        catalogVersion: p.catalogVersion,
+        opsIgnoredCount: p.opsIgnoredCount,
       }));
 
-          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,
-          );
+      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,
+          catalogVersion: CATALOG_VERSION,
+          panes,
+        },
+        req,
+        allowOrigin,
+      );
       return;
     }
 
@@ -396,6 +436,36 @@ export class OfficeBridgeServer {
     return sorted.find((p) => p.host === host) ?? null;
   }
 
+  /**
+   * Normalize a pane's advertised ops against the server catalog: keep only
+   * ops that exist in the catalog and belong to the pane's host; return null
+   * when the pane advertised nothing (legacy client).
+   */
+  private normalizeAdvertisedOps(
+    host: OfficeHostApp,
+    advertised: readonly string[] | undefined,
+  ): readonly string[] | null {
+    if (advertised === undefined || advertised.length === 0) return null;
+    const known = new Set<string>();
+    for (const op of advertised) {
+      const entry = OFFICE_CATALOG_BY_OP.get(op);
+      if (entry && entry.host === host) known.add(op);
+    }
+    return known.size > 0 ? [...known] : null;
+  }
+
+  /** Count ops the pane advertised that this server dropped as unknown/host-mismatched. */
+  private countIgnoredOps(
+    host: OfficeHostApp,
+    advertised: readonly string[] | undefined,
+  ): number {
+    if (advertised === undefined) return 0;
+    return advertised.filter((op) => {
+      const entry = OFFICE_CATALOG_BY_OP.get(op);
+      return entry === undefined || entry.host !== host;
+    }).length;
+  }
+
   private handleConnection(ws: WebSocket): void {
     let pane: AttachedPane | null = null;
 
@@ -432,6 +502,12 @@ export class OfficeBridgeServer {
             clientName: msg.clientName,
             connectedAt: Date.now(),
             lastSeen: Date.now(),
+            // Normalize advertised ops against the server catalog: entries the
+            // server does not know (or that belong to a different host) are
+            // dropped and counted so the operator can see the mismatch.
+            ops: this.normalizeAdvertisedOps(msg.host, msg.ops),
+            catalogVersion: msg.catalogVersion ?? null,
+            opsIgnoredCount: this.countIgnoredOps(msg.host, msg.ops),
           };
           // A pane reconnecting replaces any older pane with the same paneId.
           this.panes.splice(

package/src/index.ts

@@ -25,7 +25,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { BRIDGE_DEFAULT_PORT } from "./protocol.js";
+import { CATALOG_VERSION, BRIDGE_DEFAULT_PORT } from "./protocol.js";
 import type { AttachedPane } from "./bridge-server.js";
 import { OfficeBridgeServer } from "./bridge-server.js";
 import {
@@ -35,6 +35,10 @@ import {
   HOST_APP_LABEL,
 } from "./office-tools.js";
 import type { OfficeToolDescriptor } from "./office-tools.js";
+import {
+  reconcileOfficeToolActivation,
+  type PaneCapability,
+} from "./active-tools.js";
 
 const FLAG_PORT = "office-bridge-port";
 
@@ -83,12 +87,14 @@ export default function (pi: ExtensionAPI): void {
     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;
+      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;
+      if (Number.isFinite(parsed) && parsed > 0 && parsed < 65536)
+        return parsed;
     }
     return BRIDGE_DEFAULT_PORT;
   }
@@ -103,11 +109,17 @@ export default function (pi: ExtensionAPI): void {
     }
     const port = server.actualPort ?? resolvePort();
     if (panes.length === 0) {
-      ui.setStatus("office-bridge", `office bridge on :${port} — no app attached`);
+      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})`);
+    ui.setStatus(
+      "office-bridge",
+      `office: ${labels} attached (bridge :${port})`,
+    );
   }
 
   let panesChangedTimer: ReturnType<typeof setTimeout> | null = null;
@@ -130,7 +142,8 @@ export default function (pi: ExtensionAPI): void {
       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);
+      if (p.type === "thinking" && typeof p.text === "string")
+        parts.push(p.text);
     }
     return parts.join("\n").trim();
   }
@@ -142,6 +155,7 @@ export default function (pi: ExtensionAPI): void {
       name: descriptor.name,
       label: descriptor.label,
       description: descriptor.description,
+      promptSnippet: descriptor.promptSnippet,
       promptGuidelines: descriptor.promptGuidelines,
       parameters: descriptor.parameters,
       executionMode: "sequential",
@@ -162,8 +176,16 @@ export default function (pi: ExtensionAPI): void {
             `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 };
+        const result = await active.callOfficeTool(
+          descriptor.host,
+          descriptor.op,
+          args,
+          signal,
+        );
+        return {
+          content: [{ type: "text", text: result.text }],
+          details: result.details,
+        };
       },
     });
   }
@@ -174,6 +196,46 @@ export default function (pi: ExtensionAPI): void {
     }
   }
 
+  /**
+   * Reconcile the Pi active tool set with the currently attached panes: only
+   * the office ops the attached panes advertise stay active; everything else
+   * (user/other-extension tools) is preserved. Called on attach/detach.
+   */
+  function reconcileActiveTools(panes: readonly AttachedPane[]): void {
+    const capabilities: PaneCapability[] = panes.map((pane) => ({
+      host: pane.host,
+      ops: pane.ops,
+    }));
+    const next = reconcileOfficeToolActivation(
+      pi.getActiveTools(),
+      capabilities,
+    );
+    pi.setActiveTools(next);
+  }
+
+  /** Stable per-turn pane-awareness block appended to the system prompt. */
+  function paneContextBlock(): string | null {
+    const active = server;
+    if (!active?.isRunning) return null;
+    const panes = active.attachedPanes();
+    if (panes.length === 0) return null;
+
+    const lines = panes.map((p) => {
+      const legacy =
+        p.ops === null
+          ? " (legacy client: only v1 ops — update the add-in for newer tools)"
+          : "";
+      return `- ${HOST_APP_LABEL[p.host]} is attached via the office bridge${legacy}. The open document is live: the office_${p.host}_* tools edit it directly.`;
+    });
+    return (
+      "\n\n## Attached Office documents\n" +
+      lines.join("\n") +
+      "\n\nEditing these documents with the office_* tools is fully supported, including formatting and " +
+      "structured documents (titles, headings, lists, tables, alignment, indents). Never claim formatting is " +
+      "unavailable, and never emit HTML for Word — use the office_word_* tools."
+    );
+  }
+
   /* ── lifecycle ─────────────────────────────────────────────────────── */
 
   pi.on("session_start", async (_event, ctx) => {
@@ -199,16 +261,23 @@ 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(),
+        // Keep the TUI status line live and the active tool set in sync:
+        // opening an app activates that host's office tools; closing it
+        // deactivates them.
+        onPanesChanged: (panes) => {
+          scheduleStatusUpdate();
+          reconcileActiveTools(panes);
+        },
       },
     });
 
     try {
       await bridge.start();
       server = bridge;
-      ctx.ui.notify(`Office bridge listening on ws://127.0.0.1:${port}`, "info");
+      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);
       const code = (error as NodeJS.ErrnoException | null)?.code;
@@ -243,6 +312,14 @@ export default function (pi: ExtensionAPI): void {
 
   /* ── agent → pane forwarding ───────────────────────────────────────── */
 
+  // Tell the agent which Office apps are attached before each turn so it uses
+  // the office_* tools directly instead of claiming capabilities are missing.
+  pi.on("before_agent_start", (event, _ctx) => {
+    const block = paneContextBlock();
+    if (block === null) return undefined;
+    return { systemPrompt: event.systemPrompt + block };
+  });
+
   // Forward the final assistant reply to the pane that prompted it.
   pi.on("message_end", async (event, _ctx) => {
     if (event.message.role !== "assistant") return;
@@ -285,7 +362,9 @@ export default function (pi: ExtensionAPI): void {
       type: "tool_activity",
       tool: event.toolName,
       status: event.isError ? "error" : "end",
-      summary: event.isError ? String(event.result ?? "tool failed") : undefined,
+      summary: event.isError
+        ? String(event.result ?? "tool failed")
+        : undefined,
     });
   });
 
@@ -303,16 +382,30 @@ export default function (pi: ExtensionAPI): void {
       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");
+        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`;
+        const ops =
+          p.ops !== null
+            ? `${p.ops.length} ops${p.catalogVersion ? ` (catalog v${p.catalogVersion})` : ""}`
+            : "legacy client (v1 ops)";
+        const ignored =
+          p.opsIgnoredCount > 0
+            ? `, ${p.opsIgnoredCount} advertised op(s) ignored (unknown to this server)`
+            : "";
+        return `- ${HOST_APP_LABEL[p.host]} (${p.clientName}, pane ${p.paneId.slice(0, 8)})${model}${provider}, seen ${ago}s ago — ${ops}${ignored}`;
       });
-      ctx.ui.notify(`Office bridge on :${port}\n${lines.join("\n")}`, "info");
+      ctx.ui.notify(
+        `Office bridge on :${port} (catalog v${CATALOG_VERSION})\n${lines.join("\n")}`,
+        "info",
+      );
     },
   };
 
@@ -320,10 +413,11 @@ export default function (pi: ExtensionAPI): void {
 
   // 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.",
+    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")}`,
+        `Office tools (${OFFICE_TOOL_NAMES.length}, catalog v${CATALOG_VERSION}):\n${OFFICE_TOOL_NAMES.join("\n")}`,
         "info",
       );
     },

package/src/office-tools.ts

@@ -1,18 +1,19 @@
 /**
- * Office tool catalog — the Office.js operations the Pi agent can drive
- * through the bridge.
+ * Office tool catalog adapter — thin wrapper over the shared catalog.
  *
- * 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.
+ * The authoritative op definitions (names, schemas, descriptions) live in
+ * `@dieulc/pi-office-protocol` (`office-catalog.ts`). This module only maps
+ * catalog entries to the descriptors this extension registers with Pi, so the
+ * Pi side can never drift from the add-in's pane-side registry.
  */
 
-import { Type, type TSchema } from "typebox";
-import { StringEnum } from "@earendil-works/pi-ai";
+import type { TSchema } from "typebox";
+import {
+  CATALOG_VERSION,
+  HOST_APP_LABEL,
+  OFFICE_CATALOG,
+  hostForToolName,
+} from "./protocol.js";
 import type { OfficeHostApp } from "./protocol.js";
 
 export interface OfficeToolDescriptor {
@@ -24,239 +25,39 @@ export interface OfficeToolDescriptor {
   name: string;
   label: string;
   description: string;
+  promptSnippet?: 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)." })),
-    }),
-  },
-];
+/** The catalog version this extension's tool surface was built from. */
+export const TOOL_CATALOG_VERSION = CATALOG_VERSION;
+
+/** All descriptors built from the shared catalog (deterministic order). */
+export const OFFICE_TOOL_DESCRIPTORS: readonly OfficeToolDescriptor[] =
+  OFFICE_CATALOG.map((entry) => ({
+    host: entry.host,
+    op: entry.op,
+    name: entry.name,
+    label: entry.label,
+    description: entry.description,
+    ...(entry.promptSnippet === undefined
+      ? null
+      : { promptSnippet: entry.promptSnippet }),
+    ...(entry.promptGuidelines === undefined
+      ? null
+      : { promptGuidelines: entry.promptGuidelines }),
+    parameters: entry.parameters,
+  }));
 
 /** 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]),
-);
+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);
+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;
-}
+/** The office host this tool name drives, or null when unknown. (from catalog) */
+export { HOST_APP_LABEL, hostForToolName };

package/src/protocol.ts

@@ -1,7 +1,10 @@
 /**
- * Re-export of the shared bridge protocol.
+ * Re-export of the shared bridge protocol + office op catalog.
  *
  * 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.
+ * extension (server) and the add-in task pane (client) stay in lockstep. The
+ * catalog is re-exported from its subpath (the main entry keeps Node-loadable
+ * raw TS without a `.js`→`.ts` rewrite).
  */
 export * from "@dieulc/pi-office-protocol";
+export * from "@dieulc/pi-office-protocol/office-catalog";