@inflexa-ai/harness 0.39.2 → 0.40.0

package/dist/providers/ai-sdk.js

@@ -1,5 +1,9 @@
+import { createHash } from "node:crypto";
 import { streamText, wrapLanguageModel, } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
+// Any `providerOptions.anthropic.thinking` bypasses this table's thinking
+// selection (see `thinkingWithBinding`).
+import { getModelCapabilities } from "@ai-sdk/anthropic/internal";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { OpenTelemetry } from "@ai-sdk/otel";
@@ -11,6 +15,7 @@ import { scopeWorkloadId } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { passThroughTracer } from "../lib/otel-spans.js";
 import { DEFAULT_SUSPEND_ON, classifyProviderError, RequestTimeoutError, toProviderError } from "./errors.js";
+import { DEFAULT_REASONING } from "./reasoning.js";
 import { headersRefusalError, requestHeadersFor } from "./request-headers.js";
 /**
  * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
@@ -25,11 +30,10 @@ export const RETRY_BACKOFF_FACTOR = 2;
 export const RETRY_MAX_DELAY_MS = 30_000;
 /**
  * Output-token ceiling requested when a config names none — a floor against a
- * provider default, not a target. `@ai-sdk/anthropic` resolves an unset value
- * from a capability table that lags Anthropic's releases and falls back to 4096
- * for ids it does not know, so the newest models silently truncate mid
- * tool-call. The SDK clamps this down per known model (opus-4-x to 32k,
- * claude-3-haiku to 4096), so it cannot over-request one it recognizes.
+ * provider default, not a target. For an unset value, `@ai-sdk/anthropic`
+ * defaults to 128000 for an unknown `claude-*` id and 4096 for a non-Claude
+ * id. The anthropic arm always sends a value, so it never truncates mid
+ * tool-call.
  *
  * Lower it per-config for servers that validate `prompt + max_tokens <= context`
  * (vLLM and similar) against a small-context model.
@@ -63,6 +67,50 @@ function routeSdkWarningsTo(logger) {
 function workloadOf(session) {
     return `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
 }
+/**
+ * Identifiers only, never a name or address. The run frame wins over the
+ * thread so parallel steps of one run keep separate gateway cache accounts.
+ */
+export function sessionKeyOf(session) {
+    const { scope, runFrame } = session;
+    if (runFrame !== undefined) {
+        return runFrame.stepId === undefined ? `${scope.analysisId}:${runFrame.runId}` : `${scope.analysisId}:${runFrame.runId}:${runFrame.stepId}`;
+    }
+    return scope.threadId === undefined ? scope.analysisId : `${scope.analysisId}:${scope.threadId}`;
+}
+/**
+ * Base64url SHA-256 digest of {@link sessionKeyOf}, always 43 characters.
+ * OpenAI and Azure reject a `prompt_cache_key` over 64 characters with a
+ * non-retryable 400.
+ */
+export function sessionKeyDigestOf(session) {
+    return createHash("sha256").update(sessionKeyOf(session)).digest("base64url");
+}
+/**
+ * CAUTION: setting `providerOptions.anthropic.thinking` without a `type`
+ * turns thinking off. Call only for a model whose capability row says
+ * `rejectsThinkingDisabled`.
+ */
+function thinkingWithBinding(reasoning, mode) {
+    const blockBinding = { prefixMismatchBehavior: mode };
+    if (reasoning === "none" || reasoning === "provider-default")
+        return { blockBinding };
+    return { type: "adaptive", display: "summarized", blockBinding };
+}
+/** Reads `providerMetadata.anthropic.inputTransformations`; empty for another vendor. */
+function inputTransformationsOf(metadata) {
+    const entries = metadata?.["anthropic"]?.["inputTransformations"];
+    if (!Array.isArray(entries))
+        return [];
+    return entries.map((entry) => {
+        const fields = typeof entry === "object" && entry !== null ? entry : {};
+        const text = (key) => {
+            const value = fields[key];
+            return typeof value === "string" ? value : undefined;
+        };
+        return { type: text("type"), path: text("path"), reason: text("reason") };
+    });
+}
 function isAbortError(value) {
     if (value instanceof DOMException && value.name === "AbortError")
         return true;
@@ -252,6 +300,10 @@ function toChatUsage(usage) {
 function requestedModelIdOf(model) {
     return typeof model === "string" ? model : model.modelId;
 }
+/** The provider id of the model bound into this provider, as the AI SDK names it — a bare id string names no provider. */
+function providerIdOf(model) {
+    return typeof model === "string" ? undefined : model.provider;
+}
 /**
  * Capture the served model id at the raw model boundary, because that is the
  * only place it is still distinguishable from the requested one: `streamText`
@@ -294,13 +346,13 @@ function captureServedModelId(model) {
     return { model: wrapped, servedModelId: () => served };
 }
 function responseFromMessages(input) {
-    const { messages, fallbackText, finishReason, rawFinishReason, requestedModelId, servedModelId } = input;
+    const { messages, fallbackText, finishReason, rawFinishReason, requestedModelId, servedModelId, provider } = input;
     const usage = toChatUsage(input.usage);
     const message = [...messages].reverse().find((m) => m.role === "assistant");
     if (message === undefined) {
-        return { message: { role: "assistant", content: fallbackText }, finishReason, rawFinishReason, usage, requestedModelId, servedModelId };
+        return { message: { role: "assistant", content: fallbackText }, finishReason, rawFinishReason, usage, requestedModelId, servedModelId, provider };
     }
-    return { message, finishReason, rawFinishReason, usage, requestedModelId, servedModelId };
+    return { message, finishReason, rawFinishReason, usage, requestedModelId, servedModelId, provider };
 }
 /**
  * Drop empty text parts — and messages left with no content at all — before
@@ -435,6 +487,8 @@ export function createAiSdkProvider(deps) {
     const suspendOn = deps.suspendOn ?? DEFAULT_SUSPEND_ON;
     const requestTimeoutMs = deps.requestTimeoutMs;
     const requestedModelId = requestedModelIdOf(deps.model);
+    const providerId = providerIdOf(deps.model);
+    const effortOf = (req) => req.reasoning ?? deps.reasoning ?? DEFAULT_REASONING;
     // Each model call emits OpenTelemetry GenAI spans through the AI SDK, with no
     // prompt or completion text on them. The integration rides on each call
     // instead of the global registry, so the harness never traces the embedder's
@@ -461,7 +515,18 @@ export function createAiSdkProvider(deps) {
             ...logger.errorFields(thrown),
         });
     }
+    /**
+     * Logs each dropped thinking block; the drop does not fail the call.
+     * `reason` is `prefix_binding_mismatch` or `model_binding_mismatch`.
+     */
+    function logDroppedThinkingBlocks(session, metadata) {
+        for (const drop of inputTransformationsOf(metadata)) {
+            logger.warn("thinking block dropped", { workload: workloadOf(session), type: drop.type, path: drop.path, reason: drop.reason });
+        }
+    }
     function chat(req, session, signal) {
+        const reasoning = effortOf(req);
+        const providerOptions = deps.providerOptionsFor?.({ session, reasoning });
         const run = async () => {
             const hookCall = { unsettled: false };
             const retry = createRetry(signal, logger, maxRetries, suspendOn, hookCall);
@@ -504,8 +569,8 @@ export function createAiSdkProvider(deps) {
                         // carries the one configured bound, and a turn that writes
                         // steadily runs as long as it needs.
                         ...(requestTimeoutMs !== undefined ? { timeout: { firstChunkMs: requestTimeoutMs, chunkMs: requestTimeoutMs } } : {}),
-                        providerOptions: req.providerOptions,
-                        reasoning: req.reasoning,
+                        providerOptions,
+                        reasoning,
                     });
                     // The drain sits inside the retried closure, thus a failure at any
                     // point of the stream re-runs the whole attempt and the envelope
@@ -530,14 +595,20 @@ export function createAiSdkProvider(deps) {
                         finishReason: await result.finishReason,
                         rawFinishReason: await result.rawFinishReason,
                         usage: await result.usage,
+                        providerMetadata: (await result.finalStep).providerMetadata,
                     };
                 });
+                // Logged past the envelope, thus only the attempt that succeeded
+                // reports its drops.
+                const { providerMetadata: metadata, ...reply } = collected;
+                logDroppedThinkingBlocks(session, metadata);
                 return ok(responseFromMessages({
-                    ...collected,
+                    ...reply,
                     requestedModelId,
                     // Read after the drain: the metadata chunk that carries the
                     // served id reaches the capture only as the stream is consumed.
                     servedModelId: capture.servedModelId(),
+                    provider: providerId,
                 }));
             }
             catch (e) {
@@ -551,6 +622,8 @@ export function createAiSdkProvider(deps) {
         return new ResultAsync(run());
     }
     async function* chatStream(req, session, signal) {
+        const reasoning = effortOf(req);
+        const providerOptions = deps.providerOptionsFor?.({ session, reasoning });
         const hookCall = { unsettled: false };
         const retry = createRetry(signal, logger, maxRetries, suspendOn, hookCall);
         const capture = captureServedModelId(deps.model);
@@ -583,8 +656,8 @@ export function createAiSdkProvider(deps) {
                     // no content, for example a keep-alive comment, produces no part,
                     // thus it feeds neither bound.
                     ...(requestTimeoutMs !== undefined ? { timeout: { firstChunkMs: requestTimeoutMs, chunkMs: requestTimeoutMs } } : {}),
-                    providerOptions: req.providerOptions,
-                    reasoning: req.reasoning,
+                    providerOptions,
+                    reasoning,
                 });
                 const iterator = result.fullStream[Symbol.asyncIterator]();
                 const first = await pullNextDelta(iterator);
@@ -612,11 +685,13 @@ export function createAiSdkProvider(deps) {
                         finishReason: await result.finishReason,
                         rawFinishReason: await result.rawFinishReason,
                         usage: await result.usage,
+                        providerMetadata: (await result.finalStep).providerMetadata,
                     };
                 }
                 return { kind: "streaming", result, iterator, firstDelta: first.text };
             });
             if (opened.kind === "completed") {
+                logDroppedThinkingBlocks(session, opened.providerMetadata);
                 const response = responseFromMessages({
                     messages: opened.messages,
                     fallbackText: "",
@@ -625,6 +700,7 @@ export function createAiSdkProvider(deps) {
                     usage: opened.usage,
                     requestedModelId,
                     servedModelId: capture.servedModelId(),
+                    provider: providerId,
                 });
                 yield { type: "done", response };
                 return;
@@ -655,7 +731,9 @@ export function createAiSdkProvider(deps) {
                 // Read after the drain: the metadata chunk carrying the served id
                 // reaches the capture only as the stream is consumed.
                 servedModelId: capture.servedModelId(),
+                provider: providerId,
             });
+            logDroppedThinkingBlocks(session, (await result.finalStep).providerMetadata);
             yield { type: "done", response };
         }
         catch (e) {
@@ -729,11 +807,10 @@ export function wrapFetchWithRequestTimeout(fetchImpl, requestTimeoutMs) {
  *
  * The middleware merges the value into the `openai` namespace of
  * `providerOptions`. It keeps each other namespace, and it keeps each other key
- * of the `openai` namespace, thus a cache directive of a different vendor rides
- * through untouched. The arm value wins over a request-level `store`, because
- * the retention mode belongs to the connection and not to one turn. A thread
- * that mixes the two modes replays a reference onto an item that the server
- * never stored.
+ * of the `openai` namespace, thus the session key of the call
+ * (`promptCacheKey`) rides through untouched. The retention mode belongs to the
+ * connection and not to one turn: a thread that mixes the two modes replays a
+ * reference onto an item that the server never stored.
  */
 function withStoreDirective(model, store) {
     return wrapLanguageModel({
@@ -783,6 +860,9 @@ export function createConfiguredAiSdkProvider(deps) {
         // must declare the capability. A config value overrides this default in
         // both directions.
         const pictureDefault = config.baseURL === undefined ? { imageToolResults: true } : {};
+        // A model that can run without thinking gets no binding (see `thinkingWithBinding`).
+        const bindingMode = config.thinkingBinding ?? "drop_block";
+        const binding = bindingMode !== "off" && getModelCapabilities(config.model).rejectsThinkingDisabled ? bindingMode : undefined;
         return createAiSdkProvider({
             model: provider.chat(config.model),
             ...hostPolicyOf(deps),
@@ -791,6 +871,15 @@ export function createConfiguredAiSdkProvider(deps) {
             ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
             ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
             ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
+            ...(config.reasoning !== undefined ? { reasoning: config.reasoning } : {}),
+            // The package sends the key as `metadata.user_id`, and the binding as
+            // `thinking.block_binding`.
+            providerOptionsFor: ({ session, reasoning }) => ({
+                anthropic: {
+                    metadata: { userId: sessionKeyDigestOf(session) },
+                    ...(binding !== undefined ? { thinking: thinkingWithBinding(reasoning, binding) } : {}),
+                },
+            }),
         });
     }
     if (config.kind === "openai") {
@@ -823,6 +912,10 @@ export function createConfiguredAiSdkProvider(deps) {
             maxOutputTokens: config.maxOutputTokens ?? "provider-maximum",
             ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
             ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
+            ...(config.reasoning !== undefined ? { reasoning: config.reasoning } : {}),
+            // The package sends the key as `prompt_cache_key`. The store
+            // directive merges into the same namespace, and it keeps this key.
+            providerOptionsFor: ({ session }) => ({ openai: { promptCacheKey: sessionKeyDigestOf(session) } }),
         });
     }
     const provider = createOpenAICompatible({
@@ -830,7 +923,12 @@ export function createConfiguredAiSdkProvider(deps) {
         baseURL: config.baseURL,
         apiKey: config.apiKey,
         fetch: effectiveFetch,
+        // Each call of the provider streams, `chat` included. Without this flag
+        // the package asks for no usage on a stream, and the call reports none.
+        includeUsage: true,
     });
+    // The compatible wire has no standard field for a session key, thus this arm
+    // gives no provider options of its own.
     return createAiSdkProvider({
         // The compatible package reads the neutral `reasoning` of the call, thus
         // the seam needs no middleware to carry the depth into its namespace.
@@ -841,5 +939,6 @@ export function createConfiguredAiSdkProvider(deps) {
         ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
         ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
         ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
+        ...(config.reasoning !== undefined ? { reasoning: config.reasoning } : {}),
     });
 }

package/dist/providers/errors.d.ts

@@ -89,6 +89,8 @@ export type SuspendError = Extract<ProviderError, {
  * and the non-enumerable `.cause` does not. Thus the walk also reads `.value`.
  */
 export declare function findSuspendError(err: unknown): SuspendError | undefined;
+/** Find a `ProviderError` of any kind, by the walk of {@link findSuspendError}. */
+export declare function findProviderError(err: unknown): ProviderError | undefined;
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
  * `classifyProviderError` with the `suspendOn` map of the provider, so the

package/dist/providers/errors.js

@@ -63,6 +63,11 @@ export function findSuspendError(err) {
     const asSuspend = (value) => (isProviderError(value) && value.type === "suspend" ? value : undefined);
     return findInCauseChain(err, (link) => asSuspend(link) ?? (typeof link === "object" && link !== null ? asSuspend(link.value) : undefined));
 }
+/** Find a `ProviderError` of any kind, by the walk of {@link findSuspendError}. */
+export function findProviderError(err) {
+    const asProviderError = (value) => (isProviderError(value) ? value : undefined);
+    return findInCauseChain(err, (link) => asProviderError(link) ?? (typeof link === "object" && link !== null ? asProviderError(link.value) : undefined));
+}
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
  * `classifyProviderError` with the `suspendOn` map of the provider, so the

package/dist/providers/prompt-cache.d.ts

@@ -15,29 +15,17 @@
  * error — on an OpenAI-compatible model, which is exactly what we want: that
  * family does automatic server-side prefix caching and needs no directive.
  *
- * ## What the Anthropic namespace does, and where the marker must go
- *
- * The options go on the LAST MESSAGE of the request, never on the request
- * itself. Both placements cache the same bytes — one breakpoint at the end of
- * the messages covers the whole prefix (tools → system → history), because the
- * cache keys on a prefix — but only the message placement survives an
- * intermediary.
- *
- * A REQUEST-level `cacheControl` makes the provider emit a top-level
- * `cache_control` field instead of a per-block marker, and the server then
- * places the breakpoint itself. That is one fewer thing for the harness to get
- * right, and it is why this module used to do it. It is also invisible: an
- * intermediary that counts breakpoints to stay under Anthropic's cap of four
- * counts BLOCKS, so a top-level field is a breakpoint nothing on the way
- * upstream can see. CLIProxyAPI — what the OSS CLI routes through on the Claude
- * OAuth path — injects up to four block markers of its own and trims to four by
- * that blind count, so the harness's invisible fifth breakpoint made every
- * request past a thread's first turn fail with `A maximum of 4 blocks with
- * cache_control may be provided. Found 5.` (HTTP 400, non-retryable — the thread
- * is wedged, because the next turn rebuilds the same shape).
- *
- * A marker on a message block is counted, trimmed, and reasoned about by every
- * hop. Keep it there. {@link withPromptCacheBreakpoint} is the only writer.
+ * ## What the Anthropic namespace does, and where the markers must go
+ *
+ * A request carries two markers, each on a block, never on the request itself:
+ * {@link withSystemPromptBreakpoint} at the end of the system prompt, and
+ * {@link withPromptCacheBreakpoint} at the last eligible message.
+ *
+ * A REQUEST-level `cacheControl` emits an invisible top-level field instead.
+ * CLIProxyAPI (the Claude OAuth path) counts BLOCKS toward Anthropic's cap of
+ * four, not this field, so the uncounted marker overflows it and fails with
+ * `A maximum of 4 blocks with cache_control may be provided. Found 5.`
+ * (HTTP 400, non-retryable — the thread stays wedged).
  *
  * ## Which vendors need a marker at all
  *
@@ -54,9 +42,9 @@
  * cache RESOURCE created out of band and referenced by name, which is not a
  * marker and does not fit a ttl policy.
  *
- * So both markers ride together on the one chosen message. A provider reads only
- * its own namespace, thus the pair is free to whichever vendor is not serving
- * the call, and the placement never learns which one that is.
+ * So both vendor markers ride together on each chosen message. A provider reads
+ * only its own namespace, thus the pair is free to whichever vendor is not
+ * serving the call, and the placement never learns which one that is.
  *
  * The asymmetry worth remembering: under-marking silently costs money, while
  * over-marking hard-fails. Anthropic answers 400 past four breakpoints, and the
@@ -65,20 +53,18 @@
  *
  * ## Cache defeaters — what silently kills the hit rate
  *
- * The cache keys on an *exact prefix*. Anything that perturbs the head of the
- * request invalidates everything after it. One known defeater remains in this
- * codebase, flagged at its own site as a separate change:
+ * The cache keys on an *exact prefix*, so anything that perturbs the head of the
+ * request invalidates everything after it. The wrap-up of `runAgent`, the
+ * salvage of `runToTerminal`, and a step's summary and file-metadata
+ * continuations extend one conversation under a tool mask, thus they keep its
+ * prefix (`loop/run-agent.ts`, `loop/continue-agent.ts`). A tool choice that
+ * forbids a call would defeat the cache — see the CAUTION on `ChatRequest.toolChoice`.
  *
- *  1. `runAgent`'s forced wrap-up swaps the tool set to `{}` — tools sit at the
- *     very front of the prefix, so that one call reads nothing back and rewrites
- *     the cache from scratch (`loop/run-agent.ts`).
+ * `loadRecent` gives the view of the latest compaction marker
+ * (`memory/conversation-view.ts`). A compaction moves the start of the view one
+ * time, and the message prefix holds still between two compactions.
  *
- * `loadRecent`'s history eviction used to be a second defeater — it advanced the
- * window one turn per turn, shifting the message prefix every request. It now
- * evicts in whole blocks so the prefix holds still between block boundaries
- * (`memory/thread-history.ts`).
- *
- * A sandbox agent's system prompt is NOT one of them: it is a pure function of
+ * A sandbox agent's system prompt is NOT a defeater: it is a pure function of
  * its agent type, byte-identical across every step of every run, and the per-step
  * paths ride in the step's briefing instead (`agents/sandbox/shared.ts`,
  * `prompts/briefing.ts`). Keep it that way — one interpolated id or path there
@@ -106,6 +92,7 @@
  * flat-zero read counter beside a non-zero write counter is still the signature
  * of an endpoint billing for writes and serving no reads.
  */
+import type { SystemModelMessage } from "ai";
 import type { ModelMessage, PromptCachePolicy, ProviderOptions } from "./types.js";
 /**
  * The default policy: cache with the 5-minute TTL.
@@ -120,6 +107,12 @@ import type { ModelMessage, PromptCachePolicy, ProviderOptions } from "./types.j
  * premium for a cache nothing ever reads.
  */
 export declare const DEFAULT_PROMPT_CACHE: PromptCachePolicy;
+/**
+ * The policy of the root loop of a chat turn only: a person can reply 5 to 60 minutes later, and a
+ * 5-minute entry does not last that gap. Each other loop keeps {@link DEFAULT_PROMPT_CACHE}, because
+ * its requests start less than 5 minutes apart.
+ */
+export declare const CONVERSATION_PROMPT_CACHE: PromptCachePolicy;
 /**
  * Translate a neutral cache policy into provider wire options.
  *
@@ -141,11 +134,20 @@ export declare const DEFAULT_PROMPT_CACHE: PromptCachePolicy;
  *
  * CAUTION: this is the marker's VALUE, not its placement. Attaching it to a
  * `ChatRequest` emits the invisible top-level field the module header warns
- * about. Place it with {@link withPromptCacheBreakpoint}.
+ * about. Place it with {@link withSystemPromptBreakpoint} and
+ * {@link withPromptCacheBreakpoint}.
  */
 export declare function promptCacheProviderOptions(policy: PromptCachePolicy): ProviderOptions | undefined;
 /**
- * Place the request's ONE cache breakpoint, on the last message that can host it.
+ * Marks the end of the system prompt, the sibling marker of {@link withPromptCacheBreakpoint}.
+ *
+ * Skips an empty prompt — the Anthropic package renders it as an empty text
+ * block, which cannot carry a marker.
+ */
+export declare function withSystemPromptBreakpoint(system: string, policy: PromptCachePolicy): string | SystemModelMessage;
+/**
+ * Places the message-level breakpoint on the last eligible message — the sibling
+ * marker sits at the end of the system prompt ({@link withSystemPromptBreakpoint}).
  *
  * Returns a copy — the caller's array is the transcript the loop keeps pushing
  * onto and the host later persists, and a marker written into it would ride into
@@ -160,7 +162,7 @@ export declare function promptCacheProviderOptions(policy: PromptCachePolicy): P
  * what an agent loop needs.
  *
  * A marker already on any other message is REMOVED — the invariant is exactly one
- * breakpoint per request, and a stored message that carries one from an older
+ * breakpoint among the messages, and a stored message that carries one from an older
  * build (`memory/ai-sdk-message-storage.ts` reads `cache_control` back off a
  * stored block) would otherwise spend a slot that the harness never budgeted.
  * `"off"` strips and places nothing, so turning caching off really does send no

package/dist/providers/prompt-cache.js

@@ -15,29 +15,17 @@
  * error — on an OpenAI-compatible model, which is exactly what we want: that
  * family does automatic server-side prefix caching and needs no directive.
  *
- * ## What the Anthropic namespace does, and where the marker must go
- *
- * The options go on the LAST MESSAGE of the request, never on the request
- * itself. Both placements cache the same bytes — one breakpoint at the end of
- * the messages covers the whole prefix (tools → system → history), because the
- * cache keys on a prefix — but only the message placement survives an
- * intermediary.
- *
- * A REQUEST-level `cacheControl` makes the provider emit a top-level
- * `cache_control` field instead of a per-block marker, and the server then
- * places the breakpoint itself. That is one fewer thing for the harness to get
- * right, and it is why this module used to do it. It is also invisible: an
- * intermediary that counts breakpoints to stay under Anthropic's cap of four
- * counts BLOCKS, so a top-level field is a breakpoint nothing on the way
- * upstream can see. CLIProxyAPI — what the OSS CLI routes through on the Claude
- * OAuth path — injects up to four block markers of its own and trims to four by
- * that blind count, so the harness's invisible fifth breakpoint made every
- * request past a thread's first turn fail with `A maximum of 4 blocks with
- * cache_control may be provided. Found 5.` (HTTP 400, non-retryable — the thread
- * is wedged, because the next turn rebuilds the same shape).
- *
- * A marker on a message block is counted, trimmed, and reasoned about by every
- * hop. Keep it there. {@link withPromptCacheBreakpoint} is the only writer.
+ * ## What the Anthropic namespace does, and where the markers must go
+ *
+ * A request carries two markers, each on a block, never on the request itself:
+ * {@link withSystemPromptBreakpoint} at the end of the system prompt, and
+ * {@link withPromptCacheBreakpoint} at the last eligible message.
+ *
+ * A REQUEST-level `cacheControl` emits an invisible top-level field instead.
+ * CLIProxyAPI (the Claude OAuth path) counts BLOCKS toward Anthropic's cap of
+ * four, not this field, so the uncounted marker overflows it and fails with
+ * `A maximum of 4 blocks with cache_control may be provided. Found 5.`
+ * (HTTP 400, non-retryable — the thread stays wedged).
  *
  * ## Which vendors need a marker at all
  *
@@ -54,9 +42,9 @@
  * cache RESOURCE created out of band and referenced by name, which is not a
  * marker and does not fit a ttl policy.
  *
- * So both markers ride together on the one chosen message. A provider reads only
- * its own namespace, thus the pair is free to whichever vendor is not serving
- * the call, and the placement never learns which one that is.
+ * So both vendor markers ride together on each chosen message. A provider reads
+ * only its own namespace, thus the pair is free to whichever vendor is not
+ * serving the call, and the placement never learns which one that is.
  *
  * The asymmetry worth remembering: under-marking silently costs money, while
  * over-marking hard-fails. Anthropic answers 400 past four breakpoints, and the
@@ -65,20 +53,18 @@
  *
  * ## Cache defeaters — what silently kills the hit rate
  *
- * The cache keys on an *exact prefix*. Anything that perturbs the head of the
- * request invalidates everything after it. One known defeater remains in this
- * codebase, flagged at its own site as a separate change:
- *
- *  1. `runAgent`'s forced wrap-up swaps the tool set to `{}` — tools sit at the
- *     very front of the prefix, so that one call reads nothing back and rewrites
- *     the cache from scratch (`loop/run-agent.ts`).
+ * The cache keys on an *exact prefix*, so anything that perturbs the head of the
+ * request invalidates everything after it. The wrap-up of `runAgent`, the
+ * salvage of `runToTerminal`, and a step's summary and file-metadata
+ * continuations extend one conversation under a tool mask, thus they keep its
+ * prefix (`loop/run-agent.ts`, `loop/continue-agent.ts`). A tool choice that
+ * forbids a call would defeat the cache — see the CAUTION on `ChatRequest.toolChoice`.
  *
- * `loadRecent`'s history eviction used to be a second defeater — it advanced the
- * window one turn per turn, shifting the message prefix every request. It now
- * evicts in whole blocks so the prefix holds still between block boundaries
- * (`memory/thread-history.ts`).
+ * `loadRecent` gives the view of the latest compaction marker
+ * (`memory/conversation-view.ts`). A compaction moves the start of the view one
+ * time, and the message prefix holds still between two compactions.
  *
- * A sandbox agent's system prompt is NOT one of them: it is a pure function of
+ * A sandbox agent's system prompt is NOT a defeater: it is a pure function of
  * its agent type, byte-identical across every step of every run, and the per-step
  * paths ride in the step's briefing instead (`agents/sandbox/shared.ts`,
  * `prompts/briefing.ts`). Keep it that way — one interpolated id or path there
@@ -119,6 +105,12 @@
  * premium for a cache nothing ever reads.
  */
 export const DEFAULT_PROMPT_CACHE = { ttl: "5m" };
+/**
+ * The policy of the root loop of a chat turn only: a person can reply 5 to 60 minutes later, and a
+ * 5-minute entry does not last that gap. Each other loop keeps {@link DEFAULT_PROMPT_CACHE}, because
+ * its requests start less than 5 minutes apart.
+ */
+export const CONVERSATION_PROMPT_CACHE = { ttl: "1h" };
 /**
  * Translate a neutral cache policy into provider wire options.
  *
@@ -140,7 +132,8 @@ export const DEFAULT_PROMPT_CACHE = { ttl: "5m" };
  *
  * CAUTION: this is the marker's VALUE, not its placement. Attaching it to a
  * `ChatRequest` emits the invisible top-level field the module header warns
- * about. Place it with {@link withPromptCacheBreakpoint}.
+ * about. Place it with {@link withSystemPromptBreakpoint} and
+ * {@link withPromptCacheBreakpoint}.
  */
 export function promptCacheProviderOptions(policy) {
     if (policy === "off")
@@ -149,6 +142,18 @@ export function promptCacheProviderOptions(policy) {
     const bedrock = { cachePoint: { type: "default", ttl: policy.ttl } };
     return { anthropic, bedrock };
 }
+/**
+ * Marks the end of the system prompt, the sibling marker of {@link withPromptCacheBreakpoint}.
+ *
+ * Skips an empty prompt — the Anthropic package renders it as an empty text
+ * block, which cannot carry a marker.
+ */
+export function withSystemPromptBreakpoint(system, policy) {
+    const providerOptions = promptCacheProviderOptions(policy);
+    if (providerOptions === undefined || system === "")
+        return system;
+    return { role: "system", content: system, providerOptions };
+}
 /**
  * Every namespace that can carry a breakpoint, and the key it carries it under.
  *
@@ -229,7 +234,8 @@ function withoutBreakpoint(message) {
     return { ...message, providerOptions: remaining };
 }
 /**
- * Place the request's ONE cache breakpoint, on the last message that can host it.
+ * Places the message-level breakpoint on the last eligible message — the sibling
+ * marker sits at the end of the system prompt ({@link withSystemPromptBreakpoint}).
  *
  * Returns a copy — the caller's array is the transcript the loop keeps pushing
  * onto and the host later persists, and a marker written into it would ride into
@@ -244,7 +250,7 @@ function withoutBreakpoint(message) {
  * what an agent loop needs.
  *
  * A marker already on any other message is REMOVED — the invariant is exactly one
- * breakpoint per request, and a stored message that carries one from an older
+ * breakpoint among the messages, and a stored message that carries one from an older
  * build (`memory/ai-sdk-message-storage.ts` reads `cache_control` back off a
  * stored block) would otherwise spend a slot that the harness never budgeted.
  * `"off"` strips and places nothing, so turning caching off really does send no

package/dist/providers/reasoning.d.ts

@@ -1,35 +1,24 @@
 /**
- * The reasoning depth of a run.
+ * The reasoning depth of a call.
  *
- * The harness states the depth one time, on `ChatRequest.reasoning`, with the
- * neutral names of the AI SDK. It names no vendor key. Each provider package
- * holds the table of what its own models accept, and it maps the neutral name
- * onto the wire. The Anthropic package also selects adaptive thinking there.
+ * The effort resolves in order: `ChatRequest.reasoning` (set only through
+ * `RunAgentOptions.reasoning`), the provider configuration's `reasoning`, then
+ * {@link DEFAULT_REASONING}. Anthropic discards its message cache when the
+ * top-level effort changes between calls.
  *
- * ## Why the harness names no vendor key
- *
- * The harness wrote `providerOptions.anthropic.effort` before. A value on that
- * key turns the per-model table of the Anthropic package off, thus the raw name
- * reached the wire. A model that accepts `high` but not `xhigh` answered 400.
- * The neutral field has no such hazard, because the package resolves the name
- * for the model that it is bound to.
- *
- * ## Where the policy belongs
- *
- * The policy rides on the run, not on the provider, for the same reason that the
- * cache policy does. A one-shot LLM call elsewhere in the harness has its own
- * depth needs, and it must not inherit the depth of an agent loop.
+ * Do not set `providerOptions.anthropic.effort` directly. It bypasses the
+ * per-model table, and a model that rejects the raw name answers 400.
  */
 import type { ReasoningPolicy } from "./types.js";
 /**
- * The default policy: the deepest name of the neutral ladder.
+ * The last source of the effort: the deepest rung of the neutral ladder.
  *
  * Each agent of the harness drives tools over many iterations. A shallow turn
  * there wastes more calls than a deeper turn costs in tokens. The Anthropic
  * package sends `xhigh` to a model that accepts it, and `max` to a model that
  * does not. The OpenAI-compatible package sends the name as it is.
  *
- * A host that wants a cheaper loop passes a lower name. A host on a model with
- * no reasoning support passes `"provider-default"`.
+ * A host that wants a cheaper role sets a lower name on that role's provider
+ * configuration. With no reasoning support, a host sets `"provider-default"`.
  */
 export declare const DEFAULT_REASONING: ReasoningPolicy;