@dieulc/pi-office-protocol 0.1.0 → 0.3.0

package/src/protocol.ts

@@ -17,7 +17,13 @@
  *    session and streams the assistant's reply back as `agent_message`.
  *
  * Every connection starts with a `hello` (client) / `welcome` (server) pair so
- * both sides know which Office host app is attached.
+ * both sides know which Office host app is attached. The client may also
+ * advertise the op ids it can execute (`hello.ops`) plus the catalog version
+ * they were derived from; the server validates them against its own catalog.
+ *
+ * The office op catalog is exported via the `@dieulc/pi-office-protocol/office-catalog`
+ * subpath (kept out of this entry so Node loads this raw-TS file without a
+ * `.js`→`.ts` rewrite).
  */
 
 /** Default TCP port the bridge server listens on (loopback only). */
@@ -35,109 +41,135 @@ export type OfficeToolId = string;
 /* ── Client → Server ─────────────────────────────────────────────────── */
 
 export interface HelloMessage {
-  type: "hello";
-  protocolVersion: number;
-  host: OfficeHostApp;
-  clientName: string;
-  paneId: string;
+ type: "hello";
+ protocolVersion: number;
+ host: OfficeHostApp;
+ clientName: string;
+ paneId: string;
+ /**
+  * Op ids this pane can execute (optional; additive since protocol v1).
+  * When absent the pane is treated as a legacy 0.2.x client and only the
+  * v1 op set is activated server-side.
+  */
+ ops?: string[];
+ /** Catalog version the pane's ops were derived from (see office-catalog.ts). */
+ catalogVersion?: number;
 }
 
 export interface PingMessage {
-  type: "ping";
-  ts: number;
+ type: "ping";
+ ts: number;
 }
 
 /** Result of a proxied Office.js tool call executed by the pane. */
 export interface ToolResultMessage {
-  type: "tool_result";
-  id: string;
-  ok: boolean;
-  /** Markdown/text shown to the LLM. */
-  text: string;
-  /** Structured details (may be large; used by the agent tool result). */
-  details?: unknown;
-  error?: string;
+ type: "tool_result";
+ id: string;
+ ok: boolean;
+ /** Markdown/text shown to the LLM. */
+ text: string;
+ /** Structured details (may be large; used by the agent tool result). */
+ details?: unknown;
+ error?: string;
 }
 
 /** User typed a prompt in the add-in sidebar; ask Pi to answer it. */
 export interface UserMessageMessage {
-  type: "user_message";
-  text: string;
+ type: "user_message";
+ text: string;
 }
 
 /** Pane notifies the server it finished applying a message (optional). */
 export interface ClientStatusMessage {
-  type: "status";
-  model?: string;
-  provider?: string;
+ type: "status";
+ model?: string;
+ provider?: string;
 }
 
 export type ClientMessage =
-  | HelloMessage
-  | PingMessage
-  | ToolResultMessage
-  | UserMessageMessage
-  | ClientStatusMessage;
+ | HelloMessage
+ | PingMessage
+ | ToolResultMessage
+ | UserMessageMessage
+ | ClientStatusMessage;
 
 /* ── Server → Client ─────────────────────────────────────────────────── */
 
+/**
+ * Optional server capabilities advertised in `welcome`. Clients must treat an
+ * absent `capabilities` array as "legacy bridge" and degrade gracefully.
+ *
+ * - `http-health` — the server answers `GET /health` with JSON metadata.
+ */
+export type BridgeCapability = "http-health";
+
 export interface WelcomeMessage {
-  type: "welcome";
-  protocolVersion: number;
-  piVersion: string | null;
-  serverName: string;
+ type: "welcome";
+ protocolVersion: number;
+ piVersion: string | null;
+ serverName: string;
+ /**
+  * The bridge extension's own package version (e.g. `"0.2.0"`). Optional so
+  * older servers (0.1.0) keep working — absent means "unknown/legacy".
+  */
+ serverVersion?: string;
+ /**
+  * Optional server capabilities. Additive: absent means the server predates
+  * capability advertisement (legacy 0.1.0 bridge).
+  */
+ capabilities?: BridgeCapability[];
 }
 
 export interface PongMessage {
-  type: "pong";
-  ts: number;
+ type: "pong";
+ ts: number;
 }
 
 /** Pi agent asks the pane to execute one Office.js operation. */
 export interface ToolCallMessage {
-  type: "tool_call";
-  id: string;
-  tool: OfficeToolId;
-  args: Record<string, unknown>;
+ type: "tool_call";
+ id: string;
+ tool: OfficeToolId;
+ args: Record<string, unknown>;
 }
 
 /** A chunk of the assistant's reply (streamed, display-only). */
 export interface AgentDeltaMessage {
-  type: "agent_message";
-  kind: "delta";
-  text: string;
+ type: "agent_message";
+ kind: "delta";
+ text: string;
 }
 
 /** Final assistant reply for a pane-initiated prompt. */
 export interface AgentFinalMessage {
-  type: "agent_message";
-  kind: "final";
-  text: string;
-  messageId?: string;
+ type: "agent_message";
+ kind: "final";
+ text: string;
+ messageId?: string;
 }
 
 /** Non-office tool activity (bash, read, …) so the pane can show progress. */
 export interface ToolActivityMessage {
-  type: "tool_activity";
-  tool: string;
-  status: "start" | "end" | "error";
-  summary?: string;
+ type: "tool_activity";
+ tool: string;
+ status: "start" | "end" | "error";
+ summary?: string;
 }
 
 export interface ServerErrorMessage {
-  type: "error";
-  code: string;
-  message: string;
+ type: "error";
+ code: string;
+ message: string;
 }
 
 export type ServerMessage =
-  | WelcomeMessage
-  | PongMessage
-  | ToolCallMessage
-  | AgentDeltaMessage
-  | AgentFinalMessage
-  | ToolActivityMessage
-  | ServerErrorMessage;
+ | WelcomeMessage
+ | PongMessage
+ | ToolCallMessage
+ | AgentDeltaMessage
+ | AgentFinalMessage
+ | ToolActivityMessage
+ | ServerErrorMessage;
 
 /* ── Utilities ───────────────────────────────────────────────────────── */
 
@@ -145,34 +177,59 @@ let callCounter = 0;
 
 /** Monotonic id generator for tool_call / tool_result correlation. */
 export function nextCallId(prefix = "c"): string {
-  callCounter += 1;
-  return `${prefix}-${Date.now().toString(36)}-${callCounter.toString(36)}`;
+ callCounter += 1;
+ return `${prefix}-${Date.now().toString(36)}-${callCounter.toString(36)}`;
 }
 
 /** Validate an incoming client frame. Returns the parsed message or throws. */
 export function parseClientMessage(raw: string): ClientMessage {
-  const data: unknown = JSON.parse(raw);
-  if (typeof data !== "object" || data === null) {
-    throw new Error("bridge: expected a JSON object message");
-  }
-  const msg = data as Record<string, unknown>;
-  if (typeof msg.type !== "string") {
-    throw new Error("bridge: message missing 'type'");
-  }
-  switch (msg.type) {
-    case "hello": {
-      const m = data as HelloMessage;
-      if (!["excel", "word", "powerpoint"].includes(m.host)) {
-        throw new Error(`bridge: hello with unknown host '${String(m.host)}'`);
-      }
-      return m;
+ // JSON.parse throws on malformed input — wrap it at this boundary so the
+ // caller always sees a descriptive bridge error instead of a SyntaxError.
+ let data: unknown;
+ try {
+  data = JSON.parse(raw);
+ } catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  throw new Error(`bridge: message is not valid JSON (${detail})`);
+ }
+ if (typeof data !== "object" || data === null) {
+  throw new Error("bridge: expected a JSON object message");
+ }
+ const msg = data as Record<string, unknown>;
+ if (typeof msg.type !== "string") {
+  throw new Error("bridge: message missing 'type'");
+ }
+ switch (msg.type) {
+  case "hello": {
+   const m = data as HelloMessage;
+   if (!["excel", "word", "powerpoint"].includes(m.host)) {
+    throw new Error(`bridge: hello with unknown host '${String(m.host)}'`);
+   }
+   if (m.ops !== undefined) {
+    if (!Array.isArray(m.ops) || m.ops.some((op) => typeof op !== "string")) {
+     throw new Error("bridge: hello with malformed 'ops' (expected string[])");
+    }
+   }
+   if (m.catalogVersion !== undefined) {
+    if (
+     typeof m.catalogVersion !== "number" ||
+     !Number.isFinite(m.catalogVersion) ||
+     !Number.isInteger(m.catalogVersion) ||
+     m.catalogVersion < 1
+    ) {
+     throw new Error(
+      `bridge: hello with malformed 'catalogVersion' (${String(m.catalogVersion)})`,
+     );
     }
-    case "ping":
-    case "tool_result":
-    case "user_message":
-    case "status":
-      return data as ClientMessage;
-    default:
-      throw new Error(`bridge: unknown client message type '${String(msg.type)}'`);
+   }
+   return m;
   }
+  case "ping":
+  case "tool_result":
+  case "user_message":
+  case "status":
+   return data as ClientMessage;
+  default:
+   throw new Error(`bridge: unknown client message type '${String(msg.type)}'`);
+ }
 }