@inflexa-ai/harness 0.35.0 → 0.35.1

package/README.md

@@ -9,6 +9,7 @@ Requirements:
 - Node.js `>=24` (the runtime; Bun is used only to run tests)
 - Postgres with pgvector (app tables + durable workflow state)
 - a sandbox backend, selected by `SANDBOX_BACKEND` (`docker` | `k8s`)
+- a package store, plus a `farmSource` that names where the package farm of an analysis comes from
 - a chat/embedding provider — Anthropic, or any OpenAI-compatible endpoint
 
 ```bash
@@ -18,6 +19,8 @@ tsc -p tsconfig.json              # build: emit dist/ from src/ (also `npm run b
 bun test                          # run the test suite
 ```
 
+The runtime image bakes no R or Python package, so the packages arrive from a host **package store** that the backend mounts read-only at `/mnt/libs`. `farmSource` is a **required** backend config field, and it has two kinds: `fixed` names one farm for every analysis (the managed shape), and `per-analysis` supplies a resolver of the embedder. `ExtendAnalysisFarm` is the optional link seam behind the `link_packages` tool. The harness composes no farm and installs nothing — the embedder owns the store — and the harness names the missing packages but no host command, because a managed deployment holds no `inflexa` binary.
+
 The package emits `dist/` from `src/` and publishes only `dist`. Most configuration arrives through dependency objects passed to the composition point — the LLM backend, for instance, is a fully injected provider config (endpoint/key/model or a `LanguageModel` instance), not read from env; helper modules read conventional env vars (`DB_PG_*`, sandbox limits) — see `CONTEXT.md` and the specs for the catalog.
 
 ## Public surface

package/dist/index.d.ts

@@ -71,7 +71,7 @@ export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps } from "./provide
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
 export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, ReasoningPolicy, } from "./providers/types.js";
-export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "./providers/prompt-cache.js";
+export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";

package/dist/index.js

@@ -110,8 +110,14 @@ export { createEmbeddingProvider } from "./providers/embedding.js";
 // re-sends its prefix every iteration and breaks even immediately). Hosts whose
 // endpoint ignores cache directives — notably the Claude Max OAuth path — pass
 // `"off"`; the `cortex.harness.agent.cache_*_tokens` metrics show which case a
-// deployment is actually in.
-export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "./providers/prompt-cache.js";
+// deployment is actually in. `withPromptCacheBreakpoint` is the placement: it
+// puts the ONE marker of a request on its last message, where every hop upstream
+// can count it, in the namespace of each vendor that needs an explicit
+// breakpoint (Anthropic and Bedrock; the OpenAI family and Gemini cache without
+// one). Never attach `promptCacheProviderOptions` to a request itself — that
+// emits a top-level field an intermediary cannot see, and a proxy that trims to
+// Anthropic's cap of four breakpoints then sends five.
+export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
 // Reasoning depth. `ReasoningPolicy` is the vendor-neutral name for how deep a
 // model reasons; a composition root sets it per run through
 // `RunAgentOptions.reasoning`. It defaults to `DEFAULT_REASONING` — `xhigh` —

package/dist/loop/run-agent.js

@@ -7,7 +7,7 @@ import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { stripUnansweredToolCalls } from "../memory/tool-call-integrity.js";
 import { classifyProviderError } from "../providers/errors.js";
-import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
+import { DEFAULT_PROMPT_CACHE, withPromptCacheBreakpoint } from "../providers/prompt-cache.js";
 import { DEFAULT_REASONING } from "../providers/reasoning.js";
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
@@ -82,10 +82,11 @@ export async function runAgent(agent, initial, session, opts) {
     // `debug` records name the tools when that distinction is not enough.
     let toolCallCount = 0;
     let toolErrorCount = 0;
-    // Resolved once, not per iteration: an identical options object across every
-    // call is itself part of the cache contract — the request prefix has to be
-    // byte-identical to be read back.
-    const providerOptions = promptCacheProviderOptions(opts.promptCache ?? DEFAULT_PROMPT_CACHE);
+    // Resolved once, not per iteration: an identical policy across every call is
+    // itself part of the cache contract — the request prefix has to be
+    // byte-identical to be read back. The breakpoint it places is re-derived per
+    // call, because it rides the last message and the transcript grows.
+    const promptCache = opts.promptCache ?? DEFAULT_PROMPT_CACHE;
     // The depth is a neutral name, and the provider package resolves it for the
     // model. A vendor key here would turn that resolution off.
     const reasoning = opts.reasoning ?? DEFAULT_REASONING;
@@ -232,10 +233,9 @@ export async function runAgent(agent, initial, session, opts) {
         iterations = i + 1;
         const request = {
             system: agent.systemPrompt,
-            messages,
+            messages: withPromptCacheBreakpoint(messages, promptCache),
             tools: toolDefs,
             ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
-            providerOptions,
             reasoning,
         };
         const llmStepName = formatStepName.llm(i);
@@ -343,11 +343,11 @@ export async function runAgent(agent, initial, session, opts) {
     // Cache defeater (known; not fixed here). Emptying the tool set changes the
     // very front of the request prefix — tool definitions are cached ahead of
     // system and history — so this call reads *nothing* back from the cache and
-    // rewrites the whole prefix from scratch. It still carries the cache options
+    // rewrites the whole prefix from scratch. It still places the breakpoint
     // because it is the one call whose write is pure waste, and the
     // cache_write_tokens counter is what makes that waste visible.
     const wrapUpStepName = formatStepName.llm(agent.maxIterations);
-    const wrapUp = await resultStep(runStep)(wrapUpStepName, () => provider.chat({ system: agent.systemPrompt, messages, tools: {}, toolChoice: "none", providerOptions, reasoning }, session, signal));
+    const wrapUp = await resultStep(runStep)(wrapUpStepName, () => provider.chat({ system: agent.systemPrompt, messages: withPromptCacheBreakpoint(messages, promptCache), tools: {}, toolChoice: "none", reasoning }, session, signal));
     accountForCall(wrapUp, wrapUpStepName);
     if (wrapUp.finishReason === "aborted") {
         // An abort during the tool-less wrap-up is still the user cutting the turn — the

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

@@ -15,12 +15,53 @@
  * 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
+ * ## What the Anthropic namespace does, and where the marker must go
  *
- * A request-level `cacheControl` makes the provider emit a single top-level
- * `cache_control` marker; the server then places the breakpoint on the last
- * cacheable block, so the whole prefix (tools → system → history) is cached
- * without the harness hand-placing per-block markers.
+ * 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.
+ *
+ * ## Which vendors need a marker at all
+ *
+ * Only two of them, and both take it on a message:
+ *
+ *  - **Anthropic** — `anthropic.cacheControl`. Fully opt-in: no marker, no
+ *    caching, at full price.
+ *  - **Amazon Bedrock** — `bedrock.cachePoint`. Also fully opt-in.
+ *
+ * The OpenAI family caches prefixes server-side, unprompted, and exposes no
+ * breakpoint to place (`promptCacheKey` and `promptCacheRetention` are request
+ * settings for affinity and retention, not placement — a separate concern from
+ * this policy). Gemini caches implicitly by default, and its explicit mode is a
+ * 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.
+ *
+ * The asymmetry worth remembering: under-marking silently costs money, while
+ * over-marking hard-fails. Anthropic answers 400 past four breakpoints, and the
+ * legacy Bedrock integration answers 400 on a top-level `cache_control`. Every
+ * failure in this area comes from asking for too much.
  *
  * ## Cache defeaters — what silently kills the hit rate
  *
@@ -43,15 +84,29 @@
  * `prompts/briefing.ts`). Keep it that way — one interpolated id or path there
  * makes every step's ~20k-char prefix unique.
  *
- * ## Where caching is a no-op regardless
+ * ## What the cache-token metrics do and do not prove
+ *
+ * Caching DOES engage on the Claude OAuth path the OSS CLI routes through a
+ * local CLIProxyAPI: measured, 2050-2151 cache-read tokens on the turns after
+ * the first. An earlier note here claimed that path ignores cache directives
+ * outright. It does not.
  *
- * The Claude Max OAuth path does not honour cache directives, and the OSS CLI
- * defaults to routing through a local CLIProxyAPI on exactly that path. Caching
- * only engages against a direct API key or a gateway. The cache-token metrics
- * (`loop/metrics.ts`) are what tell the two apart at runtime — a flat-zero
- * `cache_read_tokens` counter is the symptom.
+ * But a read there is not evidence that OUR breakpoint earned it. While cloaking
+ * — which is what that path does — the proxy places breakpoints of its own on
+ * the system block, the first user message, the system message it relocates, and
+ * the last message. Those cache the prefix whatever the harness sends: with
+ * `promptCache: "off"` and no marker of ours on the wire, a repeat request still
+ * read 1902 tokens back.
+ *
+ * So on that path `cache_read_tokens` (`loop/metrics.ts`) reports whether the
+ * deployment gets caching at all, which is what the counter is for. It does not
+ * attribute the read, and it cannot tell a working harness breakpoint from a
+ * proxy that is quietly doing the work. Against a direct API key or a gateway,
+ * where nothing injects markers, the counter does mean exactly that — and a
+ * 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 { PromptCachePolicy, ProviderOptions } from "./types.js";
+import type { ModelMessage, PromptCachePolicy, ProviderOptions } from "./types.js";
 /**
  * The default policy: cache with the 5-minute TTL.
  *
@@ -68,7 +123,47 @@ export declare const DEFAULT_PROMPT_CACHE: PromptCachePolicy;
 /**
  * Translate a neutral cache policy into provider wire options.
  *
- * Returns `undefined` for `"off"` so the caller can leave `providerOptions`
- * entirely unset rather than sending an empty bag.
+ * Returns `undefined` for `"off"` so the caller can leave the bag entirely unset
+ * rather than sending an empty one.
+ *
+ * Both vendors that take an explicit marker get one, in their own namespace. A
+ * provider reads only its own key, so the pair costs nothing to whichever one is
+ * not serving the call, and the placement needs no idea which vendor it is
+ * talking to. The two shapes differ in more than spelling: Anthropic marks the
+ * last content block of the message, while Bedrock appends a `cachePoint` block
+ * after it. Both end up at the same position in the prefix.
+ *
+ * The `satisfies` clauses are the point of naming the vendor types at all. This
+ * bag is a `Record<string, JSONObject>`, thus nothing here is checked by
+ * default, and a renamed key would compile and silently stop caching —
+ * `cacheControl` has already been renamed once, and the provider still accepts
+ * `cache_control` as its alias.
+ *
+ * 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}.
  */
 export declare function promptCacheProviderOptions(policy: PromptCachePolicy): ProviderOptions | undefined;
+/**
+ * Place the request's ONE cache breakpoint, on the last message that can host it.
+ *
+ * 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
+ * the stored thread and come back on every later turn, one more breakpoint per
+ * turn until the request is refused. Only the request-shaped copy carries one.
+ *
+ * The placement is deliberately ROLLING, not pinned to the end of the stable
+ * prefix: within one run the loop appends an assistant reply and its tool results
+ * on every iteration, and a breakpoint that advances with them lets iteration N+1
+ * read back everything iteration N wrote. A pinned breakpoint would re-process
+ * the whole tool transcript uncached on every iteration, which is the opposite of
+ * 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
+ * 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
+ * directive at all.
+ */
+export declare function withPromptCacheBreakpoint<M extends ModelMessage>(messages: readonly M[], policy: PromptCachePolicy): readonly M[];

package/dist/providers/prompt-cache.js

@@ -15,12 +15,53 @@
  * 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
+ * ## What the Anthropic namespace does, and where the marker must go
  *
- * A request-level `cacheControl` makes the provider emit a single top-level
- * `cache_control` marker; the server then places the breakpoint on the last
- * cacheable block, so the whole prefix (tools → system → history) is cached
- * without the harness hand-placing per-block markers.
+ * 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.
+ *
+ * ## Which vendors need a marker at all
+ *
+ * Only two of them, and both take it on a message:
+ *
+ *  - **Anthropic** — `anthropic.cacheControl`. Fully opt-in: no marker, no
+ *    caching, at full price.
+ *  - **Amazon Bedrock** — `bedrock.cachePoint`. Also fully opt-in.
+ *
+ * The OpenAI family caches prefixes server-side, unprompted, and exposes no
+ * breakpoint to place (`promptCacheKey` and `promptCacheRetention` are request
+ * settings for affinity and retention, not placement — a separate concern from
+ * this policy). Gemini caches implicitly by default, and its explicit mode is a
+ * 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.
+ *
+ * The asymmetry worth remembering: under-marking silently costs money, while
+ * over-marking hard-fails. Anthropic answers 400 past four breakpoints, and the
+ * legacy Bedrock integration answers 400 on a top-level `cache_control`. Every
+ * failure in this area comes from asking for too much.
  *
  * ## Cache defeaters — what silently kills the hit rate
  *
@@ -43,13 +84,27 @@
  * `prompts/briefing.ts`). Keep it that way — one interpolated id or path there
  * makes every step's ~20k-char prefix unique.
  *
- * ## Where caching is a no-op regardless
+ * ## What the cache-token metrics do and do not prove
  *
- * The Claude Max OAuth path does not honour cache directives, and the OSS CLI
- * defaults to routing through a local CLIProxyAPI on exactly that path. Caching
- * only engages against a direct API key or a gateway. The cache-token metrics
- * (`loop/metrics.ts`) are what tell the two apart at runtime — a flat-zero
- * `cache_read_tokens` counter is the symptom.
+ * Caching DOES engage on the Claude OAuth path the OSS CLI routes through a
+ * local CLIProxyAPI: measured, 2050-2151 cache-read tokens on the turns after
+ * the first. An earlier note here claimed that path ignores cache directives
+ * outright. It does not.
+ *
+ * But a read there is not evidence that OUR breakpoint earned it. While cloaking
+ * — which is what that path does — the proxy places breakpoints of its own on
+ * the system block, the first user message, the system message it relocates, and
+ * the last message. Those cache the prefix whatever the harness sends: with
+ * `promptCache: "off"` and no marker of ours on the wire, a repeat request still
+ * read 1902 tokens back.
+ *
+ * So on that path `cache_read_tokens` (`loop/metrics.ts`) reports whether the
+ * deployment gets caching at all, which is what the counter is for. It does not
+ * attribute the read, and it cannot tell a working harness breakpoint from a
+ * proxy that is quietly doing the work. Against a direct API key or a gateway,
+ * where nothing injects markers, the counter does mean exactly that — and a
+ * flat-zero read counter beside a non-zero write counter is still the signature
+ * of an endpoint billing for writes and serving no reads.
  */
 /**
  * The default policy: cache with the 5-minute TTL.
@@ -67,11 +122,138 @@ export const DEFAULT_PROMPT_CACHE = { ttl: "5m" };
 /**
  * Translate a neutral cache policy into provider wire options.
  *
- * Returns `undefined` for `"off"` so the caller can leave `providerOptions`
- * entirely unset rather than sending an empty bag.
+ * Returns `undefined` for `"off"` so the caller can leave the bag entirely unset
+ * rather than sending an empty one.
+ *
+ * Both vendors that take an explicit marker get one, in their own namespace. A
+ * provider reads only its own key, so the pair costs nothing to whichever one is
+ * not serving the call, and the placement needs no idea which vendor it is
+ * talking to. The two shapes differ in more than spelling: Anthropic marks the
+ * last content block of the message, while Bedrock appends a `cachePoint` block
+ * after it. Both end up at the same position in the prefix.
+ *
+ * The `satisfies` clauses are the point of naming the vendor types at all. This
+ * bag is a `Record<string, JSONObject>`, thus nothing here is checked by
+ * default, and a renamed key would compile and silently stop caching —
+ * `cacheControl` has already been renamed once, and the provider still accepts
+ * `cache_control` as its alias.
+ *
+ * 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}.
  */
 export function promptCacheProviderOptions(policy) {
     if (policy === "off")
         return undefined;
-    return { anthropic: { cacheControl: { type: "ephemeral", ttl: policy.ttl } } };
+    const anthropic = { cacheControl: { type: "ephemeral", ttl: policy.ttl } };
+    const bedrock = { cachePoint: { type: "default", ttl: policy.ttl } };
+    return { anthropic, bedrock };
+}
+/**
+ * Every namespace that can carry a breakpoint, and the key it carries it under.
+ *
+ * The writer and the stripper both read this list, thus they cannot drift apart,
+ * and the one-breakpoint invariant covers each vendor rather than only the one
+ * that happens to be serving the call. `@ai-sdk/amazon-bedrock` reads either
+ * `bedrock` or `amazonBedrock`; its own documentation uses `bedrock`.
+ */
+const BREAKPOINT_SITES = [
+    ["anthropic", "cacheControl"],
+    ["bedrock", "cachePoint"],
+];
+/**
+ * Whether a message can HOST the breakpoint — that is, whether the marker put on
+ * it actually reaches the wire.
+ *
+ * The Anthropic provider resolves a message-level marker onto the message's last
+ * content part. A thinking block cannot carry `cache_control`, so a marker on an
+ * assistant message that ends in one is dropped by the provider: no error, no
+ * breakpoint, and a silent cache miss on every call after it. Walking back past
+ * such a message is what the server-side placement did for us before, so this
+ * keeps the behaviour rather than introducing a new failure mode.
+ *
+ * An empty content array hosts nothing either — there is no last part to mark.
+ * The content is read as `unknown` because the four message roles carry four
+ * different part unions and this predicate cares about exactly one field.
+ */
+function canHostBreakpoint(message) {
+    const content = message.content;
+    if (typeof content === "string")
+        return content.length > 0;
+    if (!Array.isArray(content))
+        return false;
+    const last = content.at(-1);
+    if (typeof last !== "object" || last === null)
+        return false;
+    return last.type !== "reasoning";
+}
+/** The index of the last message that can host the breakpoint, or `-1` when none can. */
+function lastHostIndex(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message !== undefined && canHostBreakpoint(message))
+            return i;
+    }
+    return -1;
+}
+/** Whether this message already carries a cache marker in ANY breakpoint namespace. */
+function carriesBreakpoint(message) {
+    return BREAKPOINT_SITES.some(([namespace, key]) => message.providerOptions?.[namespace]?.[key] !== undefined);
+}
+/** The same message with each namespace of `options` merged into its own bag. */
+function withBreakpoint(message, options) {
+    const merged = { ...message.providerOptions };
+    for (const [namespace] of BREAKPOINT_SITES) {
+        const marker = options[namespace];
+        if (marker === undefined)
+            continue;
+        merged[namespace] = { ...message.providerOptions?.[namespace], ...marker };
+    }
+    return { ...message, providerOptions: merged };
+}
+/** The same message with every marker removed, and each namespace dropped when it held nothing else. */
+function withoutBreakpoint(message) {
+    if (!carriesBreakpoint(message))
+        return message;
+    const remaining = { ...message.providerOptions };
+    for (const [namespace, key] of BREAKPOINT_SITES) {
+        const bag = remaining[namespace];
+        if (bag?.[key] === undefined)
+            continue;
+        const { [key]: _dropped, ...rest } = bag;
+        if (Object.keys(rest).length === 0)
+            delete remaining[namespace];
+        else
+            remaining[namespace] = rest;
+    }
+    return { ...message, providerOptions: remaining };
+}
+/**
+ * Place the request's ONE cache breakpoint, on the last message that can host it.
+ *
+ * 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
+ * the stored thread and come back on every later turn, one more breakpoint per
+ * turn until the request is refused. Only the request-shaped copy carries one.
+ *
+ * The placement is deliberately ROLLING, not pinned to the end of the stable
+ * prefix: within one run the loop appends an assistant reply and its tool results
+ * on every iteration, and a breakpoint that advances with them lets iteration N+1
+ * read back everything iteration N wrote. A pinned breakpoint would re-process
+ * the whole tool transcript uncached on every iteration, which is the opposite of
+ * 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
+ * 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
+ * directive at all.
+ */
+export function withPromptCacheBreakpoint(messages, policy) {
+    const options = promptCacheProviderOptions(policy);
+    const target = options === undefined ? -1 : lastHostIndex(messages);
+    if (target < 0 && !messages.some(carriesBreakpoint))
+        return messages;
+    return messages.map((message, index) => (index === target && options !== undefined ? withBreakpoint(message, options) : withoutBreakpoint(message)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.35.0",
+    "version": "0.35.1",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -94,6 +94,7 @@
         "uuid": "^11.1.1"
     },
     "devDependencies": {
+        "@ai-sdk/amazon-bedrock": "^5.0.74",
         "@eslint/js": "^10.0.1",
         "@types/bun": "latest",
         "@types/dockerode": "^3.3.47",