@superdoc/sdk 2.13.0-next.9 → 2.13.1-next.1

package/dist/tools.d.ts

@@ -43,6 +43,22 @@ export type ToolChooserInput = {
      * ignore it. Unknown names throw.
      */
     excludeActions?: readonly string[];
+    /**
+     * Fail-closed tracked-changes-only agent (core preset). `'tracked'` hides
+     * every direct-only action (see `getActionDispositions()`) from the tools and
+     * prompt, refuses it at dispatch, and upgrades every tracked-capable action
+     * to `changeMode: "tracked"` no matter what the model passed. Only
+     * `'tracked'` is accepted.
+     */
+    enforceChangeMode?: 'tracked';
+    /**
+     * Direct-only actions this host still permits under `enforceChangeMode`
+     * (e.g. `['add_comments', 'insert_page_break']`). They stay advertised and
+     * run directly. `['*']` allows every direct-only action while tracked-capable
+     * actions stay forced tracked. Requires `enforceChangeMode`; unknown names
+     * throw; tracked-capable names are ignored.
+     */
+    allowDirectActions?: readonly string[];
 };
 /**
  * Select tools for a specific provider from a preset.
@@ -91,6 +107,10 @@ export declare function dispatchSuperDocTool(documentHandle: BoundDocApi, toolNa
     preset?: string;
     /** Refuse dispatch of these actions (defense-in-depth for exclusion configs). */
     excludeActions?: readonly string[];
+    /** Refuse direct-only actions and force tracked mode (see {@link ToolChooserInput.enforceChangeMode}). */
+    enforceChangeMode?: 'tracked';
+    /** Direct-only actions still permitted under `enforceChangeMode`. */
+    allowDirectActions?: readonly string[];
 }): Promise<unknown>;
 /**
  * Read the SDK system prompt for the given preset (default: {@link DEFAULT_PRESET}).
@@ -136,9 +156,10 @@ export type AgentToolkit = {
 };
 /**
  * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
- * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
- * apply to all three, so an action can never linger in the prompt after
- * being excluded from the tool array (or vice versa).
+ * that are coherent BY CONSTRUCTION — the same preset, `excludeActions`,
+ * `enforceChangeMode`, and `allowDirectActions` apply to all three, so an
+ * action can never linger in the prompt after being excluded from the tool
+ * array (or vice versa).
  *
  * The legacy preset ignores exclusion options everywhere (it has no action
  * surface); passing `excludeActions` with `preset: 'legacy'` is a no-op,
@@ -207,4 +228,8 @@ export declare function getSystemPromptForProvider(input: {
     cache?: boolean;
     /** Same exclusions as chooseTools — keeps the provider-shaped prompt and the tool surface narrowed together. */
     excludeActions?: readonly string[];
+    /** Same policy as chooseTools (see {@link ToolChooserInput.enforceChangeMode}). */
+    enforceChangeMode?: 'tracked';
+    /** Same allowlist as chooseTools. */
+    allowDirectActions?: readonly string[];
 }): Promise<SystemPromptForProviderResult>;

package/dist/tools.js

@@ -32,6 +32,8 @@ export async function chooseTools(input) {
     const { tools, cacheStrategy } = await preset.getTools(input.provider, {
         cache: input.cache === true,
         excludeActions: input.excludeActions,
+        enforceChangeMode: input.enforceChangeMode,
+        allowDirectActions: input.allowDirectActions,
     });
     return {
         tools,
@@ -100,16 +102,25 @@ const CUSTOM_TOOLKIT_PRESET_ID = 'custom_superdoc_preset';
 const TOOL_PROVIDERS = new Set(['openai', 'anthropic', 'vercel', 'generic']);
 /**
  * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
- * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
- * apply to all three, so an action can never linger in the prompt after
- * being excluded from the tool array (or vice versa).
+ * that are coherent BY CONSTRUCTION — the same preset, `excludeActions`,
+ * `enforceChangeMode`, and `allowDirectActions` apply to all three, so an
+ * action can never linger in the prompt after being excluded from the tool
+ * array (or vice versa).
  *
  * The legacy preset ignores exclusion options everywhere (it has no action
  * surface); passing `excludeActions` with `preset: 'legacy'` is a no-op,
  * matching the standalone functions.
  */
 export async function createAgentToolkit(input) {
-    const excludeActions = input.excludeActions ? [...input.excludeActions] : undefined;
+    // Copy the lists so later caller mutation cannot desync dispatch from the
+    // tools and prompt that were generated here.
+    const policy = {
+        ...(input.excludeActions ? { excludeActions: [...input.excludeActions] } : {}),
+        ...(input.enforceChangeMode !== undefined ? { enforceChangeMode: input.enforceChangeMode } : {}),
+        ...(input.allowDirectActions ? { allowDirectActions: [...input.allowDirectActions] } : {}),
+    };
+    const hasPolicy = Object.keys(policy).length > 0;
+    const excludeActions = policy.excludeActions;
     // One-call custom-actions path: define your actions, hand them here as
     // `customActions`, use the
     // returned toolkit. We build an ephemeral extended/composed preset over
@@ -120,6 +131,16 @@ export async function createAgentToolkit(input) {
     // otherwise `{ base: 'core', customActions: [] }` would silently fall through to
     // the default (legacy) preset, a different tool family than the one named.
     if ((input.customActions && input.customActions.length > 0) || input.includeActions != null || input.base != null) {
+        // A custom action runs its own step list through runCustomAction, which
+        // never passes the core dispatch guard, so the tracked-only policy cannot
+        // cover it. Enforcing built-ins while custom actions edit directly would be
+        // a policy that silently does not hold — refuse the combination instead.
+        if (input.enforceChangeMode !== undefined) {
+            throw new SuperDocCliError('enforceChangeMode is not supported together with custom actions; a custom action bypasses the tracked-changes guard.', {
+                code: 'INVALID_ARGUMENT',
+                details: { enforceChangeMode: input.enforceChangeMode, reason: 'custom-actions-unsupported' },
+            });
+        }
         // This path builds tools directly (no chooseTools), so it must validate
         // the provider itself; an unknown value would otherwise yield a silently
         // mixed-dialect tool list. Mirrors the Python `create_agent_toolkit` guard.
@@ -154,12 +175,12 @@ export async function createAgentToolkit(input) {
         };
     }
     const presetId = input.preset ?? DEFAULT_PRESET;
-    const { tools, meta } = await chooseTools({ ...input, preset: presetId, excludeActions });
-    const systemPrompt = await getSystemPrompt(presetId, excludeActions ? { excludeActions } : undefined);
+    const { tools, meta } = await chooseTools({ ...input, preset: presetId, ...policy });
+    const systemPrompt = await getSystemPrompt(presetId, hasPolicy ? policy : undefined);
     const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => dispatchSuperDocTool(documentHandle, toolName, args, {
         ...invokeOptions,
         preset: presetId,
-        ...(excludeActions ? { excludeActions } : {}),
+        ...policy,
     });
     return { tools, meta, systemPrompt, dispatch };
 }
@@ -200,7 +221,12 @@ export async function getMcpPrompt(preset) {
  * ```
  */
 export async function getSystemPromptForProvider(input) {
-    const text = await getSystemPrompt(input.preset, input.excludeActions ? { excludeActions: input.excludeActions } : undefined);
+    const promptOptions = {
+        ...(input.excludeActions ? { excludeActions: input.excludeActions } : {}),
+        ...(input.enforceChangeMode !== undefined ? { enforceChangeMode: input.enforceChangeMode } : {}),
+        ...(input.allowDirectActions ? { allowDirectActions: input.allowDirectActions } : {}),
+    };
+    const text = await getSystemPrompt(input.preset, Object.keys(promptOptions).length > 0 ? promptOptions : undefined);
     const cacheRequested = input.cache === true;
     if (input.provider === 'anthropic') {
         const block = { type: 'text', text };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.13.0-next.9",
+  "version": "2.13.1-next.1",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -38,11 +38,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.13.0-next.9",
-    "@superdoc/sdk-darwin-x64": "2.13.0-next.9",
-    "@superdoc/sdk-linux-x64": "2.13.0-next.9",
-    "@superdoc/sdk-linux-arm64": "2.13.0-next.9",
-    "@superdoc/sdk-windows-x64": "2.13.0-next.9"
+    "@superdoc/sdk-darwin-arm64": "2.13.1-next.1",
+    "@superdoc/sdk-darwin-x64": "2.13.1-next.1",
+    "@superdoc/sdk-linux-x64": "2.13.1-next.1",
+    "@superdoc/sdk-linux-arm64": "2.13.1-next.1",
+    "@superdoc/sdk-windows-x64": "2.13.1-next.1"
   },
   "publishConfig": {
     "access": "public"
@@ -51,7 +51,7 @@
     "build": "rm -rf dist && node scripts/embed-version.mjs && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && pnpm run typecheck:consumer && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
     "audit:publish": "node ../../../../scripts/audit-publish-artifact.mjs dist --label sdk-node-dist",
     "typecheck": "tsc --noEmit",
-    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts ../../../../tests/consumer-typecheck/src/sd4807-sdk-inspect.mts",
+    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts ../../../../tests/consumer-typecheck/src/sd4807-sdk-inspect.mts ../../../../tests/consumer-typecheck/src/sdk-tracked-only-policy.mts",
     "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.test.ts src/__tests__/custom-actions.test.ts src/__tests__/textbox-snapshot.test.ts",
     "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts src/__tests__/agent-evidence.e2e.test.ts src/__tests__/agent-apply.e2e.test.ts src/__tests__/find-text.e2e.test.ts src/__tests__/custom-actions.e2e.test.ts",
     "smoke:product-action": "node scripts/product-action-smoke.mjs"