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

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 presets = require('./presets.cjs');
 
 // ---------------------------------------------------------------------------
 // Session-bound runtime wrapper
@@ -172,6 +173,9 @@ exports.getSystemPromptForProvider = tools.getSystemPromptForProvider;
 exports.getToolCatalog = tools.getToolCatalog;
 exports.listTools = tools.listTools;
 exports.dispatchIntentTool = intentDispatch_generated.dispatchIntentTool;
+exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
+exports.getPreset = presets.getPreset;
+exports.listPresets = presets.listPresets;
 exports.SuperDocClient = SuperDocClient;
 exports.SuperDocDocument = SuperDocDocument;
 exports.createSuperDocClient = createSuperDocClient;

package/dist/index.d.ts

@@ -81,8 +81,8 @@ export declare class SuperDocClient {
 }
 export declare function createSuperDocClient(options?: SuperDocClientOptions): SuperDocClient;
 export { getSkill, installSkill, listSkills } from './skills.js';
-export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, } from './tools.js';
-export type { AnthropicSystemPrompt, CacheStrategy, SystemPromptForProviderResult, ToolChooserInput, ToolProvider, } from './tools.js';
+export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, DEFAULT_PRESET, getPreset, listPresets, } from './tools.js';
+export type { AnthropicSystemPrompt, CacheStrategy, SystemPromptForProviderResult, ToolCatalog, ToolCatalogEntry, ToolCatalogOperation, ToolChooserInput, ToolProvider, } from './tools.js';
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { SuperDocCliError } from './runtime/errors.js';
 export type { InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.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

@@ -154,6 +154,6 @@ export function createSuperDocClient(options = {}) {
     return new SuperDocClient(options);
 }
 export { getSkill, installSkill, listSkills } from './skills.js';
-export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, } from './tools.js';
+export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, DEFAULT_PRESET, getPreset, listPresets, } from './tools.js';
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { SuperDocCliError } from './runtime/errors.js';

package/dist/presets/legacy.cjs

@@ -0,0 +1,297 @@
+'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 _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/**
+ * Legacy preset — wraps the existing codegen-emitted intent tools verbatim.
+ *
+ * The legacy preset is a read-through over the packaged tool artifacts in
+ * `packages/sdk/tools/` (catalog, per-provider tool JSON, system prompts) and
+ * delegates dispatch to the codegen-emitted `dispatchIntentTool`. It is the
+ * default preset returned by `chooseTools()` when callers omit `preset`.
+ *
+ * Nothing in this file relocates or rewrites the packaged artifacts. The whole
+ * point of the read-through wrapper is that running `generate:all` continues
+ * to refresh `packages/sdk/tools/*.json` in place; the legacy preset picks up
+ * the new files on the next call.
+ *
+ * @internal
+ */
+// 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('presets/legacy.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 readProviderTools(provider) {
+    return readJson(providerFileByName[provider]);
+}
+// Cached catalog instance — loaded once per process.
+let _catalogCache = null;
+async function getCachedCatalog() {
+    if (_catalogCache == null) {
+        _catalogCache = await readJson('catalog.json');
+    }
+    return _catalogCache;
+}
+/**
+ * Apply provider-specific caching markers to the tools array. Clones the last
+ * entry instead of mutating 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 tool list 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;
+}
+/**
+ * Validate tool arguments against the catalog schema.
+ *
+ * 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`)
+ */
+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 (additionalProperties: false in merged schema)
+    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 (merged schema `required`)
+    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 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);
+    }
+}
+/**
+ * Check per-operation required constraints. Handles both flat `required: string[]`
+ * and discriminated `requiredOneOf: string[][]` shapes emitted by codegen.
+ */
+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 },
+            });
+        }
+    }
+}
+async function legacyGetTools(provider, options) {
+    const { tools } = await readProviderTools(provider);
+    // Fail fast on malformed provider artifacts so agents don't silently boot
+    // with zero tools. Matches the pre-presets behavior of the public
+    // `listTools` path (TOOLS_ASSET_INVALID).
+    if (!Array.isArray(tools)) {
+        throw new errors.SuperDocCliError('Tool provider bundle is missing tools array.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: { provider },
+        });
+    }
+    return applyCacheMarkers(tools, provider, options?.cache === true);
+}
+async function legacyGetCatalog() {
+    return getCachedCatalog();
+}
+async function legacyGetSystemPrompt() {
+    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 legacyGetMcpPrompt() {
+    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 legacyDispatch(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 },
+        });
+    }
+    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);
+    });
+}
+const legacyPreset = {
+    id: 'legacy',
+    description: 'Codegen-emitted intent tools (default). Wraps packages/sdk/tools/ artifacts verbatim.',
+    supportsCacheControl: true,
+    getTools: legacyGetTools,
+    getCatalog: legacyGetCatalog,
+    getSystemPrompt: legacyGetSystemPrompt,
+    getMcpPrompt: legacyGetMcpPrompt,
+    dispatch: legacyDispatch,
+};
+
+exports.legacyPreset = legacyPreset;

package/dist/presets/legacy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Legacy preset — wraps the existing codegen-emitted intent tools verbatim.
+ *
+ * The legacy preset is a read-through over the packaged tool artifacts in
+ * `packages/sdk/tools/` (catalog, per-provider tool JSON, system prompts) and
+ * delegates dispatch to the codegen-emitted `dispatchIntentTool`. It is the
+ * default preset returned by `chooseTools()` when callers omit `preset`.
+ *
+ * Nothing in this file relocates or rewrites the packaged artifacts. The whole
+ * point of the read-through wrapper is that running `generate:all` continues
+ * to refresh `packages/sdk/tools/*.json` in place; the legacy preset picks up
+ * the new files on the next call.
+ *
+ * @internal
+ */
+import type { PresetDescriptor } from '../presets.js';
+export declare const legacyPreset: PresetDescriptor;
+//# sourceMappingURL=legacy.d.ts.map

package/dist/presets/legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.d.ts","sourceRoot":"","sources":["../../src/presets/legacy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,OAAO,KAAK,EAGV,gBAAgB,EAKjB,MAAM,eAAe,CAAC;AAqTvB,eAAO,MAAM,YAAY,EAAE,gBAU1B,CAAC"}

package/dist/presets/legacy.js

@@ -0,0 +1,291 @@
+/**
+ * Legacy preset — wraps the existing codegen-emitted intent tools verbatim.
+ *
+ * The legacy preset is a read-through over the packaged tool artifacts in
+ * `packages/sdk/tools/` (catalog, per-provider tool JSON, system prompts) and
+ * delegates dispatch to the codegen-emitted `dispatchIntentTool`. It is the
+ * default preset returned by `chooseTools()` when callers omit `preset`.
+ *
+ * Nothing in this file relocates or rewrites the packaged artifacts. The whole
+ * point of the read-through wrapper is that running `generate:all` continues
+ * to refresh `packages/sdk/tools/*.json` in place; the legacy preset picks up
+ * the new files on the next call.
+ *
+ * @internal
+ */
+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 readProviderTools(provider) {
+    return readJson(providerFileByName[provider]);
+}
+// Cached catalog instance — loaded once per process.
+let _catalogCache = null;
+async function getCachedCatalog() {
+    if (_catalogCache == null) {
+        _catalogCache = await readJson('catalog.json');
+    }
+    return _catalogCache;
+}
+/**
+ * Apply provider-specific caching markers to the tools array. Clones the last
+ * entry instead of mutating 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 tool list 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;
+}
+/**
+ * Validate tool arguments against the catalog schema.
+ *
+ * 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`)
+ */
+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 (additionalProperties: false in merged schema)
+    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 (merged schema `required`)
+    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 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);
+    }
+}
+/**
+ * Check per-operation required constraints. Handles both flat `required: string[]`
+ * and discriminated `requiredOneOf: string[][]` shapes emitted by codegen.
+ */
+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 },
+            });
+        }
+    }
+}
+async function legacyGetTools(provider, options) {
+    const { tools } = await readProviderTools(provider);
+    // Fail fast on malformed provider artifacts so agents don't silently boot
+    // with zero tools. Matches the pre-presets behavior of the public
+    // `listTools` path (TOOLS_ASSET_INVALID).
+    if (!Array.isArray(tools)) {
+        throw new SuperDocCliError('Tool provider bundle is missing tools array.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: { provider },
+        });
+    }
+    return applyCacheMarkers(tools, provider, options?.cache === true);
+}
+async function legacyGetCatalog() {
+    return getCachedCatalog();
+}
+async function legacyGetSystemPrompt() {
+    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 },
+        });
+    }
+}
+async function legacyGetMcpPrompt() {
+    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 },
+        });
+    }
+}
+async function legacyDispatch(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 },
+        });
+    }
+    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);
+    });
+}
+export const legacyPreset = {
+    id: 'legacy',
+    description: 'Codegen-emitted intent tools (default). Wraps packages/sdk/tools/ artifacts verbatim.',
+    supportsCacheControl: true,
+    getTools: legacyGetTools,
+    getCatalog: legacyGetCatalog,
+    getSystemPrompt: legacyGetSystemPrompt,
+    getMcpPrompt: legacyGetMcpPrompt,
+    dispatch: legacyDispatch,
+};