@mmnto/totem 1.12.0 → 1.14.0

package/dist/config-schema.d.ts

@@ -109,6 +109,30 @@ export declare const ShellOrchestratorSchema: z.ZodObject<{
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"shell">;
     /** Shell command with {file} and {model} placeholders */
     command: z.ZodString;
@@ -119,6 +143,8 @@ export declare const ShellOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "shell";
     command: string;
@@ -126,6 +152,8 @@ export declare const ShellOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>;
 export declare const GeminiOrchestratorSchema: z.ZodObject<{
     /** Default model name if --model is not passed */
@@ -136,6 +164,30 @@ export declare const GeminiOrchestratorSchema: z.ZodObject<{
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"gemini">;
 }, "strip", z.ZodTypeAny, {
     provider: "gemini";
@@ -143,12 +195,16 @@ export declare const GeminiOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "gemini";
     defaultModel?: string | undefined;
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>;
 export declare const AnthropicOrchestratorSchema: z.ZodObject<{
     /** Default model name if --model is not passed */
@@ -159,6 +215,30 @@ export declare const AnthropicOrchestratorSchema: z.ZodObject<{
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"anthropic">;
 }, "strip", z.ZodTypeAny, {
     provider: "anthropic";
@@ -166,12 +246,16 @@ export declare const AnthropicOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "anthropic";
     defaultModel?: string | undefined;
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>;
 export declare const OpenAIOrchestratorSchema: z.ZodObject<{
     /** Default model name if --model is not passed */
@@ -182,6 +266,30 @@ export declare const OpenAIOrchestratorSchema: z.ZodObject<{
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"openai">;
     /** Optional base URL for OpenAI-compatible servers (Ollama, LM Studio, etc.) */
     baseUrl: z.ZodOptional<z.ZodString>;
@@ -192,6 +300,8 @@ export declare const OpenAIOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "openai";
     baseUrl?: string | undefined;
@@ -199,6 +309,8 @@ export declare const OpenAIOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>;
 export declare const OllamaOrchestratorSchema: z.ZodObject<{
     /** Default model name if --model is not passed */
@@ -209,6 +321,30 @@ export declare const OllamaOrchestratorSchema: z.ZodObject<{
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"ollama">;
     /** Base URL for the Ollama server */
     baseUrl: z.ZodDefault<z.ZodString>;
@@ -221,6 +357,8 @@ export declare const OllamaOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
     numCtx?: number | undefined;
 }, {
     provider: "ollama";
@@ -229,6 +367,8 @@ export declare const OllamaOrchestratorSchema: z.ZodObject<{
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
     numCtx?: number | undefined;
 }>;
 export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.ZodObject<{
@@ -240,6 +380,30 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"shell">;
     /** Shell command with {file} and {model} placeholders */
     command: z.ZodString;
@@ -250,6 +414,8 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "shell";
     command: string;
@@ -257,6 +423,8 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>, z.ZodObject<{
     /** Default model name if --model is not passed */
     defaultModel: z.ZodOptional<z.ZodString>;
@@ -266,6 +434,30 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"gemini">;
 }, "strip", z.ZodTypeAny, {
     provider: "gemini";
@@ -273,12 +465,16 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "gemini";
     defaultModel?: string | undefined;
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>, z.ZodObject<{
     /** Default model name if --model is not passed */
     defaultModel: z.ZodOptional<z.ZodString>;
@@ -288,6 +484,30 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"anthropic">;
 }, "strip", z.ZodTypeAny, {
     provider: "anthropic";
@@ -295,12 +515,16 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "anthropic";
     defaultModel?: string | undefined;
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>, z.ZodObject<{
     /** Default model name if --model is not passed */
     defaultModel: z.ZodOptional<z.ZodString>;
@@ -310,6 +534,30 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"openai">;
     /** Optional base URL for OpenAI-compatible servers (Ollama, LM Studio, etc.) */
     baseUrl: z.ZodOptional<z.ZodString>;
@@ -320,6 +568,8 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }, {
     provider: "openai";
     baseUrl?: string | undefined;
@@ -327,6 +577,8 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
 }>, z.ZodObject<{
     /** Default model name if --model is not passed */
     defaultModel: z.ZodOptional<z.ZodString>;
@@ -336,6 +588,30 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
     cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+     * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+     * `systemPrompt` segments will be marked with cache_control directives to
+     * reduce input-token cost on repeat invocations within the TTL window.
+     * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+     * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+     * orthogonal response-level cache (mmnto/totem#52, closed) at
+     * `.totem/cache/<command>-<hash>.json`.
+     */
+    enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+     * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+     * — 2x write cost, ~10% read cost). Only consulted when
+     * `enableContextCaching` is true. Defaults to 300 when omitted.
+     *
+     * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+     * fail fast at config load instead of silently falling through to 5m at
+     * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+     * Anthropic docs verified for both values:
+     * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
     provider: z.ZodLiteral<"ollama">;
     /** Base URL for the Ollama server */
     baseUrl: z.ZodDefault<z.ZodString>;
@@ -348,6 +624,8 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
     numCtx?: number | undefined;
 }, {
     provider: "ollama";
@@ -356,6 +634,8 @@ export declare const OrchestratorSchema: z.ZodDiscriminatedUnion<"provider", [z.
     fallbackModel?: string | undefined;
     overrides?: Record<string, string> | undefined;
     cacheTtls?: Record<string, number> | undefined;
+    enableContextCaching?: boolean | undefined;
+    cacheTTL?: 300 | 3600 | undefined;
     numCtx?: number | undefined;
 }>]>;
 export declare const GarbageCollectionSchema: z.ZodObject<{
@@ -462,6 +742,30 @@ export declare const TotemConfigSchema: z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
         cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        /**
+         * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+         * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+         * `systemPrompt` segments will be marked with cache_control directives to
+         * reduce input-token cost on repeat invocations within the TTL window.
+         * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+         * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+         * orthogonal response-level cache (mmnto/totem#52, closed) at
+         * `.totem/cache/<command>-<hash>.json`.
+         */
+        enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+         * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+         * — 2x write cost, ~10% read cost). Only consulted when
+         * `enableContextCaching` is true. Defaults to 300 when omitted.
+         *
+         * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+         * fail fast at config load instead of silently falling through to 5m at
+         * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+         * Anthropic docs verified for both values:
+         * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+         */
+        cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
         provider: z.ZodLiteral<"shell">;
         /** Shell command with {file} and {model} placeholders */
         command: z.ZodString;
@@ -472,6 +776,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }, {
         provider: "shell";
         command: string;
@@ -479,6 +785,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }>, z.ZodObject<{
         /** Default model name if --model is not passed */
         defaultModel: z.ZodOptional<z.ZodString>;
@@ -488,6 +796,30 @@ export declare const TotemConfigSchema: z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
         cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        /**
+         * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+         * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+         * `systemPrompt` segments will be marked with cache_control directives to
+         * reduce input-token cost on repeat invocations within the TTL window.
+         * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+         * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+         * orthogonal response-level cache (mmnto/totem#52, closed) at
+         * `.totem/cache/<command>-<hash>.json`.
+         */
+        enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+         * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+         * — 2x write cost, ~10% read cost). Only consulted when
+         * `enableContextCaching` is true. Defaults to 300 when omitted.
+         *
+         * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+         * fail fast at config load instead of silently falling through to 5m at
+         * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+         * Anthropic docs verified for both values:
+         * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+         */
+        cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
         provider: z.ZodLiteral<"gemini">;
     }, "strip", z.ZodTypeAny, {
         provider: "gemini";
@@ -495,12 +827,16 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }, {
         provider: "gemini";
         defaultModel?: string | undefined;
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }>, z.ZodObject<{
         /** Default model name if --model is not passed */
         defaultModel: z.ZodOptional<z.ZodString>;
@@ -510,6 +846,30 @@ export declare const TotemConfigSchema: z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
         cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        /**
+         * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+         * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+         * `systemPrompt` segments will be marked with cache_control directives to
+         * reduce input-token cost on repeat invocations within the TTL window.
+         * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+         * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+         * orthogonal response-level cache (mmnto/totem#52, closed) at
+         * `.totem/cache/<command>-<hash>.json`.
+         */
+        enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+         * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+         * — 2x write cost, ~10% read cost). Only consulted when
+         * `enableContextCaching` is true. Defaults to 300 when omitted.
+         *
+         * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+         * fail fast at config load instead of silently falling through to 5m at
+         * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+         * Anthropic docs verified for both values:
+         * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+         */
+        cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
         provider: z.ZodLiteral<"anthropic">;
     }, "strip", z.ZodTypeAny, {
         provider: "anthropic";
@@ -517,12 +877,16 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }, {
         provider: "anthropic";
         defaultModel?: string | undefined;
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }>, z.ZodObject<{
         /** Default model name if --model is not passed */
         defaultModel: z.ZodOptional<z.ZodString>;
@@ -532,6 +896,30 @@ export declare const TotemConfigSchema: z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
         cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        /**
+         * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+         * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+         * `systemPrompt` segments will be marked with cache_control directives to
+         * reduce input-token cost on repeat invocations within the TTL window.
+         * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+         * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+         * orthogonal response-level cache (mmnto/totem#52, closed) at
+         * `.totem/cache/<command>-<hash>.json`.
+         */
+        enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+         * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+         * — 2x write cost, ~10% read cost). Only consulted when
+         * `enableContextCaching` is true. Defaults to 300 when omitted.
+         *
+         * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+         * fail fast at config load instead of silently falling through to 5m at
+         * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+         * Anthropic docs verified for both values:
+         * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+         */
+        cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
         provider: z.ZodLiteral<"openai">;
         /** Optional base URL for OpenAI-compatible servers (Ollama, LM Studio, etc.) */
         baseUrl: z.ZodOptional<z.ZodString>;
@@ -542,6 +930,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }, {
         provider: "openai";
         baseUrl?: string | undefined;
@@ -549,6 +939,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     }>, z.ZodObject<{
         /** Default model name if --model is not passed */
         defaultModel: z.ZodOptional<z.ZodString>;
@@ -558,6 +950,30 @@ export declare const TotemConfigSchema: z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Per-command cache TTLs in seconds (e.g., { 'triage': 3600, 'shield': 0 }) */
         cacheTtls: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        /**
+         * Enable provider-native prompt caching (mmnto/totem#1291 Proposal 217). When true and
+         * the provider supports it (Anthropic in 1.15.0, Gemini in 1.16.0+), persistent
+         * `systemPrompt` segments will be marked with cache_control directives to
+         * reduce input-token cost on repeat invocations within the TTL window.
+         * Defaults to undefined (off) — opt-in for 1.15.0 to avoid surprising existing
+         * users mid-cycle. Distinct from `cacheTtls` above, which controls the
+         * orthogonal response-level cache (mmnto/totem#52, closed) at
+         * `.totem/cache/<command>-<hash>.json`.
+         */
+        enableContextCaching: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * Prompt cache TTL in seconds (mmnto/totem#1291). Anthropic supports exactly
+         * two values today: 300 (5m, default ephemeral) and 3600 (1h, extended cache
+         * — 2x write cost, ~10% read cost). Only consulted when
+         * `enableContextCaching` is true. Defaults to 300 when omitted.
+         *
+         * Constrained to literals at parse time so invalid TTLs (e.g. 600, 1800)
+         * fail fast at config load instead of silently falling through to 5m at
+         * provider-invocation time. Caught by CodeRabbit on PR #1292 review.
+         * Anthropic docs verified for both values:
+         * https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+         */
+        cacheTTL: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<300>, z.ZodLiteral<3600>]>>;
         provider: z.ZodLiteral<"ollama">;
         /** Base URL for the Ollama server */
         baseUrl: z.ZodDefault<z.ZodString>;
@@ -570,6 +986,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
         numCtx?: number | undefined;
     }, {
         provider: "ollama";
@@ -578,6 +996,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
         numCtx?: number | undefined;
     }>]>, {
         provider: "shell";
@@ -586,18 +1006,24 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "gemini";
         defaultModel?: string | undefined;
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "anthropic";
         defaultModel?: string | undefined;
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "openai";
         baseUrl?: string | undefined;
@@ -605,6 +1031,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "ollama";
         baseUrl: string;
@@ -612,6 +1040,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
         numCtx?: number | undefined;
     }, unknown>>;
     /** Optional: override the .totem/ directory path */
@@ -744,18 +1174,24 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "gemini";
         defaultModel?: string | undefined;
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "anthropic";
         defaultModel?: string | undefined;
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "openai";
         baseUrl?: string | undefined;
@@ -763,6 +1199,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
     } | {
         provider: "ollama";
         baseUrl: string;
@@ -770,6 +1208,8 @@ export declare const TotemConfigSchema: z.ZodObject<{
         fallbackModel?: string | undefined;
         overrides?: Record<string, string> | undefined;
         cacheTtls?: Record<string, number> | undefined;
+        enableContextCaching?: boolean | undefined;
+        cacheTTL?: 300 | 3600 | undefined;
         numCtx?: number | undefined;
     } | undefined;
     docs?: {