@animalabs/membrane 0.5.81 → 0.5.82

package/src/providers/anthropic.ts

@@ -130,6 +130,18 @@ export function thinkingEnabled(request: ProviderRequest): boolean {
 // Adapter Configuration
 // ============================================================================
 
+/**
+ * What the dynamicHeaders callback is told about the request it stamps.
+ * `lane` names the transport shape: 'stream' is the conversational turn loop,
+ * 'complete' the non-streamed lane (compression, side-calls, keepalive
+ * touches). A stamp that describes WHY the agent's turn fired belongs on the
+ * stream lane only — a compression call running in the background is not the
+ * turn, and stamping it with the turn's cause would lie to the ledger.
+ */
+export interface DynamicHeadersContext {
+  lane: 'stream' | 'complete';
+}
+
 export interface AnthropicAdapterConfig {
   /** API key (defaults to ANTHROPIC_API_KEY env var) */
   apiKey?: string | null;
@@ -157,7 +169,7 @@ export interface AnthropicAdapterConfig {
    * never replayed stale — an unstamped touch is honest, a stale stamp lies.
    * null/undefined/'' values are dropped.
    */
-  dynamicHeaders?: () => Record<string, string | number | null | undefined>;
+  dynamicHeaders?: (ctx?: DynamicHeadersContext) => Record<string, string | number | null | undefined>;
   
   /** Default max tokens */
   defaultMaxTokens?: number;
@@ -196,7 +208,7 @@ export class AnthropicAdapter implements ProviderAdapter {
   /** Holds idle agents' cached prefixes warm; undefined when disabled. */
   readonly cacheKeepalive: CacheKeepalive | undefined;
   /** Live per-request header source (see AnthropicAdapterConfig.dynamicHeaders). */
-  private readonly dynamicHeaders?: () => Record<string, string | number | null | undefined>;
+  private readonly dynamicHeaders?: (ctx?: DynamicHeadersContext) => Record<string, string | number | null | undefined>;
 
   constructor(config: AnthropicAdapterConfig = {}) {
     const clientOptions: ClientOptions = {
@@ -250,7 +262,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const response = await this.client.messages.create(fullRequest, {
         signal: options?.signal,
-        headers: this.liveHeaders(headers),
+        headers: this.liveHeaders(headers, 'complete'),
       });
 
       return this.parseResponse(response, fullRequest);
@@ -323,7 +335,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const stream = await this.client.messages.stream(anthropicRequest, {
         signal: idleAbort.signal,
-        headers: this.liveHeaders(this.betaHeaders(request)),
+        headers: this.liveHeaders(this.betaHeaders(request), 'stream'),
       });
 
       // Accumulate response metadata from SSE events directly, so we can
@@ -573,8 +585,8 @@ export class AnthropicAdapter implements ProviderAdapter {
   /** Base headers + the live dynamicHeaders stamp. Request time only: the
    *  keepalive recorder receives the base headers BEFORE this merge, so
    *  replayed touches never carry a stale telemetry value. */
-  private liveHeaders(base: Record<string, string> | undefined): Record<string, string> | undefined {
-    const dyn = this.dynamicHeaders?.();
+  private liveHeaders(base: Record<string, string> | undefined, lane: DynamicHeadersContext['lane']): Record<string, string> | undefined {
+    const dyn = this.dynamicHeaders?.({ lane });
     if (!dyn) return base;
     const out: Record<string, string> = { ...(base ?? {}) };
     for (const [k, v] of Object.entries(dyn)) {

package/src/providers/index.ts

@@ -7,6 +7,7 @@ export {
   toAnthropicContent,
   fromAnthropicContent,
   type AnthropicAdapterConfig,
+  type DynamicHeadersContext,
 } from './anthropic.js';
 
 export { flattenRootSchemaUnion } from './anthropic-tool-schema.js';

package/src/types/request.ts

@@ -112,6 +112,9 @@ export type ToolMode =
 // ============================================================================
 
 export interface NormalizedRequest {
+  /** Receives the exact post-format/post-hook cache receipt immediately before
+   * network submission. Observability only; never forwarded to providers. */
+  onCacheWireReceipt?: (receipt: import('../cache-wire-receipt.js').CacheWireReceipt) => void;
   /**
    * Explicitly own the loss of old inline images when the serialized request
    * exceeds the API byte cap: oldest images are replaced with loud
@@ -152,6 +155,10 @@ export interface NormalizedRequest {
    */
   promptCaching?: boolean;
 
+  /** Marker ownership policy. `cm-owned` disables every formatter-generated
+   * system/context-prefix marker; only normalized message breakpoints survive. */
+  cacheMarkers?: 'membrane-system' | 'cm-owned';
+
   /**
    * Cache TTL for Anthropic prompt caching.
    * '5m' (default) = 5 minute TTL

package/src/utils/cache-marker-budget.ts

@@ -149,6 +149,35 @@ export function countWireCacheMarkers(surfaces: WireCacheSurfaces): number {
   return collectMarkedBlocks(surfaces).length;
 }
 
+/**
+ * Validate a caller-owned marker layout without changing it.
+ *
+ * In `cm-owned` mode the caller has deliberately allocated the complete
+ * breakpoint set. Silently stripping or reordering those markers would make
+ * the cache receipt describe a request that was never sent, so invalid
+ * layouts fail before submission instead of using the legacy repair clamp.
+ */
+export function assertCacheMarkersWithinLimit(
+  surfaces: WireCacheSurfaces,
+  site: string
+): number {
+  const marked = collectMarkedBlocks(surfaces);
+  const invalidThinking = marked.filter(
+    (block) => block.type === 'thinking' || block.type === 'redacted_thinking'
+  ).length;
+  if (invalidThinking > 0) {
+    throw new Error(
+      `${site}: caller-owned cache_control cannot be attached to thinking/redacted_thinking blocks`
+    );
+  }
+  if (marked.length > MAX_CACHE_BREAKPOINTS) {
+    throw new Error(
+      `${site}: cache_control limit exceeded: ${marked.length} markers (maximum ${MAX_CACHE_BREAKPOINTS})`
+    );
+  }
+  return marked.length;
+}
+
 /**
  * Bring a request inside the breakpoint budget, in place, at the last exit
  * before the adapter call. Two repairs, both loud: