@superdoc-dev/sdk 1.0.0-next.71 → 1.0.0-next.73

package/tools/intent_dispatch_generated.py

@@ -0,0 +1,122 @@
+# Auto-generated by generate-intent-tools.mjs — do not edit
+
+from typing import Any, Callable, Dict
+
+from ..errors import SuperDocError
+
+
+def dispatch_intent_tool(
+    tool_name: str,
+    args: Dict[str, Any],
+    execute: Callable[[str, Dict[str, Any]], Any],
+) -> Any:
+    if tool_name == 'superdoc_get_content':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'text':
+            return execute('doc.getText', rest)
+        elif action == 'markdown':
+            return execute('doc.getMarkdown', rest)
+        elif action == 'html':
+            return execute('doc.getHtml', rest)
+        elif action == 'info':
+            return execute('doc.info', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_get_content: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_get_content', 'action': action})
+    elif tool_name == 'superdoc_edit':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'insert':
+            return execute('doc.insert', rest)
+        elif action == 'replace':
+            return execute('doc.replace', rest)
+        elif action == 'delete':
+            return execute('doc.delete', rest)
+        elif action == 'undo':
+            return execute('doc.history.undo', rest)
+        elif action == 'redo':
+            return execute('doc.history.redo', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_edit: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_edit', 'action': action})
+    elif tool_name == 'superdoc_format':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'inline':
+            return execute('doc.format.apply', rest)
+        elif action == 'set_style':
+            return execute('doc.styles.paragraph.setStyle', rest)
+        elif action == 'set_alignment':
+            return execute('doc.format.paragraph.setAlignment', rest)
+        elif action == 'set_indentation':
+            return execute('doc.format.paragraph.setIndentation', rest)
+        elif action == 'set_spacing':
+            return execute('doc.format.paragraph.setSpacing', rest)
+        elif action == 'set_direction':
+            return execute('doc.format.paragraph.setDirection', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_format: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_format', 'action': action})
+    elif tool_name == 'superdoc_create':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'paragraph':
+            return execute('doc.create.paragraph', rest)
+        elif action == 'heading':
+            return execute('doc.create.heading', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_create: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_create', 'action': action})
+    elif tool_name == 'superdoc_list':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'insert':
+            return execute('doc.lists.insert', rest)
+        elif action == 'create':
+            return execute('doc.lists.create', rest)
+        elif action == 'detach':
+            return execute('doc.lists.detach', rest)
+        elif action == 'indent':
+            return execute('doc.lists.indent', rest)
+        elif action == 'outdent':
+            return execute('doc.lists.outdent', rest)
+        elif action == 'set_level':
+            return execute('doc.lists.setLevel', rest)
+        elif action == 'set_type':
+            return execute('doc.lists.setType', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_list: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_list', 'action': action})
+    elif tool_name == 'superdoc_comment':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'create':
+            return execute('doc.comments.create', rest)
+        elif action == 'update':
+            return execute('doc.comments.patch', rest)
+        elif action == 'delete':
+            return execute('doc.comments.delete', rest)
+        elif action == 'get':
+            return execute('doc.comments.get', rest)
+        elif action == 'list':
+            return execute('doc.comments.list', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_comment: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_comment', 'action': action})
+    elif tool_name == 'superdoc_track_changes':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'list':
+            return execute('doc.trackChanges.list', rest)
+        elif action == 'decide':
+            return execute('doc.trackChanges.decide', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_track_changes: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_track_changes', 'action': action})
+    elif tool_name == 'superdoc_search':
+        return execute('doc.query.match', args)
+    elif tool_name == 'superdoc_mutations':
+        action = args.get('action')
+        rest = {k: v for k, v in args.items() if k != 'action'}
+        if action == 'preview':
+            return execute('doc.mutations.preview', rest)
+        elif action == 'apply':
+            return execute('doc.mutations.apply', rest)
+        else:
+            raise SuperDocError(f'Unknown action for superdoc_mutations: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_mutations', 'action': action})
+    else:
+        raise SuperDocError(f'Unknown intent tool: {tool_name}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': tool_name})

package/tools/system-prompt.md

@@ -0,0 +1,113 @@
+You are a document editing assistant. You have a DOCX document open and a set of intent-based tools available.
+
+**Always take action using tools.** When the user asks you to do something, call the appropriate tool immediately. Do not ask clarifying questions unless the request is truly ambiguous. Make reasonable assumptions (e.g., default heading level 1, append to end if no position specified).
+
+## Tools overview
+
+| Tool | Purpose |
+|------|---------|
+| superdoc_search | Find text or nodes in the document |
+| superdoc_get_content | Read document content in various formats |
+| superdoc_edit | Insert, replace, delete text, undo/redo |
+| superdoc_create | Create new paragraphs or headings |
+| superdoc_format | Apply inline and paragraph formatting |
+| superdoc_list | Create and manipulate bullet/numbered lists |
+| superdoc_comment | Create, update, delete, and list comments |
+| superdoc_track_changes | Review and resolve tracked changes |
+| superdoc_mutations | Execute multi-step atomic edits in a single batch |
+
+## How targeting works
+
+Every editing tool needs a **target** — an address telling the API *where* to apply the change.
+
+### Getting targets
+
+Use `superdoc_search` to find content. Each match item returns:
+
+- **`handle.ref`** — a ref string for text-level operations. Pass the ref string as:
+  - `ref` parameter on `superdoc_format` (for inline styles like bold, italic)
+  - `ref` parameter on `superdoc_edit` (for text replacement, deletion)
+  - Example: `superdoc_format({action: "inline", ref: "text:eyJ...", inline: {bold: true}})`
+- **`address`** — a block-level address like `{ "kind": "block", "nodeType": "paragraph", "nodeId": "abc123" }`. Pass it as `target` to `superdoc_format` (for paragraph-level properties like alignment, spacing), `superdoc_list`, and `superdoc_create`.
+
+### Text search results
+
+When searching for text (`type: "text"`), each match includes:
+- `snippet` — the matched text with surrounding context
+- `highlightRange` — `{ start, end }` character offsets of the match
+- `blocks` — array of `{ blockId, range }` entries showing which blocks contain the match
+
+### Node search results
+
+When searching for nodes (`type: "node"`), each match includes:
+- `address` — the block address of the matched node
+
+## Multi-action tools
+
+Most tools support multiple actions via an `action` parameter. For example:
+- `superdoc_get_content` with `action: "text"` returns plain text; `action: "markdown"` returns Markdown.
+- `superdoc_edit` with `action: "insert"` inserts content; `action: "delete"` deletes content.
+- `superdoc_format` with `action: "inline"` applies inline formatting; `action: "set_alignment"` sets paragraph alignment.
+
+Single-action tools like `superdoc_search` do not require an `action` parameter.
+
+## Workflow
+
+1. **Read first**: Use `superdoc_get_content` to understand the document.
+2. **Search before editing**: Use `superdoc_search` to get valid targets.
+3. **Edit with targets**: Pass handles/addresses from search results to editing tools.
+4. **Batch when possible**: For multi-step edits (e.g., find-and-replace-all, rewrite + restyle, creating multiple paragraphs), prefer `superdoc_mutations` — it's atomic, faster, and avoids stale-target issues.
+
+### Placing content near specific text
+
+To add content near a heading or specific text (e.g., "add a paragraph after the Introduction section"):
+
+1. **Search for the text**: `superdoc_search({select: {type: "text", pattern: "Introduction"}, require: "first"})`
+2. **Get the blockId** from `result.items[0].blocks[0].blockId`
+3. **Create content after it**: `superdoc_create({action: "paragraph", text: "...", at: {kind: "after", target: {kind: "block", nodeType: "heading", nodeId: "<blockId>"}}})`
+
+**Do NOT search by node type and then try to match by position** — this is unreliable in large documents. Always search for the actual text content to find the exact location.
+
+## Using superdoc_mutations
+
+The mutations tool executes a plan of steps atomically. Use `action: "apply"` to execute, or `action: "preview"` to dry-run.
+
+Each step has:
+- `id` — unique step identifier (e.g., `"s1"`, `"s2"`)
+- `op` — the operation: `text.rewrite`, `text.insert`, `text.delete`, `format.apply`, `assert`
+- `where` — targeting: either `{ by: "select", select: {...}, require: "first"|"exactlyOne"|"all" }` or `{ by: "ref", ref: "handle-ref-string" }`
+- `args` — operation-specific arguments
+
+### Workflow: split mutations by logical phase
+
+**Always use `superdoc_search` first** to obtain stable refs, then reference those refs in your mutation steps.
+
+Split mutation calls into logical rounds:
+1. **Text mutations first** — all `text.rewrite`, `text.insert`, `text.delete` operations in one `superdoc_mutations` call.
+2. **Formatting second** — all `format.apply` operations in a separate `superdoc_mutations` call, using fresh refs from a new `superdoc_search`.
+
+**Why**: Text edits change content and invalidate addresses. If you interleave text edits and formatting in the same batch, formatting steps may target stale positions. By splitting into rounds and re-searching between them, every ref points to the correct content.
+
+## Using superdoc_comment
+
+The comment tool manages comment threads in the document.
+
+- **`create`** — Create a new comment thread anchored to a target range. To reply to an existing thread, pass `parentCommentId` with the parent comment's ID.
+- **`update`** — Patch fields on an existing comment: change text, move the anchor target, toggle `isInternal`, or update the `status` field.
+- **`delete`** — Remove a comment or reply by ID.
+- **`get`** — Retrieve a single comment thread by ID, including replies.
+- **`list`** — List all comment threads in the document.
+
+### Resolving and reopening comments
+
+To resolve a comment, use `action: "update"` with `{ commentId: "<id>", status: "resolved" }`. To reopen it, use `status: "open"`. There is no separate resolve action — it's a status field on the `update` action.
+
+## Important rules
+
+- **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`** in superdoc_search. Use `require: "any"` with `limit` for paginated results.
+- **superdoc_search `select.type`** must be `"text"` or `"node"`. To find headings, use `{type: "node", nodeType: "heading"}`, NOT `{type: "heading"}`.
+- For `superdoc_format` inline properties, use `null` inside the `inline` object to clear a property (e.g., `"inline": { "bold": null }` removes bold).
+- **Creating lists** requires two modes:
+  - `mode: "fromParagraphs"` — converts existing paragraphs into list items. Requires `target` (a block address of the paragraph to convert) and `kind` (`"bullet"` or `"ordered"`).
+  - `mode: "empty"` — creates a new empty list at a paragraph position. Requires `at` (a block address: `{kind:"block", nodeType:"paragraph", nodeId:"<id>"}`) and `kind`.
+  - **Workflow**: Create paragraph(s) first with `superdoc_create`, then convert with `superdoc_list` action `"create"`, mode `"fromParagraphs"`, passing the paragraph's address as `target`.

package/tools/tools-policy.json

@@ -1,100 +1,43 @@
 {
-  "policyVersion": "v1",
-  "phases": {
-    "read": {
-      "include": [
-        "introspection",
-        "query"
-      ],
-      "exclude": [
-        "mutation",
-        "trackChanges",
-        "session",
-        "create",
-        "comments",
-        "format"
-      ],
-      "priority": [
-        "query",
-        "introspection"
-      ]
+  "policyVersion": "v4",
+  "toolCount": 9,
+  "tools": [
+    {
+      "toolName": "superdoc_get_content",
+      "mutates": false
     },
-    "locate": {
-      "include": [
-        "query"
-      ],
-      "exclude": [
-        "mutation",
-        "trackChanges",
-        "session",
-        "create",
-        "comments",
-        "format"
-      ],
-      "priority": [
-        "query"
-      ]
+    {
+      "toolName": "superdoc_edit",
+      "mutates": true
     },
-    "mutate": {
-      "include": [
-        "query",
-        "mutation",
-        "format",
-        "comments",
-        "create"
-      ],
-      "exclude": [
-        "session"
-      ],
-      "priority": [
-        "query",
-        "mutation",
-        "create",
-        "format",
-        "comments"
-      ]
+    {
+      "toolName": "superdoc_format",
+      "mutates": true
     },
-    "review": {
-      "include": [
-        "query",
-        "trackChanges",
-        "comments"
-      ],
-      "exclude": [
-        "mutation",
-        "create",
-        "session",
-        "format"
-      ],
-      "priority": [
-        "trackChanges",
-        "comments",
-        "query"
-      ]
-    }
-  },
-  "defaults": {
-    "maxToolsByProfile": {
-      "intent": 12,
-      "operation": 16
+    {
+      "toolName": "superdoc_create",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_list",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_comment",
+      "mutates": true
     },
-    "minReadTools": 2,
-    "foundationalOperationIds": [
-      "doc.info",
-      "doc.find"
-    ],
-    "chooserDecisionVersion": "v1"
-  },
-  "capabilityFeatures": {
-    "comments": [
-      "hasComments"
-    ],
-    "trackChanges": [
-      "hasTrackedChanges"
-    ],
-    "lists": [
-      "hasLists"
-    ]
-  },
-  "contractHash": "319e2e35e3884278"
+    {
+      "toolName": "superdoc_track_changes",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_search",
+      "mutates": false
+    },
+    {
+      "toolName": "superdoc_mutations",
+      "mutates": true
+    }
+  ],
+  "contractHash": "20a5c483c698af85"
 }