praxis-agent 0.29.0 → 0.30.0

package/dist/application/top-level-agent-manager.js

@@ -30,6 +30,14 @@ const WORKER_RUNTIME_ENVIRONMENT = [
     'PRAXIS_MAX_OUTPUT_TOKENS',
     'PRAXIS_ANTHROPIC_VERSION',
     'PRAXIS_ANTHROPIC_WEB_SEARCH',
+    'PRAXIS_ANTHROPIC_PROMPT_CACHING',
+    'PRAXIS_ANTHROPIC_PROMPT_CACHE_TTL',
+    'DISABLE_PROMPT_CACHING',
+    'DISABLE_PROMPT_CACHING_HAIKU',
+    'DISABLE_PROMPT_CACHING_SONNET',
+    'DISABLE_PROMPT_CACHING_OPUS',
+    'ENABLE_PROMPT_CACHING_1H',
+    'FORCE_PROMPT_CACHING_5M',
     'PRAXIS_CONTEXT_WINDOW_TOKENS',
     'PRAXIS_CONTEXT_RESERVE_TOKENS',
     'PRAXIS_PRICING_JSON',

package/dist/cli-runtime.js

@@ -39,6 +39,7 @@ import { writeFileAtomically } from './platform/atomic-write.js';
 import { detectInstalledClaudeVersion } from './platform/claude-version.js';
 import { redactSensitiveText, sensitiveEnvironmentValues, } from './platform/sensitive-data.js';
 import { AnthropicCompatibleProvider } from './providers/anthropic-compatible.js';
+import { createAnthropicPromptCachePolicyResolver } from './providers/anthropic-prompt-cache.js';
 import { FallbackModelProvider } from './providers/fallback-provider.js';
 import { OpenAICompatibleProvider } from './providers/openai-compatible.js';
 import { parseContextEnvironment, parseProviderEnvironment, } from './providers/environment.js';
@@ -89,34 +90,37 @@ function fileResourceHeaders(environment, providerEnvironment, credential) {
             : {}),
     };
 }
-function createProviderForModel(apiKey, providerEnvironment, context, controls, explicitThinkingControls) {
+function createProviderForModel({ apiKey, environment, dataPlane, provider, context, controls, explicitThinkingControls, }) {
+    const resolvePromptCachePolicy = createAnthropicPromptCachePolicyResolver(environment, dataPlane);
     return (selectedModel) => {
         const providerOptions = {
             apiKey,
             model: selectedModel,
-            baseUrl: providerEnvironment.baseUrl,
+            baseUrl: provider.baseUrl,
             ...('contextWindowTokens' in context
                 ? { contextWindowTokens: context.contextWindowTokens }
                 : {}),
         };
-        return providerEnvironment.provider === 'anthropic'
+        return provider.provider === 'anthropic'
             ? new AnthropicCompatibleProvider({
                 ...providerOptions,
+                promptCaching: resolvePromptCachePolicy({
+                    baseUrl: provider.baseUrl,
+                    model: selectedModel,
+                }),
                 thinking: {
                     mode: controls.thinking ?? 'enabled',
                     ...(controls.maxThinkingTokens === undefined
                         ? {}
                         : { maxTokens: controls.maxThinkingTokens }),
                 },
-                ...('maxOutputTokens' in providerEnvironment
-                    ? { maxOutputTokens: providerEnvironment.maxOutputTokens }
-                    : {}),
-                ...('anthropicVersion' in providerEnvironment
-                    ? { anthropicVersion: providerEnvironment.anthropicVersion }
+                ...('maxOutputTokens' in provider
+                    ? { maxOutputTokens: provider.maxOutputTokens }
                     : {}),
-                ...('webSearch' in providerEnvironment
-                    ? { webSearch: providerEnvironment.webSearch }
+                ...('anthropicVersion' in provider
+                    ? { anthropicVersion: provider.anthropicVersion }
                     : {}),
+                ...('webSearch' in provider ? { webSearch: provider.webSearch } : {}),
             })
             : new OpenAICompatibleProvider({
                 ...providerOptions,
@@ -245,6 +249,8 @@ Provider environment:
   PRAXIS_PROVIDER=openai|anthropic, PRAXIS_API_KEY, PRAXIS_MODEL
   PRAXIS_BASE_URL, PRAXIS_MAX_OUTPUT_TOKENS, PRAXIS_ANTHROPIC_VERSION
   PRAXIS_ANTHROPIC_WEB_SEARCH=true|false
+  PRAXIS_ANTHROPIC_PROMPT_CACHING=true|false
+  PRAXIS_ANTHROPIC_PROMPT_CACHE_TTL=5m|1h
   PRAXIS_CONTEXT_WINDOW_TOKENS, PRAXIS_CONTEXT_RESERVE_TOKENS
 `;
 const AGENTS_HELP = `Usage: praxis agents [options]
@@ -837,7 +843,15 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         if (!providerEnvironment) {
             throw new Error('Provider environment is unavailable');
         }
-        providerForModel = createProviderForModel(apiKey, providerEnvironment, context, cli, controls);
+        providerForModel = createProviderForModel({
+            apiKey,
+            environment: runtimeEnvironment,
+            dataPlane,
+            provider: providerEnvironment,
+            context,
+            controls: cli,
+            explicitThinkingControls: controls,
+        });
         const createProvider = providerForModel;
         providerForMainModel = (primaryModel) => {
             const models = [primaryModel, ...(cli.fallbackModels ?? [])].filter((candidate, index, all) => all.indexOf(candidate) === index);
@@ -1705,7 +1719,16 @@ const createDefaultAutoModeCritic = async ({ model, dataPlane, configRoot, state
     if (!apiKey || !selectedModel) {
         throw new Error('PRAXIS_API_KEY and a model (--model or PRAXIS_MODEL) are required');
     }
-    return createProviderForModel(apiKey, parseProviderEnvironment(process.env), parseContextEnvironment(process.env), {}, {})(selectedModel);
+    const providerEnvironment = parseProviderEnvironment(process.env);
+    return createProviderForModel({
+        apiKey,
+        environment: process.env,
+        dataPlane: resolvedDataPlane,
+        provider: providerEnvironment,
+        context: parseContextEnvironment(process.env),
+        controls: {},
+        explicitThinkingControls: {},
+    })(selectedModel);
 };
 const defaultPluginEvalRuntimeFactory = {
     create: async (options) => {
@@ -1805,7 +1828,16 @@ const defaultPluginEvalJudge = {
         const apiKey = environment.PRAXIS_API_KEY;
         if (!apiKey)
             throw new Error('PRAXIS_API_KEY is required for paid eval graders');
-        const provider = createProviderForModel(apiKey, parseProviderEnvironment(environment), parseContextEnvironment(environment), {}, {})(model);
+        const providerEnvironment = parseProviderEnvironment(environment);
+        const provider = createProviderForModel({
+            apiKey,
+            environment,
+            dataPlane: resolveDataPlane(environment),
+            provider: providerEnvironment,
+            context: parseContextEnvironment(environment),
+            controls: {},
+            explicitThinkingControls: {},
+        })(model);
         const prompt = `You are an eval judge. Return only JSON matching {"passed":boolean,"explanation":string}.
 
 Criteria:

package/dist/mcp/claude-mcp-tools.js

@@ -706,10 +706,11 @@ export class ClaudeMcpToolRegistry {
     definitions() {
         return [
             ...this.options.base.definitions(),
+            ...(this.resourceServers.size > 0 ? MCP_RESOURCE_TOOL_DEFINITIONS : []),
             ...[...this.connectedTools.entries()]
                 .filter(([name]) => !this.reservedTools.has(name))
+                .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
                 .map(([, tool]) => tool.definition),
-            ...(this.resourceServers.size > 0 ? MCP_RESOURCE_TOOL_DEFINITIONS : []),
         ];
     }
     schedulingPolicy(call) {

package/dist/providers/anthropic-compatible.d.ts

@@ -1,4 +1,5 @@
 import { type ModelProvider, type ModelRequest, type ModelStreamEvent, type ModelThinkingConfig } from '../core/runtime.js';
+import { type AnthropicPromptCachePolicy } from './anthropic-prompt-cache.js';
 export interface AnthropicCompatibleProviderOptions {
     baseUrl: string;
     apiKey: string;
@@ -6,6 +7,7 @@ export interface AnthropicCompatibleProviderOptions {
     maxOutputTokens?: number;
     anthropicVersion?: string;
     webSearch?: boolean;
+    promptCaching?: AnthropicPromptCachePolicy;
     contextWindowTokens?: number;
     thinking?: ModelThinkingConfig;
     maxStreamBufferBytes?: number;
@@ -29,6 +31,7 @@ export declare class AnthropicCompatibleProvider implements ModelProvider {
     private readonly maxToolMetadataBytes;
     private readonly maxErrorBodyBytes;
     private readonly thinking;
+    private readonly promptCaching;
     constructor(options: AnthropicCompatibleProviderOptions);
     complete(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
 }

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,10 @@ 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;
@@ -583,6 +624,7 @@ export class AnthropicCompatibleProvider {
     maxToolMetadataBytes;
     maxErrorBodyBytes;
     thinking;
+    promptCaching;
     constructor(options) {
         this.options = options;
         if (options.contextWindowTokens !== undefined) {
@@ -615,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;
@@ -646,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: {
@@ -664,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: [
@@ -682,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.29.0",
+  "version": "0.30.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",