rovecode 0.3.2

package/src/providers/auth.ts

@@ -0,0 +1,408 @@
+/** Provider credential store (port #37): backing for `rovecode auth set/list/remove`.
+ *
+ *  Ported from opencode packages/opencode/src/auth/index.ts @ ebece6e (MIT):
+ *  - one JSON object keyed by provider id, entries discriminated by `type` (index.ts:14-36)
+ *  - the "api" variant carries the secret in `key` (index.ts:23-27); the provider loader
+ *    consumes it as the apiKey (provider.ts:1596-1601)
+ *  - file written with mode 0o600 (index.ts:79,88)
+ *  - a missing/corrupt file reads as {} and malformed entries are dropped per-entry, never
+ *    fatal (index.ts:65-66, Record.filterMap over the schema decode)
+ *  Deviations: the file lives at ~/.rovecode/credentials.json (bar) instead of opencode's
+ *  <data>/auth.json; entries carry an rovecode-only optional `keyName` (which env var the
+ *  secret stands in for); the "api" variant plus, since the OAuth port (aion port #66, brought over
+ *  2026-09-07), the "oauth" variant (`rovecode auth login`): `access` (the bearer the provider seam
+ *  sends), `refresh` (what mints a new access token; "" when the provider issues a permanent key),
+ *  `expires` (ms since the epoch; Number.MAX_SAFE_INTEGER = never) — pi's OAuthCredential shape
+ *  (packages/ai/src/auth/types.ts). The `type` field is the record's kind discriminator. Entries with
+ *  any other `type` round-trip through save/remove unharmed but are not listed or resolved.
+ *
+ *  Also home to readSecret (the `rovecode auth set` prompt) so its TTY path is unit-testable
+ *  in-process — main.ts cannot be imported by tests (it dispatches on load).
+ *
+ *  SECRETS ARE NEVER LOGGED from this module: the only terminal output is readSecret's
+ *  prompt text plus cursor-control sequences, error messages never embed the credential
+ *  value, and the store itself prints nothing. Rendering (redacted) is the caller's job
+ *  via listProviders()/redactSecret().
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, cpSync, existsSync, rmSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+
+/** The provider index, loaded ONLY when something asks for a key name.
+ *
+ *  Two things were wrong here and they compounded. The import was at the top of the module, and what it
+ *  imported was the full models.dev snapshot: 63 MB resident, for one call site (`keyNameFor`). Meanwhile
+ *  `rovecodeHome`, three lines of path arithmetic in this same file, is imported by hooks.ts, settings.ts,
+ *  runtime.ts, the plugin loader and half the TUI — so all of them paid 63 MB to learn where `~/.rovecode`
+ *  is, and the TUI paid it at startup before drawing a frame.
+ *
+ *  Now it is deferred, and it reads the trimmed index (src/providers/models-index.json, the same file the
+ *  catalog reads) rather than the upstream snapshot. Only `env[0]` is ever used from it.
+ *
+ *  `require` rather than `await import` because `keyNameFor` is synchronous and called from synchronous
+ *  code; making it async would push the change through a dozen call sites to save nothing extra. */
+let snapshotCache: Record<string, { env?: string[] } | undefined> | null = null;
+function snapshotProvidersLazy(): Record<string, { env?: string[] } | undefined> {
+  if (snapshotCache === null) {
+    const req = createRequire(import.meta.url);
+    const m = req("./models-index.json") as { providers?: Record<string, { env?: string[] }> };
+    snapshotCache = m.providers ?? {};
+  }
+  return snapshotCache;
+}
+
+export interface StoredCredential {
+  type: "api";
+  /** the secret itself (upstream field name — auth/index.ts:24) */
+  key: string;
+  /** rovecode extension: env var name this secret stands in for (e.g. ANTHROPIC_API_KEY) */
+  keyName?: string;
+}
+
+/** An OAuth login (`rovecode auth login <provider>`), pi's OAuthCredential shape. */
+export interface StoredOAuthCredential {
+  type: "oauth";
+  /** the bearer the provider seam sends (short-lived where the provider issues one) */
+  access: string;
+  /** what refresh() presents to mint a new access token (github-copilot: the GitHub OAuth token;
+   *  openai: the refresh_token; "" when the provider issued a permanent key — openrouter) */
+  refresh: string;
+  /** access-token expiry, ms since the epoch; Number.MAX_SAFE_INTEGER = never expires */
+  expires: number;
+  /** openai: the ChatGPT account id from the access token's JWT claim (request header) */
+  accountId?: string;
+}
+
+/** Port #76: an MCP server's OAuth token (`rovecode mcp login <name>`, stored under `mcp:<name>`) — the SDK-driven
+ *  flow's whole session, so a connect needs no discovery or registration round trip: `url` (a record is attached
+ *  only to the server whose configured url EQUALS it), `access` ("" once invalidated — the record then still carries
+ *  the client + discovery), `refresh` ("" when the server issued none), `expires` (ms since the epoch;
+ *  Number.MAX_SAFE_INTEGER = never), the registered client (`client_id`, plus a DCR-issued secret when the server
+ *  insisted on one — never a configured one) and the SDK's discovery state (opaque here; mcp/oauth.ts reads it).
+ *  Listed by `auth list` (kind oauth, key name `mcp server token`), removable, NEVER resolved as a chat provider. */
+export interface StoredMcpOAuthRecord {
+  type: "mcp-oauth";
+  url: string;
+  access: string;
+  refresh: string;
+  expires: number;
+  clientInformation?: { client_id: string; client_secret?: string; client_id_issued_at?: number; client_secret_expires_at?: number };
+  discovery?: Record<string, unknown>;
+}
+
+/** The mode the store is written with (create AND re-asserted on rewrite) — the single source
+ *  the tests pin; see the Windows note on writeStore. */
+export const CREDENTIALS_FILE_MODE = 0o600;
+
+/** User-scope rovecode dir: ROVECODE_HOME overrides ~/.rovecode wholesale (tests point it at a temp
+ *  dir). homedir() already respects HOME on POSIX and USERPROFILE on Windows. Mirrors the
+ *  skills store's user-scope default (skills/index.ts: join(homedir(), ".rovecode", ...)). */
+/** what node's homedir() promises, spelled out so every runtime agrees on every host: HOME on POSIX,
+ *  USERPROFILE on Windows, the OS account's directory only when neither is set (tests point HOME at a
+ *  scratch dir and expect the home to follow) */
+const userHome = (): string => (process.platform === "win32" ? process.env.USERPROFILE : process.env.HOME) || homedir();
+
+export function rovecodeHome(): string {
+  const explicit = process.env.ROVECODE_HOME;
+  const home = explicit ?? join(userHome(), ".rovecode");
+  migrateLegacyHome(home, { explicit: explicit !== undefined });
+  return home;
+}
+
+/** The config directory used to be `~/.cumulus` (the project was called nimbus). A rename must not
+ *  cost anyone their stored API keys and providers, so the first call that resolves the new home
+ *  COPIES the old one into it — copy, not move: the old directory is left exactly as it was, so
+ *  downgrading to an older build keeps working and nothing is destroyed if this goes wrong.
+ *
+ *  Runs once per process, only when the new home does not exist yet and the old one does, and ONLY for
+ *  the default home. An explicit ROVECODE_HOME used to be migrated the same way "which is what makes it
+ *  testable", and that was a real hazard rather than a convenience: pointing ROVECODE_HOME at a fresh
+ *  path — the ordinary way to get an isolated home for a test, a script or a clean-room check — silently
+ *  filled it with a copy of the old credentials. It billed two real API calls during this repository's
+ *  own release verification (2026-09-06) before anyone noticed the scratch home was not scratch. Tests
+ *  that need to exercise the migration pass `legacyDir`; nothing else copies a user's keys into a path
+ *  they chose for isolation.
+ *
+ *  Any failure is swallowed: a migration that cannot run must not stop the agent from starting — the
+ *  user simply sees "no provider configured" and runs `rovecode connect`. */
+let migrated = false;
+export function migrateLegacyHome(home: string, opts: { explicit?: boolean; legacyDir?: string; note?: (line: string) => void } = {}): void {
+  if (migrated && opts.legacyDir === undefined) return;
+  if (opts.legacyDir === undefined) migrated = true;
+  try {
+    if (existsSync(home)) return;                        // already living in the new place
+    const legacy = opts.legacyDir ?? join(userHome(), ".cumulus");
+    // an explicit ROVECODE_HOME is a request for THIS directory, not for a copy of another one. The
+    // injected legacyDir does not override it: a test that wants the explicit case must SEE the refusal.
+    if (opts.explicit === true) return;
+    if (home === legacy || !existsSync(legacy)) return;
+    cpSync(legacy, home, { recursive: true });
+    // and it says so: a copy of someone's credentials appearing in a new directory is not a silent event
+    (opts.note ?? ((l: string) => console.error(l)))(`migrated ${legacy} → ${home} (the config directory was renamed; the old one is untouched)`);
+    // the credentials file carries the 0600 the old one had only on POSIX; re-assert it here
+    const creds = join(home, "credentials.json");
+    if (existsSync(creds) && process.platform !== "win32") chmodSync(creds, CREDENTIALS_FILE_MODE);
+  } catch { /* best effort: a failed migration is a fresh config, never a crash */ }
+}
+
+export function credentialsPath(): string {
+  return join(rovecodeHome(), "credentials.json");
+}
+
+/** Raw file contents: every entry as stored, including unknown `type`s. Missing file,
+ *  unreadable file, or non-object JSON -> {} (upstream orElseSucceed idiom). */
+function readRaw(): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+  return parsed as Record<string, unknown>;
+}
+
+function isApiCredential(value: unknown): value is StoredCredential {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as { type?: unknown; key?: unknown; keyName?: unknown };
+  // whitespace-only counts as empty: a hand-edited `"key": " "` must not shadow a valid env key
+  if (v.type !== "api" || typeof v.key !== "string" || v.key.trim().length === 0) return false;
+  return v.keyName === undefined || typeof v.keyName === "string";
+}
+
+/** Valid "api" credentials only, keyed by provider id (malformed entries dropped). */
+export function loadCredentials(): Record<string, StoredCredential> {
+  const out: Record<string, StoredCredential> = {};
+  for (const [id, value] of Object.entries(readRaw())) {
+    if (isApiCredential(value)) out[id] = value;
+  }
+  return out;
+}
+
+function isOAuthCredential(value: unknown): value is StoredOAuthCredential {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as { type?: unknown; access?: unknown; refresh?: unknown; expires?: unknown; accountId?: unknown };
+  if (v.type !== "oauth" || typeof v.access !== "string" || v.access.trim().length === 0) return false;
+  if (typeof v.refresh !== "string" || typeof v.expires !== "number" || !Number.isFinite(v.expires)) return false;
+  // `expires` must sit inside Date's range (±8.64e15 ms) or be the "never" sentinel — `auth list` renders it
+  // through toISOString, which throws RangeError beyond that, and a hand-edited entry is never fatal
+  if (Math.abs(v.expires) > 8.64e15 && v.expires !== Number.MAX_SAFE_INTEGER) return false;
+  return v.accountId === undefined || typeof v.accountId === "string";
+}
+
+/** Valid "oauth" credentials only, keyed by provider id (malformed entries dropped). */
+export function loadOAuthCredentials(): Record<string, StoredOAuthCredential> {
+  const out: Record<string, StoredOAuthCredential> = {};
+  for (const [id, value] of Object.entries(readRaw())) {
+    if (isOAuthCredential(value)) out[id] = value;
+  }
+  return out;
+}
+
+/** Port #76: the mcp-oauth variant — same range rule on `expires` as isOAuthCredential; `access` may be "" (invalidated). */
+export function isMcpOAuthRecord(value: unknown): value is StoredMcpOAuthRecord {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (v.type !== "mcp-oauth" || typeof v.url !== "string" || v.url.length === 0) return false;
+  if (typeof v.access !== "string" || typeof v.refresh !== "string" || typeof v.expires !== "number" || !Number.isFinite(v.expires)) return false;
+  if (Math.abs(v.expires) > 8.64e15 && v.expires !== Number.MAX_SAFE_INTEGER) return false;
+  const ci = v.clientInformation;
+  if (ci !== undefined && (typeof ci !== "object" || ci === null || typeof (ci as { client_id?: unknown }).client_id !== "string")) return false;
+  const d = v.discovery;
+  return d === undefined || (typeof d === "object" && d !== null && !Array.isArray(d));
+}
+
+/** Port #76: one raw entry as stored (any `type`), or undefined. The MCP module validates it (isMcpOAuthRecord). */
+export function readEntry(id: string): unknown {
+  return readRaw()[id];
+}
+
+/** Port #76: store/replace one entry verbatim (0600 on create and rewrite), or delete it (`undefined` — the file goes
+ *  when it was the last entry, like removeCredential). The value is never echoed or thrown. */
+export function writeEntry(id: string, value: object | undefined): void {
+  if (id.trim().length === 0) throw new Error("credential id must not be empty");
+  if (value === undefined) {
+    removeCredential(id);
+    return;
+  }
+  const data = readRaw();
+  data[id] = value;
+  writeStore(data);
+}
+
+/** Store/replace a provider's OAuth credential (an "api" entry under the same id is replaced —
+ *  one entry per provider). Tokens are never echoed or thrown. */
+export function saveOAuthCredential(provider: string, cred: StoredOAuthCredential): void {
+  const id = provider.trim();
+  if (id.length === 0) throw new Error("provider id must not be empty");
+  if (!isOAuthCredential(cred)) throw new Error(`refusing to store a malformed OAuth credential for ${id}`);
+  const data = readRaw();
+  data[id] = { type: "oauth", access: cred.access, refresh: cred.refresh, expires: cred.expires, ...(cred.accountId !== undefined ? { accountId: cred.accountId } : {}) };
+  writeStore(data);
+}
+
+/** Write the store with restrictive permissions.
+ *
+ *  Windows honesty note: fs mode bits on win32 map only onto the FILE_ATTRIBUTE_READONLY
+ *  flag — 0o600 does NOT create owner-only protection there. Real isolation on Windows
+ *  comes from the NTFS ACL on %USERPROFILE% (inherited by ~/.rovecode), which by default
+ *  denies other non-admin users. So this is best-effort hardening on POSIX (where the
+ *  0o600/0o700 bits are enforced) and effectively a no-op on Windows beyond the profile
+ *  ACL it inherits — we do not claim otherwise. */
+function writeStore(data: Record<string, unknown>): void {
+  const path = credentialsPath();
+  mkdirSync(rovecodeHome(), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", { mode: CREDENTIALS_FILE_MODE });
+  try {
+    chmodSync(path, CREDENTIALS_FILE_MODE); // `mode` above only applies on create; re-assert on rewrites
+  } catch {
+    // best-effort (see Windows note) — a failed chmod must not lose the write
+  }
+}
+
+/** Store/replace the credential for a provider. `secret` is never echoed or thrown. */
+export function saveCredential(provider: string, secret: string, keyName?: string): void {
+  const id = provider.trim();
+  if (id.length === 0) throw new Error("provider id must not be empty");
+  if (secret.trim().length === 0) throw new Error(`refusing to store an empty secret for ${id}`);
+  const data = readRaw();
+  const entry: StoredCredential = { type: "api", key: secret, keyName: keyName ?? keyNameFor(id) };
+  data[id] = entry;
+  writeStore(data);
+}
+
+/** Remove a provider's entry. Returns false (and leaves the file alone) when absent.
+ *  Removing the last entry deletes the file rather than leaving an empty {} around. */
+export function removeCredential(provider: string): boolean {
+  const data = readRaw();
+  if (!(provider in data)) return false;
+  delete data[provider];
+  if (Object.keys(data).length === 0) {
+    try {
+      rmSync(credentialsPath());
+    } catch {
+      writeStore(data);
+    }
+    return true;
+  }
+  writeStore(data);
+  return true;
+}
+
+/** First 4 chars + "…" (bar wording). Secrets of 8 chars or fewer collapse to "…" alone —
+ *  half of a short key is most of the key, so nothing of it is shown. */
+export function redactSecret(secret: string): string {
+  return secret.length > 8 ? secret.slice(0, 4) + "…" : "…";
+}
+
+export interface ProviderListing {
+  provider: string;
+  /** the record's `type` — api (`auth set`) or oauth (`auth login`; also the mcp-oauth records of port #76) */
+  kind: "api" | "oauth";
+  /** api: the env var the key stands in for; oauth: the literal "oauth token"; mcp-oauth: "mcp server token" */
+  keyName: string;
+  redacted: string;
+  /** oauth only: access-token expiry, ms since the epoch (Number.MAX_SAFE_INTEGER = never) */
+  expires?: number;
+}
+
+/** Redacted listing for `rovecode auth list`: provider + kind + key NAME + redacted prefix (+ expiry
+ *  for OAuth entries). No secret value — key, access token or refresh token — appears in the records. */
+export function listProviders(): ProviderListing[] {
+  const api: ProviderListing[] = Object.entries(loadCredentials()).map(([provider, cred]) => ({
+    provider, kind: "api", keyName: cred.keyName ?? keyNameFor(provider), redacted: redactSecret(cred.key),
+  }));
+  const oauth: ProviderListing[] = Object.entries(loadOAuthCredentials()).map(([provider, cred]) => ({
+    provider, kind: "oauth", keyName: "oauth token", redacted: redactSecret(cred.access), expires: cred.expires,
+  }));
+  // port #76: MCP server tokens (`mcp:<name>`) — listed and removable like any entry, never a chat provider
+  const mcp: ProviderListing[] = Object.entries(readRaw()).flatMap(([provider, value]) => isMcpOAuthRecord(value)
+    ? [{ provider, kind: "oauth" as const, keyName: "mcp server token", redacted: redactSecret(value.access), expires: value.expires }]
+    : []);
+  return [...api, ...oauth, ...mcp].sort((a, b) => a.provider.localeCompare(b.provider));
+}
+
+/** rovecode provider id -> models.dev provider key, mirroring catalog.ts PROVIDER_MAP for the
+ *  non-identity ids (together -> "togetherai", fireworks -> "fireworks-ai") plus an
+ *  auth-only alias: moonshot -> "moonshotai" (models.dev has no bare "moonshot" key — the
+ *  catalog reaches it via VENDOR_PREFIX_MAP on model ids instead, which auth cannot use).
+ *  Identity ids (anthropic/openai/deepseek/openrouter/...) need no entry: keyNameFor tries
+ *  the id itself against the snapshot first. */
+const AUTH_PROVIDER_MAP: Record<string, string> = {
+  together: "togetherai",
+  fireworks: "fireworks-ai",
+  moonshot: "moonshotai",
+};
+
+/** Which env var / key name a provider expects. models.dev drives this (snapshot
+ *  Provider.env, e.g. anthropic -> ANTHROPIC_API_KEY — same source opencode's provider
+ *  loader reads at provider.ts:1583 @ ebece6e); providers absent from models.dev (kaesra,
+ *  ollama, moondream, vllm) fall back to <ID>_API_KEY, which matches every envKey in
+ *  stream.ts builtinProviders by construction. */
+export function keyNameFor(providerId: string): string {
+  const key = AUTH_PROVIDER_MAP[providerId] ?? providerId;
+  const env = snapshotProvidersLazy()[key]?.env;
+  if (env !== undefined && env.length > 0 && env[0]) return env[0];
+  return providerId.toUpperCase().replace(/[^A-Z0-9]+/g, "_") + "_API_KEY";
+}
+
+// ---------- secret prompt (`rovecode auth set`) ----------
+
+type SecretInput = NodeJS.ReadableStream & { isTTY?: boolean; isRaw?: boolean };
+type SecretOutput = NodeJS.WritableStream & { columns?: number };
+/** Streams readSecret talks to — injectable so tests can drive a fake TTY in-process. */
+export interface SecretPromptIO { input?: SecretInput; output?: SecretOutput }
+
+/** Cursor-control sequence for the cooked-mode fallback: after Enter the terminal has echoed
+ *  prompt+line and moved to the next row, so erase ONE row per wrapped row the echo occupied
+ *  (cursor-up + erase-line each), then "\r". A single row is not enough — a 33-col prompt plus
+ *  a 108-char Anthropic key wraps on any terminal narrower than 141 columns. Pure: pinned by
+ *  the headless-xterm test at 80 and 120 columns. Unknown/zero width assumes 80. */
+export function echoScrubSequence(promptLen: number, lineLen: number, columns: number): string {
+  const cols = columns > 0 ? Math.floor(columns) : 80;
+  const rows = Math.max(1, Math.ceil((promptLen + lineLen) / cols));
+  return "\x1b[1A\x1b[2K".repeat(rows) + "\r";
+}
+
+/** Read one secret line for `rovecode auth set`. What is guaranteed:
+ *  - TTY stdin: the prompt goes to stderr and readline runs in terminal mode, which calls
+ *    setRawMode(true): the terminal driver's echo is OFF and readline's own echo goes to a
+ *    sink, so the keystrokes are never written to the terminal at all. Verified on a real
+ *    Windows console under Bun 1.3.14 — the console input mode drops ENABLE_ECHO_INPUT and
+ *    ENABLE_LINE_INPUT, the screen buffer stays clean, and the mode is restored on close.
+ *  - Fallback, only if raw mode did not take (no/failing setRawMode, input.isRaw stays false):
+ *    the driver echoed, so after Enter every row the prompt+echo wrapped onto is erased
+ *    (echoScrubSequence). A terminal that ignores VT cursor sequences keeps that echo.
+ *  - Piped stdin (scripts, tests): one line, no prompt, nothing written to any stream.
+ *  The value is returned trimmed and is never logged or embedded in an error. */
+export function readSecret(promptText: string, io: SecretPromptIO = {}): Promise<string> {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stderr;
+  const tty = input.isTTY === true;
+  if (tty) output.write(promptText);
+  const rl = tty
+    ? createInterface({ input, output: new Writable({ write: (_c, _e, cb) => cb() }), terminal: true })
+    : createInterface({ input });
+  const raw = tty && input.isRaw === true;
+  return new Promise((resolve) => {
+    let settled = false; // rl.close() emits "close" SYNCHRONOUSLY — guard the race
+    rl.once("line", (line) => {
+      if (settled) return;
+      settled = true;
+      // raw: nothing was echoed, just end the prompt line; not raw: erase the echoed rows
+      if (tty) output.write(raw ? "\n" : echoScrubSequence(promptText.length, line.length, output.columns ?? 80));
+      rl.close();
+      resolve(line.trim());
+    });
+    rl.once("close", () => { // EOF / Ctrl+C / Ctrl+D without a line
+      if (settled) return;
+      settled = true;
+      if (tty) output.write("\n");
+      resolve("");
+    });
+  });
+}

package/src/providers/cache.ts

@@ -0,0 +1,223 @@
+/** Anthropic prompt-cache boundary placement — pure transform for the /messages request body.
+ *
+ *  Prompt caching is a PREFIX match: the API render order is tools → system → messages, and a
+ *  `cache_control: {type:"ephemeral"}` marker on a content block caches everything from the start
+ *  of the request up to and including that block. Any byte change before a marker invalidates it.
+ *  Therefore boundaries only pay off on STABLE prefixes — a boundary after content that changes
+ *  every turn is a wasted breakpoint (Anthropic allows at most 4 per request).
+ *
+ *  Pattern reference (hermes-agent snapshot, research/source_snapshots/hermes-agent):
+ *  - agent/prompt_caching.py:1-8 — "The default layout uses 4 cache_control breakpoints: the static
+ *    system prefix, the end of the system prompt, and the last 2 non-system messages."
+ *  - agent/prompt_caching.py:157-162 (_build_marker) — the marker is `{"type": "ephemeral"}`.
+ *  - agent/prompt_caching.py:113-121 (_apply_cache_marker) — string content is converted to a
+ *    single text block carrying the marker; list content gets the marker on its LAST block.
+ *  - agent/prompt_caching.py:99-103, 331-333 — volatile tails ride UNMARKED ("a changed ticket ID
+ *    or timestamp no longer invalidates the whole skill body"), and empty text blocks are never
+ *    emitted (HTTP 400 on native Anthropic).
+ *  - agent/prompt_caching.py:567-573 (apply_anthropic_cache_control) — idempotence contract:
+ *    re-application "can never accumulate past 4 markers".
+ *  - agent/system_prompt.py:911-924 and agent/turn_context.py:214-217 — the stability principle:
+ *    volatile per-turn facts are kept OUT of / AFTER the cached band so the prefix stays
+ *    byte-stable turn-over-turn.
+ *
+ *  Placement policy implemented here (deliberately simpler than Hermes' 4-marker layout):
+ *  (1) SYSTEM boundary — `system: string` is converted to
+ *      `[{type:"text", text, cache_control:{type:"ephemeral"}}]` when it is ≥ minChunkChars.
+ *      A system-block array already provided by the caller gets the marker on its last block
+ *      (unless any block is already marked). Because caching is prefix-based, this single marker
+ *      also covers the `tools` array rendered before `system` — no separate tools marker needed.
+ *  (2) CONVERSATION-PREFIX boundary — the marker goes on the LAST content block of the most
+ *      recent message that has ≥ 2 messages after it (index length-3): an agent turn appends
+ *      the trailing exchange (assistant tool_use + tool_result, or user + assistant), so the
+ *      tail churns every turn while the prefix up to there is CANONICALLY stable — not
+ *      byte-identical. Two rewrites make consecutive requests differ in raw bytes: the marker
+ *      moves forward each turn (dropped from the old anchor, added at the new one), and the
+ *      marked message's string content is rewritten to [{type:"text",...}] by
+ *      withMarkerOnLastBlock below. Anthropic's cache key normalizes exactly those two
+ *      (cache_control is placement metadata, and string content is equivalent to a single
+ *      text block), so the previous request's prefix still cache-hits. Pinned by the
+ *      consecutive-turn stability test in test/unit/cache.test.ts.
+ *      If the anchor message cannot carry a marker (empty content — cf. Hermes _can_carry_marker,
+ *      prompt_caching.py:127-140, "so the breakpoints land on messages that count"), the
+ *      boundary reallocates to the nearest earlier eligible message. String content is
+ *      converted to a one-block array, preserving the text byte-for-byte.
+ *  (3) BUDGET — never exceed maxBreakpoints total, counting markers already present in
+ *      system/messages/tools before placing new ones. System wins over conversation prefix.
+ *  (4) IDEMPOTENT — a position that already carries a marker is left untouched, existing markers
+ *      count toward the budget, and untouched inputs are returned by reference, so
+ *      apply(apply(body)) deep-equals apply(body).
+ *  (5) Bodies without messages/system pass through untouched (same reference), as does anything
+ *      whose shapes don't match — this is a best-effort decorator, never a validator.
+ *
+ *  minChunkChars default: 4096 chars ≈ 1024 tokens (~4 chars/token) — the documented minimum
+ *  cacheable prefix for Sonnet/Opus-class models (model-dependent, 512–4096 tokens per the API
+ *  docs). Prefixes below the model minimum are silently NOT cached, so spending a breakpoint on
+ *  them is pure waste. For the message boundary the gate compares the CUMULATIVE prefix
+ *  (system + messages[0..anchor]) against minChunkChars, since that whole span is what the
+ *  marker would cache (tools text is not counted — a conservative undercount).
+ *
+ *  Pure: the input body is never mutated; modified paths are copied copy-on-write.
+ */
+
+export interface CacheOptions {
+  /** Maximum cache_control markers allowed in the request. Anthropic's limit — and the default — is 4. */
+  maxBreakpoints?: number;
+  /** Don't spend a breakpoint on a prefix shorter than this many characters. Default 4096 (≈1024 tokens). */
+  minChunkChars?: number;
+}
+
+export interface CacheControl { type: "ephemeral" }
+
+/** Loose ("-ish") view of the body anthropicStream builds (src/providers/stream.ts:152-160):
+ *  `{ model, max_tokens, system?: string, messages: [...], tools?: [...] }`. Every field is
+ *  unknown-typed so the adapter's `Record<string, unknown>` is directly assignable; this module
+ *  narrows at runtime and passes through anything it does not recognize. */
+export interface AnthropicishBody {
+  system?: unknown;
+  messages?: unknown;
+  tools?: unknown;
+  [key: string]: unknown;
+}
+
+export const DEFAULT_MAX_BREAKPOINTS = 4;
+export const DEFAULT_MIN_CHUNK_CHARS = 4096;
+
+const EPHEMERAL: CacheControl = { type: "ephemeral" };
+
+type Rec = Record<string, unknown>;
+
+function isRec(v: unknown): v is Rec {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Marker presence on a content block / tool entry (block-level only — the shapes this module emits). */
+function hasMarker(block: unknown): boolean {
+  return isRec(block) && block["cache_control"] !== undefined;
+}
+
+function blockText(block: unknown): string {
+  if (!isRec(block)) return "";
+  return typeof block["text"] === "string" ? block["text"] : "";
+}
+
+function systemChars(system: unknown): number {
+  if (typeof system === "string") return system.length;
+  if (Array.isArray(system)) return system.reduce((n: number, b) => n + blockText(b).length, 0);
+  return 0;
+}
+
+function contentChars(content: unknown): number {
+  if (typeof content === "string") return content.length;
+  if (!Array.isArray(content)) return 0;
+  let n = 0;
+  for (const b of content) {
+    n += blockText(b).length;
+    // tool_result blocks carry their payload under "content" (string form only; arrays undercount)
+    if (isRec(b) && typeof b["content"] === "string") n += b["content"].length;
+  }
+  return n;
+}
+
+function messageMarkerCount(msg: unknown): number {
+  if (!isRec(msg)) return 0;
+  const content = msg["content"];
+  return Array.isArray(content) ? content.filter(hasMarker).length : 0;
+}
+
+function countExistingMarkers(system: unknown, messages: readonly unknown[] | null, tools: unknown): number {
+  let n = 0;
+  if (Array.isArray(system)) n += system.filter(hasMarker).length;
+  for (const m of messages ?? []) n += messageMarkerCount(m);
+  if (Array.isArray(tools)) n += tools.filter(hasMarker).length;
+  return n;
+}
+
+/** A marker on this message would actually land on the wire: non-empty string content (an empty
+ *  string would convert to an empty text block — HTTP 400), or a non-empty block array whose last
+ *  element is an object. Mirrors Hermes _can_carry_marker (prompt_caching.py:127-154). */
+function canCarryMarker(msg: unknown): boolean {
+  if (!isRec(msg)) return false;
+  const content = msg["content"];
+  if (typeof content === "string") return content.length > 0;
+  if (Array.isArray(content) && content.length > 0) return isRec(content[content.length - 1]);
+  return false;
+}
+
+/** Copy of `msg` with the ephemeral marker on its last content block; string content becomes a
+ *  one-block array with the text preserved byte-for-byte (Hermes prompt_caching.py:113-121). */
+function withMarkerOnLastBlock(msg: Rec): Rec {
+  const content = msg["content"];
+  if (typeof content === "string") {
+    return { ...msg, content: [{ type: "text", text: content, cache_control: EPHEMERAL }] };
+  }
+  if (Array.isArray(content) && content.length > 0) {
+    const last = content[content.length - 1];
+    if (isRec(last)) {
+      const blocks = content.slice();
+      blocks[blocks.length - 1] = { ...last, cache_control: EPHEMERAL };
+      return { ...msg, content: blocks };
+    }
+  }
+  return msg; // callers gate on canCarryMarker(); unreachable in practice
+}
+
+export function applyAnthropicCacheBoundaries(body: AnthropicishBody, opts?: CacheOptions): AnthropicishBody {
+  const maxBreakpoints = opts?.maxBreakpoints ?? DEFAULT_MAX_BREAKPOINTS;
+  const minChunkChars = opts?.minChunkChars ?? DEFAULT_MIN_CHUNK_CHARS;
+
+  const system = body.system;
+  const messages: readonly unknown[] | null = Array.isArray(body.messages) ? body.messages : null;
+
+  const hasSystem = (typeof system === "string" && system.length > 0) || (Array.isArray(system) && system.length > 0);
+  const hasMessages = messages !== null && messages.length > 0;
+  if (!hasSystem && !hasMessages) return body; // policy (5): pass through untouched
+
+  let used = countExistingMarkers(system, messages, body.tools);
+  let out = body;
+  const copyOnWrite = (): AnthropicishBody => (out === body ? (out = { ...body }) : out);
+
+  // ---- policy (1): system boundary ------------------------------------------------------------
+  if (used < maxBreakpoints && hasSystem) {
+    if (typeof system === "string") {
+      if (system.length >= minChunkChars) {
+        copyOnWrite().system = [{ type: "text", text: system, cache_control: EPHEMERAL }];
+        used += 1;
+      }
+    } else if (Array.isArray(system) && !system.some(hasMarker)) {
+      const last = system[system.length - 1];
+      if (isRec(last) && systemChars(system) >= minChunkChars) {
+        const blocks = system.slice();
+        blocks[blocks.length - 1] = { ...last, cache_control: EPHEMERAL };
+        copyOnWrite().system = blocks;
+        used += 1;
+      }
+    }
+  }
+
+  // ---- policy (2): conversation-prefix boundary ------------------------------------------------
+  // Anchor = most recent message with ≥2 messages after it (index length-3); the trailing two
+  // messages are this turn's churn. Reallocate backwards past marker-incapable messages.
+  if (used < maxBreakpoints && messages !== null && messages.length >= 3) {
+    let anchor = -1;
+    for (let i = messages.length - 3; i >= 0; i -= 1) {
+      if (canCarryMarker(messages[i])) { anchor = i; break; }
+    }
+    const msg = anchor >= 0 ? messages[anchor] : undefined;
+    if (isRec(msg) && messageMarkerCount(msg) === 0) {
+      let prefixChars = systemChars(system);
+      for (let i = 0; i <= anchor; i += 1) {
+        const m = messages[i];
+        if (isRec(m)) prefixChars += contentChars(m["content"]);
+      }
+      if (prefixChars >= minChunkChars) {
+        const next = messages.slice();
+        next[anchor] = withMarkerOnLastBlock(msg);
+        copyOnWrite().messages = next;
+        used += 1;
+      }
+    }
+  }
+
+  return out;
+}