@superdoc-dev/sdk 1.0.0-alpha.44 → 1.0.0-alpha.46

package/tools/intent_dispatch_generated.py

@@ -0,0 +1,120 @@
+# 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)
+        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,94 @@
+You are a document editing assistant. You have a DOCX document open and a set of intent-based tools available.
+
+## 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`** — an opaque reference for text-level operations. Pass it directly as `target` to `superdoc_edit` and `superdoc_format` (for inline styles like bold, italic, etc.).
+- **`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), prefer `superdoc_mutations` — it's atomic, faster, and avoids stale-target issues.
+
+## 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.
+- For `superdoc_format` inline properties, use `null` inside the `inline` object to clear a property (e.g., `"inline": { "bold": null }` removes bold).
+- For `superdoc_list` create action: this converts existing paragraphs into list items. Create the paragraph first with `superdoc_create`, then convert it with `superdoc_list` action `create`.

package/tools/tools-policy.json

@@ -1,98 +1,43 @@
 {
-  "policyVersion": "v3",
-  "groups": [
-    "core",
-    "format",
-    "create",
-    "tables",
-    "sections",
-    "lists",
-    "comments",
-    "trackChanges",
-    "toc",
-    "history",
-    "session"
-  ],
-  "groupDescriptions": {
-    "core": "Core operations: read nodes, get text, insert/replace/delete content, mutations",
-    "format": "Text formatting, paragraph styles, alignment, spacing, borders, shading",
-    "create": "Create structural elements: headings, paragraphs, tables, sections, TOC",
-    "tables": "Table creation, manipulation, formatting, borders, and cell operations",
-    "sections": "Page layout, margins, columns, headers/footers, page numbering",
-    "lists": "Bullet and numbered lists, indentation, list types",
-    "comments": "Comment threads — create, edit, delete, list",
-    "trackChanges": "Track changes — list, inspect, accept/reject",
-    "toc": "Table of contents — create, configure, update, manage entries",
-    "history": "Undo, redo, history inspection",
-    "session": "Session management — open, close, save, list sessions"
-  },
-  "defaults": {
-    "mode": "essential",
-    "maxTools": 20,
-    "alwaysInclude": [
-      "core"
-    ],
-    "foundationalOperationIds": [
-      "doc.info",
-      "doc.query.match"
-    ]
-  },
-  "capabilityFeatures": {
-    "comments": [
-      "hasComments"
-    ],
-    "trackChanges": [
-      "hasTrackedChanges"
-    ],
-    "lists": [
-      "hasLists"
-    ],
-    "tables": [
-      "hasTables"
-    ],
-    "toc": [
-      "hasToc"
-    ]
-  },
-  "essentialTools": [
-    "get_node_by_id",
-    "get_document_text",
-    "blocks_list",
-    "query_match",
-    "apply_mutations",
-    "undo"
-  ],
-  "discoverTool": {
-    "name": "discover_tools",
-    "description": "Load additional tool groups when you need capabilities beyond the essential set. Call this BEFORE attempting to use tools from a specific group.\n\nAvailable groups:\n  - core: Core operations: read nodes, get text, insert/replace/delete content, mutations\n  - format: Text formatting, paragraph styles, alignment, spacing, borders, shading\n  - create: Create structural elements: headings, paragraphs, tables, sections, TOC\n  - tables: Table creation, manipulation, formatting, borders, and cell operations\n  - sections: Page layout, margins, columns, headers/footers, page numbering\n  - lists: Bullet and numbered lists, indentation, list types\n  - comments: Comment threads — create, edit, delete, list\n  - trackChanges: Track changes — list, inspect, accept/reject\n  - toc: Table of contents — create, configure, update, manage entries\n  - history: Undo, redo, history inspection\n  - session: Session management — open, close, save, list sessions",
-    "schema": {
-      "type": "object",
-      "properties": {
-        "groups": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": [
-              "core",
-              "format",
-              "create",
-              "tables",
-              "sections",
-              "lists",
-              "comments",
-              "trackChanges",
-              "toc",
-              "history",
-              "session"
-            ]
-          },
-          "description": "Which tool groups to load. You can request multiple at once."
-        }
-      },
-      "required": [
-        "groups"
-      ]
+  "policyVersion": "v4",
+  "toolCount": 9,
+  "tools": [
+    {
+      "toolName": "superdoc_get_content",
+      "mutates": false
+    },
+    {
+      "toolName": "superdoc_edit",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_format",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_create",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_list",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_comment",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_track_changes",
+      "mutates": true
+    },
+    {
+      "toolName": "superdoc_search",
+      "mutates": false
+    },
+    {
+      "toolName": "superdoc_mutations",
+      "mutates": true
     }
-  },
-  "contractHash": "a352150e32ad347a"
+  ],
+  "contractHash": "f095fb10203af04f"
 }