praxis-agent 0.28.0 → 0.30.0

package/dist/providers/anthropic-compatible.js

@@ -1,5 +1,6 @@
 import { ModelProviderError, } from '../core/runtime.js';
 import { transportFailureKind } from './provider-errors.js';
+import { createAnthropicPromptCachePolicyResolver, } from './anthropic-prompt-cache.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -451,6 +452,34 @@ function parseSseEvent(data, state, maxToolArgumentsBytes, maxToolCallsPerRespon
     }
     return [];
 }
+const ANTHROPIC_CACHE_LOOKBACK_BLOCKS = 20;
+function cacheControl(ttl) {
+    return {
+        type: 'ephemeral',
+        ...(ttl === '1h' ? { ttl } : {}),
+    };
+}
+function markLatestCacheableMessageBlock(messages, control) {
+    let inspectedBlocks = 0;
+    for (let messageIndex = messages.length - 1; messageIndex >= 0; messageIndex--) {
+        const content = messages[messageIndex]?.content;
+        if (!content)
+            continue;
+        for (let blockIndex = content.length - 1; blockIndex >= 0; blockIndex--) {
+            if (inspectedBlocks >= ANTHROPIC_CACHE_LOOKBACK_BLOCKS)
+                return;
+            inspectedBlocks += 1;
+            const block = content[blockIndex];
+            if (!block ||
+                block.type === 'thinking' ||
+                block.type === 'redacted_thinking') {
+                continue;
+            }
+            content[blockIndex] = { ...block, cache_control: control };
+            return;
+        }
+    }
+}
 function serializeMediaContent(message) {
     const blocks = message.contentBlocks
         ? [...message.contentBlocks]
@@ -481,9 +510,10 @@ function serializeMediaContent(message) {
             },
         });
 }
-function serializeMessages(messages) {
+function serializeMessages(messages, stableSystemMessageCount, promptCaching) {
     const system = [];
     const serialized = [];
+    let systemIndex = 0;
     const append = (role, content) => {
         if (content.length === 0)
             return;
@@ -495,7 +525,15 @@ function serializeMessages(messages) {
     };
     for (const message of messages) {
         if (message.role === 'system') {
-            system.push(message.content);
+            const block = {
+                type: 'text',
+                text: `${systemIndex === 0 ? '' : '\n\n'}${message.content}`,
+                ...(promptCaching && systemIndex + 1 === stableSystemMessageCount
+                    ? { cache_control: promptCaching }
+                    : {}),
+            };
+            system.push(block);
+            systemIndex += 1;
             continue;
         }
         if (message.role === 'user') {
@@ -553,7 +591,24 @@ function serializeMessages(messages) {
         }
         append('assistant', content);
     }
-    return { system: system.join('\n\n'), messages: serialized };
+    if (promptCaching) {
+        markLatestCacheableMessageBlock(serialized, promptCaching);
+    }
+    return { system, messages: serialized };
+}
+function validateStableSystemPrefix(request) {
+    const count = request.stableSystemMessageCount;
+    if (count === undefined)
+        return;
+    const systemMessageCount = request.messages.filter((message) => message.role === 'system').length;
+    if (!Number.isSafeInteger(count) || count < 0 || count > systemMessageCount) {
+        throw new Error('Stable system message count must identify a valid system-message prefix');
+    }
+    if (request.messages
+        .slice(0, count)
+        .some((message) => message.role !== 'system')) {
+        throw new Error('Stable system message count must identify a valid system-message prefix');
+    }
 }
 export class AnthropicCompatibleProvider {
     options;
@@ -569,6 +624,7 @@ export class AnthropicCompatibleProvider {
     maxToolMetadataBytes;
     maxErrorBodyBytes;
     thinking;
+    promptCaching;
     constructor(options) {
         this.options = options;
         if (options.contextWindowTokens !== undefined) {
@@ -601,6 +657,16 @@ export class AnthropicCompatibleProvider {
             terminalReasons: true,
         };
         this.thinking = validateThinking(options.thinking);
+        const promptCaching = options.promptCaching === false
+            ? undefined
+            : (options.promptCaching ??
+                createAnthropicPromptCachePolicyResolver({}, 'native')({
+                    baseUrl: options.baseUrl,
+                    model: options.model,
+                }));
+        this.promptCaching = promptCaching
+            ? cacheControl(promptCaching.ttl)
+            : undefined;
         this.anthropicVersion = options.anthropicVersion ?? '2023-06-01';
         this.maxStreamBufferBytes = options.maxStreamBufferBytes ?? 1024 * 1024;
         this.maxToolArgumentsBytes = options.maxToolArgumentsBytes ?? 1024 * 1024;
@@ -609,6 +675,7 @@ export class AnthropicCompatibleProvider {
         this.maxErrorBodyBytes = options.maxErrorBodyBytes ?? 64 * 1024;
     }
     async *complete(request) {
+        validateStableSystemPrefix(request);
         if (request.webSearch && !this.capabilities.webSearch) {
             throw new Error('Provider does not support web search');
         }
@@ -631,7 +698,8 @@ export class AnthropicCompatibleProvider {
                 ? ['interleaved-thinking-2025-05-14']
                 : []),
         ].filter((beta, index, all) => all.indexOf(beta) === index);
-        const serialized = serializeMessages(request.messages);
+        const serialized = serializeMessages(request.messages, request.stableSystemMessageCount, this.promptCaching);
+        const requestTools = request.tools;
         const requestInit = {
             method: 'POST',
             headers: {
@@ -649,7 +717,7 @@ export class AnthropicCompatibleProvider {
                 ...(request.effort
                     ? { output_config: { effort: request.effort } }
                     : {}),
-                ...(serialized.system ? { system: serialized.system } : {}),
+                ...(serialized.system.length ? { system: serialized.system } : {}),
                 ...(request.webSearch
                     ? {
                         tools: [
@@ -667,12 +735,15 @@ export class AnthropicCompatibleProvider {
                         ],
                         tool_choice: { type: 'tool', name: 'web_search' },
                     }
-                    : request.tools?.length
+                    : requestTools?.length
                         ? {
-                            tools: request.tools.map((tool) => ({
+                            tools: requestTools.map((tool, index) => ({
                                 name: tool.name,
                                 description: tool.description,
                                 input_schema: tool.inputSchema,
+                                ...(this.promptCaching && index === requestTools.length - 1
+                                    ? { cache_control: this.promptCaching }
+                                    : {}),
                             })),
                         }
                         : {}),

package/dist/providers/anthropic-prompt-cache.d.ts

@@ -0,0 +1,11 @@
+export type AnthropicPromptCachePolicy = false | {
+    ttl: '5m' | '1h';
+};
+export interface AnthropicPromptCacheTarget {
+    baseUrl: string;
+    model: string;
+}
+/** Captures prompt-cache configuration once, then resolves a policy for each
+ * Anthropic model adapter created during the same session. */
+export declare function createAnthropicPromptCachePolicyResolver(environment: NodeJS.ProcessEnv, dataPlane: 'native' | 'claude'): (target: AnthropicPromptCacheTarget) => AnthropicPromptCachePolicy;
+//# sourceMappingURL=anthropic-prompt-cache.d.ts.map

package/dist/providers/anthropic-prompt-cache.js

@@ -0,0 +1,58 @@
+function officialAnthropicEndpoint(baseUrl) {
+    try {
+        return new URL(baseUrl).hostname === 'api.anthropic.com';
+    }
+    catch {
+        return false;
+    }
+}
+function modelFamily(model) {
+    const normalized = model.toLowerCase();
+    if (normalized.includes('haiku'))
+        return 'haiku';
+    if (normalized.includes('sonnet'))
+        return 'sonnet';
+    if (normalized.includes('opus'))
+        return 'opus';
+    return undefined;
+}
+/** Captures prompt-cache configuration once, then resolves a policy for each
+ * Anthropic model adapter created during the same session. */
+export function createAnthropicPromptCachePolicyResolver(environment, dataPlane) {
+    const praxisEnabled = environment.PRAXIS_ANTHROPIC_PROMPT_CACHING;
+    if (praxisEnabled !== undefined &&
+        praxisEnabled !== 'true' &&
+        praxisEnabled !== 'false') {
+        throw new Error('PRAXIS_ANTHROPIC_PROMPT_CACHING must be true or false');
+    }
+    const praxisTtl = environment.PRAXIS_ANTHROPIC_PROMPT_CACHE_TTL;
+    if (praxisTtl !== undefined && praxisTtl !== '5m' && praxisTtl !== '1h') {
+        throw new Error('PRAXIS_ANTHROPIC_PROMPT_CACHE_TTL must be 5m or 1h');
+    }
+    if (praxisEnabled === 'false' && praxisTtl !== undefined) {
+        throw new Error('PRAXIS_ANTHROPIC_PROMPT_CACHE_TTL cannot be set when prompt caching is false');
+    }
+    const claudeCompatibility = dataPlane === 'claude';
+    const disableAll = environment.DISABLE_PROMPT_CACHING === '1';
+    const disabledFamilies = new Set(['haiku', 'sonnet', 'opus'].filter((family) => environment[`DISABLE_PROMPT_CACHING_${family.toUpperCase()}`] === '1'));
+    const forceFiveMinutes = environment.FORCE_PROMPT_CACHING_5M === '1';
+    const enableOneHour = environment.ENABLE_PROMPT_CACHING_1H === '1';
+    return ({ baseUrl, model }) => {
+        if (claudeCompatibility) {
+            const family = modelFamily(model);
+            if (disableAll || (family && disabledFamilies.has(family)))
+                return false;
+        }
+        if (praxisEnabled === 'false')
+            return false;
+        if (claudeCompatibility && forceFiveMinutes)
+            return { ttl: '5m' };
+        if (claudeCompatibility && enableOneHour)
+            return { ttl: '1h' };
+        if (praxisEnabled === 'true' || praxisTtl !== undefined) {
+            return { ttl: praxisTtl ?? '5m' };
+        }
+        return officialAnthropicEndpoint(baseUrl) ? { ttl: '5m' } : false;
+    };
+}
+//# sourceMappingURL=anthropic-prompt-cache.js.map

package/dist/providers/environment.js

@@ -1,3 +1,4 @@
+import { createAnthropicPromptCachePolicyResolver } from './anthropic-prompt-cache.js';
 export function parseProviderEnvironment(environment) {
     const provider = environment.PRAXIS_PROVIDER ?? 'openai';
     if (provider !== 'openai' && provider !== 'anthropic') {
@@ -29,6 +30,17 @@ export function parseProviderEnvironment(environment) {
     if (provider === 'openai' && webSearch !== undefined) {
         throw new Error('PRAXIS_ANTHROPIC_WEB_SEARCH requires PRAXIS_PROVIDER=anthropic');
     }
+    for (const name of [
+        'PRAXIS_ANTHROPIC_PROMPT_CACHING',
+        'PRAXIS_ANTHROPIC_PROMPT_CACHE_TTL',
+    ]) {
+        if (provider === 'openai' && environment[name] !== undefined) {
+            throw new Error(`${name} requires PRAXIS_PROVIDER=anthropic`);
+        }
+    }
+    if (provider === 'anthropic') {
+        createAnthropicPromptCachePolicyResolver(environment, 'native');
+    }
     return {
         provider,
         baseUrl: environment.PRAXIS_BASE_URL ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",