@superdoc-dev/sdk 1.14.0 → 1.15.0-next.2

package/dist/presets.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+var errors = require('./runtime/errors.cjs');
+var legacy = require('./presets/legacy.cjs');
+
+/**
+ * Preset registry for SuperDoc LLM tools.
+ *
+ * A preset is a self-contained collection of LLM tools — provider catalogs
+ * (openai / anthropic / vercel / generic), a system prompt, and a dispatcher.
+ * Multiple presets can coexist in the SDK; consumers select one at runtime via
+ * `chooseTools({ preset })`.
+ *
+ *     const { tools, meta } = await chooseTools({ provider: 'vercel', preset: 'legacy' });
+ *
+ * v1 ships a single preset: `'legacy'` — a thin wrapper around today's
+ * codegen-emitted intent tools. When callers omit `preset`, `legacy` is used.
+ * The default may move once a replacement preset reaches parity; bumping it is
+ * a coordinated change in this file alone.
+ *
+ * Presets are NOT versioned. The preset id encodes the variant; a new shape
+ * ships as a new id, not a new version of an existing one.
+ *
+ * @internal
+ */
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * The default preset returned when callers omit `preset`. Set to `'legacy'`
+ * so consumers built before presets existed (today's intent-tool path) keep
+ * working without changes.
+ */
+const DEFAULT_PRESET = 'legacy';
+const PRESETS = {
+    legacy: legacy.legacyPreset,
+};
+/** List the IDs of all registered presets. */
+function listPresets() {
+    return Object.keys(PRESETS);
+}
+/**
+ * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
+ * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to
+ * get the default preset.
+ */
+function getPreset(id = DEFAULT_PRESET) {
+    const preset = PRESETS[id];
+    if (preset == null) {
+        throw new errors.SuperDocCliError(`Unknown LLM-tools preset: "${id}"`, {
+            code: 'PRESET_NOT_FOUND',
+            details: { id, availablePresets: Object.keys(PRESETS) },
+        });
+    }
+    return preset;
+}
+
+exports.DEFAULT_PRESET = DEFAULT_PRESET;
+exports.getPreset = getPreset;
+exports.listPresets = listPresets;

package/dist/presets.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Preset registry for SuperDoc LLM tools.
+ *
+ * A preset is a self-contained collection of LLM tools — provider catalogs
+ * (openai / anthropic / vercel / generic), a system prompt, and a dispatcher.
+ * Multiple presets can coexist in the SDK; consumers select one at runtime via
+ * `chooseTools({ preset })`.
+ *
+ *     const { tools, meta } = await chooseTools({ provider: 'vercel', preset: 'legacy' });
+ *
+ * v1 ships a single preset: `'legacy'` — a thin wrapper around today's
+ * codegen-emitted intent tools. When callers omit `preset`, `legacy` is used.
+ * The default may move once a replacement preset reaches parity; bumping it is
+ * a coordinated change in this file alone.
+ *
+ * Presets are NOT versioned. The preset id encodes the variant; a new shape
+ * ships as a new id, not a new version of an existing one.
+ *
+ * @internal
+ */
+import type { BoundDocApi } from './generated/client.js';
+import type { InvokeOptions } from './runtime/process.js';
+/**
+ * Wire format the tools are emitted in.
+ *
+ * - `openai`     — OpenAI Chat Completions / Responses
+ * - `anthropic`  — Anthropic Messages API
+ * - `vercel`     — Vercel AI SDK (provider-agnostic adapter)
+ * - `generic`    — vendor-neutral JSON Schema shape
+ */
+export type ToolProvider = 'openai' | 'anthropic' | 'vercel' | 'generic';
+/**
+ * Prompt-cache strategy returned by `chooseTools.meta.cacheStrategy`.
+ *
+ * - `explicit`    — preset emitted provider-specific cache markers (Anthropic `cache_control`)
+ * - `automatic`   — provider caches automatically (OpenAI ≥ 1024 prompt tokens)
+ * - `unsupported` — pass-through; caching depends on the underlying model (vercel/generic)
+ * - `disabled`    — caller passed `cache: false` or omitted the flag
+ */
+export type CacheStrategy = 'explicit' | 'automatic' | 'unsupported' | 'disabled';
+/**
+ * One operation row in a {@link ToolCatalogEntry}. Each catalog entry can
+ * dispatch to one or more operations (e.g. multi-action intent tools), so
+ * the catalog records the operation id and the action discriminator that
+ * routes to it.
+ */
+export type ToolCatalogOperation = {
+    operationId: string;
+    intentAction: string;
+    required?: string[];
+    requiredOneOf?: string[][];
+};
+/**
+ * One entry in the {@link ToolCatalog}. Matches the shape of the catalog
+ * emitted by the legacy preset's codegen — kept stable as the public
+ * catalog row shape so TypeScript consumers can introspect `tools[i]`
+ * without losing property typing.
+ */
+export type ToolCatalogEntry = {
+    toolName: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    mutates: boolean;
+    operations: ToolCatalogOperation[];
+};
+/**
+ * Full tool catalog shape. The legacy preset returns the existing codegen
+ * catalog with `contractVersion`, `generatedAt`, `toolCount`, `tools`.
+ */
+export type ToolCatalog = {
+    contractVersion: string;
+    generatedAt: string | null;
+    toolCount: number;
+    tools: ToolCatalogEntry[];
+};
+export interface GetToolsOptions {
+    /**
+     * When `true`, the preset applies provider-specific prompt-cache markers
+     * (Anthropic `cache_control: { type: "ephemeral" }` on the last tool,
+     * for example). When omitted or `false`, no markers are added.
+     */
+    cache?: boolean;
+}
+export interface GetToolsResult {
+    tools: unknown[];
+    cacheStrategy: CacheStrategy;
+}
+/**
+ * Self-contained preset of LLM tools.
+ *
+ * Each preset owns:
+ *   - its tool catalogs per provider format
+ *   - its system prompt (and MCP-flavored variant)
+ *   - its dispatcher (how a named tool call routes against a doc handle)
+ *
+ * Presets are stateless; the same descriptor handles every call.
+ *
+ * @internal
+ */
+export interface PresetDescriptor {
+    /** Stable identifier — used as the preset's only "version" reference. */
+    readonly id: string;
+    /** Human-readable description shown by `listPresets()`. */
+    readonly description: string;
+    /**
+     * Whether this preset's provider adapters emit Anthropic prompt-cache
+     * markers when called with `cache: true`. Informational; per-provider
+     * behavior is reported via `GetToolsResult.cacheStrategy`.
+     */
+    readonly supportsCacheControl: boolean;
+    /** Tool definitions for the requested provider format. */
+    getTools(provider: ToolProvider, options?: GetToolsOptions): Promise<GetToolsResult>;
+    /** Full tool catalog with metadata (contract version, tool count, etc.). */
+    getCatalog(): Promise<ToolCatalog>;
+    /** System prompt for embedded LLM usage (OpenAI/Anthropic/Vercel APIs). */
+    getSystemPrompt(): Promise<string>;
+    /** System prompt for MCP server `instructions`. */
+    getMcpPrompt(): Promise<string>;
+    /**
+     * Dispatch a tool call against a bound document handle.
+     *
+     * The handle injects session targeting; `args` must NOT carry `doc` or
+     * `sessionId`. Returns whatever the underlying operation produces.
+     */
+    dispatch(documentHandle: BoundDocApi, toolName: string, args: Record<string, unknown>, invokeOptions?: InvokeOptions): Promise<unknown>;
+}
+/**
+ * The default preset returned when callers omit `preset`. Set to `'legacy'`
+ * so consumers built before presets existed (today's intent-tool path) keep
+ * working without changes.
+ */
+export declare const DEFAULT_PRESET = "legacy";
+/** List the IDs of all registered presets. */
+export declare function listPresets(): readonly string[];
+/**
+ * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
+ * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to
+ * get the default preset.
+ */
+export declare function getPreset(id?: string): PresetDescriptor;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;AAElF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAEvC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAErF,4EAA4E;IAC5E,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAEnC,2EAA2E;IAC3E,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnC,mDAAmD;IACnD,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CACN,cAAc,EAAE,WAAW,EAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAMD;;;;GAIG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC;AAMvC,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,SAAS,MAAM,EAAE,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,GAAE,MAAuB,GAAG,gBAAgB,CASvE"}

package/dist/presets.js

@@ -0,0 +1,53 @@
+/**
+ * Preset registry for SuperDoc LLM tools.
+ *
+ * A preset is a self-contained collection of LLM tools — provider catalogs
+ * (openai / anthropic / vercel / generic), a system prompt, and a dispatcher.
+ * Multiple presets can coexist in the SDK; consumers select one at runtime via
+ * `chooseTools({ preset })`.
+ *
+ *     const { tools, meta } = await chooseTools({ provider: 'vercel', preset: 'legacy' });
+ *
+ * v1 ships a single preset: `'legacy'` — a thin wrapper around today's
+ * codegen-emitted intent tools. When callers omit `preset`, `legacy` is used.
+ * The default may move once a replacement preset reaches parity; bumping it is
+ * a coordinated change in this file alone.
+ *
+ * Presets are NOT versioned. The preset id encodes the variant; a new shape
+ * ships as a new id, not a new version of an existing one.
+ *
+ * @internal
+ */
+import { SuperDocCliError } from './runtime/errors.js';
+import { legacyPreset } from './presets/legacy.js';
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * The default preset returned when callers omit `preset`. Set to `'legacy'`
+ * so consumers built before presets existed (today's intent-tool path) keep
+ * working without changes.
+ */
+export const DEFAULT_PRESET = 'legacy';
+const PRESETS = {
+    legacy: legacyPreset,
+};
+/** List the IDs of all registered presets. */
+export function listPresets() {
+    return Object.keys(PRESETS);
+}
+/**
+ * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
+ * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to
+ * get the default preset.
+ */
+export function getPreset(id = DEFAULT_PRESET) {
+    const preset = PRESETS[id];
+    if (preset == null) {
+        throw new SuperDocCliError(`Unknown LLM-tools preset: "${id}"`, {
+            code: 'PRESET_NOT_FOUND',
+            details: { id, availablePresets: Object.keys(PRESETS) },
+        });
+    }
+    return preset;
+}

package/dist/tools.cjs

@@ -1,334 +1,101 @@
 'use strict';
 
-var promises = require('node:fs/promises');
-var path = require('node:path');
-var node_url = require('node:url');
-var errors = require('./runtime/errors.cjs');
-var intentDispatch_generated = require('./generated/intent-dispatch.generated.cjs');
+var presets = require('./presets.cjs');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-// Resolve tools directory relative to package root (works from both src/ and dist/)
-const toolsDir = path.resolve(path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('tools.cjs', document.baseURI).href)))), '..', 'tools');
-const providerFileByName = {
-    openai: 'tools.openai.json',
-    anthropic: 'tools.anthropic.json',
-    vercel: 'tools.vercel.json',
-    generic: 'tools.generic.json',
-};
-const STRIP_EMPTY_OPTIONAL_ARGS = new Set(['parentId', 'parentCommentId', 'id', 'status']);
-function isRecord(value) {
-    return typeof value === 'object' && value != null && !Array.isArray(value);
-}
-function isObviouslyCorruptedToolArgKey(key) {
-    const trimmed = key.trim();
-    return trimmed.length === 0 || !/[\p{L}\p{N}]/u.test(trimmed);
-}
-function stripCorruptedToolArgKeys(value) {
-    if (Array.isArray(value)) {
-        return value.map((item) => stripCorruptedToolArgKeys(item));
-    }
-    if (!isRecord(value))
-        return value;
-    const clean = {};
-    for (const [key, entryValue] of Object.entries(value)) {
-        if (isObviouslyCorruptedToolArgKey(key))
-            continue;
-        clean[key] = stripCorruptedToolArgKeys(entryValue);
-    }
-    return clean;
-}
-async function readJson(fileName) {
-    const filePath = path.join(toolsDir, fileName);
-    let raw = '';
-    try {
-        raw = await promises.readFile(filePath, 'utf8');
-    }
-    catch (error) {
-        throw new errors.SuperDocCliError('Unable to load packaged tool artifact.', {
-            code: 'TOOLS_ASSET_NOT_FOUND',
-            details: {
-                filePath,
-                message: error instanceof Error ? error.message : String(error),
-            },
-        });
-    }
-    try {
-        return JSON.parse(raw);
-    }
-    catch (error) {
-        throw new errors.SuperDocCliError('Packaged tool artifact is invalid JSON.', {
-            code: 'TOOLS_ASSET_INVALID',
-            details: {
-                filePath,
-                message: error instanceof Error ? error.message : String(error),
-            },
-        });
-    }
-}
-async function loadProviderBundle(provider) {
-    return readJson(providerFileByName[provider]);
-}
-async function loadCatalog() {
-    return readJson('catalog.json');
-}
-async function getToolCatalog() {
-    return getCachedCatalog();
-}
-async function listTools(provider) {
-    const bundle = await loadProviderBundle(provider);
-    const tools = bundle.tools;
-    if (!Array.isArray(tools)) {
-        throw new errors.SuperDocCliError('Tool provider bundle is missing tools array.', {
-            code: 'TOOLS_ASSET_INVALID',
-            details: { provider },
-        });
-    }
-    return tools;
-}
 /**
- * Select all intent tools for a specific provider.
+ * Public LLM-tools API. Thin layer over the preset registry — every call here
+ * resolves a preset (defaulting to `legacy` for backwards compat) and delegates
+ * to it.
  *
- * Returns all intent tools in the requested provider format. Pass
- * `cache: true` to apply provider-specific caching markers (see
- * {@link ToolChooserInput.cache}).
+ * Presets are the unit of swapping. To add a new tool surface (e.g. handwritten
+ * "core" tools, prompt-caching variant, lazy-load experiment), register a new
+ * descriptor in `presets.ts` — no changes here required.
+ */
+/**
+ * Select tools for a specific provider from a preset.
  *
  * @example
  * ```ts
+ * // Default — legacy preset, no cache markers.
+ * const { tools, meta } = await chooseTools({ provider: 'vercel' });
+ *
  * // Anthropic — last tool gets cache_control automatically.
  * const { tools, meta } = await chooseTools({ provider: 'anthropic', cache: true });
  *
- * // OpenAI — caching is automatic when prompts exceed 1024 tokens.
- * const { tools } = await chooseTools({ provider: 'openai', cache: true });
+ * // Pick a specific preset by ID.
+ * const { tools, meta } = await chooseTools({ provider: 'openai', preset: 'legacy' });
  * ```
  */
 async function chooseTools(input) {
-    const bundle = await loadProviderBundle(input.provider);
-    const rawTools = Array.isArray(bundle.tools) ? bundle.tools : [];
-    const cacheRequested = input.cache === true;
-    const { tools, cacheStrategy } = applyCacheMarkers(rawTools, input.provider, cacheRequested);
+    const presetId = input.preset ?? presets.DEFAULT_PRESET;
+    const preset = presets.getPreset(presetId);
+    const { tools, cacheStrategy } = await preset.getTools(input.provider, {
+        cache: input.cache === true,
+    });
     return {
         tools,
         meta: {
             provider: input.provider,
+            preset: presetId,
             toolCount: tools.length,
             cacheStrategy,
         },
     };
 }
-/**
- * Apply provider-specific caching markers to the tools array. Mutates a clone,
- * never the input. Anthropic gets an explicit `cache_control` on the last
- * tool; other providers pass through.
- */
-function applyCacheMarkers(tools, provider, cacheRequested) {
-    if (!cacheRequested) {
-        return { tools, cacheStrategy: 'disabled' };
-    }
-    if (provider === 'anthropic') {
-        if (tools.length === 0)
-            return { tools, cacheStrategy: 'explicit' };
-        // Anthropic: marking the LAST tool with cache_control caches the entire
-        // tools block (and everything before it in the request — system prompt
-        // first if it also has cache_control). Shallow-spread the last entry so we
-        // don't mutate the cached bundle in place.
-        const next = tools.slice(0, -1);
-        const last = {
-            ...tools[tools.length - 1],
-            cache_control: { type: 'ephemeral' },
-        };
-        next.push(last);
-        return { tools: next, cacheStrategy: 'explicit' };
-    }
-    if (provider === 'openai') {
-        // OpenAI caches prompts ≥ 1024 tokens automatically. No marker needed,
-        // but we still report cacheStrategy:'automatic' so callers can branch on
-        // it (e.g. for measurement).
-        return { tools, cacheStrategy: 'automatic' };
-    }
-    // vercel / generic — depends on underlying model.
-    return { tools, cacheStrategy: 'unsupported' };
-}
-function resolveDocApiMethod(documentHandle, operationId) {
-    const tokens = operationId.split('.').slice(1);
-    let cursor = documentHandle;
-    for (const token of tokens) {
-        if (!isRecord(cursor) || !(token in cursor)) {
-            throw new errors.SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
-                code: 'TOOL_DISPATCH_NOT_FOUND',
-                details: { operationId, token },
-            });
-        }
-        cursor = cursor[token];
-    }
-    if (typeof cursor !== 'function') {
-        throw new errors.SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
-            code: 'TOOL_DISPATCH_NOT_FOUND',
-            details: { operationId },
-        });
-    }
-    return cursor;
-}
-// Cached catalog instance — loaded once per process.
-let _catalogCache = null;
-async function getCachedCatalog() {
-    if (_catalogCache == null) {
-        _catalogCache = await loadCatalog();
-    }
-    return _catalogCache;
+// ---------------------------------------------------------------------------
+// Catalog + listings (preset-scoped; default to legacy)
+// ---------------------------------------------------------------------------
+/** Return the full tool catalog for a preset (default: legacy). */
+async function getToolCatalog(preset) {
+    return presets.getPreset(preset ?? presets.DEFAULT_PRESET).getCatalog();
 }
 /**
- * Validate tool arguments against the catalog schema.
+ * Return the raw tool array for a provider from a preset (default: legacy).
  *
- * Checks three things in order:
- * 1. No unknown keys (additionalProperties: false in merged schema)
- * 2. All universally-required keys present (merged schema `required`)
- * 3. All action-specific required keys present (per-operation `required`)
+ * No cache markers are applied. Use {@link chooseTools} when you need cache
+ * markers and metadata.
  */
-function validateToolArgs(toolName, args, tool) {
-    const schema = tool.inputSchema;
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const required = Array.isArray(schema.required) ? schema.required : [];
-    // 1. Reject unknown keys
-    const knownKeys = new Set(Object.keys(properties));
-    const unknownKeys = Object.keys(args).filter((k) => !knownKeys.has(k));
-    if (unknownKeys.length > 0) {
-        throw new errors.SuperDocCliError(`Unknown argument(s) for ${toolName}: ${unknownKeys.join(', ')}`, {
-            code: 'INVALID_ARGUMENT',
-            details: { toolName, unknownKeys, knownKeys: [...knownKeys] },
-        });
-    }
-    // 2. Reject missing universally-required keys
-    const missingKeys = required.filter((k) => args[k] == null);
-    if (missingKeys.length > 0) {
-        throw new errors.SuperDocCliError(`Missing required argument(s) for ${toolName}: ${missingKeys.join(', ')}`, {
-            code: 'INVALID_ARGUMENT',
-            details: { toolName, missingKeys },
-        });
-    }
-    // 3. Reject missing per-operation required keys.
-    //    For multi-action tools, resolve the operation by action; for single-op
-    //    tools, use the sole operation entry.
-    const action = args.action;
-    let op;
-    if (typeof action === 'string' && tool.operations.length > 1) {
-        op = tool.operations.find((o) => o.intentAction === action);
-    }
-    else if (tool.operations.length === 1) {
-        op = tool.operations[0];
-    }
-    if (op) {
-        validateOperationRequired(toolName, action, args, op);
-    }
+async function listTools(provider, preset) {
+    const { tools } = await presets.getPreset(preset ?? presets.DEFAULT_PRESET).getTools(provider, { cache: false });
+    return tools;
 }
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
 /**
- * Check per-operation required constraints.
+ * Dispatch a tool call against a bound document handle using the default
+ * preset (`legacy`).
  *
- * Handles two shapes emitted by the codegen:
- *   - `required: string[]`        — all listed keys must be present
- *   - `requiredOneOf: string[][]`  — at least one branch must be fully satisfied
- *     (mirrors JSON Schema `oneOf` with per-branch `required` arrays)
- */
-function validateOperationRequired(toolName, action, args, op) {
-    const actionLabel = typeof action === 'string' ? ` action "${action}"` : '';
-    if (op.requiredOneOf && op.requiredOneOf.length > 0) {
-        const satisfied = op.requiredOneOf.some((branch) => branch.every((k) => args[k] != null));
-        if (!satisfied) {
-            const options = op.requiredOneOf.map((b) => b.join(' + ')).join(' | ');
-            throw new errors.SuperDocCliError(`Missing required argument(s) for ${toolName}${actionLabel}: must provide one of: ${options}`, {
-                code: 'INVALID_ARGUMENT',
-                details: { toolName, action, requiredOneOf: op.requiredOneOf },
-            });
-        }
-    }
-    else if (op.required && op.required.length > 0) {
-        const missingActionKeys = op.required.filter((k) => args[k] == null);
-        if (missingActionKeys.length > 0) {
-            throw new errors.SuperDocCliError(`Missing required argument(s) for ${toolName}${actionLabel}: ${missingActionKeys.join(', ')}`, {
-                code: 'INVALID_ARGUMENT',
-                details: { toolName, action, missingKeys: missingActionKeys },
-            });
-        }
-    }
-}
-/**
- * Dispatch a tool call against a bound document handle.
+ * The document handle injects session targeting automatically; tool arguments
+ * should not contain `doc` or `sessionId`.
  *
- * The document handle injects session targeting automatically.
- * Tool arguments should not contain `doc` or `sessionId`.
+ * For preset-aware dispatch — e.g. when comparing two presets — call
+ * `getPreset('id').dispatch(...)` directly.
  */
 async function dispatchSuperDocTool(documentHandle, toolName, args = {}, invokeOptions) {
-    if (!isRecord(args)) {
-        throw new errors.SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
-            code: 'INVALID_ARGUMENT',
-            details: { toolName },
-        });
-    }
-    const sanitizedArgs = stripCorruptedToolArgKeys(args);
-    if (!isRecord(sanitizedArgs)) {
-        throw new errors.SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
-            code: 'INVALID_ARGUMENT',
-            details: { toolName },
-        });
-    }
-    // Validate against the tool schema before dispatch.
-    const catalog = await getCachedCatalog();
-    const tool = catalog.tools.find((t) => t.toolName === toolName);
-    if (tool == null) {
-        throw new errors.SuperDocCliError(`Unknown tool: ${toolName}`, {
-            code: 'TOOL_DISPATCH_NOT_FOUND',
-            details: { toolName },
-        });
-    }
-    validateToolArgs(toolName, sanitizedArgs, tool);
-    // Strip empty strings for known optional ID/enum params that LLMs fill with ""
-    // instead of omitting. Only target params where "" is never a valid value.
-    const cleanArgs = {};
-    for (const [key, value] of Object.entries(sanitizedArgs)) {
-        if (value === '' && STRIP_EMPTY_OPTIONAL_ARGS.has(key))
-            continue;
-        cleanArgs[key] = value;
-    }
-    return intentDispatch_generated.dispatchIntentTool(toolName, cleanArgs, (operationId, input) => {
-        const method = resolveDocApiMethod(documentHandle, operationId);
-        return method(input, invokeOptions);
-    });
+    return presets.getPreset(presets.DEFAULT_PRESET).dispatch(documentHandle, toolName, args, invokeOptions);
 }
+// ---------------------------------------------------------------------------
+// System prompts (preset-scoped; default to legacy)
+// ---------------------------------------------------------------------------
 /**
- * Read the bundled SDK system prompt for intent tools.
+ * Read the packaged SDK system prompt (default preset: legacy).
  *
- * This prompt includes a persona preamble ("You are a document editing assistant…")
- * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs).
- * For MCP server instructions, use {@link getMcpPrompt} instead.
+ * Includes a persona preamble ("You are a document editing assistant…")
+ * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs). For MCP
+ * server instructions, use {@link getMcpPrompt} instead.
  */
-async function getSystemPrompt() {
-    const promptPath = path.join(toolsDir, 'system-prompt.md');
-    try {
-        return await promises.readFile(promptPath, 'utf8');
-    }
-    catch {
-        throw new errors.SuperDocCliError('System prompt not found.', {
-            code: 'TOOLS_ASSET_NOT_FOUND',
-            details: { filePath: promptPath },
-        });
-    }
+async function getSystemPrompt(preset) {
+    return presets.getPreset(preset ?? presets.DEFAULT_PRESET).getSystemPrompt();
 }
 /**
- * Read the bundled MCP system prompt for intent tools.
+ * Read the packaged MCP system prompt for intent tools (default preset: legacy).
  *
- * This prompt omits the persona preamble and includes session lifecycle
- * instructions (open/save/close) suitable for MCP server `instructions`.
+ * Omits the persona preamble and includes session lifecycle instructions
+ * (open/save/close) suitable for MCP server `instructions`.
  */
-async function getMcpPrompt() {
-    const promptPath = path.join(toolsDir, 'system-prompt-mcp.md');
-    try {
-        return await promises.readFile(promptPath, 'utf8');
-    }
-    catch {
-        throw new errors.SuperDocCliError('MCP system prompt not found.', {
-            code: 'TOOLS_ASSET_NOT_FOUND',
-            details: { filePath: promptPath },
-        });
-    }
+async function getMcpPrompt(preset) {
+    return presets.getPreset(preset ?? presets.DEFAULT_PRESET).getMcpPrompt();
 }
 /**
  * Get the system prompt formatted for a specific LLM provider, with optional
@@ -355,7 +122,7 @@ async function getMcpPrompt() {
  * ```
  */
 async function getSystemPromptForProvider(input) {
-    const text = await getSystemPrompt();
+    const text = await getSystemPrompt(input.preset);
     const cacheRequested = input.cache === true;
     if (input.provider === 'anthropic') {
         const block = { type: 'text', text };
@@ -375,6 +142,9 @@ async function getSystemPromptForProvider(input) {
     return { provider: input.provider, content: text, cacheStrategy };
 }
 
+exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
+exports.getPreset = presets.getPreset;
+exports.listPresets = presets.listPresets;
 exports.chooseTools = chooseTools;
 exports.dispatchSuperDocTool = dispatchSuperDocTool;
 exports.getMcpPrompt = getMcpPrompt;