SD-2091 - Document API SDK - Agentic collab example code by mattConnHarbour · Pull Request #2490 · superdoc-dev/superdoc

mattConnHarbour · 2026-03-20T04:50:29Z

No description provided.

linear · 2026-03-20T04:50:34Z

SD-2091 Doc API SDK - make example based on documentation

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bde471577

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-20T04:55:38Z

examples/document-api/agentic-collaboration/Dockerfile

+RUN npm ci --omit=dev
+
+# Copy server files only (not the Vue client source)
+COPY server.ts start.ts agent.ts ./


Copy the actual agent sources into the backend image

I checked this example's tree and package.json: the only agent implementation lives under agent/ (agent/index.ts plus agent/chat.ts), while this Dockerfile copies a non-existent top-level agent.ts. That makes docker build/gcloud builds submit fail for the Cloud Run backend from a clean checkout, so deploy-backend.sh cannot produce a runnable image.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-20T04:55:38Z

examples/document-api/agentic-collaboration/start.ts

+
+// Wait a bit for server to start, then start agent
+setTimeout(() => {
+  const agent = spawn('npx', ['tsx', join(__dirname, 'agent.ts')], {


Launch agent/index.ts from the combined startup script

Even if the image contents are fixed, this startup path still points tsx at agent.ts, but the example's agent entrypoint is agent/index.ts (the same path used by npm run dev:agent). Running start.ts will therefore spawn a child that immediately exits because the file does not exist, and the parent then exits in agent.on('exit'), leaving the deployment without the AI agent.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-20T04:55:38Z

examples/document-api/agentic-collaboration/src/App.vue

+  ws.onopen = () => {
+    console.log('[Client] Chat connected');
+    // Clear chat history on connect (fresh start each page load)
+    ws.send(JSON.stringify({ type: 'clear' }));


Stop resetting the shared chat state on every connect

Connecting a browser now sends clear unconditionally. In this example, server.ts handles clear by wiping room.messages and broadcasting the event, and agent/chat.ts maps that broadcast to clearConversation(). That means opening a second tab or refreshing the page erases the chat transcript and the agent's context for everyone in the room, which breaks follow-up requests in collaborative sessions.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5b2a145de1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-23T06:06:51Z

examples/document-api/agentic-collaboration/README.md

+```bash
+npm install
+```


Tell users to install the child package dependencies

Following the Quick Start from a clean checkout cannot work: this example is not an npm workspace, so npm install here only installs the root concurrently dependency. The actual runtime packages live in client/package.json, server/package.json, and agent/package.json, so npm run dev immediately fails with missing vite/tsx binaries unless readers also run npm run install:all.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-23T06:06:51Z

examples/document-api/agentic-collaboration/package.json

+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently \"npm run dev:server\" \"npm run dev:client\" \"npm run dev:agent\"",


Wait for the backend before spawning the agent

npm run dev launches the server and agent at the same time, but agent/agent.ts immediately connects to ws://localhost:3050 twice (client.open(...collaboration...) and new Chat(...).connect()) without any retry/backoff. On a normal cold start the server can lose that race, causing the agent process to die with ECONNREFUSED and leaving the sidebar permanently offline until the user restarts it manually.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-23T06:06:51Z

examples/document-api/agentic-collaboration/agent/agent.ts

+  while (true) {
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages,
+      tools: tools as OpenAI.ChatCompletionTool[],


Cap the tool-calling loop for each chat turn

processMessage() has an unbounded while (true) around model/tool execution. If the model keeps emitting tool calls—for example after a malformed argument or a prompt that makes it bounce between read/edit actions—the request never completes and keeps burning OpenAI tokens until the process is killed. The example README already shows a bounded loop, so this runtime path should have the same guard.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-23T06:06:51Z

examples/document-api/agentic-collaboration/agent/chat.ts

+    this.ws.on('message', async (data) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.type === 'message' && msg.message?.role === 'user') {
+        this.setStatus('thinking');
+        try {


Serialize chat turns before touching shared history

Chat.serve() starts a fresh async handler for every incoming user message, but agent.ts keeps one module-level conversationHistory for all turns. In a collaborative room, two users can send requests close together and both turns will read/append that shared array concurrently, so future context can end up out of order or attributed to the wrong request.

Useful? React with 👍 / 👎.

andrii-harbour

there are things that are not up to date
and a few things that need more attention from the dev perspective. We should assume this code can be run immediately after providing api key.

andrii-harbour · 2026-03-23T21:41:45Z

examples/document-api/agentic-collaboration/agent/agent.ts

+
+  while (true) {
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o',


please use the most recent model

andrii-harbour · 2026-03-23T21:43:38Z

examples/document-api/agentic-collaboration/agent/agent.ts

+async function processMessage(userMessage: string): Promise<string> {
+  conversationHistory.push({ role: 'user', content: userMessage });
+  const messages: OpenAI.ChatCompletionMessageParam[] = [...conversationHistory];
+
+  while (true) {
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages,
+      tools: tools as OpenAI.ChatCompletionTool[],
+    });
+
+    const message = response.choices[0].message;
+    messages.push(message);
+
+    if (!message.tool_calls?.length) {
+      conversationHistory.push({ role: 'assistant', content: message.content || 'Done.' });
+      return message.content || 'Done.';
+    }
+
+    for (const call of message.tool_calls) {
+      const result = await dispatchSuperDocTool(
+        doc,
+        call.function.name,
+        JSON.parse(call.function.arguments),
+      );
+      messages.push({
+        role: 'tool',
+        tool_call_id: call.id,
+        content: JSON.stringify(result),
+      });
+    }
+  }
+}


while (true) {

No iteration cap. If the LLM keeps generating tool calls (hallucinating or stuck in a loop), this runs forever. Add a max iterations guard (e.g., 10-20 rounds).

andrii-harbour · 2026-03-23T21:44:33Z

examples/document-api/agentic-collaboration/agent/package.json

+  "dependencies": {
+    "@superdoc-dev/sdk": "^1.0.0",
+    "dotenv": "^16.4.7",
+    "openai": "^4.78.0",


this is not the most recent version

andrii-harbour · 2026-03-23T21:45:46Z

examples/document-api/agentic-collaboration/client/src/App.vue

+      url: sampleDocument,
+      isNewFile: true,
+    },
+    pagination: false,


as I remember we don't have this parameter anymore, we're using layoutEngineOptions instead

andrii-harbour · 2026-03-23T21:47:09Z

examples/document-api/agentic-collaboration/server/server.ts

+const handleOnChange = async (params: CollaborationParams): Promise<void> => {
+  // Quiet - too noisy
+};
+
+const handleAutoSave = async (params: CollaborationParams): Promise<void> => {
+  // Quiet - too noisy
+};


do we really need them then?

andrii-harbour · 2026-03-23T21:50:02Z

examples/document-api/agentic-collaboration/README.md

+
+const { tools } = await chooseTools({
+  provider: 'openai',
+  mode: 'all',  // Include mutation tools


we don't have that

andrii-harbour · 2026-03-23T21:50:32Z

examples/document-api/agentic-collaboration/README.md

+  value: '# New Heading\n\nSome paragraph text.',
+  type: 'markdown',


let's use another example (non-markdown one)

andrii-harbour · 2026-03-23T22:35:36Z

examples/document-api/agentic-collaboration/README.md

+- **Wrangler CLI** (`npx wrangler`) authenticated with Cloudflare
+- **OpenAI API key** in `.env`
+
+### Step 1: Deploy Backend (Cloud Run)
+
+The backend includes the collaboration server and AI agent in a single container.
+
+```bash
+# Make sure .env has your OpenAI key
+npm run deploy:backend
+```
+
+This will:
+1. Build a Docker container with the server and agent
+2. Push it to Google Container Registry
+3. Deploy to Cloud Run with WebSocket support
+4. Output the service URL (e.g., `https://superdoc-agent-demo-xxxxx.run.app`)


do we really need that for example code?

andrii-harbour · 2026-03-23T22:36:12Z

examples/document-api/agentic-collaboration/README.md

+### Step 3: Deploy Frontend (Cloudflare Pages)
+
+```bash
+npm run deploy:frontend
+```
+
+This will:
+1. Build the Vue client with the backend URL baked in
+2. Deploy to Cloudflare Pages (project: `document-api-agentic-demo`)
+
+The frontend will be available at: `https://document-api-agentic-demo.pages.dev`


same as above

andrii-harbour · 2026-03-23T22:37:55Z

CLAUDE.md

-**When writing copy or content:** see `brand.md` for the full brand identity — strategy, voice, and visual guidelines. Product name is always **SuperDoc** (capital S, capital D).
+**When writing copy or content:** see `brand/brand-guidelines.md` for voice, tone, and the dual-register pattern (developer vs. leader). Product name is always **SuperDoc** (capital S, capital D).
+
+## SD-2091: chooseTools() Investigation Findings (RESOLVED)


this document is not up-to-date

mattConnHarbour added 4 commits March 4, 2026 19:15

Merge branch 'main' into SD-2091

8077e6b

feat: add document API collab example

0b54019

Merge branch 'main' into SD-2091

c1ffd9f

fix: update doc api sdk example to use latest version

2bde471

mattConnHarbour marked this pull request as draft March 20, 2026 04:50

superdoc-bot bot added the review: quick label Mar 20, 2026

chatgpt-codex-connector bot reviewed Mar 20, 2026

View reviewed changes

mattConnHarbour force-pushed the SD-2091 branch 5 times, most recently from 851c177 to d93c944 Compare March 23, 2026 04:55

Merge branch 'main' into SD-2091

5b2a145

mattConnHarbour force-pushed the SD-2091 branch from d93c944 to 5b2a145 Compare March 23, 2026 05:59

mattConnHarbour marked this pull request as ready for review March 23, 2026 05:59

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

mattConnHarbour requested a review from andrii-harbour March 23, 2026 13:39

andrii-harbour requested changes Mar 23, 2026

View reviewed changes

		value: '# New Heading\n\nSome paragraph text.',
		type: 'markdown',

Conversation

mattConnHarbour commented Mar 20, 2026

Uh oh!

linear bot commented Mar 20, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

andrii-harbour left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants