@inflexa-ai/harness 0.35.0 → 0.35.2

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/execution/dbos-run-launcher.d.ts

@@ -1,7 +1,18 @@
 /**
  * DBOS realization of the `RunLauncher` seam — the single production adapter,
- * shared by every embedder. Host-neutral: it references only DBOS, which the harness
- * already depends on, so it ships in the harness.
+ * shared by every embedder. Host-neutral: it references only DBOS and the OTel
+ * API, which the harness already depends on, so it ships in the harness.
+ *
+ * A launch detaches the run from the caller's trace. The DBOS workflow span
+ * takes the active context as its parent, and the caller is a chat request
+ * (or another short-lived operation) whose span ends in milliseconds while the
+ * run lasts hours. So the launch opens a root span of its own, runs
+ * `startWorkflow` under it, and joins the two traces by a span link back to
+ * the originating span plus `inflexa.run_id` on both sides. With no
+ * TracerProvider registered every call here is a no-op on the API's
+ * non-recording span.
  */
 import type { RunLauncher } from "./run-launcher.js";
+/** Attribute carrying the run id on the originating span and on the run's root span. */
+export declare const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
 export declare function createDbosRunLauncher(): RunLauncher;

package/dist/execution/dbos-run-launcher.js

@@ -1,13 +1,38 @@
 /**
  * DBOS realization of the `RunLauncher` seam — the single production adapter,
- * shared by every embedder. Host-neutral: it references only DBOS, which the harness
- * already depends on, so it ships in the harness.
+ * shared by every embedder. Host-neutral: it references only DBOS and the OTel
+ * API, which the harness already depends on, so it ships in the harness.
+ *
+ * A launch detaches the run from the caller's trace. The DBOS workflow span
+ * takes the active context as its parent, and the caller is a chat request
+ * (or another short-lived operation) whose span ends in milliseconds while the
+ * run lasts hours. So the launch opens a root span of its own, runs
+ * `startWorkflow` under it, and joins the two traces by a span link back to
+ * the originating span plus `inflexa.run_id` on both sides. With no
+ * TracerProvider registered every call here is a no-op on the API's
+ * non-recording span.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { context, isSpanContextValid, ROOT_CONTEXT, trace } from "@opentelemetry/api";
+/** Attribute carrying the run id on the originating span and on the run's root span. */
+export const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
+const TRACER_NAME = "inflexa.harness.run-launcher";
 export function createDbosRunLauncher() {
     return {
         async launch(workflow, opts, input) {
-            await DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input);
+            const originating = trace.getSpan(context.active());
+            const links = [];
+            if (originating !== undefined && isSpanContextValid(originating.spanContext())) {
+                originating.setAttribute(ATTR_INFLEXA_RUN_ID, opts.workflowId);
+                links.push({ context: originating.spanContext() });
+            }
+            const root = trace.getTracer(TRACER_NAME).startSpan("launch run", { links, attributes: { [ATTR_INFLEXA_RUN_ID]: opts.workflowId } }, ROOT_CONTEXT);
+            try {
+                await context.with(trace.setSpan(ROOT_CONTEXT, root), () => DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input));
+            }
+            finally {
+                root.end();
+            }
         },
     };
 }

package/dist/execution/reconcile-manifest.js

@@ -23,7 +23,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { classifyWithinRoot, computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
-import { artifactReconcileDropped, lineageInputDropped } from "../lib/metrics.js";
+import { recordArtifactReconcileDropped, recordLineageInputDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
     const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
@@ -62,7 +62,7 @@ export async function reconcileManifestWithDisk(input) {
                 logger.debug("dropping phantom entry", { path: entry.path });
                 collector.removeRecord(entry.path);
                 droppedCount++;
-                artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+                recordArtifactReconcileDropped({ agentId });
                 continue;
             }
             throw err;
@@ -75,7 +75,7 @@ export async function reconcileManifestWithDisk(input) {
             logger.debug("dropping non-file entry", { path: entry.path });
             collector.removeRecord(entry.path);
             droppedCount++;
-            artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+            recordArtifactReconcileDropped({ agentId });
             continue;
         }
         // The registration payload reads output hashes from `entries` (this
@@ -140,14 +140,14 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         const containerPrefix = `/${resourceId}`;
         if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, boundSite: "container-prefix" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "container-prefix" });
+            recordLineageInputDropped({ agentId, reason: "container-prefix" });
             collector.dropInput(ref);
             continue;
         }
         const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
         if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "workspace-root" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "workspace-root" });
+            recordLineageInputDropped({ agentId, reason: "workspace-root" });
             collector.dropInput(ref);
             continue;
         }
@@ -159,7 +159,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         // verdict (a dangling link) falls through to the ENOENT drop below.
         if ((await classifyWithinRoot(resourceRoot, hostPath)) === "escaped") {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "realpath" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "symlink-escape" });
+            recordLineageInputDropped({ agentId, reason: "symlink-escape" });
             collector.dropInput(ref);
             continue;
         }
@@ -173,7 +173,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
                 // consumed, and the count of those is how a reader tells a noisy
                 // hook from an artifact that genuinely vanished under the step.
                 logger.warn("dropping input not present at reconcile from lineage", { ...attestation, hostPath, dropSite: "input-enoent" });
-                lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "missing" });
+                recordLineageInputDropped({ agentId, reason: "missing" });
                 collector.dropInput(ref);
                 continue;
             }
@@ -187,7 +187,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
             // as drift; a directory is not drift.
             logger.debug("dropping non-file input from lineage", attestation);
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "directory" });
+            recordLineageInputDropped({ agentId, reason: "directory" });
             collector.dropInput(ref);
             continue;
         }

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/lib/metrics.d.ts

@@ -4,6 +4,24 @@
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *
+ * Both carry `agent_id` (about 15 values) and never a per-step or per-run
+ * identifier: a label with unbounded values multiplies the series count.
+ *
+ * Instruments are lazy so the record site binds to whichever `MeterProvider`
+ * is globally registered at first use. The metrics API has no late-binding
+ * proxy: a meter taken at module load, before `initOtel` runs, would stay
+ * on the no-op provider for the life of the process.
  */
-export declare const artifactReconcileDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
-export declare const lineageInputDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Record one manifest entry dropped at reconcile. */
+export declare function recordArtifactReconcileDropped(args: {
+    readonly agentId: string;
+}): void;
+export type LineageInputDropReason = "container-prefix" | "workspace-root" | "symlink-escape" | "missing" | "directory";
+/** Record one tracked input read dropped from lineage at reconcile. */
+export declare function recordLineageInputDropped(args: {
+    readonly agentId: string;
+    readonly reason: LineageInputDropReason;
+}): void;
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export declare function __resetReconcileMetricsForTest(): void;

package/dist/lib/metrics.js

@@ -4,16 +4,44 @@
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *
+ * Both carry `agent_id` (about 15 values) and never a per-step or per-run
+ * identifier: a label with unbounded values multiplies the series count.
+ *
+ * Instruments are lazy so the record site binds to whichever `MeterProvider`
+ * is globally registered at first use. The metrics API has no late-binding
+ * proxy: a meter taken at module load, before `initOtel` runs, would stay
+ * on the no-op provider for the life of the process.
  */
 import { metrics } from "@opentelemetry/api";
-const meter = metrics.getMeter("cortex");
-export const artifactReconcileDropped = meter.createCounter("cortex.artifact.reconcile.dropped", {
-    description: "Manifest entries dropped because their on-disk file was missing at " +
-        "registration time (writes-then-deletes, renames). Tagged by agent_id, step_id.",
-});
-export const lineageInputDropped = meter.createCounter("cortex.artifact.reconcile.input_dropped", {
-    description: "Tracked input reads dropped from lineage at reconcile because they are " +
-        "not content-attestable files of the analysis (directory reads, " +
-        "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
-        "agent_id, step_id, reason.",
-});
+let instruments;
+function getInstruments() {
+    if (instruments === undefined) {
+        const meter = metrics.getMeter("cortex");
+        instruments = {
+            artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
+                description: "Manifest entries dropped because their on-disk file was missing at " +
+                    "registration time (writes-then-deletes, renames). Tagged by agent_id.",
+            }),
+            lineageInputDropped: meter.createCounter("cortex.artifact.reconcile.input_dropped", {
+                description: "Tracked input reads dropped from lineage at reconcile because they are " +
+                    "not content-attestable files of the analysis (directory reads, " +
+                    "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
+                    "agent_id, reason.",
+            }),
+        };
+    }
+    return instruments;
+}
+/** Record one manifest entry dropped at reconcile. */
+export function recordArtifactReconcileDropped(args) {
+    getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });
+}
+/** Record one tracked input read dropped from lineage at reconcile. */
+export function recordLineageInputDropped(args) {
+    getInstruments().lineageInputDropped.add(1, { agent_id: args.agentId, reason: args.reason });
+}
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export function __resetReconcileMetricsForTest() {
+    instruments = undefined;
+}

package/dist/lib/otel.d.ts

@@ -1,14 +1,22 @@
 /**
  * OpenTelemetry SDK initialization — traces + metrics.
  *
- * Exported as `initOtel()` and called explicitly from index.ts to prevent
- * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ * Exported as `initOtel()` and called explicitly from the host's boot sequence
+ * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
  * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
  *         is set.
  *
- * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *          is set. Custom Cortex metrics are defined in metrics.ts.
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
+ *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
+ *          metrics are defined in metrics.ts.
+ *
+ * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
+ *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
+ *           the environment wins on a conflict, so a deployment can set
+ *           `deployment.environment.name` or override the service name without
+ *           a code change. Traces and metrics share the one resource.
  *
  * Note: OTEL's instrumentation-http patches node:http but does not cover
  *        Hono's request handling or Node 22's undici-based globalThis.fetch,
@@ -16,16 +24,45 @@
  *        not currently wired.
  */
 import type { Logger } from "./logger.js";
+/** The SDK's own default when neither the host nor the environment says otherwise. */
+export declare const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60000;
+export interface InitOtelOptions {
+    /** Diagnostics sink; omitted falls back to no-op. */
+    readonly logger?: Logger;
+    /** `service.name` when `OTEL_SERVICE_NAME` is unset. Default `cortex`. */
+    readonly serviceName?: string;
+    /** `service.version` — the host's package version. Omitted leaves the attribute unset. */
+    readonly serviceVersion?: string;
+}
+/**
+ * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
+ * stays set for traces. Any other value (including unset) keeps the OTLP
+ * exporter, the only one the harness ships.
+ */
+export declare function metricsExportDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Export interval from `OTEL_METRIC_EXPORT_INTERVAL` (milliseconds). An unset,
+ * non-numeric, or non-positive value falls back to the 60 s default.
+ */
+export declare function metricExportIntervalMs(env?: NodeJS.ProcessEnv): number;
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export declare function initOtel(injected?: Logger): void;
+export declare function initOtel(options?: InitOtelOptions): void;
 /**
  * Flush and shut down the OTel exporters. Called by the graceful-shutdown
  * sequence so in-flight batch spans/metrics make it to the collector
  * before the process exits. Never throws.
  */
 export declare function shutdownOtel(): Promise<void>;
+/**
+ * Test hook: shut the providers down and unregister every global the init
+ * touched, so a test can drive `initOtel` again under a different environment.
+ * Test-only.
+ */
+export declare function __resetOtelForTest(): Promise<void>;
+/** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
+export declare function __otelMeterProviderRegisteredForTest(): boolean;

package/dist/lib/otel.js

@@ -1,21 +1,29 @@
 /**
  * OpenTelemetry SDK initialization — traces + metrics.
  *
- * Exported as `initOtel()` and called explicitly from index.ts to prevent
- * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ * Exported as `initOtel()` and called explicitly from the host's boot sequence
+ * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
  * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
  *         is set.
  *
- * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *          is set. Custom Cortex metrics are defined in metrics.ts.
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
+ *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
+ *          metrics are defined in metrics.ts.
+ *
+ * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
+ *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
+ *           the environment wins on a conflict, so a deployment can set
+ *           `deployment.environment.name` or override the service name without
+ *           a code change. Traces and metrics share the one resource.
  *
  * Note: OTEL's instrumentation-http patches node:http but does not cover
  *        Hono's request handling or Node 22's undici-based globalThis.fetch,
  *        so inbound/outbound trace-context propagation across those paths is
  *        not currently wired.
  */
-import { propagation, metrics, trace } from "@opentelemetry/api";
+import { context, propagation, metrics, trace } from "@opentelemetry/api";
 import { createNoopLogger } from "./console-logger.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
@@ -23,25 +31,59 @@ import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { detectResources, envDetector, resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+/** The SDK's own default when neither the host nor the environment says otherwise. */
+export const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60_000;
 let initialized = false;
 let registeredTracerProvider;
 let registeredMeterProvider;
+/**
+ * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
+ * stays set for traces. Any other value (including unset) keeps the OTLP
+ * exporter, the only one the harness ships.
+ */
+export function metricsExportDisabled(env = process.env) {
+    return env.OTEL_METRICS_EXPORTER === "none";
+}
+/**
+ * Export interval from `OTEL_METRIC_EXPORT_INTERVAL` (milliseconds). An unset,
+ * non-numeric, or non-positive value falls back to the 60 s default.
+ */
+export function metricExportIntervalMs(env = process.env) {
+    const raw = env.OTEL_METRIC_EXPORT_INTERVAL;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+    return Math.floor(parsed);
+}
+function buildResource(options) {
+    const manual = {
+        [ATTR_SERVICE_NAME]: options.serviceName ?? "cortex",
+    };
+    if (options.serviceVersion)
+        manual[ATTR_SERVICE_VERSION] = options.serviceVersion;
+    // `merge` gives precedence to the argument: the environment overrides the
+    // host's values, which is the OTel SDK convention for env configuration.
+    return resourceFromAttributes(manual).merge(detectResources({ detectors: [envDetector] }));
+}
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export function initOtel(injected) {
+export function initOtel(options = {}) {
     if (initialized)
         return;
     initialized = true;
-    const logger = (injected ?? createNoopLogger()).named("otel");
+    const logger = (options.logger ?? createNoopLogger()).named("otel");
     // ── W3C Trace Context propagation ──────────────────────────────────
     propagation.setGlobalPropagator(new W3CTraceContextPropagator());
     const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    const resource = buildResource(options);
     // ── Traces ─────────────────────────────────────────────────────────
     // Always register a TracerProvider so trace.getTracer() returns real spans
     // with unique IDs. Without this, the OtelBridge gets no-op spans (all zeros)
@@ -52,10 +94,6 @@ export function initOtel(injected) {
             const base = endpoint.replace(/\/+$/, "");
             spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` })));
         }
-        const serviceName = process.env.OTEL_SERVICE_NAME || "cortex";
-        const resource = resourceFromAttributes({
-            [ATTR_SERVICE_NAME]: serviceName,
-        });
         const tracerProvider = new NodeTracerProvider({
             resource,
             spanProcessors,
@@ -71,20 +109,29 @@ export function initOtel(injected) {
         // `initTelemetry: () => {}` — its TUI owns stdout, so the banner corrupted
         // the screen and the whole of the harness's traces + metrics were switched
         // off to avoid it. At debug through the injected seam it costs nothing.
-        logger.debug("TracerProvider registered", { spanId: ctx.spanId, noop: isNoop, endpoint: endpoint ?? null, processors: spanProcessors.length });
+        logger.debug("TracerProvider registered", {
+            spanId: ctx.spanId,
+            noop: isNoop,
+            endpoint: endpoint ?? null,
+            processors: spanProcessors.length,
+            resource: resource.attributes,
+        });
         testSpan.end();
     }
     // ── Metrics ────────────────────────────────────────────────────────
-    if (endpoint) {
+    // With no MeterProvider registered the API's global no-op provider serves
+    // every instrument, so the record sites stay valid when export is off.
+    if (endpoint && !metricsExportDisabled()) {
         const base = endpoint.replace(/\/+$/, "");
         const metricExporter = new OTLPMetricExporter({
             url: `${base}/v1/metrics`,
         });
         const meterProvider = new MeterProvider({
+            resource,
             readers: [
                 new PeriodicExportingMetricReader({
                     exporter: metricExporter,
-                    exportIntervalMillis: 30_000,
+                    exportIntervalMillis: metricExportIntervalMs(),
                 }),
             ],
         });
@@ -105,3 +152,22 @@ export async function shutdownOtel() {
         tasks.push(registeredMeterProvider.shutdown());
     await Promise.allSettled(tasks);
 }
+/**
+ * Test hook: shut the providers down and unregister every global the init
+ * touched, so a test can drive `initOtel` again under a different environment.
+ * Test-only.
+ */
+export async function __resetOtelForTest() {
+    await shutdownOtel();
+    registeredTracerProvider = undefined;
+    registeredMeterProvider = undefined;
+    trace.disable();
+    metrics.disable();
+    context.disable();
+    propagation.disable();
+    initialized = false;
+}
+/** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
+export function __otelMeterProviderRegisteredForTest() {
+    return registeredMeterProvider !== undefined;
+}

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/dist/runtime/dbos.d.ts

@@ -12,6 +12,7 @@
  *
  * See `openspec/changes/harness-dbos-runtime`.
  */
+import { type DBOSConfig, type DLogger } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
 /**
@@ -31,18 +32,60 @@ export interface DbosConfig {
     /** Stable per-pod executor id (e.g. `process.env.HOSTNAME ?? "local-dev"`). */
     readonly executorId: string;
     /**
-     * SDK log verbosity (winston levels; the SDK's own default is `info`).
-     * Interactive embedders pass `warn` so the launch banner and migration
-     * chatter don't interleave with their own command output; the server root
-     * omits it and keeps the informative default.
+     * Least severe SDK record forwarded to the host's `Logger` (winston level
+     * names; the SDK's own default is `info`). The SDK's lines ride the
+     * harness `Logger` seam under `[dbos.sdk]`, so this threshold is applied by
+     * the bridge, not by the SDK. Interactive embedders pass `warn` so the
+     * launch banner and migration chatter stay out of their logs; the server
+     * root omits it and keeps the informative default.
      */
     readonly logLevel?: string;
+    /**
+     * Emit DBOS workflow and step spans on the globally registered
+     * TracerProvider, and run every workflow and step body under an active
+     * OTel context. Default `false`.
+     *
+     * DBOS installs nothing of its own here: with no OTLP endpoint of its own it
+     * probes the global provider and, when one is registered, emits under the
+     * instrumentation scope `dbos-tracer` through that provider's processors.
+     * A host that registers no provider (the CLI passes a no-op
+     * `initTelemetry`) must leave this off, otherwise the SDK installs its own
+     * `BasicTracerProvider` and every span is created and never exported.
+     *
+     * Attribute names follow the `dbos.*` semantic-convention layout
+     * (`otelAttributeFormat: "semconv"`).
+     *
+     * Known SDK behavior a host must plan for:
+     * - a recovered workflow starts a new root trace, with no link to the trace
+     *   of the original execution
+     * - every already-completed step re-emits a `cached=true` span on replay,
+     *   so a restart with many in-flight steps bursts spans; size
+     *   `OTEL_BSP_MAX_QUEUE_SIZE` for it
+     * - step span names embed the step, tool-use, or exec id
+     */
+    readonly tracingEnabled?: boolean;
 }
 /** DBOS lifecycle facts a host's readiness probe reports on. */
 export interface DbosState {
     launched: boolean;
     recoveryStarted: boolean;
 }
+/**
+ * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
+ * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
+ * host's sink instead of on the process console. The SDK does not filter by
+ * `logLevel` before it delegates to a custom logger, so the threshold is
+ * applied here. Records arrive as strings; an `Error` arrives as its message
+ * with the stack (and cause chain) in `metadata.stack`; inside a workflow or
+ * step body `metadata.span.attributes` carries the operation context, which
+ * rides as fields.
+ */
+export declare function dbosSdkLogger(logger: Logger, logLevel: string | undefined): DLogger;
+/**
+ * The SDK config `launchDbos` sets. Pure over `DbosConfig`, so a test can
+ * assert on the mapping without a launch.
+ */
+export declare function dbosSdkConfig(config: DbosConfig, logger: Logger): DBOSConfig;
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.

package/dist/runtime/dbos.js

@@ -45,6 +45,76 @@ function systemDatabaseUrl(config) {
     const database = encodeURIComponent(config.dbName);
     return `postgresql://${user}:${password}@${host}:${port}/${database}?sslmode=${dbosSslMode(config.dbSslMode)}`;
 }
+/** Winston severity ranks, ascending verbosity — the scale `DbosConfig.logLevel` names. */
+const SDK_LOG_LEVEL_RANK = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    http: 3,
+    verbose: 4,
+    debug: 5,
+    silly: 6,
+};
+const SDK_DEFAULT_LOG_LEVEL = "info";
+/**
+ * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
+ * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
+ * host's sink instead of on the process console. The SDK does not filter by
+ * `logLevel` before it delegates to a custom logger, so the threshold is
+ * applied here. Records arrive as strings; an `Error` arrives as its message
+ * with the stack (and cause chain) in `metadata.stack`; inside a workflow or
+ * step body `metadata.span.attributes` carries the operation context, which
+ * rides as fields.
+ */
+export function dbosSdkLogger(logger, logLevel) {
+    const sink = logger.named("sdk");
+    const threshold = SDK_LOG_LEVEL_RANK[logLevel ?? SDK_DEFAULT_LOG_LEVEL] ?? SDK_LOG_LEVEL_RANK[SDK_DEFAULT_LOG_LEVEL];
+    const passes = (level) => SDK_LOG_LEVEL_RANK[level] <= threshold;
+    const fields = (metadata) => {
+        const attributes = metadata?.span?.attributes;
+        const stack = metadata?.stack;
+        if (attributes === undefined && stack === undefined)
+            return undefined;
+        return { ...attributes, ...(stack !== undefined ? { stack } : {}) };
+    };
+    const message = (entry) => (typeof entry === "string" ? entry : String(entry));
+    return {
+        debug: (entry, metadata) => {
+            if (passes("debug"))
+                sink.debug(message(entry), fields(metadata));
+        },
+        info: (entry, metadata) => {
+            if (passes("info"))
+                sink.info(message(entry), fields(metadata));
+        },
+        warn: (entry, metadata) => {
+            if (passes("warn"))
+                sink.warn(message(entry), fields(metadata));
+        },
+        error: (entry, metadata) => {
+            if (passes("error"))
+                sink.error(message(entry), fields(metadata));
+        },
+    };
+}
+/**
+ * The SDK config `launchDbos` sets. Pure over `DbosConfig`, so a test can
+ * assert on the mapping without a launch.
+ */
+export function dbosSdkConfig(config, logger) {
+    return {
+        name: config.appName,
+        systemDatabaseUrl: systemDatabaseUrl(config),
+        systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
+        executorID: config.executorId,
+        applicationVersion: config.applicationVersion,
+        adminPort: parseInt(config.adminPort, 10),
+        logLevel: config.logLevel,
+        logger: dbosSdkLogger(logger, config.logLevel),
+        tracingEnabled: config.tracingEnabled ?? false,
+        otelAttributeFormat: "semconv",
+    };
+}
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.
@@ -57,25 +127,17 @@ export async function launchDbos({ config, logger: injected }) {
     if (state.launched)
         return;
     const logger = injected.named("dbos");
-    const executorID = config.executorId;
-    const adminPort = parseInt(config.adminPort, 10);
-    DBOS.setConfig({
-        name: config.appName,
-        systemDatabaseUrl: systemDatabaseUrl(config),
-        systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
-        executorID,
-        applicationVersion: config.applicationVersion,
-        adminPort,
-        logLevel: config.logLevel,
-    });
+    const sdkConfig = dbosSdkConfig(config, logger);
+    DBOS.setConfig(sdkConfig);
     const start = performance.now();
     await DBOS.launch();
     state.launched = true;
     state.recoveryStarted = true;
     logger.info("launched", {
-        executorID,
+        executorID: sdkConfig.executorID,
         applicationVersion: config.applicationVersion,
-        adminPort,
+        adminPort: sdkConfig.adminPort,
+        tracingEnabled: sdkConfig.tracingEnabled,
         durationMs: Math.round(performance.now() - start),
     });
 }

package/dist/workflows/metrics.d.ts

@@ -1,15 +1,10 @@
 /**
- * Workflow-side OTel metrics → Middleware.io.
+ * Workflow-side OTel metrics.
  *
- * Two signals so 3-hour runs and pause-resume cascades are observable:
  *   - cortex.workflow.parent.cancelled_children — counter, incremented once
  *     per child the fail-fast or pause cascade reaps. A baseline near 0
  *     means runs land cleanly; a spike means siblings keep colliding with
  *     a single failing step.
- *   - cortex.workflow.stream.bytes               — counter, incremented by
- *     the byte count of every UI part written onto the DBOS stream. The
- *     leading indicator for 3-hour stream growth is monotonic — a runaway
- *     emitter shows up as an unbounded slope.
  *
  * Instruments are lazy so the workflow body binds to whichever
  * `MeterProvider` is globally registered at startup.
@@ -23,15 +18,5 @@
 export declare function recordCancelledChild(args: {
     readonly cause: "fail_fast" | "budget_exceeded" | "external_cancel";
 }): void;
-/**
- * Record one UI-part write. `bytes` is the serialised JSON size of the
- * part as it lands on the stream; `kind` is the part `type` for
- * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
- * so a single emitter records once per part.
- */
-export declare function recordStreamWrite(args: {
-    readonly bytes: number;
-    readonly kind: string;
-}): void;
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export declare function __resetWorkflowMetricsForTest(): void;

package/dist/workflows/metrics.js

@@ -1,15 +1,10 @@
 /**
- * Workflow-side OTel metrics → Middleware.io.
+ * Workflow-side OTel metrics.
  *
- * Two signals so 3-hour runs and pause-resume cascades are observable:
  *   - cortex.workflow.parent.cancelled_children — counter, incremented once
  *     per child the fail-fast or pause cascade reaps. A baseline near 0
  *     means runs land cleanly; a spike means siblings keep colliding with
  *     a single failing step.
- *   - cortex.workflow.stream.bytes               — counter, incremented by
- *     the byte count of every UI part written onto the DBOS stream. The
- *     leading indicator for 3-hour stream growth is monotonic — a runaway
- *     emitter shows up as an unbounded slope.
  *
  * Instruments are lazy so the workflow body binds to whichever
  * `MeterProvider` is globally registered at startup.
@@ -23,10 +18,6 @@ function getInstruments() {
             cancelledChildren: meter.createCounter("cortex.workflow.parent.cancelled_children", {
                 description: "Children cancelled by the parent's fail-fast or pause cascade",
             }),
-            streamBytes: meter.createCounter("cortex.workflow.stream.bytes", {
-                description: "Bytes written to the parent's DBOS UI-parts stream — proxy for " + "3-hour stream growth",
-                unit: "By",
-            }),
         };
     }
     return instruments;
@@ -40,15 +31,6 @@ function getInstruments() {
 export function recordCancelledChild(args) {
     getInstruments().cancelledChildren.add(1, { cause: args.cause });
 }
-/**
- * Record one UI-part write. `bytes` is the serialised JSON size of the
- * part as it lands on the stream; `kind` is the part `type` for
- * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
- * so a single emitter records once per part.
- */
-export function recordStreamWrite(args) {
-    getInstruments().streamBytes.add(args.bytes, { kind: args.kind });
-}
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export function __resetWorkflowMetricsForTest() {
     instruments = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.35.0",
+    "version": "0.35.2",
     "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",