@superdoc-dev/sdk 1.20.2 → 1.21.0-next.2

package/dist/agent/catalog.cjs

@@ -478,6 +478,7 @@ exports.AGENT_TOOL_DEFINITIONS = AGENT_TOOL_DEFINITIONS;
 exports.AGENT_TOOL_NAMES = AGENT_TOOL_NAMES;
 exports.PUBLIC_AGENT_TOOL_NAMES = PUBLIC_AGENT_TOOL_NAMES;
 exports.SELECTOR_SCHEMA = SELECTOR_SCHEMA;
+exports.buildPerformActionDefinition = buildPerformActionDefinition;
 exports.isAgentToolName = isAgentToolName;
 exports.listAgentTools = listAgentTools;
 exports.validateExclusions = validateExclusions;

package/dist/agent/catalog.d.ts

@@ -74,6 +74,14 @@ export declare const SELECTOR_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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/agent/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,eAAO,MAAM,gBAAgB,qIAOnB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,0DAM1B,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,aAAa,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,gBAAgB,CAAC;KAC9B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,gBAAgB,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE1G,eAAO,MAAM,eAAe;;;;;;;;;CAQlB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA6FrD,CAAC;AAyHF,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EA0JvD,CAAC;AA+CX,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG;IACnE,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B,CAYA;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB,EAAE,CAY3G;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,aAAa,CAE3E"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/agent/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,eAAO,MAAM,gBAAgB,qIAOnB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,0DAM1B,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,aAAa,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,gBAAgB,CAAC;KAC9B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,gBAAgB,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE1G,eAAO,MAAM,eAAe;;;;;;;;;CAQlB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA6FrD,CAAC;AA8FF;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,mBAAmB,CAkBpG;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EA0JvD,CAAC;AA+CX,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG;IACnE,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B,CAYA;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB,EAAE,CAY3G;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,aAAa,CAE3E"}

package/dist/agent/catalog.js

@@ -219,7 +219,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

@@ -7,6 +7,7 @@ var errors = require('./runtime/errors.cjs');
 var skills = require('./skills.cjs');
 var tools = require('./tools.cjs');
 var intentDispatch_generated = require('./generated/intent-dispatch.generated.cjs');
+var define = require('./actions/define.cjs');
 var presets = require('./presets.cjs');
 
 // ---------------------------------------------------------------------------
@@ -167,6 +168,10 @@ exports.getSystemPromptForProvider = tools.getSystemPromptForProvider;
 exports.getToolCatalog = tools.getToolCatalog;
 exports.listTools = tools.listTools;
 exports.dispatchIntentTool = intentDispatch_generated.dispatchIntentTool;
+exports.composePreset = define.composePreset;
+exports.defineAction = define.defineAction;
+exports.executionKindOf = define.executionKindOf;
+exports.extendPreset = define.extendPreset;
 exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
 exports.getPreset = presets.getPreset;
 exports.listPresets = presets.listPresets;

package/dist/index.d.ts

@@ -86,6 +86,8 @@ export type { AgentReceipt } from './agent/runtime.js';
 export type { GetSystemPromptOptions, GetToolsOptions, GetToolsResult, PresetDescriptor } from './presets.js';
 export { createAgentToolkit } from './tools.js';
 export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';
+export { defineAction, extendPreset, composePreset, executionKindOf } from './actions/define.js';
+export type { ActionSpec, ActionStep, DefineActionInput, ExtendPresetOptions, ComposePresetOptions, JSONSchemaObject, } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';
 export type { InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';
 export type { DocOpenResult } from './generated/client.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -150,4 +150,7 @@ export { getSkill, installSkill, listSkills } from './skills.js';
 export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, } from './tools.js';
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { createAgentToolkit } from './tools.js';
+// Custom-action authoring kit: define actions in two execution tiers
+// (steps / run) and extend or compose presets with them.
+export { defineAction, extendPreset, composePreset, executionKindOf } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';

package/dist/tools.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 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 +96,8 @@ function resolvePromptPresetArg(preset) {
     }
     return presets.DEFAULT_PRESET;
 }
+/** Label for the ephemeral preset built by the one-call `actions` path. */
+const CUSTOM_TOOLKIT_PRESET_ID = 'custom_superdoc_preset';
 /**
  * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
  * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
@@ -106,8 +109,41 @@ 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, 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.
+    if ((input.actions && input.actions.length > 0) || input.includeCoreActions != null) {
+        // `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 actions = input.actions ?? [];
+        const descriptor = input.includeCoreActions != null
+            ? define.composePreset({
+                id: CUSTOM_TOOLKIT_PRESET_ID,
+                baseId,
+                includeCoreActions: input.includeCoreActions,
+                actions,
+            })
+            : define.extendPreset(baseId, { id: CUSTOM_TOOLKIT_PRESET_ID, actions });
+        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
+     * simple path: define your actions, hand them here, use the returned toolkit.
+     * Advanced callers can still `extendPreset`/`composePreset` + `preset`.
+     */
+    actions?: readonly ActionSpec[];
+    /** Base preset to extend when `actions` is set (default `'core'`). Ignored otherwise. */
+    base?: string;
+    /**
+     * With `actions`, keep only these built-in action names (∪ your custom
+     * actions) — builds via `composePreset` instead of `extendPreset`.
+     */
+    includeCoreActions?: readonly string[];
+};
 export type AgentToolkit = {
     /** Provider-shaped tool definitions (see {@link chooseTools}). */
     tools: unknown[];

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -8,6 +8,7 @@
  * descriptor in `presets.ts` — no changes here required.
  */
 import { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, } from './presets.js';
+import { extendPreset, composePreset } from './actions/define.js';
 export { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset };
 /**
  * Select tools for a specific provider from a preset.
@@ -93,6 +94,8 @@ function resolvePromptPresetArg(preset) {
     }
     return DEFAULT_PRESET;
 }
+/** Label for the ephemeral preset built by the one-call `actions` path. */
+const CUSTOM_TOOLKIT_PRESET_ID = 'custom_superdoc_preset';
 /**
  * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
  * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
@@ -104,8 +107,41 @@ 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, 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.
+    if ((input.actions && input.actions.length > 0) || input.includeCoreActions != null) {
+        // `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 actions = input.actions ?? [];
+        const descriptor = input.includeCoreActions != null
+            ? composePreset({
+                id: CUSTOM_TOOLKIT_PRESET_ID,
+                baseId,
+                includeCoreActions: input.includeCoreActions,
+                actions,
+            })
+            : extendPreset(baseId, { id: CUSTOM_TOOLKIT_PRESET_ID, actions });
+        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-dev/sdk",
-  "version": "1.20.2",
+  "version": "1.21.0-next.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,11 +26,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc-dev/sdk-darwin-arm64": "1.20.2",
-    "@superdoc-dev/sdk-linux-arm64": "1.20.2",
-    "@superdoc-dev/sdk-windows-x64": "1.20.2",
-    "@superdoc-dev/sdk-linux-x64": "1.20.2",
-    "@superdoc-dev/sdk-darwin-x64": "1.20.2"
+    "@superdoc-dev/sdk-darwin-arm64": "1.21.0-next.2",
+    "@superdoc-dev/sdk-darwin-x64": "1.21.0-next.2",
+    "@superdoc-dev/sdk-linux-x64": "1.21.0-next.2",
+    "@superdoc-dev/sdk-linux-arm64": "1.21.0-next.2",
+    "@superdoc-dev/sdk-windows-x64": "1.21.0-next.2"
   },
   "publishConfig": {
     "access": "public"