@superdoc-dev/sdk 1.8.0-next.8 → 1.8.0-next.80

package/dist/generated/intent-dispatch.generated.cjs

@@ -55,6 +55,7 @@ function dispatchIntentTool(toolName, args, execute) {
                 case 'create': return execute('doc.lists.create', rest);
                 case 'attach': return execute('doc.lists.attach', rest);
                 case 'detach': return execute('doc.lists.detach', rest);
+                case 'delete': return execute('doc.lists.delete', rest);
                 case 'indent': return execute('doc.lists.indent', rest);
                 case 'outdent': return execute('doc.lists.outdent', rest);
                 case 'merge': return execute('doc.lists.merge', rest);
@@ -95,6 +96,29 @@ function dispatchIntentTool(toolName, args, execute) {
                 default: throw new Error(`Unknown action for superdoc_mutations: ${action}`);
             }
         }
+        case 'superdoc_table': {
+            const { action, ...rest } = args;
+            switch (action) {
+                case 'delete': return execute('doc.tables.delete', rest);
+                case 'set_layout': return execute('doc.tables.setLayout', rest);
+                case 'insert_row': return execute('doc.tables.insertRow', rest);
+                case 'delete_row': return execute('doc.tables.deleteRow', rest);
+                case 'set_row': return execute('doc.tables.setRowHeight', rest);
+                case 'set_row_options': return execute('doc.tables.setRowOptions', rest);
+                case 'insert_column': return execute('doc.tables.insertColumn', rest);
+                case 'delete_column': return execute('doc.tables.deleteColumn', rest);
+                case 'set_column': return execute('doc.tables.setColumnWidth', rest);
+                case 'merge_cells': return execute('doc.tables.mergeCells', rest);
+                case 'unmerge_cells': return execute('doc.tables.unmergeCells', rest);
+                case 'set_cell': return execute('doc.tables.setCellProperties', rest);
+                case 'set_cell_text': return execute('doc.tables.setCellText', rest);
+                case 'set_shading': return execute('doc.tables.setShading', rest);
+                case 'set_style_options': return execute('doc.tables.applyStyle', rest);
+                case 'set_borders': return execute('doc.tables.setBorders', rest);
+                case 'set_options': return execute('doc.tables.setTableOptions', rest);
+                default: throw new Error(`Unknown action for superdoc_table: ${action}`);
+            }
+        }
         default:
             throw new Error(`Unknown intent tool: ${toolName}`);
     }

package/dist/generated/intent-dispatch.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-dispatch.generated.d.ts","sourceRoot":"","sources":["../../src/generated/intent-dispatch.generated.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GACxE,OAAO,CAiGT"}
+{"version":3,"file":"intent-dispatch.generated.d.ts","sourceRoot":"","sources":["../../src/generated/intent-dispatch.generated.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GACxE,OAAO,CAyHT"}

package/dist/generated/intent-dispatch.generated.js

@@ -53,6 +53,7 @@ export function dispatchIntentTool(toolName, args, execute) {
                 case 'create': return execute('doc.lists.create', rest);
                 case 'attach': return execute('doc.lists.attach', rest);
                 case 'detach': return execute('doc.lists.detach', rest);
+                case 'delete': return execute('doc.lists.delete', rest);
                 case 'indent': return execute('doc.lists.indent', rest);
                 case 'outdent': return execute('doc.lists.outdent', rest);
                 case 'merge': return execute('doc.lists.merge', rest);
@@ -93,6 +94,29 @@ export function dispatchIntentTool(toolName, args, execute) {
                 default: throw new Error(`Unknown action for superdoc_mutations: ${action}`);
             }
         }
+        case 'superdoc_table': {
+            const { action, ...rest } = args;
+            switch (action) {
+                case 'delete': return execute('doc.tables.delete', rest);
+                case 'set_layout': return execute('doc.tables.setLayout', rest);
+                case 'insert_row': return execute('doc.tables.insertRow', rest);
+                case 'delete_row': return execute('doc.tables.deleteRow', rest);
+                case 'set_row': return execute('doc.tables.setRowHeight', rest);
+                case 'set_row_options': return execute('doc.tables.setRowOptions', rest);
+                case 'insert_column': return execute('doc.tables.insertColumn', rest);
+                case 'delete_column': return execute('doc.tables.deleteColumn', rest);
+                case 'set_column': return execute('doc.tables.setColumnWidth', rest);
+                case 'merge_cells': return execute('doc.tables.mergeCells', rest);
+                case 'unmerge_cells': return execute('doc.tables.unmergeCells', rest);
+                case 'set_cell': return execute('doc.tables.setCellProperties', rest);
+                case 'set_cell_text': return execute('doc.tables.setCellText', rest);
+                case 'set_shading': return execute('doc.tables.setShading', rest);
+                case 'set_style_options': return execute('doc.tables.applyStyle', rest);
+                case 'set_borders': return execute('doc.tables.setBorders', rest);
+                case 'set_options': return execute('doc.tables.setTableOptions', rest);
+                default: throw new Error(`Unknown action for superdoc_table: ${action}`);
+            }
+        }
         default:
             throw new Error(`Unknown intent tool: ${toolName}`);
     }

package/dist/index.cjs

@@ -161,6 +161,7 @@ exports.chooseTools = tools.chooseTools;
 exports.dispatchSuperDocTool = tools.dispatchSuperDocTool;
 exports.getMcpPrompt = tools.getMcpPrompt;
 exports.getSystemPrompt = tools.getSystemPrompt;
+exports.getSystemPromptForProvider = tools.getSystemPromptForProvider;
 exports.getToolCatalog = tools.getToolCatalog;
 exports.listTools = tools.listTools;
 exports.dispatchIntentTool = intentDispatch_generated.dispatchIntentTool;

package/dist/index.d.ts

@@ -77,10 +77,10 @@ export declare class SuperDocClient {
 }
 export declare function createSuperDocClient(options?: SuperDocClientOptions): SuperDocClient;
 export { getSkill, installSkill, listSkills } from './skills.js';
-export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getToolCatalog, listTools, } from './tools.js';
+export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, } from './tools.js';
+export type { AnthropicSystemPrompt, CacheStrategy, SystemPromptForProviderResult, 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';
-export type { ToolChooserInput, ToolProvider } from './tools.js';
 export type { DocOpenResult } from './generated/client.js';
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/tools.cjs

@@ -72,7 +72,7 @@ async function loadCatalog() {
     return readJson('catalog.json');
 }
 async function getToolCatalog() {
-    return loadCatalog();
+    return getCachedCatalog();
 }
 async function listTools(provider) {
     const bundle = await loadProviderBundle(provider);
@@ -88,24 +88,66 @@ async function listTools(provider) {
 /**
  * Select all intent tools for a specific provider.
  *
- * Returns all intent tools in the requested provider format.
+ * Returns all intent tools in the requested provider format. Pass
+ * `cache: true` to apply provider-specific caching markers (see
+ * {@link ToolChooserInput.cache}).
  *
  * @example
  * ```ts
- * const { tools } = await chooseTools({ provider: 'openai' });
+ * // 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 });
  * ```
  */
 async function chooseTools(input) {
     const bundle = await loadProviderBundle(input.provider);
-    const tools = Array.isArray(bundle.tools) ? bundle.tools : [];
+    const rawTools = Array.isArray(bundle.tools) ? bundle.tools : [];
+    const cacheRequested = input.cache === true;
+    const { tools, cacheStrategy } = applyCacheMarkers(rawTools, input.provider, cacheRequested);
     return {
         tools,
         meta: {
             provider: input.provider,
             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;
@@ -288,10 +330,55 @@ async function getMcpPrompt() {
         });
     }
 }
+/**
+ * Get the system prompt formatted for a specific LLM provider, with optional
+ * prompt caching applied.
+ *
+ * - **anthropic** with `cache: true`: returns a content array with
+ *   `cache_control: { type: "ephemeral" }` so the system prompt block is
+ *   cached. Pass directly as the `system` parameter on `messages.create()`.
+ * - **openai**: returns the prompt as a string. OpenAI caches prompts
+ *   ≥ 1024 tokens automatically — `cache: true` is informational only and
+ *   sets `cacheStrategy: 'automatic'`.
+ * - **vercel** / **generic**: returns the prompt as a string. Caching is
+ *   delegated to the underlying model.
+ *
+ * @example
+ * ```ts
+ * // Anthropic
+ * const sys = await getSystemPromptForProvider({ provider: 'anthropic', cache: true });
+ * await client.messages.create({ system: sys.content, tools, messages, model });
+ *
+ * // OpenAI
+ * const sys = await getSystemPromptForProvider({ provider: 'openai', cache: true });
+ * messages.unshift({ role: 'system', content: sys.content });
+ * ```
+ */
+async function getSystemPromptForProvider(input) {
+    const text = await getSystemPrompt();
+    const cacheRequested = input.cache === true;
+    if (input.provider === 'anthropic') {
+        const block = { type: 'text', text };
+        if (cacheRequested)
+            block.cache_control = { type: 'ephemeral' };
+        return {
+            provider: 'anthropic',
+            content: [block],
+            cacheStrategy: cacheRequested ? 'explicit' : 'disabled',
+        };
+    }
+    const cacheStrategy = !cacheRequested
+        ? 'disabled'
+        : input.provider === 'openai'
+            ? 'automatic'
+            : 'unsupported';
+    return { provider: input.provider, content: text, cacheStrategy };
+}
 
 exports.chooseTools = chooseTools;
 exports.dispatchSuperDocTool = dispatchSuperDocTool;
 exports.getMcpPrompt = getMcpPrompt;
 exports.getSystemPrompt = getSystemPrompt;
+exports.getSystemPromptForProvider = getSystemPromptForProvider;
 exports.getToolCatalog = getToolCatalog;
 exports.listTools = listTools;

package/dist/tools.d.ts

@@ -24,15 +24,37 @@ export declare function getToolCatalog(): Promise<ToolCatalog>;
 export declare function listTools(provider: ToolProvider): Promise<unknown[]>;
 export type ToolChooserInput = {
     provider: ToolProvider;
+    /**
+     * When `true`, applies provider-specific prompt-caching markers to the
+     * returned tools so subsequent identical requests reuse the cached prefix.
+     *
+     * Per-provider behavior:
+     * - **anthropic**: marks the last tool entry with
+     *   `cache_control: { type: "ephemeral" }`. The full tools block becomes
+     *   cacheable; cache TTL is ~5 minutes by default.
+     * - **openai**: no-op. OpenAI caches prompts ≥ 1024 tokens automatically;
+     *   the helper returns tools unchanged but still reports
+     *   `cacheStrategy: 'automatic'` so callers can rely on the indicator.
+     * - **vercel** / **generic**: pass-through. Caching depends on the
+     *   underlying model; reported as `'unsupported'`.
+     */
+    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.
+ * Returns all intent tools in the requested provider format. Pass
+ * `cache: true` to apply provider-specific caching markers (see
+ * {@link ToolChooserInput.cache}).
  *
  * @example
  * ```ts
- * const { tools } = await chooseTools({ provider: 'openai' });
+ * // 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 });
  * ```
  */
 export declare function chooseTools(input: ToolChooserInput): Promise<{
@@ -40,6 +62,7 @@ export declare function chooseTools(input: ToolChooserInput): Promise<{
     meta: {
         provider: ToolProvider;
         toolCount: number;
+        cacheStrategy: CacheStrategy;
     };
 }>;
 /**
@@ -64,5 +87,53 @@ export declare function getSystemPrompt(): Promise<string>;
  * instructions (open/save/close) suitable for MCP server `instructions`.
  */
 export declare function getMcpPrompt(): Promise<string>;
+/**
+ * Anthropic content block representation of the system prompt with optional
+ * `cache_control` for prompt caching.
+ */
+export type AnthropicSystemPrompt = Array<{
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}>;
+export type SystemPromptForProviderResult = {
+    provider: 'anthropic';
+    content: AnthropicSystemPrompt;
+    cacheStrategy: CacheStrategy;
+} | {
+    provider: 'openai' | 'vercel' | 'generic';
+    content: string;
+    cacheStrategy: CacheStrategy;
+};
+/**
+ * Get the system prompt formatted for a specific LLM provider, with optional
+ * prompt caching applied.
+ *
+ * - **anthropic** with `cache: true`: returns a content array with
+ *   `cache_control: { type: "ephemeral" }` so the system prompt block is
+ *   cached. Pass directly as the `system` parameter on `messages.create()`.
+ * - **openai**: returns the prompt as a string. OpenAI caches prompts
+ *   ≥ 1024 tokens automatically — `cache: true` is informational only and
+ *   sets `cacheStrategy: 'automatic'`.
+ * - **vercel** / **generic**: returns the prompt as a string. Caching is
+ *   delegated to the underlying model.
+ *
+ * @example
+ * ```ts
+ * // Anthropic
+ * const sys = await getSystemPromptForProvider({ provider: 'anthropic', cache: true });
+ * await client.messages.create({ system: sys.content, tools, messages, model });
+ *
+ * // OpenAI
+ * const sys = await getSystemPromptForProvider({ provider: 'openai', cache: true });
+ * messages.unshift({ role: 'system', content: sys.content });
+ * ```
+ */
+export declare function getSystemPromptForProvider(input: {
+    provider: ToolProvider;
+    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":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAWzE,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,KAAK,cAAc,GAAG;IACpB,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,KAAK,gBAAgB,GAAG;IACtB,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,cAAc,EAAE,CAAC;CAC9B,CAAC;AAmEF,wBAAsB,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAE3D;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAU1E;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;;;;;;;;GASG;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,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,CAAC,CAWD;AAiID;;;;;GAKG;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,CAuClB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAUvD;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAUpD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -68,7 +68,7 @@ async function loadCatalog() {
     return readJson('catalog.json');
 }
 export async function getToolCatalog() {
-    return loadCatalog();
+    return getCachedCatalog();
 }
 export async function listTools(provider) {
     const bundle = await loadProviderBundle(provider);
@@ -84,24 +84,66 @@ export async function listTools(provider) {
 /**
  * Select all intent tools for a specific provider.
  *
- * Returns all intent tools in the requested provider format.
+ * Returns all intent tools in the requested provider format. Pass
+ * `cache: true` to apply provider-specific caching markers (see
+ * {@link ToolChooserInput.cache}).
  *
  * @example
  * ```ts
- * const { tools } = await chooseTools({ provider: 'openai' });
+ * // 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 });
  * ```
  */
 export async function chooseTools(input) {
     const bundle = await loadProviderBundle(input.provider);
-    const tools = Array.isArray(bundle.tools) ? bundle.tools : [];
+    const rawTools = Array.isArray(bundle.tools) ? bundle.tools : [];
+    const cacheRequested = input.cache === true;
+    const { tools, cacheStrategy } = applyCacheMarkers(rawTools, input.provider, cacheRequested);
     return {
         tools,
         meta: {
             provider: input.provider,
             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;
@@ -284,3 +326,47 @@ export async function getMcpPrompt() {
         });
     }
 }
+/**
+ * Get the system prompt formatted for a specific LLM provider, with optional
+ * prompt caching applied.
+ *
+ * - **anthropic** with `cache: true`: returns a content array with
+ *   `cache_control: { type: "ephemeral" }` so the system prompt block is
+ *   cached. Pass directly as the `system` parameter on `messages.create()`.
+ * - **openai**: returns the prompt as a string. OpenAI caches prompts
+ *   ≥ 1024 tokens automatically — `cache: true` is informational only and
+ *   sets `cacheStrategy: 'automatic'`.
+ * - **vercel** / **generic**: returns the prompt as a string. Caching is
+ *   delegated to the underlying model.
+ *
+ * @example
+ * ```ts
+ * // Anthropic
+ * const sys = await getSystemPromptForProvider({ provider: 'anthropic', cache: true });
+ * await client.messages.create({ system: sys.content, tools, messages, model });
+ *
+ * // OpenAI
+ * const sys = await getSystemPromptForProvider({ provider: 'openai', cache: true });
+ * messages.unshift({ role: 'system', content: sys.content });
+ * ```
+ */
+export async function getSystemPromptForProvider(input) {
+    const text = await getSystemPrompt();
+    const cacheRequested = input.cache === true;
+    if (input.provider === 'anthropic') {
+        const block = { type: 'text', text };
+        if (cacheRequested)
+            block.cache_control = { type: 'ephemeral' };
+        return {
+            provider: 'anthropic',
+            content: [block],
+            cacheStrategy: cacheRequested ? 'explicit' : 'disabled',
+        };
+    }
+    const cacheStrategy = !cacheRequested
+        ? 'disabled'
+        : input.provider === 'openai'
+            ? 'automatic'
+            : 'unsupported';
+    return { provider: input.provider, content: text, cacheStrategy };
+}

package/package.json

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