@superdoc/sdk 2.11.0-next.4 → 2.11.0-next.5

package/dist/agent/catalog.cjs

@@ -586,6 +586,7 @@ exports.LIST_ITEM_SCHEMA = LIST_ITEM_SCHEMA;
 exports.PUBLIC_AGENT_TOOL_NAMES = PUBLIC_AGENT_TOOL_NAMES;
 exports.RUN_MARKS_SCHEMA = RUN_MARKS_SCHEMA;
 exports.SELECTOR_SCHEMA = SELECTOR_SCHEMA;
+exports.buildPerformActionDefinition = buildPerformActionDefinition;
 exports.isAgentToolName = isAgentToolName;
 exports.listAgentTools = listAgentTools;
 exports.validateExclusions = validateExclusions;

package/dist/agent/catalog.d.ts

@@ -317,6 +317,14 @@ export declare const CELL_SCHEMA: {
  * tool advertises those after `action`.
  */
 export declare const ACTION_ARG_SCHEMA: Record<string, unknown>;
+/**
+ * Build the `superdoc_perform_action` tool definition for a given action set.
+ * The default (all actions) is what `AGENT_TOOL_DEFINITIONS` carries; callers
+ * excluding actions get a coherently narrowed definition: enum, grouped
+ * description, AND the advertised argument properties all shrink together
+ * (an arg no remaining action declares is not advertised).
+ */
+export declare function buildPerformActionDefinition(includedActions: readonly string[]): AgentToolDefinition;
 export declare const AGENT_TOOL_DEFINITIONS: readonly AgentToolDefinition[];
 /** Customer-facing narrowing of the advertised tool surface. */
 export interface ListAgentToolsOptions {

package/dist/agent/catalog.js

@@ -306,7 +306,7 @@ function buildActionDescription(included) {
  * description, AND the advertised argument properties all shrink together
  * (an arg no remaining action declares is not advertised).
  */
-function buildPerformActionDefinition(includedActions) {
+export function buildPerformActionDefinition(includedActions) {
     const included = new Set(includedActions);
     return {
         name: 'superdoc_perform_action',

package/dist/index.cjs

@@ -10,6 +10,7 @@ var skills = require('./skills.cjs');
 var tools = require('./tools.cjs');
 var intentDispatch_generated = require('./generated/intent-dispatch.generated.cjs');
 var v2PresetCompat = require('./agent/v2-preset-compat.cjs');
+var define = require('./actions/define.cjs');
 var presets = require('./presets.cjs');
 
 // ---------------------------------------------------------------------------
@@ -215,6 +216,7 @@ exports.getToolCatalog = tools.getToolCatalog;
 exports.listTools = tools.listTools;
 exports.dispatchIntentTool = intentDispatch_generated.dispatchIntentTool;
 exports.wrapV2PresetCompat = v2PresetCompat.wrapV2PresetCompat;
+exports.defineAction = define.defineAction;
 exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
 exports.getPreset = presets.getPreset;
 exports.listPresets = presets.listPresets;

package/dist/index.d.ts

@@ -98,6 +98,8 @@ export type { AgentReceipt, AgentApplyArgs, AgentVerifyArgs } from './agent/runt
 export type { GetSystemPromptOptions, GetToolsOptions, GetToolsResult, PresetDescriptor } from './presets.js';
 export { createAgentToolkit } from './tools.js';
 export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';
+export { defineAction } from './actions/define.js';
+export type { ActionSpec, ActionStep, DefineActionInput, JSONSchemaObject } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';
 export type { CollaborationAuth, DocOpenOptions, InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';
 export type { DocOpenResult } from './generated/client.js';

package/dist/index.js

@@ -197,4 +197,7 @@ export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSy
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { wrapV2PresetCompat } from './agent/v2-preset-compat.js';
 export { createAgentToolkit } from './tools.js';
+// Custom-action authoring kit: `defineAction` builds an ActionSpec (steps or
+// run tier); hand the specs to `createAgentToolkit({ actions })`.
+export { defineAction } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';

package/dist/presets.cjs

@@ -40,8 +40,8 @@ const BUILTIN_PRESETS = {
 };
 /**
  * Mutable registry, seeded with the built-ins. Customers add their own presets
- * via {@link registerPreset} (e.g. one produced by `extendPreset` /
- * `composePreset`) so `getPreset`/`chooseTools` can resolve them by id.
+ * via {@link registerPreset} so `getPreset`/`chooseTools` can resolve them
+ * by id.
  */
 const PRESETS = { ...BUILTIN_PRESETS };
 /** List the IDs of all registered presets. */

package/dist/presets.js

@@ -37,8 +37,8 @@ const BUILTIN_PRESETS = {
 };
 /**
  * Mutable registry, seeded with the built-ins. Customers add their own presets
- * via {@link registerPreset} (e.g. one produced by `extendPreset` /
- * `composePreset`) so `getPreset`/`chooseTools` can resolve them by id.
+ * via {@link registerPreset} so `getPreset`/`chooseTools` can resolve them
+ * by id.
  */
 const PRESETS = { ...BUILTIN_PRESETS };
 /** List the IDs of all registered presets. */

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.11.0-next.4';
+const SDK_VERSION = '2.11.0-next.5';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.11.0-next.4";
+export declare const SDK_VERSION = "2.11.0-next.5";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.11.0-next.4';
+export const SDK_VERSION = '2.11.0-next.5';

package/dist/tools.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
+var errors = require('./runtime/errors.cjs');
 var presets = require('./presets.cjs');
+var define = require('./actions/define.cjs');
 
 /**
  * Public LLM-tools API. Thin layer over the preset registry — every call here
@@ -95,6 +97,9 @@ function resolvePromptPresetArg(preset) {
     }
     return presets.DEFAULT_PRESET;
 }
+/** Label for the ephemeral preset built by the one-call `customActions` path. */
+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`
@@ -106,8 +111,51 @@ function resolvePromptPresetArg(preset) {
  * matching the standalone functions.
  */
 async function createAgentToolkit(input) {
-    const presetId = input.preset ?? presets.DEFAULT_PRESET;
     const excludeActions = input.excludeActions ? [...input.excludeActions] : undefined;
+    // 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
+    // `base` (default 'core') and drive it directly — no global registerPreset,
+    // and nothing for the caller to remember at dispatch time.
+    //
+    // An explicit `base` selects this path even with an empty actions list —
+    // 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) {
+        // 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.
+        if (!TOOL_PROVIDERS.has(input.provider)) {
+            throw new errors.SuperDocCliError('provider is required.', {
+                code: 'INVALID_ARGUMENT',
+                details: { provider: input.provider },
+            });
+        }
+        // `preset` doubles as the base to extend here (so `{ preset: 'core', actions }`
+        // reads naturally); `base` wins if both are given. Default base is 'core'.
+        const baseId = input.base ?? input.preset ?? 'core';
+        const descriptor = define.extendPreset(baseId, {
+            id: CUSTOM_TOOLKIT_PRESET_ID,
+            actions: input.customActions ?? [],
+            ...(input.includeActions != null ? { includeActions: input.includeActions } : {}),
+        });
+        const { tools, cacheStrategy } = await descriptor.getTools(input.provider, {
+            cache: input.cache === true,
+            excludeActions,
+        });
+        const systemPrompt = await descriptor.getSystemPrompt(excludeActions ? { excludeActions } : undefined);
+        const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => descriptor.dispatch(documentHandle, toolName, args, {
+            ...invokeOptions,
+            ...(excludeActions ? { excludeActions } : {}),
+        });
+        return {
+            tools,
+            meta: { provider: input.provider, preset: descriptor.id, toolCount: tools.length, cacheStrategy },
+            systemPrompt,
+            dispatch,
+        };
+    }
+    const presetId = input.preset ?? presets.DEFAULT_PRESET;
     const { tools, meta } = await chooseTools({ ...input, preset: presetId, excludeActions });
     const systemPrompt = await getSystemPrompt(presetId, excludeActions ? { excludeActions } : undefined);
     const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => dispatchSuperDocTool(documentHandle, toolName, args, {

package/dist/tools.d.ts

@@ -10,6 +10,7 @@
 import type { BoundDocApi } from './generated/client.js';
 import type { InvokeOptions } from './runtime/process.js';
 import { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, type CacheStrategy, type GetSystemPromptOptions, type ToolCatalog, type ToolCatalogEntry, type ToolCatalogOperation, type ToolProvider } from './presets.js';
+import { type ActionSpec } from './actions/define.js';
 export { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset };
 export type { CacheStrategy, GetSystemPromptOptions, ToolCatalog, ToolCatalogEntry, ToolCatalogOperation, ToolProvider, };
 export type ToolChooserInput = {
@@ -98,7 +99,23 @@ export declare function dispatchSuperDocTool(documentHandle: BoundDocApi, toolNa
  * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs). For MCP
  * server instructions, use {@link getMcpPrompt} instead.
  */
-export type CreateAgentToolkitInput = ToolChooserInput;
+export type CreateAgentToolkitInput = ToolChooserInput & {
+    /**
+     * Custom actions to expose alongside the base preset's built-ins. When set,
+     * the toolkit builds the extended preset FOR YOU — no `registerPreset`, no
+     * preset id to invent or thread through later `dispatch` calls. This is the
+     * path: define your actions, hand them here, use the returned toolkit.
+     */
+    customActions?: readonly ActionSpec[];
+    /** Base preset to extend on the custom-actions path (default `'core'`). */
+    base?: string;
+    /**
+     * Of the base preset's built-in actions, keep only these (`customActions`
+     * are always included; `[]` yields a custom-only surface). See
+     * `ExtendPresetOptions.includeActions`.
+     */
+    includeActions?: readonly string[];
+};
 export type AgentToolkit = {
     /** Provider-shaped tool definitions (see {@link chooseTools}). */
     tools: unknown[];

package/dist/tools.js

@@ -7,7 +7,9 @@
  * "core" tools, prompt-caching variant, lazy-load experiment), register a new
  * descriptor in `presets.ts` — no changes here required.
  */
+import { SuperDocCliError } from './runtime/errors.js';
 import { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, } from './presets.js';
+import { extendPreset } from './actions/define.js';
 export { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset };
 /**
  * Select tools for a specific provider from a preset.
@@ -93,6 +95,9 @@ function resolvePromptPresetArg(preset) {
     }
     return DEFAULT_PRESET;
 }
+/** Label for the ephemeral preset built by the one-call `customActions` path. */
+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`
@@ -104,8 +109,51 @@ function resolvePromptPresetArg(preset) {
  * matching the standalone functions.
  */
 export async function createAgentToolkit(input) {
-    const presetId = input.preset ?? DEFAULT_PRESET;
     const excludeActions = input.excludeActions ? [...input.excludeActions] : undefined;
+    // 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
+    // `base` (default 'core') and drive it directly — no global registerPreset,
+    // and nothing for the caller to remember at dispatch time.
+    //
+    // An explicit `base` selects this path even with an empty actions list —
+    // 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) {
+        // 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.
+        if (!TOOL_PROVIDERS.has(input.provider)) {
+            throw new SuperDocCliError('provider is required.', {
+                code: 'INVALID_ARGUMENT',
+                details: { provider: input.provider },
+            });
+        }
+        // `preset` doubles as the base to extend here (so `{ preset: 'core', actions }`
+        // reads naturally); `base` wins if both are given. Default base is 'core'.
+        const baseId = input.base ?? input.preset ?? 'core';
+        const descriptor = extendPreset(baseId, {
+            id: CUSTOM_TOOLKIT_PRESET_ID,
+            actions: input.customActions ?? [],
+            ...(input.includeActions != null ? { includeActions: input.includeActions } : {}),
+        });
+        const { tools, cacheStrategy } = await descriptor.getTools(input.provider, {
+            cache: input.cache === true,
+            excludeActions,
+        });
+        const systemPrompt = await descriptor.getSystemPrompt(excludeActions ? { excludeActions } : undefined);
+        const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => descriptor.dispatch(documentHandle, toolName, args, {
+            ...invokeOptions,
+            ...(excludeActions ? { excludeActions } : {}),
+        });
+        return {
+            tools,
+            meta: { provider: input.provider, preset: descriptor.id, toolCount: tools.length, cacheStrategy },
+            systemPrompt,
+            dispatch,
+        };
+    }
+    const presetId = input.preset ?? DEFAULT_PRESET;
     const { tools, meta } = await chooseTools({ ...input, preset: presetId, excludeActions });
     const systemPrompt = await getSystemPrompt(presetId, excludeActions ? { excludeActions } : undefined);
     const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => dispatchSuperDocTool(documentHandle, toolName, args, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.11.0-next.4",
+  "version": "2.11.0-next.5",
   "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.11.0-next.4",
-    "@superdoc/sdk-darwin-x64": "2.11.0-next.4",
-    "@superdoc/sdk-linux-x64": "2.11.0-next.4",
-    "@superdoc/sdk-linux-arm64": "2.11.0-next.4",
-    "@superdoc/sdk-windows-x64": "2.11.0-next.4"
+    "@superdoc/sdk-darwin-arm64": "2.11.0-next.5",
+    "@superdoc/sdk-darwin-x64": "2.11.0-next.5",
+    "@superdoc/sdk-linux-x64": "2.11.0-next.5",
+    "@superdoc/sdk-linux-arm64": "2.11.0-next.5",
+    "@superdoc/sdk-windows-x64": "2.11.0-next.5"
   },
   "publishConfig": {
     "access": "public"
@@ -51,9 +51,9 @@
     "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",
-    "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.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",
+    "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",
+    "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.test.ts src/__tests__/custom-actions.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"
   }
 }