zidane 6.2.36 → 6.3.1

package/README.md

@@ -70,7 +70,7 @@ createAgent({
     maxTurns: 50,
     maxTokens: 16384,
     thinkingBudget: 10240,
-    thinkingDecay: { afterTurn: 5, factor: 0.5, floor: 1024 },
+    thinkingDecay: { afterTurn: 5, floor: 1024 },
     cache: true,                     // prompt-cache breakpoints
     toolOutputBudget: 32768,         // soft per-turn byte cap (off by default)
     dedupReads: true,                // dedup re-reads in `read_file`
@@ -254,6 +254,8 @@ openaiCompat({
 
 `behavior.cache` (default on). `cache_control: { type: 'ephemeral' }` is inserted on three stable prefixes (system, last tool, last message's final block). Hits + writes surface on `TurnUsage.cacheRead` / `cacheCreation` via the `usage` hook.
 
+`behavior.cacheTtl: '1h'` opts into Anthropic's extended cache (`cache_control.ttl` + the `extended-cache-ttl-2025-04-11` beta header). Writes cost 2× instead of 1.25×; reads stay ~0.1×. Worth it for interactive sessions, where a single >5-minute pause otherwise forfeits the entire cached prefix; headless back-to-back runs should keep the default `'5m'`. Caveat: the wire shape is verified, but measure actual retention on your account before counting the savings — our 2026-07 measurement saw a 1h entry evicted within 6 minutes (gated test: `INFERENCE_SLOW=1`). See `docs/ARCHITECTURE.md` § *Cache-stable configuration* for the full cache-aware settings table.
+
 | Provider | Behavior |
 |---|---|
 | `anthropic` | Honored natively. |
@@ -403,9 +405,19 @@ agent.hooks.hook('context:transform', (ctx) => {
 
 `behavior.autoCompact` is the heavy lever: loop-native auto-compaction. Once a turn's effective input crosses `threshold` (default `0.85`) of the context window, the loop runs a real LLM summary over the older turns, appends a `compact-summary` marker + file/skill restoration to the session, and continues — mid-run and at end-of-run. Window source is `autoCompact.contextWindow` → `provider.meta.contextWindow` (inert without one). Observe via the `compact:start` / `compact:end` hooks. SDK default off; chat profiles enable it. Distinct from `compactStrategy` (per-turn wire-only `tool_result` trim) and the always-on reactive `context_exceeded` recovery.
 
+### Stale-read policy
+
+`behavior.elideStaleReads` decides what happens when an `edit` / `multi_edit` / `write_file` succeeds on a file the model read earlier in the run:
+
+- `'notice'` — append-only: a persisted `<system-reminder>` naming the stale path rides the mutating tool's own result. Never rewrites cached prefix bytes, so the prompt cache is untouched. The built-in chat profiles ship this.
+- `'stub'` (or legacy `true`) — replace the stale read's output on the wire with a short stub. Reclaims the stale bytes from context, but each newly-stale read re-bills the conversation at the cache-write rate — only worth it under real context-window pressure.
+- `false` (default) — off. Detection is identical in both modes (success markers only; failed edits and no-op writes stale nothing), and dedup honesty around mutations holds in **every** mode — see below.
+
+See `docs/ARCHITECTURE.md` § *Cache-stable configuration* for the measured economics.
+
 ### Read dedup + read-before-edit guard
 
-- `behavior.dedupReads` (default **on**) — `read_file` returns `"unchanged since the previous read"` on identical re-reads. Per-session content-hash.
+- `behavior.dedupReads` (default **on**) — `read_file` returns `"unchanged since the previous read"` on identical re-reads. Per-session content-hash. Mutations are honest by construction: after an `edit`/`multi_edit`/`write_file` touches a file, the next re-read serves the full fresh body instead of the stub, then dedup resumes.
 - `behavior.requireReadBeforeEdit` (default **off** in the SDK core; **on** in the built-in `BUILD_AGENT` / `PLAN_AGENT` chat profiles) — `edit` / `multi_edit` reject when the file hasn't been read this session or has drifted. The refusal is a recoverable `tool_result` (tells the model to `read_file` first), and `write_file` seeds read-state so the write→edit flow needs no extra read.
 - `behavior.repeatGuard` (default **off** in the SDK core; **on** in the chat profiles) — breaks consecutive-identical tool streaks: blocks the Nth back-to-back identical call (default 4) with a pivot suggestion, aborts the run at the Mth (default 8) via the agent's `AbortController`. Defaults track the built-in `shell` + `read_file` tools; configurable via `RepeatGuardConfig`.
 
@@ -472,12 +484,11 @@ Pass a function for custom messages: `onExceed: ctx => ({ mode: 'steer', message
 ```ts
 behavior: {
   thinkingBudget: 8192,
-  thinkingDecay: { afterTurn: 5, factor: 0.5, floor: 1024 },
-  // turn 1-5 → 8192, turn 6 → 4096, turn 7 → 2048, turn 8+ → 1024
+  thinkingDecay: { afterTurn: 5, floor: 1024 },  // step: turns 1-5 → 8192, 6+ → 1024
 }
 ```
 
-Pass a function for arbitrary curves: `thinkingDecay: (turn, base) => base / Math.sqrt(turn)`. No-op when `thinkingBudget` is unset.
+**Prefer the step form (no `factor`) when prompt caching is on.** `thinking.budget_tokens` is part of Anthropic's cache key — a request with a different budget reads *nothing* back and re-bills the entire prefix (measured; pinned in the live suite). Each distinct value a schedule emits is one full re-bill: the step form costs exactly one per run, the geometric form `{ afterTurn: 5, factor: 0.5, floor: 1024 }` costs one per halving (8192 → 4096 → 2048 → 1024 = three), and a per-turn function like `(turn, base) => base / Math.sqrt(turn)` silently disables caching for the whole run. No-op when `thinkingBudget` is unset.
 
 ## Steering and Follow-up
 

package/dist/{acp-DZNCQaTQ.js → acp-Cs86McDR.js}

@@ -1,10 +1,10 @@
 import { l as toolResultToText } from "./types-BIarq1qE.js";
-import { c as resolveReadStateMap, r as hashContent, s as readStateKey } from "./read-state-rDmfeLmz.js";
-import { lt as basic_default, t as createAgent } from "./agent-CrPwqpLI.js";
-import { r as createProcessContext } from "./contexts-o8y5B3Tm.js";
+import { c as resolveReadStateMap, r as hashContent, s as readStateKey } from "./read-state-CNyeMG7W.js";
+import { dt as basic_default, t as createAgent } from "./agent-AZ_crMfB.js";
+import { r as createProcessContext } from "./contexts-DbMuUPjS.js";
 import { l as errorMessage } from "./errors-DJUxZg9b.js";
-import { w as defaultPromptMessage } from "./openai-compat-C77gOaHh.js";
-import { o as loadSession, t as createSession } from "./session-DpDBnktP.js";
+import { T as defaultPromptMessage } from "./openai-compat-DHlBIjj9.js";
+import { o as loadSession, t as createSession } from "./session-vmy9jTVM.js";
 import { t as effectiveInputFromTurn } from "./stats-DAKBEKjc.js";
 import { r as fetchUrl } from "./fetch-url-_5WKWpbQ.js";
 import { webSearch } from "./tools/web-search.js";
@@ -1920,4 +1920,4 @@ function runAcpStdioServer(options) {
 //#endregion
 export { createJsonRpcConnection as _, wrapToolsForAcpClient as a, sessionBlocksToAcp as c, StartUsageError as d, buildStartLocalOptions as f, JsonRpcRemoteError as g, startProviderNames as h, withAcpDefaultTools as i, stopReasonFromRun as l, startLocalArgOptions as m, AcpProtocolError as n, acpMcpServersToZidane as o, parseStartArgValues as p, createAcpServer as r, acpPromptToPromptParts as s, runAcpStdioServer as t, toolResultToAcpContent as u };
 
-//# sourceMappingURL=acp-DZNCQaTQ.js.map
+//# sourceMappingURL=acp-Cs86McDR.js.map