SD-2091 - Document API SDK - Agentic collab example code

CLAUDE.md

@@ -209,3 +209,85 @@ Preset theme overrides are defined in `packages/superdoc/src/assets/styles/helpe
 - Expose UI component-specific variables as `--sd-ui-{component}-*` so consumers can customize via CSS.
 
 **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)
+
+### Root Cause
+
+The `chooseTools()` function wasn't returning mutation tools due to:
+
+1. **Default phase is `'read'`** — excludes `mutation`, `create`, `format` categories
+2. **Wrong budget syntax** — `budget: 100` should be `budget: { maxTools: 100 }`
+3. **Default maxTools is 12** — limits tools even when phase allows more
+
+### How chooseTools() Works
+
+**Location**: `packages/sdk/langs/node/src/tools.ts`
+
+The function filters tools based on phase, then applies budget limits:
+
+| Phase | Included Categories | Excluded Categories |
+|-------|---------------------|---------------------|
+| `read` (default) | introspection, query | mutation, create, format, comments, trackChanges, session |
+| `mutate` | query, mutation, format, comments, create | session |
+| `locate` | query | mutation, create, format, comments, trackChanges, session |
+| `review` | query, trackChanges, comments | mutation, create, format, session |
+
+**Default budgets**: intent=12, operation=16 tools max.
+
+### Correct Usage for Mutation Tools
+
+**IMPORTANT:** The npm SDK (v1.0.0-alpha.44) has a different API than local development.
+
+```typescript
+// npm SDK v1.0.0-alpha.44 API
+const { tools, selected, meta } = await chooseTools({
+  provider: 'openai',
+  mode: 'all',                          // 'essential' (default) or 'all'
+  groups: ['core', 'format', 'create'], // Additional groups to include
+  includeDiscoverTool: false,           // Whether to include discover_tools meta-tool
+});
+
+// Filter out LLM-incompatible tools manually
+const EXCLUDED = new Set(['apply_mutations', 'query_match', 'preview_mutations']);
+const filteredTools = tools.filter((t) => !EXCLUDED.has(t.function.name));
+```
+
+**Available groups:** `core`, `format`, `create`, `tables`, `sections`, `lists`, `comments`, `trackChanges`, `toc`, `images`, `history`, `session`
+
+**Note:** The local dev version has more sophisticated options (`taskContext.phase`, `budget`, `policy.forceInclude/forceExclude`) that aren't in the npm package yet.
+
+### Available Tools by Category (intent profile)
+
+| Category | Tools |
+|----------|-------|
+| mutation | `insert_content`, `replace_content`, `delete_content`, `apply_mutations` |
+| create | `create_paragraph`, `create_heading`, `create_section_break`, `create_table`, `create_table_of_contents`, `create_image` |
+| query | `find_content`, `get_node`, `get_node_by_id`, `get_document_text`, `get_document_markdown`, `get_document_html`, `get_document_info`, `query_match`, `preview_mutations` |
+| format | `format_bold`, `format_italic`, `format_underline`, + 30 more |
+
+### Tools With Complex Schemas (LLM Incompatible)
+
+These tools have discriminated union schemas that LLMs cannot construct correctly:
+
+| Tool | Issue |
+|------|-------|
+| `apply_mutations` | Complex `steps` array with discriminated union variants |
+| `query_match` | Complex `select` parameter with multiple schema variants |
+| `preview_mutations` | Same as apply_mutations |
+
+Use `forceExclude` to remove these from LLM tool sets.
+
+### Files Changed
+
+**examples/collaboration/superdoc-yjs/**
+- `agent.ts` — Fixed `chooseTools()` configuration with correct budget syntax and forceInclude/forceExclude
+- `package.json` — Uses npm packages (`superdoc@^1.18.2`, `@superdoc-dev/sdk@^1.0.0-alpha.44`)
+- `src/App.vue` — Chat sidebar for agent communication
+- `README.md` — Customer documentation
+
+### Remaining Work
+
+1. **Fix tool schema generation** for `apply_mutations` and `query_match` to be LLM-compatible
+2. **Consider adding wrapper tools** with simpler schemas for complex operations
+3. **Document chooseTools() gotchas** in SDK documentation

examples/document-api/agentic-collaboration/.dockerignore

@@ -0,0 +1,14 @@
+node_modules
+npm-debug.log
+.env
+.env.local
+.env.example
+.git
+.gitignore
+README.md
+*.md
+.DS_Store
+dist
+.vite
+wrangler.toml
+deploy-*.sh

examples/document-api/agentic-collaboration/.env.example

@@ -0,0 +1,6 @@
+# OpenAI API key (required for agent)
+OPENAI_API_KEY=sk-your-key-here
+
+# Backend URL (set after Cloud Run deployment)
+# Leave empty for local development (defaults to localhost:3050)
+VITE_BACKEND_URL=

examples/document-api/agentic-collaboration/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/document-api/agentic-collaboration/Dockerfile

@@ -0,0 +1,27 @@
+# SuperDoc Collaboration Server + Agent
+# For deployment to Google Cloud Run
+
+FROM node:20-slim
+
+# Cloud Run sets PORT dynamically (usually 8080)
+# Default to 3050 for local testing
+ENV NODE_ENV=production
+
+WORKDIR /app
+
+# Install dependencies (production only - no need for vite/vue devDependencies)
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+# Copy server files only (not the Vue client source)
+COPY server.ts start.ts agent.ts ./
+COPY public ./public
+
+# Cloud Run sets PORT dynamically and routes traffic to it
+# EXPOSE is informational only (Cloud Run ignores it)
+
+# Cloud Run handles health checks via its own mechanism
+# No HEALTHCHECK needed - Cloud Run uses the startup probe
+
+# Run with tsx (TypeScript execution)
+CMD ["npx", "tsx", "start.ts"]