@eigenpal/docx-editor-agents 0.1.0 → 0.2.0

package/README.md

@@ -2,40 +2,93 @@
 
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](./LICENSE)
 
-Word-like API for AI document review. Add comments, suggest replacements, accept/reject tracked changes — all headless, no DOM required.
-
-## Install
+Word-like API for AI agents to review DOCX documents. Read, comment, suggest tracked changes, accept/reject. Headless. Server-friendly. Browser-friendly. **The library you build your AI document features on top of.**
 
 ```bash
 npm install @eigenpal/docx-editor-agents
 ```
 
-## Usage
+## Three ways to use this package
+
+### 1. Static review (`DocxReviewer`) — single function call against a parsed DOCX
 
 ```ts
 import { DocxReviewer } from '@eigenpal/docx-editor-agents';
 
 const reviewer = await DocxReviewer.fromBuffer(buffer, 'AI Reviewer');
+reviewer.addComment(5, 'This cap seems too low.');
+reviewer.replace(5, '$50k', '$500k');
+const output = await reviewer.toBuffer();
+```
 
-// Read
-const text = reviewer.getContentAsText();
+Drop into a CI bot, a queue worker, a Lambda. No editor needed. ~50 KB.
 
-// Comment
-reviewer.addComment(5, 'This cap seems too low.');
+### 2. Live editor bridge (`createEditorBridge`) — wire AI tools into a running `<DocxEditor>` instance
 
-// Replace (tracked change)
-reviewer.replace(5, '$50k', '$500k');
+```ts
+import { useAgentChat } from '@eigenpal/docx-editor-agents/bridge';
+
+const { executeToolCall, toolSchemas } = useAgentChat({ editorRef, author: 'Assistant' });
+```
+
+The agent's `add_comment`, `suggest_change`, `find_text` etc. show up live in the user's editor. Used by Eigenpal's chat panel; published for anyone building an AI document UX.
+
+### 3. Build your own MCP server (`McpServer` + `createReviewerBridge`) — the SaaS path
+
+This is the one most teams want. The published library exposes a transport-agnostic MCP server core. **You wrap it inside your own auth, storage, and transport layer.** Stdio, HTTP-SSE, WebSocket, queue-worker — your call.
+
+```ts
+// Your /api/mcp/sse route — Express, Hono, Next.js, whatever
+import { McpServer, createReviewerBridge, DocxReviewer } from '@eigenpal/docx-editor-agents';
 
-// Batch from LLM response
-reviewer.applyReview({
-  comments: [{ paragraphIndex: 5, text: 'Too low.' }],
-  proposals: [{ paragraphIndex: 5, search: '$50k', replaceWith: '$500k' }],
+app.post('/api/mcp', requireAuth, async (req, res) => {
+  // 1. Pull the DOCX from your storage (S3, Postgres bytea, etc.)
+  const buffer = await loadDocxForUser(req.user, req.params.docId);
+
+  // 2. Wire it through the bridge
+  const reviewer = await DocxReviewer.fromBuffer(buffer, req.user.name);
+  const bridge = createReviewerBridge(reviewer);
+  const server = new McpServer(bridge, {
+    name: 'acme-contract-review',
+    version: '1.0.0',
+  });
+
+  // 3. Drive MCP messages over your transport. server.handle() is sync,
+  //    transport-free, and never throws.
+  const reply = server.handle(JSON.parse(req.body));
+  res.json(reply);
+
+  // 4. After the agent's done, persist the modified DOCX back to your storage.
+  await saveDocxForUser(req.user, req.params.docId, await reviewer.toBuffer());
 });
+```
 
-// Export
-const output = await reviewer.toBuffer();
+That's the whole shape. Ten built-in agent tools (`read_document`, `find_text`, `add_comment`, `suggest_change`, `read_comments`, `read_changes`, `reply_comment`, `resolve_comment`, `read_selection`, `scroll`) are exposed automatically through MCP `tools/list` and `tools/call`. MCP spec version: `2025-06-18`.
+
+#### Why server-side, why not a local stdio bin?
+
+A local-installed stdio MCP server only works for one document per config — Claude Desktop loads its MCP server list at startup. That's a useless shape for a contract-review product where users have many documents. The right deployment is **a hosted MCP server you operate**, with your own auth and storage. The library gives you the engine; you bring the chassis.
+
+## Word JS API parity
+
+The bridge mirrors the Office.js Word API pattern — locate a stable handle (`paraId`) first, then mutate. The parity contract is enforced at compile time:
+
+```ts
+import type { WordCompatBridge } from '@eigenpal/docx-editor-agents';
 ```
 
+`WordCompatBridge` is a TypeScript interface that `EditorBridge` is statically required to satisfy. If we ever drop a method that maps to a Word API call, typecheck breaks.
+
+## What's in the package
+
+| Subpath                               | What                                                              | Use when                                                  |
+| ------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| `@eigenpal/docx-editor-agents`        | `DocxReviewer`, `createReviewerBridge`, agent tool catalog, types | Server-side review, building your own MCP server          |
+| `@eigenpal/docx-editor-agents/bridge` | `useAgentChat`, `createEditorBridge`, `EditorBridge` interface    | Wiring AI tools into a live `<DocxEditor>` in the browser |
+| `@eigenpal/docx-editor-agents/mcp`    | `McpServer`, JSON-RPC types, stdio adapter                        | Building an MCP server (any transport)                    |
+
+Zero new runtime dependencies. Tree-shakes cleanly per subpath.
+
 ## License
 
 [AGPL-3.0](./LICENSE) — free to use and modify, but you must open-source your code. For commercial licensing without AGPL obligations, contact [founders@eigenpal.com](mailto:founders@eigenpal.com).

package/dist/ai-sdk/react.d.mts

@@ -0,0 +1,67 @@
+/**
+ * Vercel AI SDK adapter (React side) — opt-in.
+ *
+ * Use this only if you're driving the chat with `useChat` from
+ * `@ai-sdk/react`. The library's `<AgentChatLog>` consumes a flat
+ * `AgentMessage[]` shape; AI SDK's `useChat` produces `UIMessage[]`
+ * with structured `parts`. `toAgentMessages()` is the bridge.
+ */
+/**
+ * Local mirror of `AgentMessage` / `AgentToolCall` from
+ * `@eigenpal/docx-js-editor`. Inlined here so this subpath has zero
+ * runtime/type coupling to the editor package — the shapes are
+ * structurally identical, so values flow either way without casting.
+ */
+interface AgentToolCall {
+    id: string;
+    name: string;
+    input?: unknown;
+    result?: string;
+    error?: string;
+    status: 'running' | 'done' | 'error';
+}
+interface AgentMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    toolCalls?: AgentToolCall[];
+    status?: 'streaming' | 'done';
+}
+/**
+ * Minimal structural shape of a Vercel AI SDK `UIMessage` — keeps the
+ * `ai` package as a peer dep, not a runtime dep.
+ */
+interface AiSdkUIMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    parts?: ReadonlyArray<{
+        type: string;
+        text?: string;
+        toolCallId?: string;
+        state?: string;
+        input?: unknown;
+        output?: unknown;
+        errorText?: string;
+    }>;
+}
+/**
+ * Adapt AI SDK's `UIMessage[]` (from `useChat`) to the `AgentMessage[]`
+ * shape `<AgentChatLog>` consumes.
+ *
+ * @param uiMessages - the `messages` array from `useChat`
+ * @param status - the `status` from `useChat`. The last assistant
+ *   message is marked `streaming` while the chat is still in flight.
+ *
+ * @example
+ * ```tsx
+ * const chat = useChat({ ... });
+ * const messages = useMemo(
+ *   () => toAgentMessages(chat.messages, chat.status),
+ *   [chat.messages, chat.status]
+ * );
+ * return <AgentChatLog messages={messages} />;
+ * ```
+ */
+declare function toAgentMessages(uiMessages: ReadonlyArray<AiSdkUIMessage>, status: string): AgentMessage[];
+
+export { type AgentMessage, type AgentToolCall, toAgentMessages };

package/dist/ai-sdk/react.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Vercel AI SDK adapter (React side) — opt-in.
+ *
+ * Use this only if you're driving the chat with `useChat` from
+ * `@ai-sdk/react`. The library's `<AgentChatLog>` consumes a flat
+ * `AgentMessage[]` shape; AI SDK's `useChat` produces `UIMessage[]`
+ * with structured `parts`. `toAgentMessages()` is the bridge.
+ */
+/**
+ * Local mirror of `AgentMessage` / `AgentToolCall` from
+ * `@eigenpal/docx-js-editor`. Inlined here so this subpath has zero
+ * runtime/type coupling to the editor package — the shapes are
+ * structurally identical, so values flow either way without casting.
+ */
+interface AgentToolCall {
+    id: string;
+    name: string;
+    input?: unknown;
+    result?: string;
+    error?: string;
+    status: 'running' | 'done' | 'error';
+}
+interface AgentMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    toolCalls?: AgentToolCall[];
+    status?: 'streaming' | 'done';
+}
+/**
+ * Minimal structural shape of a Vercel AI SDK `UIMessage` — keeps the
+ * `ai` package as a peer dep, not a runtime dep.
+ */
+interface AiSdkUIMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    parts?: ReadonlyArray<{
+        type: string;
+        text?: string;
+        toolCallId?: string;
+        state?: string;
+        input?: unknown;
+        output?: unknown;
+        errorText?: string;
+    }>;
+}
+/**
+ * Adapt AI SDK's `UIMessage[]` (from `useChat`) to the `AgentMessage[]`
+ * shape `<AgentChatLog>` consumes.
+ *
+ * @param uiMessages - the `messages` array from `useChat`
+ * @param status - the `status` from `useChat`. The last assistant
+ *   message is marked `streaming` while the chat is still in flight.
+ *
+ * @example
+ * ```tsx
+ * const chat = useChat({ ... });
+ * const messages = useMemo(
+ *   () => toAgentMessages(chat.messages, chat.status),
+ *   [chat.messages, chat.status]
+ * );
+ * return <AgentChatLog messages={messages} />;
+ * ```
+ */
+declare function toAgentMessages(uiMessages: ReadonlyArray<AiSdkUIMessage>, status: string): AgentMessage[];
+
+export { type AgentMessage, type AgentToolCall, toAgentMessages };

package/dist/ai-sdk/react.js

@@ -0,0 +1 @@
+'use strict';function g(s,r){return s.map((e,a)=>{let o="",n=[];for(let t of e.parts??[])if(t.type==="text")o+=t.text??"";else if(t.type.startsWith("tool-")){let u=t.state==="output-available"?"done":t.state==="output-error"?"error":"running";n.push({id:t.toolCallId??`${e.id}-tc-${n.length}`,name:t.type.slice(5),input:t.input,result:typeof t.output=="string"?t.output:void 0,error:t.errorText,status:u});}let i=a===s.length-1,l=e.role==="assistant"&&i&&(r==="streaming"||r==="submitted");return {id:e.id,role:e.role==="user"?"user":"assistant",text:o,toolCalls:n.length>0?n:void 0,status:l?"streaming":"done"}})}exports.toAgentMessages=g;

package/dist/ai-sdk/react.mjs

@@ -0,0 +1 @@
+function g(s,r){return s.map((e,a)=>{let o="",n=[];for(let t of e.parts??[])if(t.type==="text")o+=t.text??"";else if(t.type.startsWith("tool-")){let u=t.state==="output-available"?"done":t.state==="output-error"?"error":"running";n.push({id:t.toolCallId??`${e.id}-tc-${n.length}`,name:t.type.slice(5),input:t.input,result:typeof t.output=="string"?t.output:void 0,error:t.errorText,status:u});}let i=a===s.length-1,l=e.role==="assistant"&&i&&(r==="streaming"||r==="submitted");return {id:e.id,role:e.role==="user"?"user":"assistant",text:o,toolCalls:n.length>0?n:void 0,status:l?"streaming":"done"}})}export{g as toAgentMessages};

package/dist/ai-sdk/server.d.mts

@@ -0,0 +1,42 @@
+import { Tool } from 'ai';
+
+/**
+ * Vercel AI SDK adapter (server side) — opt-in.
+ *
+ * The core toolkit is runtime-agnostic. Use this entry only if you're
+ * wiring `streamText` / `generateText` from `ai` in your route handler.
+ * For LangChain / Anthropic SDK / OpenAI direct, import
+ * `getToolSchemas` from `@eigenpal/docx-editor-agents/server` and
+ * shape it however your runtime expects.
+ *
+ * @example
+ * ```ts
+ * import { getAiSdkTools } from '@eigenpal/docx-editor-agents/ai-sdk/server';
+ * import { streamText, stepCountIs, convertToModelMessages } from 'ai';
+ *
+ * const tools = getAiSdkTools();
+ *
+ * export async function POST(req: Request) {
+ *   const { messages } = await req.json();
+ *   const result = streamText({
+ *     model: 'openai/gpt-4o',
+ *     messages: await convertToModelMessages(messages),
+ *     tools,
+ *     stopWhen: stepCountIs(12),
+ *   });
+ *   return result.toUIMessageStreamResponse();
+ * }
+ * ```
+ */
+
+/**
+ * Get tool schemas in Vercel AI SDK shape (`{ [name]: Tool }`). Pass
+ * directly to `streamText({ tools })`. No `execute` is set, so AI SDK
+ * forwards each tool call to the client's `useChat({ onToolCall })`
+ * handler — wire that to `useDocxAgentTools().executeToolCall` from
+ * `@eigenpal/docx-editor-agents/ai-sdk/react` or
+ * `@eigenpal/docx-editor-agents/react`.
+ */
+declare function getAiSdkTools(): Record<string, Tool>;
+
+export { getAiSdkTools };

package/dist/ai-sdk/server.d.ts

@@ -0,0 +1,42 @@
+import { Tool } from 'ai';
+
+/**
+ * Vercel AI SDK adapter (server side) — opt-in.
+ *
+ * The core toolkit is runtime-agnostic. Use this entry only if you're
+ * wiring `streamText` / `generateText` from `ai` in your route handler.
+ * For LangChain / Anthropic SDK / OpenAI direct, import
+ * `getToolSchemas` from `@eigenpal/docx-editor-agents/server` and
+ * shape it however your runtime expects.
+ *
+ * @example
+ * ```ts
+ * import { getAiSdkTools } from '@eigenpal/docx-editor-agents/ai-sdk/server';
+ * import { streamText, stepCountIs, convertToModelMessages } from 'ai';
+ *
+ * const tools = getAiSdkTools();
+ *
+ * export async function POST(req: Request) {
+ *   const { messages } = await req.json();
+ *   const result = streamText({
+ *     model: 'openai/gpt-4o',
+ *     messages: await convertToModelMessages(messages),
+ *     tools,
+ *     stopWhen: stepCountIs(12),
+ *   });
+ *   return result.toUIMessageStreamResponse();
+ * }
+ * ```
+ */
+
+/**
+ * Get tool schemas in Vercel AI SDK shape (`{ [name]: Tool }`). Pass
+ * directly to `streamText({ tools })`. No `execute` is set, so AI SDK
+ * forwards each tool call to the client's `useChat({ onToolCall })`
+ * handler — wire that to `useDocxAgentTools().executeToolCall` from
+ * `@eigenpal/docx-editor-agents/ai-sdk/react` or
+ * `@eigenpal/docx-editor-agents/react`.
+ */
+declare function getAiSdkTools(): Record<string, Tool>;
+
+export { getAiSdkTools };

package/dist/ai-sdk/server.js

@@ -0,0 +1 @@
+'use strict';var chunkGZG3RJXW_js=require('../chunk-GZG3RJXW.js'),ai=require('ai');function n(){return Object.fromEntries(chunkGZG3RJXW_js.a.map(o=>[o.name,{description:o.description,inputSchema:ai.jsonSchema(o.inputSchema)}]))}exports.getAiSdkTools=n;

package/dist/ai-sdk/server.mjs

@@ -0,0 +1 @@
+import {a}from'../chunk-S2PFUY23.mjs';import {jsonSchema}from'ai';function n(){return Object.fromEntries(a.map(o=>[o.name,{description:o.description,inputSchema:jsonSchema(o.inputSchema)}]))}export{n as getAiSdkTools};

package/dist/bridge.d.mts

@@ -1,11 +1 @@
-/**
- * Editor ref bridge — optional client-side integration.
- *
- * Separate entry point: import from '@eigenpal/docx-editor-agents/bridge'
- * This file may import React/ProseMirror — NOT included in the main headless bundle.
- *
- * TODO: Implement in task 9.1
- */
-declare function createReviewBridge(_editorRef: unknown): Record<string, unknown>;
-
-export { createReviewBridge };
+export { A as AgentToolDefinition, a as AgentToolResult, n as ContentChangeEvent, v as EditorBridge, E as EditorRefLike, o as SelectionChangeEvent, U as UseAgentChatOptions, c as UseAgentChatReturn, r as agentTools, w as createEditorBridge, s as createReviewerBridge, t as executeToolCall, g as getToolSchemas, u as useAgentChat } from './server-B7dGWiLh.mjs';

package/dist/bridge.d.ts

@@ -1,11 +1 @@
-/**
- * Editor ref bridge — optional client-side integration.
- *
- * Separate entry point: import from '@eigenpal/docx-editor-agents/bridge'
- * This file may import React/ProseMirror — NOT included in the main headless bundle.
- *
- * TODO: Implement in task 9.1
- */
-declare function createReviewBridge(_editorRef: unknown): Record<string, unknown>;
-
-export { createReviewBridge };
+export { A as AgentToolDefinition, a as AgentToolResult, n as ContentChangeEvent, v as EditorBridge, E as EditorRefLike, o as SelectionChangeEvent, U as UseAgentChatOptions, c as UseAgentChatReturn, r as agentTools, w as createEditorBridge, s as createReviewerBridge, t as executeToolCall, g as getToolSchemas, u as useAgentChat } from './server-B7dGWiLh.js';

package/dist/bridge.js

@@ -1 +1 @@
-'use strict';function n(e){throw new Error("createReviewBridge is not yet implemented")}exports.createReviewBridge=n;
+'use strict';var chunk2MJYWSD3_js=require('./chunk-2MJYWSD3.js'),chunkDOKVZKIP_js=require('./chunk-DOKVZKIP.js'),chunkGZG3RJXW_js=require('./chunk-GZG3RJXW.js');Object.defineProperty(exports,"createEditorBridge",{enumerable:true,get:function(){return chunk2MJYWSD3_js.b}});Object.defineProperty(exports,"useAgentChat",{enumerable:true,get:function(){return chunk2MJYWSD3_js.a}});Object.defineProperty(exports,"createReviewerBridge",{enumerable:true,get:function(){return chunkDOKVZKIP_js.m}});Object.defineProperty(exports,"agentTools",{enumerable:true,get:function(){return chunkGZG3RJXW_js.a}});Object.defineProperty(exports,"executeToolCall",{enumerable:true,get:function(){return chunkGZG3RJXW_js.b}});Object.defineProperty(exports,"getToolSchemas",{enumerable:true,get:function(){return chunkGZG3RJXW_js.d}});

package/dist/bridge.mjs

@@ -1 +1 @@
-function n(e){throw new Error("createReviewBridge is not yet implemented")}export{n as createReviewBridge};
+export{b as createEditorBridge,a as useAgentChat}from'./chunk-AITWKLUF.mjs';export{m as createReviewerBridge}from'./chunk-4OJA3FMM.mjs';export{a as agentTools,b as executeToolCall,d as getToolSchemas}from'./chunk-S2PFUY23.mjs';