rovecode 0.3.3 → 0.4.0-beta.3

package/src/providers/auth.ts

@@ -1,408 +0,0 @@
-/** 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

@@ -1,223 +0,0 @@
-/** 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;
-}