@superdoc-dev/sdk 1.19.2 → 1.20.1

package/dist/generated/contract.cjs

@@ -13474,7 +13474,7 @@ const CONTRACT = {
                 "list"
             ],
             "category": "core",
-            "description": "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: <StoryLocator>`.",
+            "description": "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Text, previews, lengths, and formatting hints use the VISIBLE model: pending tracked deletions are excluded (matching how edit refs resolve), and inline atoms render as a single placeholder character. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: <StoryLocator>`.",
             "requiresDocumentContext": true,
             "docRequirement": "optional",
             "responseEnvelopeKey": "result",
@@ -13884,6 +13884,65 @@ const CONTRACT = {
                                     },
                                     "additionalProperties": false
                                 },
+                                "numbering": {
+                                    "type": "object",
+                                    "description": "Computed numbering rendering (marker/path/kind) for numbered list items and numbered headings — e.g. the rendered clause label \"2.3.\". Absent for non-numbered blocks.",
+                                    "properties": {
+                                        "marker": {
+                                            "oneOf": [
+                                                {
+                                                    "type": "string"
+                                                },
+                                                {
+                                                    "type": "null"
+                                                }
+                                            ]
+                                        },
+                                        "path": {
+                                            "oneOf": [
+                                                {
+                                                    "type": "array",
+                                                    "items": {
+                                                        "type": "number"
+                                                    }
+                                                },
+                                                {
+                                                    "type": "null"
+                                                }
+                                            ]
+                                        },
+                                        "kind": {
+                                            "oneOf": [
+                                                {
+                                                    "type": "string"
+                                                },
+                                                {
+                                                    "type": "null"
+                                                }
+                                            ]
+                                        }
+                                    },
+                                    "additionalProperties": false
+                                },
+                                "indent": {
+                                    "type": "object",
+                                    "description": "Direct paragraph indentation in twips (only non-zero fields present).",
+                                    "properties": {
+                                        "left": {
+                                            "type": "number"
+                                        },
+                                        "right": {
+                                            "type": "number"
+                                        },
+                                        "firstLine": {
+                                            "type": "number"
+                                        },
+                                        "hanging": {
+                                            "type": "number"
+                                        }
+                                    },
+                                    "additionalProperties": false
+                                },
                                 "ref": {
                                     "type": "string",
                                     "description": "Ref handle for this block. Pass directly to superdoc_format or superdoc_edit ref param. Only present for non-empty blocks."
@@ -112872,7 +112931,7 @@ const CONTRACT = {
                 "attach"
             ],
             "category": "lists",
-            "description": "Convert non-list paragraphs to list items under an existing list sequence.",
+            "description": "Convert non-list paragraphs to list items under an existing list sequence. With changeMode:\"tracked\" the former (unnumbered) paragraph properties are recorded as a w:pPrChange so a reviewer can accept/reject the numbering.",
             "requiresDocumentContext": true,
             "docRequirement": "optional",
             "responseEnvelopeKey": "result",
@@ -113222,7 +113281,7 @@ const CONTRACT = {
             "constraints": null,
             "mutates": true,
             "idempotency": "conditional",
-            "supportsTrackedMode": false,
+            "supportsTrackedMode": true,
             "supportsDryRun": true,
             "inputSchema": {
                 "type": "object",
@@ -134541,6 +134600,17 @@ const CONTRACT = {
                                             }
                                         ],
                                         "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed."
+                                    },
+                                    "side": {
+                                        "oneOf": [
+                                            {
+                                                "const": "inserted"
+                                            },
+                                            {
+                                                "const": "deleted"
+                                            }
+                                        ],
+                                        "description": "Optional replacement side. When the id resolves to a paired replacement, decides only the 'inserted' or 'deleted' half, leaving the other half as a standalone pending change."
                                     }
                                 },
                                 "required": [
@@ -135837,6 +135907,17 @@ const CONTRACT = {
                                             }
                                         ],
                                         "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed."
+                                    },
+                                    "side": {
+                                        "oneOf": [
+                                            {
+                                                "const": "inserted"
+                                            },
+                                            {
+                                                "const": "deleted"
+                                            }
+                                        ],
+                                        "description": "Optional replacement side. When the id resolves to a paired replacement, decides only the 'inserted' or 'deleted' half."
                                     }
                                 },
                                 "required": [
@@ -136293,6 +136374,13 @@ const CONTRACT = {
                                             "destination"
                                         ],
                                         "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed."
+                                    },
+                                    "side": {
+                                        "enum": [
+                                            "inserted",
+                                            "deleted"
+                                        ],
+                                        "description": "Optional replacement side. When the id resolves to a paired replacement, decides only the 'inserted' or 'deleted' half, leaving the other half as a standalone pending change."
                                     }
                                 },
                                 "additionalProperties": false,
@@ -136486,6 +136574,13 @@ const CONTRACT = {
                                             "destination"
                                         ],
                                         "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed."
+                                    },
+                                    "side": {
+                                        "enum": [
+                                            "inserted",
+                                            "deleted"
+                                        ],
+                                        "description": "Optional replacement side. When the id resolves to a paired replacement, decides only the 'inserted' or 'deleted' half."
                                     }
                                 },
                                 "additionalProperties": false,
@@ -251114,6 +251209,112 @@ const CONTRACT = {
                 ]
             }
         },
+        "doc.executeCode": {
+            "operationId": "doc.executeCode",
+            "sdkSurface": "document",
+            "command": "execute code",
+            "commandTokens": [
+                "execute",
+                "code"
+            ],
+            "category": "core",
+            "description": "Run model-authored JavaScript IN-HOST against the live, SYNCHRONOUS Document API for the open session. Two globals are injected: `doc` (the synchronous Document API — do NOT await doc.* calls) and `console`. `return` a short summary; logs and the return value come back structured as { ok, result, logs, error }. Use for complex/multi-step workflows (loops, per-item branching, extract-then-generate) in ONE call instead of chaining many narrow tools. Large code can be passed on stdin.",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [
+                {
+                    "name": "sessionId",
+                    "kind": "flag",
+                    "type": "string",
+                    "flag": "session",
+                    "description": "Session ID for multi-session workflows. Optional when only one session is open."
+                },
+                {
+                    "name": "expectedRevision",
+                    "kind": "flag",
+                    "type": "number",
+                    "flag": "expected-revision",
+                    "agentVisible": false
+                },
+                {
+                    "name": "code",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "JavaScript body run as an async function with `doc` (synchronous Document API — do NOT await) and `console` injected. Omit to pass code on stdin."
+                }
+            ],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "code": {
+                        "type": "string",
+                        "description": "JavaScript body run as an async function with `doc` (synchronous Document API — do NOT await) and `console` injected. Omit to pass code on stdin."
+                    }
+                },
+                "additionalProperties": false
+            },
+            "mutates": true,
+            "idempotency": "non-idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object",
+                "properties": {
+                    "ok": {
+                        "type": "boolean"
+                    },
+                    "result": {},
+                    "logs": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "level": {
+                                    "type": "string"
+                                },
+                                "message": {
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    },
+                    "error": {
+                        "type": "object",
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            },
+                            "message": {
+                                "type": "string"
+                            },
+                            "stack": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "context": {
+                        "type": "object",
+                        "properties": {
+                            "dirty": {
+                                "type": "boolean"
+                            },
+                            "revision": {
+                                "type": "number"
+                            },
+                            "mutated": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                },
+                "required": [
+                    "ok",
+                    "logs"
+                ]
+            }
+        },
         "doc.status": {
             "operationId": "doc.status",
             "sdkSurface": "internal",
@@ -251702,6 +251903,424 @@ const CONTRACT = {
                     "activeSessionId"
                 ]
             }
+        },
+        "doc.preset.list": {
+            "operationId": "doc.preset.list",
+            "sdkSurface": "document",
+            "command": "preset list",
+            "commandTokens": [
+                "preset",
+                "list"
+            ],
+            "category": "session",
+            "description": "List the LLM-tools preset ids registered in the Node SDK preset registry, plus the default preset id.",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+            },
+            "mutates": false,
+            "idempotency": "idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object",
+                "properties": {
+                    "presets": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "defaultPreset": {
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "presets",
+                    "defaultPreset"
+                ]
+            },
+            "skipAsATool": true
+        },
+        "doc.preset.getCatalog": {
+            "operationId": "doc.preset.getCatalog",
+            "sdkSurface": "document",
+            "command": "preset get-catalog",
+            "commandTokens": [
+                "preset",
+                "get-catalog"
+            ],
+            "category": "session",
+            "description": "Return the full tool catalog for an LLM-tools preset (defaults to the registered default preset).",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [
+                {
+                    "name": "preset",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                }
+            ],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "preset": {
+                        "type": "string",
+                        "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                    }
+                },
+                "additionalProperties": false
+            },
+            "mutates": false,
+            "idempotency": "idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object"
+            },
+            "skipAsATool": true
+        },
+        "doc.preset.getTools": {
+            "operationId": "doc.preset.getTools",
+            "sdkSurface": "document",
+            "command": "preset get-tools",
+            "commandTokens": [
+                "preset",
+                "get-tools"
+            ],
+            "category": "session",
+            "description": "Return the provider-shaped tool array (openai|anthropic|vercel|generic) for an LLM-tools preset, plus the active cache strategy.",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [
+                {
+                    "name": "provider",
+                    "kind": "flag",
+                    "type": "string",
+                    "required": true,
+                    "schema": {
+                        "oneOf": [
+                            {
+                                "const": "openai"
+                            },
+                            {
+                                "const": "anthropic"
+                            },
+                            {
+                                "const": "vercel"
+                            },
+                            {
+                                "const": "generic"
+                            }
+                        ]
+                    },
+                    "description": "Tool provider format: openai | anthropic | vercel | generic."
+                },
+                {
+                    "name": "preset",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                },
+                {
+                    "name": "cache",
+                    "kind": "flag",
+                    "type": "boolean",
+                    "description": "Apply provider-specific prompt-cache markers."
+                },
+                {
+                    "name": "excludeActions",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Comma-separated action names to remove from the advertised action surface (core preset). Unknown names fail."
+                }
+            ],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "provider": {
+                        "type": "string",
+                        "oneOf": [
+                            {
+                                "const": "openai"
+                            },
+                            {
+                                "const": "anthropic"
+                            },
+                            {
+                                "const": "vercel"
+                            },
+                            {
+                                "const": "generic"
+                            }
+                        ],
+                        "description": "Tool provider format: openai | anthropic | vercel | generic."
+                    },
+                    "preset": {
+                        "type": "string",
+                        "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                    },
+                    "cache": {
+                        "type": "boolean",
+                        "description": "Apply provider-specific prompt-cache markers."
+                    },
+                    "excludeActions": {
+                        "type": "string",
+                        "description": "Comma-separated action names to remove from the advertised action surface (core preset). Unknown names fail."
+                    }
+                },
+                "required": [
+                    "provider"
+                ],
+                "additionalProperties": false
+            },
+            "mutates": false,
+            "idempotency": "idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object",
+                "properties": {
+                    "tools": {
+                        "type": "array"
+                    },
+                    "cacheStrategy": {
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "tools",
+                    "cacheStrategy"
+                ]
+            },
+            "skipAsATool": true
+        },
+        "doc.preset.getSystemPrompt": {
+            "operationId": "doc.preset.getSystemPrompt",
+            "sdkSurface": "document",
+            "command": "preset get-system-prompt",
+            "commandTokens": [
+                "preset",
+                "get-system-prompt"
+            ],
+            "category": "session",
+            "description": "Return the SDK-style system prompt for an LLM-tools preset.",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [
+                {
+                    "name": "preset",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                },
+                {
+                    "name": "excludeActions",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Comma-separated action names whose per-action documentation lines are dropped from the prompt (core preset)."
+                }
+            ],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "preset": {
+                        "type": "string",
+                        "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                    },
+                    "excludeActions": {
+                        "type": "string",
+                        "description": "Comma-separated action names whose per-action documentation lines are dropped from the prompt (core preset)."
+                    }
+                },
+                "additionalProperties": false
+            },
+            "mutates": false,
+            "idempotency": "idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object",
+                "properties": {
+                    "prompt": {
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "prompt"
+                ]
+            },
+            "skipAsATool": true
+        },
+        "doc.preset.getMcpPrompt": {
+            "operationId": "doc.preset.getMcpPrompt",
+            "sdkSurface": "document",
+            "command": "preset get-mcp-prompt",
+            "commandTokens": [
+                "preset",
+                "get-mcp-prompt"
+            ],
+            "category": "session",
+            "description": "Return the MCP-flavored system prompt for an LLM-tools preset.",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [
+                {
+                    "name": "preset",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                }
+            ],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "preset": {
+                        "type": "string",
+                        "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                    }
+                },
+                "additionalProperties": false
+            },
+            "mutates": false,
+            "idempotency": "idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object",
+                "properties": {
+                    "prompt": {
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "prompt"
+                ]
+            },
+            "skipAsATool": true
+        },
+        "doc.preset.dispatch": {
+            "operationId": "doc.preset.dispatch",
+            "sdkSurface": "document",
+            "command": "preset dispatch",
+            "commandTokens": [
+                "preset",
+                "dispatch"
+            ],
+            "category": "core",
+            "description": "Dispatch an LLM tool call through the named preset's dispatcher against the active session's live document. Used by cross-language SDKs (e.g. Python) to proxy preset behavior over the CLI.",
+            "requiresDocumentContext": false,
+            "docRequirement": "none",
+            "responseEnvelopeKey": null,
+            "params": [
+                {
+                    "name": "sessionId",
+                    "kind": "flag",
+                    "type": "string",
+                    "flag": "session",
+                    "description": "Session ID for multi-session workflows. Optional when only one session is open."
+                },
+                {
+                    "name": "expectedRevision",
+                    "kind": "flag",
+                    "type": "number",
+                    "flag": "expected-revision",
+                    "agentVisible": false
+                },
+                {
+                    "name": "toolName",
+                    "kind": "flag",
+                    "type": "string",
+                    "flag": "tool-name",
+                    "required": true,
+                    "description": "Tool name to dispatch (e.g. superdoc_perform_action, superdoc_inspect, superdoc_execute_code)."
+                },
+                {
+                    "name": "args",
+                    "kind": "jsonFlag",
+                    "type": "json",
+                    "flag": "args-json",
+                    "description": "Tool arguments as a JSON object (matches the preset tool input schema)."
+                },
+                {
+                    "name": "excludeActions",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Comma-separated action names to refuse at dispatch (defense-in-depth for a narrowed tool surface)."
+                },
+                {
+                    "name": "preset",
+                    "kind": "flag",
+                    "type": "string",
+                    "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                }
+            ],
+            "constraints": null,
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "toolName": {
+                        "type": "string",
+                        "description": "Tool name to dispatch (e.g. superdoc_perform_action, superdoc_inspect, superdoc_execute_code)."
+                    },
+                    "args": {
+                        "type": "object",
+                        "description": "Tool arguments as a JSON object (matches the preset tool input schema)."
+                    },
+                    "excludeActions": {
+                        "type": "string",
+                        "description": "Comma-separated action names to refuse at dispatch (defense-in-depth for a narrowed tool surface)."
+                    },
+                    "preset": {
+                        "type": "string",
+                        "description": "Preset id. Defaults to the SDK default preset (legacy)."
+                    }
+                },
+                "required": [
+                    "toolName"
+                ],
+                "additionalProperties": false
+            },
+            "mutates": true,
+            "idempotency": "non-idempotent",
+            "supportsTrackedMode": false,
+            "supportsDryRun": false,
+            "outputSchema": {
+                "type": "object",
+                "properties": {
+                    "result": {},
+                    "context": {
+                        "type": "object",
+                        "properties": {
+                            "dirty": {
+                                "type": "boolean"
+                            },
+                            "revision": {
+                                "type": "number"
+                            },
+                            "mutated": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            },
+            "skipAsATool": true
         }
     }
 };