diff --git a/docs/concepts/session-pruning.md b/docs/concepts/session-pruning.md index fdd5080e0fe..c49fe537042 100644 --- a/docs/concepts/session-pruning.md +++ b/docs/concepts/session-pruning.md @@ -15,6 +15,17 @@ Session pruning trims **old tool results** from the in-memory context right befo - For best results, match `ttl` to your model `cacheControlTtl`. - After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again. +## Smart defaults (Anthropic) +- **OAuth or setup-token** profiles: enable `cache-ttl` pruning and set heartbeat to `1h`. +- **API key** profiles: enable `cache-ttl` pruning, set heartbeat to `30m`, and default `cacheControlTtl` to `1h` on Anthropic models. +- If you set any of these values explicitly, Clawdbot does **not** override them. + +## What this improves (cost + cache behavior) +- **Why prune:** Anthropic prompt caching only applies within the TTL. If a session goes idle past the TTL, the next request re-caches the full prompt unless you trim it first. +- **What gets cheaper:** pruning reduces the **cacheWrite** size for that first request after the TTL expires. +- **Why the TTL reset matters:** once pruning runs, the cache window resets, so follow‑up requests can reuse the freshly cached prompt instead of re-caching the full history again. +- **What it does not do:** pruning doesn’t add tokens or “double” costs; it only changes what gets cached on that first post‑TTL request. + ## What can be pruned - Only `toolResult` messages. - User + assistant messages are **never** modified. diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index b6fd7d141e5..dafbc5830ca 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1600,7 +1600,7 @@ Notes / current limitations: - After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again. - For best results, match `contextPruning.ttl` to the model `cacheControlTtl` you set in `agents.defaults.models.*.params`. -Default (off): +Default (off, unless Anthropic auth profiles are detected): ```json5 { agents: { defaults: { contextPruning: { mode: "off" } } } diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md index 639ee23cbc7..3b882f59239 100644 --- a/docs/gateway/heartbeat.md +++ b/docs/gateway/heartbeat.md @@ -10,7 +10,7 @@ surface anything that needs attention without spamming you. ## Quick start (beginner) -1. Leave heartbeats enabled (default is `30m`) or set your own cadence. +1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence. 2. Create a tiny `HEARTBEAT.md` checklist in the agent workspace (optional but recommended). 3. Decide where heartbeat messages should go (`target: "last"` is the default). 4. Optional: enable heartbeat reasoning delivery for transparency. @@ -33,7 +33,7 @@ Example config: ## Defaults -- Interval: `30m` (set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable). +- Interval: `30m` (or `1h` when Anthropic OAuth/setup-token is the detected auth mode). Set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable. - Prompt body (configurable via `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` - The heartbeat prompt is sent **verbatim** as the user message. The system diff --git a/docs/token-use.md b/docs/token-use.md index c27412ff741..f73bbb97027 100644 --- a/docs/token-use.md +++ b/docs/token-use.md @@ -65,6 +65,41 @@ These are **USD per 1M tokens** for `input`, `output`, `cacheRead`, and `cacheWrite`. If pricing is missing, Clawdbot shows tokens only. OAuth tokens never show dollar cost. +## Cache TTL and pruning impact + +Provider prompt caching only applies within the cache TTL window. Clawdbot can +optionally run **cache-ttl pruning**: it prunes the session once the cache TTL +has expired, then resets the cache window so subsequent requests can re-use the +freshly cached context instead of re-caching the full history. This keeps cache +write costs lower when a session goes idle past the TTL. + +Configure it in [Gateway configuration](/gateway/configuration) and see the +behavior details in [Session pruning](/concepts/session-pruning). + +Heartbeat can keep the cache **warm** across idle gaps. If your model cache TTL +is `1h`, setting the heartbeat interval just under that (e.g., `55m`) can avoid +re-caching the full prompt, reducing cache write costs. + +For Anthropic API pricing, cache reads are significantly cheaper than input +tokens, while cache writes are billed at a higher multiplier. See Anthropic’s +prompt caching pricing for the latest rates and TTL multipliers: +https://docs.anthropic.com/docs/build-with-claude/prompt-caching + +### Example: keep 1h cache warm with heartbeat + +```yaml +agents: + defaults: + model: + primary: "anthropic/claude-opus-4-5" + models: + "anthropic/claude-opus-4-5": + params: + cacheControlTtl: "1h" + heartbeat: + every: "55m" +``` + ## Tips for reducing token pressure - Use `/compact` to summarize long sessions. diff --git a/src/config/config.pruning-defaults.test.ts b/src/config/config.pruning-defaults.test.ts index 8bc4d7e20b2..0eadd862aee 100644 --- a/src/config/config.pruning-defaults.test.ts +++ b/src/config/config.pruning-defaults.test.ts @@ -5,6 +5,10 @@ import { withTempHome } from "./test-helpers.js"; describe("config pruning defaults", () => { it("does not enable contextPruning by default", async () => { + const prevApiKey = process.env.ANTHROPIC_API_KEY; + const prevOauthToken = process.env.ANTHROPIC_OAUTH_TOKEN; + process.env.ANTHROPIC_API_KEY = ""; + process.env.ANTHROPIC_OAUTH_TOKEN = ""; await withTempHome(async (home) => { const configDir = path.join(home, ".clawdbot"); await fs.mkdir(configDir, { recursive: true }); @@ -20,6 +24,85 @@ describe("config pruning defaults", () => { expect(cfg.agents?.defaults?.contextPruning?.mode).toBeUndefined(); }); + if (prevApiKey === undefined) { + delete process.env.ANTHROPIC_API_KEY; + } else { + process.env.ANTHROPIC_API_KEY = prevApiKey; + } + if (prevOauthToken === undefined) { + delete process.env.ANTHROPIC_OAUTH_TOKEN; + } else { + process.env.ANTHROPIC_OAUTH_TOKEN = prevOauthToken; + } + }); + + it("enables cache-ttl pruning + 1h heartbeat for Anthropic OAuth", async () => { + await withTempHome(async (home) => { + const configDir = path.join(home, ".clawdbot"); + await fs.mkdir(configDir, { recursive: true }); + await fs.writeFile( + path.join(configDir, "clawdbot.json"), + JSON.stringify( + { + auth: { + profiles: { + "anthropic:me": { provider: "anthropic", mode: "oauth", email: "me@example.com" }, + }, + }, + agents: { defaults: {} }, + }, + null, + 2, + ), + "utf-8", + ); + + vi.resetModules(); + const { loadConfig } = await import("./config.js"); + const cfg = loadConfig(); + + expect(cfg.agents?.defaults?.contextPruning?.mode).toBe("cache-ttl"); + expect(cfg.agents?.defaults?.contextPruning?.ttl).toBe("1h"); + expect(cfg.agents?.defaults?.heartbeat?.every).toBe("1h"); + }); + }); + + it("enables cache-ttl pruning + 1h cache TTL for Anthropic API keys", async () => { + await withTempHome(async (home) => { + const configDir = path.join(home, ".clawdbot"); + await fs.mkdir(configDir, { recursive: true }); + await fs.writeFile( + path.join(configDir, "clawdbot.json"), + JSON.stringify( + { + auth: { + profiles: { + "anthropic:api": { provider: "anthropic", mode: "api_key" }, + }, + }, + agents: { + defaults: { + model: { primary: "anthropic/claude-opus-4-5" }, + }, + }, + }, + null, + 2, + ), + "utf-8", + ); + + vi.resetModules(); + const { loadConfig } = await import("./config.js"); + const cfg = loadConfig(); + + expect(cfg.agents?.defaults?.contextPruning?.mode).toBe("cache-ttl"); + expect(cfg.agents?.defaults?.contextPruning?.ttl).toBe("1h"); + expect(cfg.agents?.defaults?.heartbeat?.every).toBe("30m"); + expect( + cfg.agents?.defaults?.models?.["anthropic/claude-opus-4-5"]?.params?.cacheControlTtl, + ).toBe("1h"); + }); }); it("does not override explicit contextPruning mode", async () => { diff --git a/src/config/defaults.ts b/src/config/defaults.ts index 9976a64ef0b..c88c1625f49 100644 --- a/src/config/defaults.ts +++ b/src/config/defaults.ts @@ -1,3 +1,4 @@ +import { parseModelRef } from "../agents/model-selection.js"; import { resolveTalkApiKey } from "./talk.js"; import type { ClawdbotConfig } from "./types.js"; import { DEFAULT_AGENT_MAX_CONCURRENT, DEFAULT_SUBAGENT_MAX_CONCURRENT } from "./agent-limits.js"; @@ -6,6 +7,8 @@ type WarnState = { warned: boolean }; let defaultWarnState: WarnState = { warned: false }; +type AnthropicAuthDefaultsMode = "api_key" | "oauth"; + const DEFAULT_MODEL_ALIASES: Readonly> = { // Anthropic (pi-ai catalog uses "latest" ids without date suffix) opus: "anthropic/claude-opus-4-5", @@ -20,6 +23,40 @@ const DEFAULT_MODEL_ALIASES: Readonly> = { "gemini-flash": "google/gemini-3-flash-preview", }; +function resolveAnthropicDefaultAuthMode(cfg: ClawdbotConfig): AnthropicAuthDefaultsMode | null { + const profiles = cfg.auth?.profiles ?? {}; + const anthropicProfiles = Object.entries(profiles).filter( + ([, profile]) => profile?.provider === "anthropic", + ); + + const order = cfg.auth?.order?.anthropic ?? []; + for (const profileId of order) { + const entry = profiles[profileId]; + if (!entry || entry.provider !== "anthropic") continue; + if (entry.mode === "api_key") return "api_key"; + if (entry.mode === "oauth" || entry.mode === "token") return "oauth"; + } + + const hasApiKey = anthropicProfiles.some(([, profile]) => profile?.mode === "api_key"); + const hasOauth = anthropicProfiles.some( + ([, profile]) => profile?.mode === "oauth" || profile?.mode === "token", + ); + if (hasApiKey && !hasOauth) return "api_key"; + if (hasOauth && !hasApiKey) return "oauth"; + + if (process.env.ANTHROPIC_OAUTH_TOKEN?.trim()) return "oauth"; + if (process.env.ANTHROPIC_API_KEY?.trim()) return "api_key"; + return null; +} + +function resolvePrimaryModelRef(raw?: string): string | null { + if (!raw || typeof raw !== "string") return null; + const trimmed = raw.trim(); + if (!trimmed) return null; + const aliasKey = trimmed.toLowerCase(); + return DEFAULT_MODEL_ALIASES[aliasKey] ?? trimmed; +} + export type SessionDefaultsOptions = { warn?: (message: string) => void; warnState?: WarnState; @@ -157,7 +194,82 @@ export function applyLoggingDefaults(cfg: ClawdbotConfig): ClawdbotConfig { } export function applyContextPruningDefaults(cfg: ClawdbotConfig): ClawdbotConfig { - return cfg; + const defaults = cfg.agents?.defaults; + if (!defaults) return cfg; + + const authMode = resolveAnthropicDefaultAuthMode(cfg); + if (!authMode) return cfg; + + let mutated = false; + const nextDefaults = { ...defaults }; + + if (defaults.contextPruning?.mode === undefined) { + nextDefaults.contextPruning = { + ...(defaults.contextPruning ?? {}), + mode: "cache-ttl", + ttl: defaults.contextPruning?.ttl ?? "1h", + }; + mutated = true; + } + + if (defaults.heartbeat?.every === undefined) { + nextDefaults.heartbeat = { + ...(defaults.heartbeat ?? {}), + every: authMode === "oauth" ? "1h" : "30m", + }; + mutated = true; + } + + if (authMode === "api_key") { + const nextModels = defaults.models ? { ...defaults.models } : {}; + let modelsMutated = false; + + for (const [key, entry] of Object.entries(nextModels)) { + const parsed = parseModelRef(key, "anthropic"); + if (!parsed || parsed.provider !== "anthropic") continue; + const current = entry ?? {}; + const params = (current as { params?: Record }).params ?? {}; + if (typeof params.cacheControlTtl === "string") continue; + nextModels[key] = { + ...(current as Record), + params: { ...params, cacheControlTtl: "1h" }, + }; + modelsMutated = true; + } + + const primary = resolvePrimaryModelRef(defaults.model?.primary ?? undefined); + if (primary) { + const parsedPrimary = parseModelRef(primary, "anthropic"); + if (parsedPrimary?.provider === "anthropic") { + const key = `${parsedPrimary.provider}/${parsedPrimary.model}`; + const entry = nextModels[key]; + const current = entry ?? {}; + const params = (current as { params?: Record }).params ?? {}; + if (typeof params.cacheControlTtl !== "string") { + nextModels[key] = { + ...(current as Record), + params: { ...params, cacheControlTtl: "1h" }, + }; + modelsMutated = true; + } + } + } + + if (modelsMutated) { + nextDefaults.models = nextModels; + mutated = true; + } + } + + if (!mutated) return cfg; + + return { + ...cfg, + agents: { + ...cfg.agents, + defaults: nextDefaults, + }, + }; } export function applyCompactionDefaults(cfg: ClawdbotConfig): ClawdbotConfig {