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

package/dist/actions/define.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Customer-extensible **custom actions** for the SuperDoc LLM-tools SDK. The
+ * canonical ActionSpec has exactly ONE execution tier:
+ *
+ *   - `steps` — declarative composition of built-in core actions with
+ *               {{arg}} templating; dispatches through the base preset and
+ *               inherits its target resolution, receipts, and verification.
+ *   - `run`   — a native function executed in the CALLER'S process against
+ *               the typed session-bound doc handle, with synthesized
+ *               truth-telling receipts (pre/post revision, partialMutation).
+ *
+ * NOTE: a third, IN-HOST tier — a JS function-expression run inside the
+ * document host via `superdoc_execute_code` — is intentionally not part of the
+ * kit yet. It lands together with the code-act execution path (and its safety
+ * envelope); until then the kit exposes only `steps` and `run`.
+ *
+ * `extendPreset` merges custom actions into the
+ * superdoc_perform_action enum, tool description, system prompt, and dispatch
+ * COHERENTLY — including excludeActions, which may name built-in actions
+ * (forwarded to the base) or custom ones (handled by the wrapper). No CLI
+ * host changes are required by either tier.
+ *
+ * Cross-runtime contract: templating semantics, input-schema defaults, and
+ * receipt shapes are identical to the Python mirror
+ * (`langs/python/superdoc/presets/custom.py`) for any JSON-serializable tool
+ * input. (NaN/Infinity/lone-surrogates are out of scope: they cannot appear in
+ * a JSON tool call.)
+ *
+ * @module
+ */
+import type { BoundDocApi } from '../generated/client.js';
+import { type PresetDescriptor } from '../presets.js';
+/** Minimal JSON Schema object describing a action's flat args. */
+export type JSONSchemaObject = {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+};
+/**
+ * One step of a declarative (`steps`-tier) custom action: an existing built-in
+ * core action plus its args. String values may reference the custom action's
+ * own args with `{{name}}` templates — a whole-string `"{{x}}"` substitutes the
+ * raw value (preserving arrays/objects/numbers), a partial `"...{{x}}..."`
+ * interpolates as text.
+ */
+export type ActionStep = {
+    action: string;
+    args?: Record<string, unknown>;
+};
+/**
+ * The shared, language-neutral custom-action contract — the canonical type.
+ *
+ * - `name` — namespaced "<ns>.<verb>" (e.g. "footnotes.add"). MUST NOT collide
+ *   with a built-in core action name.
+ * - `description` — shown to the model.
+ * - `inputSchema` — JSON Schema for the FLAT args (NOT the `action`
+ *   discriminator key). `properties.*.default` values are applied before
+ *   execution on every tier.
+ *
+ * Exactly ONE execution tier is set:
+ *
+ * - `steps` — DECLARATIVE (recommended): a sequence of built-in core actions
+ *   with `{{arg}}` templating. Dispatches through the base preset, so it
+ *   inherits target resolution, placement handling, receipts, and
+ *   verification. Pure data — serializable, cross-language by construction.
+ * - `run` — NATIVE escape hatch: an async function executed in the caller's
+ *   process against the typed session-bound doc handle. Receipts are
+ *   synthesized (pre/post revision, partialMutation, recovery).
+ */
+export interface ActionSpec {
+    name: string;
+    description: string;
+    inputSchema: JSONSchemaObject;
+    steps?: readonly ActionStep[];
+    run?: (doc: BoundDocApi, args: Record<string, unknown>) => unknown;
+}
+/** Which execution tier a spec uses. */
+export declare function executionKindOf(spec: ActionSpec): 'steps' | 'run';
+type DefineActionInputBase = {
+    name: string;
+    description: string;
+    /**
+     * JSON Schema object describing the action's flat args. Pass a plain JSON
+     * Schema (`{ type: 'object', properties: {...} }`). Zod (and other schema
+     * libraries) are NOT accepted directly — convert first, e.g. with
+     * `zod-to-json-schema` — otherwise `defineAction` throws a clear error rather
+     * than silently dropping your types.
+     */
+    input?: JSONSchemaObject | Record<string, unknown>;
+};
+type DefineActionWithSteps = DefineActionInputBase & {
+    /** Declarative tier: built-in core actions with {{arg}} templating. */
+    steps: readonly ActionStep[];
+    run?: never;
+};
+type DefineActionWithRun = DefineActionInputBase & {
+    /**
+     * Native tier: runs IN THE CALLER'S PROCESS against the typed session-bound
+     * doc handle (async `doc.*` client API).
+     */
+    run: (doc: BoundDocApi, args: Record<string, unknown>) => unknown;
+    steps?: never;
+};
+export type DefineActionInput = DefineActionWithSteps | DefineActionWithRun;
+/**
+ * Author a {@link ActionSpec}. Pass exactly one execution tier: `steps`
+ * (declarative — recommended) or `run` (native function in your process).
+ */
+export declare function defineAction(input: DefineActionInput): ActionSpec;
+export interface ExtendPresetOptions {
+    /** New preset id. */
+    id: string;
+    /** Optional description override. */
+    description?: string;
+    /** Custom actions to add. */
+    actions?: readonly ActionSpec[];
+    /**
+     * Of the base preset's BUILT-IN actions, keep only these. Custom actions are
+     * always included; `[]` yields a custom-only surface. Applied coherently to
+     * the superdoc_perform_action enum, description, and argument properties,
+     * the system prompt, the catalog, and dispatch (a built-in outside the
+     * allowlist is refused even on a guessed call). Unknown names throw.
+     *
+     * Prefer this over `excludeActions` for a curated surface: an allowlist does
+     * not silently grow when a later SDK release adds built-in actions.
+     */
+    includeActions?: readonly string[];
+    /** Wholesale system-prompt addendum; defaults to an auto-generated bullet list. */
+    systemPromptExtra?: string;
+    /** When true, expose each action as its own tool instead of merging into superdoc_perform_action. */
+    standalone?: boolean;
+}
+/**
+ * Wrap `getPreset(baseId)` with custom actions. Returns a new
+ * {@link PresetDescriptor} that advertises and dispatches the custom actions
+ * while delegating everything else to the base preset. With
+ * `includeActions`, the base's built-in surface is narrowed to that allowlist.
+ */
+export declare function extendPreset(baseId: string, options: ExtendPresetOptions): PresetDescriptor;
+export {};