@superdoc-dev/sdk 1.19.2 → 1.20.1

package/dist/presets/core.js

@@ -0,0 +1,447 @@
+/**
+ * `core` preset — actions-only LLM-facing surface.
+ *
+ * Two advertised tools: superdoc_inspect (read-only deterministic snapshots)
+ * and superdoc_perform_action (named, statically validated, deterministic edit
+ * verbs — the action registry in agent/actions.ts).
+ *
+ * superdoc_execute_code (model-authored JS against a synchronous in-host doc)
+ * is WIP: dispatchable for SDK callers, NOT advertised and NOT in the served
+ * system prompt until it ships behind a safety flag. The agent_apply /
+ * agent_verify / agent_operation tools are likewise dispatchable but never
+ * advertised.
+ *
+ * @internal
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SuperDocCliError } from '../runtime/errors.js';
+import { AGENT_TOOL_DEFINITIONS, isAgentToolName, listAgentTools, validateExclusions, PUBLIC_AGENT_TOOL_NAMES, } from '../agent/catalog.js';
+import { agentApply, agentInspect, agentOperation, agentVerify } from '../agent/runtime.js';
+import { superdocPerformAction } from '../agent/actions.js';
+import { EMBEDDED_PROMPTS } from '../embedded-prompts.generated.js';
+// Prompts ship as <dist>/prompts/*.md. Resolve relative to the compiled
+// module, but the module's depth differs by build: in the SDK package this
+// file is dist/presets/core.js (so prompts are at ../prompts), while the
+// bundled CLI inlines it into dist/index.js (so prompts are at ./prompts).
+// Try both so getSystemPrompt works through the SDK AND the CLI host (the
+// path the Python SDK proxies through).
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PROMPT_DIR_CANDIDATES = [path.resolve(MODULE_DIR, '..', 'prompts'), path.resolve(MODULE_DIR, 'prompts')];
+let _actionsOnlyPromptCache = null;
+let _mcpPromptCache = null;
+/** Exported for unit tests; production callers use the default candidates. */
+export async function readPromptFile(fileName, label, candidateDirs = PROMPT_DIR_CANDIDATES) {
+    const tried = [];
+    let lastIoError;
+    for (const dir of candidateDirs) {
+        const promptPath = path.join(dir, fileName);
+        tried.push(promptPath);
+        try {
+            return await readFile(promptPath, 'utf8');
+        }
+        catch (err) {
+            const ioError = err;
+            if (ioError?.code !== 'ENOENT') {
+                // Permission/IO failures are not "asset missing" — remember the real
+                // cause, but still try the other layout candidate.
+                lastIoError = ioError;
+            }
+        }
+    }
+    // Filesystem candidates exhausted. Native binaries (bun --compile) resolve
+    // MODULE_DIR inside bun's virtual filesystem where the .md assets don't
+    // exist — fall back to the compiled-in copies (identical content by
+    // construction; a drift test enforces it).
+    const embedded = EMBEDDED_PROMPTS[fileName];
+    if (typeof embedded === 'string') {
+        return embedded;
+    }
+    if (lastIoError) {
+        throw new SuperDocCliError(`${label} could not be read: ${lastIoError.message}`, {
+            code: 'TOOLS_ASSET_UNREADABLE',
+            details: { triedPaths: tried, cause: `${lastIoError.code ?? lastIoError.name}: ${lastIoError.message}` },
+        });
+    }
+    throw new SuperDocCliError(`${label} not found.`, {
+        code: 'TOOLS_ASSET_NOT_FOUND',
+        details: { triedPaths: tried },
+    });
+}
+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;
+}
+function validateAgentToolArgs(toolName, args) {
+    const definition = AGENT_TOOL_DEFINITIONS.find((entry) => entry.name === toolName);
+    if (definition == null)
+        return;
+    const schema = definition.inputSchema;
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    const knownKeys = new Set(Object.keys(properties));
+    const unknownKeys = Object.keys(args).filter((key) => !knownKeys.has(key));
+    if (unknownKeys.length > 0) {
+        throw new SuperDocCliError(`Unknown argument(s) for ${toolName}: ${unknownKeys.join(', ')}`, {
+            code: 'INVALID_ARGUMENT',
+            details: { toolName, unknownKeys, knownKeys: [...knownKeys] },
+        });
+    }
+    const missingKeys = required.filter((key) => args[key] == null);
+    if (missingKeys.length > 0) {
+        throw new SuperDocCliError(`Missing required argument(s) for ${toolName}: ${missingKeys.join(', ')}`, {
+            code: 'INVALID_ARGUMENT',
+            details: { toolName, missingKeys },
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Compaction helpers — keep agent receipts tight in the tool-result payload
+// ---------------------------------------------------------------------------
+/**
+ * Max entries for per-item receipt lists (executedOperations, selectedTargets).
+ * Receipts live in the conversation and are re-billed as prompt tokens on every
+ * subsequent turn; unbounded lists (one op per formatted range/paragraph) made
+ * single receipts cost thousands of tokens. 8 keeps enough shape to audit while
+ * the accompanying *Count field preserves the true total.
+ */
+const RECEIPT_LIST_CAP = 8;
+function compactCountMap(counts) {
+    const compact = {};
+    for (const [key, value] of Object.entries(counts)) {
+        if (typeof value === 'number' && value !== 0)
+            compact[key] = value;
+    }
+    if (Object.keys(compact).length === 0 && typeof counts.blocks === 'number') {
+        compact.blocks = counts.blocks;
+    }
+    return compact;
+}
+function pickScalarFields(value, keys, limit = 6) {
+    if (!isRecord(value))
+        return {};
+    const entries = keys
+        ? keys.filter((key) => key in value).map((key) => [key, value[key]])
+        : Object.entries(value);
+    const compact = {};
+    for (const [key, entryValue] of entries) {
+        if (typeof entryValue === 'string' ||
+            typeof entryValue === 'number' ||
+            typeof entryValue === 'boolean' ||
+            entryValue == null) {
+            compact[key] = entryValue ?? null;
+        }
+        if (Object.keys(compact).length >= limit)
+            break;
+    }
+    return compact;
+}
+function compactOperationResult(result) {
+    if (result == null || typeof result === 'string' || typeof result === 'number' || typeof result === 'boolean') {
+        return result;
+    }
+    if (Array.isArray(result))
+        return { itemCount: result.length };
+    if (!isRecord(result))
+        return { kind: typeof result };
+    const compact = {
+        ...pickScalarFields(result, ['success', 'status', 'count', 'total', 'applied', 'created', 'deleted']),
+    };
+    if (isRecord(result.revision)) {
+        const revision = pickScalarFields(result.revision, ['before', 'after', 'current']);
+        if (Object.keys(revision).length > 0)
+            compact.revision = revision;
+    }
+    if (Array.isArray(result.steps)) {
+        compact.stepCount = result.steps.length;
+        compact.steps = result.steps
+            .slice(0, 4)
+            .map((step) => (isRecord(step) ? pickScalarFields(step, ['stepId', 'op', 'effect', 'matchCount'], 4) : {}));
+    }
+    if (Array.isArray(result.items))
+        compact.itemCount = result.items.length;
+    if (Array.isArray(result.changes))
+        compact.changeCount = result.changes.length;
+    if (Array.isArray(result.matches))
+        compact.matchCount = result.matches.length;
+    if (Object.keys(compact).length === 0)
+        return { kind: 'object' };
+    return compact;
+}
+function compactAgentReceipt(receipt) {
+    // Compact the known heavy fields; pass every action-specific evidence field
+    // (editsApplied, marker, placement, revertHint, recovery, …) through
+    // verbatim — truth-telling receipts are only useful if the model sees them.
+    const { status, intent, preSnapshot, postSnapshot, selectedTargets, executedOperations, verification, saveReopen, errors, ...evidence } = receipt;
+    return {
+        status,
+        intent,
+        ...(preSnapshot
+            ? {
+                preSnapshot: {
+                    revision: preSnapshot.revision,
+                    ...(preSnapshot.counts ? { counts: compactCountMap(preSnapshot.counts) } : {}),
+                },
+            }
+            : {}),
+        ...(postSnapshot
+            ? {
+                postSnapshot: {
+                    revision: postSnapshot.revision,
+                    ...(postSnapshot.counts ? { counts: compactCountMap(postSnapshot.counts) } : {}),
+                },
+            }
+            : {}),
+        ...(selectedTargets
+            ? {
+                // Cap per-item lists: batch actions (add_comments selectors[],
+                // whole-body formatting) can select hundreds of targets, and the
+                // receipt is re-sent in conversation history on EVERY later turn.
+                // The count carries the evidence; the head carries the shape.
+                selectedTargets: selectedTargets.slice(0, RECEIPT_LIST_CAP).map((target) => ({
+                    selector: target.selector,
+                    matchedCount: target.matched.length,
+                })),
+                ...(selectedTargets.length > RECEIPT_LIST_CAP ? { selectedTargetCount: selectedTargets.length } : {}),
+            }
+            : {}),
+        ...(executedOperations
+            ? {
+                // Same cap: per-range/per-item actions (format_text on every
+                // occurrence, whole-body set_font_family) execute one op per item —
+                // an uncapped list dominates the token cost of the receipt.
+                executedOperations: executedOperations.slice(0, RECEIPT_LIST_CAP).map((operation) => ({
+                    operationId: operation.operationId,
+                    ...(operation.rationale ? { rationale: operation.rationale } : {}),
+                    ...(operation.result !== undefined ? { result: compactOperationResult(operation.result) } : {}),
+                })),
+                ...(executedOperations.length > RECEIPT_LIST_CAP
+                    ? { executedOperationCount: executedOperations.length }
+                    : {}),
+            }
+            : {}),
+        ...(verification
+            ? {
+                verificationPassed: verification.every((entry) => entry.passed),
+                verification: verification.map((entry) => ({
+                    check: pickScalarFields(entry.check, undefined, 6),
+                    passed: entry.passed,
+                    ...(entry.detail ? { detail: entry.detail } : {}),
+                })),
+            }
+            : {}),
+        ...(saveReopen ? { saveReopen } : {}),
+        ...(errors ? { errors } : {}),
+        ...evidence,
+    };
+}
+// ---------------------------------------------------------------------------
+// superdoc_execute_code — in-host dispatch for the CLI/SDK-only `doc.executeCode` op
+// ---------------------------------------------------------------------------
+const EXECUTE_CODE_SPEC = {
+    operationId: 'doc.executeCode',
+    commandTokens: ['execute', 'code'],
+    params: [
+        { name: 'sessionId', kind: 'flag', flag: 'session', type: 'string' },
+        { name: 'code', kind: 'flag', flag: 'code', type: 'string' },
+    ],
+};
+function asRawOperationCapable(documentHandle) {
+    const candidate = documentHandle;
+    if (typeof candidate.invokeRawOperation !== 'function') {
+        throw new SuperDocCliError('superdoc_execute_code requires a session-bound document handle from client.open(); the provided handle cannot dispatch CLI/SDK-only operations.', {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+            details: { toolName: 'superdoc_execute_code' },
+        });
+    }
+    return candidate;
+}
+async function dispatchExecuteCode(documentHandle, args, invokeOptions) {
+    const code = typeof args.code === 'string' ? args.code : '';
+    // The generated bound client exposes doc.executeCode directly — use it.
+    // The invokeRawOperation path predates that binding and no handle produced
+    // by client.open() implements it; it remains only for callers that inject
+    // their own raw-capable handle.
+    const direct = documentHandle.executeCode;
+    if (typeof direct === 'function') {
+        return direct.call(documentHandle, { code }, invokeOptions);
+    }
+    const runner = asRawOperationCapable(documentHandle);
+    return runner.invokeRawOperation(EXECUTE_CODE_SPEC, { code }, invokeOptions);
+}
+// ---------------------------------------------------------------------------
+// Dispatcher
+// ---------------------------------------------------------------------------
+async function dispatchAgentTool(documentHandle, toolName, args, invokeOptions) {
+    switch (toolName) {
+        case 'superdoc_inspect':
+            return agentInspect(documentHandle, args);
+        case 'agent_apply':
+            return compactAgentReceipt(await agentApply(documentHandle, args));
+        case 'agent_verify':
+            return compactAgentReceipt(await agentVerify(documentHandle, args));
+        case 'agent_operation':
+            return agentOperation(documentHandle, args);
+        case 'superdoc_perform_action':
+            return compactAgentReceipt(await superdocPerformAction(documentHandle, args));
+        case 'superdoc_execute_code':
+            return dispatchExecuteCode(documentHandle, args, invokeOptions);
+    }
+    throw new SuperDocCliError(`Unknown agent tool: ${toolName}`, {
+        code: 'TOOL_DISPATCH_NOT_FOUND',
+        details: { toolName },
+    });
+}
+// ---------------------------------------------------------------------------
+// Provider cache markers — mirrors the legacy preset
+// ---------------------------------------------------------------------------
+function applyCacheMarkers(tools, provider, cacheRequested) {
+    if (!cacheRequested)
+        return { tools, cacheStrategy: 'disabled' };
+    if (provider === 'anthropic') {
+        if (tools.length === 0)
+            return { tools, cacheStrategy: 'explicit' };
+        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')
+        return { tools, cacheStrategy: 'automatic' };
+    return { tools, cacheStrategy: 'unsupported' };
+}
+// ---------------------------------------------------------------------------
+// PresetDescriptor surface
+// ---------------------------------------------------------------------------
+async function coreGetTools(provider, options) {
+    const tools = listAgentTools(provider, { excludeActions: options?.excludeActions });
+    return applyCacheMarkers(tools, provider, options?.cache === true);
+}
+async function coreGetCatalog() {
+    // Synthetic catalog — describes the advertised LLM-facing tools.
+    const publicSet = new Set(PUBLIC_AGENT_TOOL_NAMES);
+    const tools = AGENT_TOOL_DEFINITIONS.filter((d) => publicSet.has(d.name)).map((d) => ({
+        toolName: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        mutates: d.name !== 'superdoc_inspect',
+        operations: [],
+    }));
+    return {
+        contractVersion: 'core/v2',
+        generatedAt: null,
+        toolCount: tools.length,
+        tools,
+    };
+}
+/**
+ * Drop the per-action documentation lines for excluded actions. Entries render
+ * as single "- name: ..." lines (the drift-guard test enforces the format), so
+ * line-level filtering is deterministic. Prose cross-references elsewhere in
+ * the prompt are left alone — a mention costs a few tokens; a full per-action
+ * manual for an uncallable action teaches the model to call it.
+ */
+function stripExcludedActionLines(prompt, excludedActions) {
+    if (excludedActions.size === 0)
+        return prompt;
+    return prompt
+        .split('\n')
+        .filter((line) => {
+        const match = /^- ([a-z_]+)(?: \/ ([a-z_]+))?:/.exec(line);
+        if (!match)
+            return true;
+        const names = [match[1], match[2]].filter((n) => Boolean(n));
+        // Drop the line only when EVERY action it documents is excluded (the
+        // paired accept/reject line survives if one side remains callable).
+        return !names.every((name) => excludedActions.has(name));
+    })
+        .join('\n');
+}
+async function coreGetSystemPrompt(options) {
+    const { excludedActions } = validateExclusions({ excludeActions: options?.excludeActions });
+    // The core preset is ACTIONS-ONLY: superdoc_execute_code is WIP and not
+    // advertised, and the prompt documents only the action surface (this exact
+    // prompt is what the eval suite validates). Code-execution guidance will be
+    // added when the safety-flag work ships that tool.
+    if (_actionsOnlyPromptCache == null) {
+        _actionsOnlyPromptCache = await readPromptFile('system-prompt.md', 'Core system prompt');
+    }
+    return stripExcludedActionLines(_actionsOnlyPromptCache, excludedActions);
+}
+async function coreGetMcpPrompt() {
+    if (_mcpPromptCache == null) {
+        _mcpPromptCache = await readPromptFile('mcp-prompt.md', 'MCP system prompt');
+    }
+    return _mcpPromptCache;
+}
+async function coreDispatch(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 },
+        });
+    }
+    // Defense-in-depth for exclusion configs: a host that narrowed the advertised
+    // surface (getTools excludeActions) can pass the same list here so a
+    // guessed/injected call to an excluded action is refused, not run.
+    const exclusionOptions = invokeOptions;
+    if (toolName === 'superdoc_perform_action' &&
+        typeof sanitizedArgs.action === 'string' &&
+        exclusionOptions?.excludeActions?.includes(sanitizedArgs.action)) {
+        throw new SuperDocCliError(`Action ${sanitizedArgs.action} is excluded by configuration.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { toolName, action: sanitizedArgs.action, excluded: true },
+        });
+    }
+    let forwardOptions = invokeOptions;
+    if (exclusionOptions && 'excludeActions' in exclusionOptions) {
+        const { excludeActions: _ea, ...rest } = exclusionOptions;
+        forwardOptions = rest;
+    }
+    if (isAgentToolName(toolName)) {
+        validateAgentToolArgs(toolName, sanitizedArgs);
+        return dispatchAgentTool(documentHandle, toolName, sanitizedArgs, forwardOptions);
+    }
+    throw new SuperDocCliError(`Unknown tool: ${toolName}`, {
+        code: 'TOOL_DISPATCH_NOT_FOUND',
+        details: { toolName, preset: 'core' },
+    });
+}
+export const corePreset = {
+    id: 'core',
+    description: 'Actions-only LLM surface: superdoc_inspect (reads) and superdoc_perform_action (named, deterministic edit verbs). superdoc_execute_code exists but is WIP — dispatchable, not advertised.',
+    supportsCacheControl: true,
+    getTools: coreGetTools,
+    getCatalog: coreGetCatalog,
+    getSystemPrompt: coreGetSystemPrompt,
+    getMcpPrompt: coreGetMcpPrompt,
+    dispatch: coreDispatch,
+};

package/dist/presets.cjs

@@ -2,6 +2,7 @@
 
 var errors = require('./runtime/errors.cjs');
 var legacy = require('./presets/legacy.cjs');
+var core = require('./presets/core.cjs');
 
 /**
  * Preset registry for SuperDoc LLM tools.
@@ -13,10 +14,10 @@ var legacy = require('./presets/legacy.cjs');
  *
  *     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.
+ * Two presets ship built-in: `'legacy'` (codegen-emitted intent tools; the
+ * default when callers omit `preset`) and `'core'` (the actions-only LLM
+ * surface). The default may move once core fully replaces legacy; 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.
@@ -27,18 +28,62 @@ var legacy = require('./presets/legacy.cjs');
 // 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.
+ * The default preset returned when callers omit `preset`. Stays as `'legacy'`
+ * for backward compatibility — consumers built before presets existed (today's
+ * intent-tool path) keep working without changes. To exercise the `core`
+ * preset, callers pass `preset: 'core'` explicitly.
  */
 const DEFAULT_PRESET = 'legacy';
-const PRESETS = {
+const BUILTIN_PRESETS = {
     legacy: legacy.legacyPreset,
+    core: core.corePreset,
 };
+/**
+ * Mutable registry, seeded with the built-ins. Customers add their own presets
+ * via {@link registerPreset} (e.g. one produced by `extendPreset` /
+ * `composePreset`) so `getPreset`/`chooseTools` can resolve them by id.
+ */
+const PRESETS = { ...BUILTIN_PRESETS };
 /** List the IDs of all registered presets. */
 function listPresets() {
     return Object.keys(PRESETS);
 }
+/**
+ * Register one or more presets so they resolve by id through `getPreset` and
+ * the `chooseTools`/`dispatchSuperDocTool` plumbing. Re-registering a custom id
+ * replaces the previously registered preset for that id (tests / hot-reload
+ * rely on this). Built-in ids (legacy / core) cannot
+ * be overwritten.
+ */
+function registerPreset(...presets) {
+    for (const preset of presets) {
+        if (preset == null || typeof preset.id !== 'string' || preset.id.length === 0) {
+            throw new errors.SuperDocCliError('registerPreset requires a preset with a non-empty string id.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        if (preset.id in BUILTIN_PRESETS) {
+            throw new errors.SuperDocCliError(`Cannot overwrite built-in preset "${preset.id}".`, {
+                code: 'INVALID_ARGUMENT',
+                details: { id: preset.id },
+            });
+        }
+        PRESETS[preset.id] = preset;
+    }
+}
+/**
+ * Unregister a customer-registered preset. Idempotent (no-op if absent).
+ * Rejects unregistering a built-in preset id.
+ */
+function unregisterPreset(id) {
+    if (id in BUILTIN_PRESETS) {
+        throw new errors.SuperDocCliError(`Cannot unregister built-in preset "${id}".`, {
+            code: 'INVALID_ARGUMENT',
+            details: { id },
+        });
+    }
+    delete PRESETS[id];
+}
 /**
  * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
  * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to
@@ -58,3 +103,5 @@ function getPreset(id = DEFAULT_PRESET) {
 exports.DEFAULT_PRESET = DEFAULT_PRESET;
 exports.getPreset = getPreset;
 exports.listPresets = listPresets;
+exports.registerPreset = registerPreset;
+exports.unregisterPreset = unregisterPreset;

package/dist/presets.d.ts

@@ -8,10 +8,10 @@
  *
  *     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.
+ * Two presets ship built-in: `'legacy'` (codegen-emitted intent tools; the
+ * default when callers omit `preset`) and `'core'` (the actions-only LLM
+ * surface). The default may move once core fully replaces legacy; 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.
@@ -80,6 +80,23 @@ export interface GetToolsOptions {
      * for example). When omitted or `false`, no markers are added.
      */
     cache?: boolean;
+    /**
+     * Action names to REMOVE from the advertised action surface (the `core`
+     * preset's `superdoc_perform_action` enum/description/args shrink together).
+     * Unknown names throw. Presets without an action surface (e.g. `legacy`)
+     * ignore this option.
+     */
+    excludeActions?: readonly string[];
+}
+/**
+ * Options for {@link PresetDescriptor.getSystemPrompt}. Mirrors the exclusion
+ * options on getTools so the prompt and the advertised tool surface can be
+ * narrowed TOGETHER — a prompt that documents an uncallable action teaches the
+ * model to call it.
+ */
+export interface GetSystemPromptOptions {
+    /** Drop the per-action documentation lines for these actions (core preset). */
+    excludeActions?: readonly string[];
 }
 export interface GetToolsResult {
     tools: unknown[];
@@ -113,7 +130,7 @@ export interface PresetDescriptor {
     /** 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>;
+    getSystemPrompt(options?: GetSystemPromptOptions): Promise<string>;
     /** System prompt for MCP server `instructions`. */
     getMcpPrompt(): Promise<string>;
     /**
@@ -125,13 +142,27 @@ export interface PresetDescriptor {
     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.
+ * The default preset returned when callers omit `preset`. Stays as `'legacy'`
+ * for backward compatibility — consumers built before presets existed (today's
+ * intent-tool path) keep working without changes. To exercise the `core`
+ * preset, callers pass `preset: 'core'` explicitly.
  */
 export declare const DEFAULT_PRESET = "legacy";
 /** List the IDs of all registered presets. */
 export declare function listPresets(): readonly string[];
+/**
+ * Register one or more presets so they resolve by id through `getPreset` and
+ * the `chooseTools`/`dispatchSuperDocTool` plumbing. Re-registering a custom id
+ * replaces the previously registered preset for that id (tests / hot-reload
+ * rely on this). Built-in ids (legacy / core) cannot
+ * be overwritten.
+ */
+export declare function registerPreset(...presets: PresetDescriptor[]): void;
+/**
+ * Unregister a customer-registered preset. Idempotent (no-op if absent).
+ * Rejects unregistering a built-in preset id.
+ */
+export declare function unregisterPreset(id: string): void;
 /**
  * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
  * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to

package/dist/presets.d.ts.map

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