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

package/dist/tools.d.ts

@@ -1,29 +1,25 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
 import type { BoundDocApi } from './generated/client.js';
 import type { InvokeOptions } from './runtime/process.js';
-export type ToolProvider = 'openai' | 'anthropic' | 'vercel' | 'generic';
-export type ToolCatalog = {
-    contractVersion: string;
-    generatedAt: string | null;
-    toolCount: number;
-    tools: ToolCatalogEntry[];
-};
-type OperationEntry = {
-    operationId: string;
-    intentAction: string;
-    required?: string[];
-    requiredOneOf?: string[][];
-};
-type ToolCatalogEntry = {
-    toolName: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    mutates: boolean;
-    operations: OperationEntry[];
-};
-export declare function getToolCatalog(): Promise<ToolCatalog>;
-export declare function listTools(provider: ToolProvider): Promise<unknown[]>;
+import { DEFAULT_PRESET, getPreset, listPresets, type CacheStrategy, type ToolCatalog, type ToolCatalogEntry, type ToolCatalogOperation, type ToolProvider } from './presets.js';
+export { DEFAULT_PRESET, getPreset, listPresets };
+export type { CacheStrategy, ToolCatalog, ToolCatalogEntry, ToolCatalogOperation, ToolProvider };
 export type ToolChooserInput = {
     provider: ToolProvider;
+    /**
+     * Preset ID to load tools from. Defaults to {@link DEFAULT_PRESET}
+     * (`'legacy'`) for backwards compatibility. Use {@link listPresets} to
+     * discover available presets.
+     */
+    preset?: string;
     /**
      * When `true`, applies provider-specific prompt-caching markers to the
      * returned tools so subsequent identical requests reuse the cached prefix.
@@ -40,53 +36,65 @@ export type ToolChooserInput = {
      */
     cache?: boolean;
 };
-export type CacheStrategy = 'explicit' | 'automatic' | 'unsupported' | 'disabled';
 /**
- * Select all intent tools for a specific provider.
- *
- * Returns all intent tools in the requested provider format. Pass
- * `cache: true` to apply provider-specific caching markers (see
- * {@link ToolChooserInput.cache}).
+ * 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' });
  * ```
  */
 export declare function chooseTools(input: ToolChooserInput): Promise<{
     tools: unknown[];
     meta: {
         provider: ToolProvider;
+        preset: string;
         toolCount: number;
         cacheStrategy: CacheStrategy;
     };
 }>;
+/** Return the full tool catalog for a preset (default: legacy). */
+export declare function getToolCatalog(preset?: string): Promise<ToolCatalog>;
 /**
- * Dispatch a tool call against a bound document handle.
+ * Return the raw tool array for a provider from a preset (default: legacy).
+ *
+ * No cache markers are applied. Use {@link chooseTools} when you need cache
+ * markers and metadata.
+ */
+export declare function listTools(provider: ToolProvider, preset?: string): Promise<unknown[]>;
+/**
+ * Dispatch a tool call against a bound document handle using the default
+ * preset (`legacy`).
+ *
+ * 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.
  */
 export declare function dispatchSuperDocTool(documentHandle: BoundDocApi, toolName: string, args?: Record<string, unknown>, invokeOptions?: InvokeOptions): Promise<unknown>;
 /**
- * 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.
  */
-export declare function getSystemPrompt(): Promise<string>;
+export declare function getSystemPrompt(preset?: string): Promise<string>;
 /**
- * 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`.
  */
-export declare function getMcpPrompt(): Promise<string>;
+export declare function getMcpPrompt(preset?: string): Promise<string>;
 /**
  * Anthropic content block representation of the system prompt with optional
  * `cache_control` for prompt caching.
@@ -133,7 +141,7 @@ export type SystemPromptForProviderResult = {
  */
 export declare function getSystemPromptForProvider(input: {
     provider: ToolProvider;
+    preset?: string;
     cache?: boolean;
 }): Promise<SystemPromptForProviderResult>;
-export {};
 //# sourceMappingURL=tools.d.ts.map

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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,SAAS,EACT,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,YAAY,EAAE,CAAC;AAMjG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAClE,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,IAAI,EAAE;QACJ,QAAQ,EAAE,YAAY,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,aAAa,CAAC;KAC9B,CAAC;CACH,CAAC,CAeD;AAMD,mEAAmE;AACnE,wBAAsB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE1E;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAG3F;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,cAAc,EAAE,WAAW,EAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAMD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAMD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,CAAC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,GACvF;IAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,0BAA0B,CAAC,KAAK,EAAE;IACtD,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAqBzC"}

package/dist/tools.js

@@ -1,330 +1,99 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { SuperDocCliError } from './runtime/errors.js';
-import { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
-// Resolve tools directory relative to package root (works from both src/ and dist/)
-const toolsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '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 readFile(filePath, 'utf8');
-    }
-    catch (error) {
-        throw new 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 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');
-}
-export async function getToolCatalog() {
-    return getCachedCatalog();
-}
-export async function listTools(provider) {
-    const bundle = await loadProviderBundle(provider);
-    const tools = bundle.tools;
-    if (!Array.isArray(tools)) {
-        throw new 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.
+ */
+import { DEFAULT_PRESET, getPreset, listPresets, } from './presets.js';
+export { DEFAULT_PRESET, getPreset, listPresets };
+/**
+ * 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' });
  * ```
  */
 export 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 ?? DEFAULT_PRESET;
+    const preset = 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 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 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). */
+export async function getToolCatalog(preset) {
+    return getPreset(preset ?? 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 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 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);
-    }
+export async function listTools(provider, preset) {
+    const { tools } = await getPreset(preset ?? 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 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 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.
  */
 export async function dispatchSuperDocTool(documentHandle, toolName, args = {}, invokeOptions) {
-    if (!isRecord(args)) {
-        throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
-            code: 'INVALID_ARGUMENT',
-            details: { toolName },
-        });
-    }
-    const sanitizedArgs = stripCorruptedToolArgKeys(args);
-    if (!isRecord(sanitizedArgs)) {
-        throw new 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 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 dispatchIntentTool(toolName, cleanArgs, (operationId, input) => {
-        const method = resolveDocApiMethod(documentHandle, operationId);
-        return method(input, invokeOptions);
-    });
+    return getPreset(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.
  */
-export async function getSystemPrompt() {
-    const promptPath = path.join(toolsDir, 'system-prompt.md');
-    try {
-        return await readFile(promptPath, 'utf8');
-    }
-    catch {
-        throw new SuperDocCliError('System prompt not found.', {
-            code: 'TOOLS_ASSET_NOT_FOUND',
-            details: { filePath: promptPath },
-        });
-    }
+export async function getSystemPrompt(preset) {
+    return getPreset(preset ?? 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`.
  */
-export async function getMcpPrompt() {
-    const promptPath = path.join(toolsDir, 'system-prompt-mcp.md');
-    try {
-        return await readFile(promptPath, 'utf8');
-    }
-    catch {
-        throw new SuperDocCliError('MCP system prompt not found.', {
-            code: 'TOOLS_ASSET_NOT_FOUND',
-            details: { filePath: promptPath },
-        });
-    }
+export async function getMcpPrompt(preset) {
+    return getPreset(preset ?? DEFAULT_PRESET).getMcpPrompt();
 }
 /**
  * Get the system prompt formatted for a specific LLM provider, with optional
@@ -351,7 +120,7 @@ export async function getMcpPrompt() {
  * ```
  */
 export 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.14.0",
+  "version": "1.15.0-next.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,11 +26,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc-dev/sdk-darwin-x64": "1.14.0",
-    "@superdoc-dev/sdk-darwin-arm64": "1.14.0",
-    "@superdoc-dev/sdk-linux-arm64": "1.14.0",
-    "@superdoc-dev/sdk-linux-x64": "1.14.0",
-    "@superdoc-dev/sdk-windows-x64": "1.14.0"
+    "@superdoc-dev/sdk-darwin-arm64": "1.15.0-next.2",
+    "@superdoc-dev/sdk-darwin-x64": "1.15.0-next.2",
+    "@superdoc-dev/sdk-linux-x64": "1.15.0-next.2",
+    "@superdoc-dev/sdk-windows-x64": "1.15.0-next.2",
+    "@superdoc-dev/sdk-linux-arm64": "1.15.0-next.2"
   },
   "publishConfig": {
     "access": "public"