@animalabs/membrane 0.5.42 → 0.5.43

package/src/membrane.ts

@@ -53,6 +53,8 @@ import type {
 import type { PrefillFormatter, StreamParser } from './formatters/types.js';
 import { AnthropicXmlFormatter } from './formatters/anthropic-xml.js';
 import { YieldingStreamImpl } from './yielding-stream.js';
+import { calculateCost } from './utils/cost.js';
+import { getDefaultPricing } from './registry/default-pricing.js';
 
 // ============================================================================
 // Membrane Class
@@ -273,6 +275,7 @@ export class Membrane {
     const parser = formatter.createStreamParser();
     let toolDepth = 0;
     let totalUsage: DetailedUsage = { inputTokens: 0, outputTokens: 0 };
+    const pricing = this.resolvePricing(request.config.model);
     const contentBlocks: ContentBlock[] = [];
     let lastStopReason: StopReason = 'end_turn';
     let lastStopSequence: string | undefined;
@@ -425,6 +428,7 @@ export class Membrane {
         if (streamResult.usage.cacheReadTokens) {
           totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
         }
+        if (pricing) totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
         onUsage?.(totalUsage);
 
         // Flush the parser to complete any in-progress streaming block
@@ -737,6 +741,7 @@ export class Membrane {
 
     let toolDepth = 0;
     let totalUsage: DetailedUsage = { inputTokens: 0, outputTokens: 0 };
+    const pricing = this.resolvePricing(request.config.model);
     let lastStopReason: StopReason = 'end_turn';
     let lastStopSequence: string | undefined;
     let rawRequest: unknown;
@@ -807,6 +812,7 @@ export class Membrane {
         if (streamResult.usage.cacheReadTokens) {
           totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
         }
+        if (pricing) totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
         onUsage?.(totalUsage);
 
         // Parse content blocks from response
@@ -960,10 +966,13 @@ export class Membrane {
     const assistantName = request.assistantParticipant
       ?? this.config.assistantParticipant ?? 'Claude';
 
+    const promptCaching = request.promptCaching ?? true;
+    const cacheControl = promptCaching ? { type: 'ephemeral' as const, ...(request.cacheTtl ? { ttl: request.cacheTtl } : {}) } : undefined;
+
     for (const msg of messages) {
       const isAssistant = msg.participant === assistantName;
       const role = isAssistant ? 'assistant' : 'user';
-      
+
       // Convert content blocks
       const content: any[] = [];
       for (const block of msg.content) {
@@ -1005,19 +1014,42 @@ export class Membrane {
           }
         }
       }
-      
+
+      // Apply cache_control to last block of messages with cacheBreakpoint
+      if (msg.cacheBreakpoint && cacheControl && content.length > 0) {
+        content[content.length - 1].cache_control = cacheControl;
+      }
+
       providerMessages.push({ role, content });
     }
     
     // Convert tools to provider format.
     // Native tool names must match ^[a-zA-Z0-9_-]{1,128}$ — sanitize colons
     // from the module:tool namespace convention. Reversed in parseProviderContent.
-    const tools = request.tools?.map(tool => ({
-      name: sanitizeToolName(tool.name),
-      description: tool.description,
-      input_schema: tool.inputSchema,
-    }));
-    
+    const tools = request.tools?.map((tool, idx) => {
+      const t: Record<string, unknown> = {
+        name: sanitizeToolName(tool.name),
+        description: tool.description,
+        input_schema: tool.inputSchema,
+      };
+      // Cache the tool list — mark the last tool with cache_control
+      if (cacheControl && request.tools && idx === request.tools.length - 1) {
+        t.cache_control = cacheControl;
+      }
+      return t;
+    });
+
+    // Wrap system prompt with cache_control if prompt caching is enabled
+    let system: unknown = request.system;
+    if (cacheControl && typeof system === 'string' && system.length > 0) {
+      system = [{ type: 'text', text: system, cache_control: cacheControl }];
+    } else if (cacheControl && Array.isArray(system) && system.length > 0) {
+      const blocks = system as Record<string, unknown>[];
+      system = blocks.map((block, idx) =>
+        idx === blocks.length - 1 ? { ...block, cache_control: cacheControl } : block
+      );
+    }
+
     // Build thinking config for native extended thinking
     const thinking = request.config.thinking?.enabled
       ? {
@@ -1034,7 +1066,7 @@ export class Membrane {
       maxTokens: request.config.maxTokens,
       temperature,
       messages: providerMessages,
-      system: request.system,
+      system,
       tools,
       thinking,
       extra: request.providerParams,
@@ -1377,6 +1409,7 @@ export class Membrane {
           outputTokens: providerResponse.usage.outputTokens,
           cacheCreationTokens: providerResponse.usage.cacheCreationTokens,
           cacheReadTokens: providerResponse.usage.cacheReadTokens,
+          estimatedCost: this.estimateCost(providerResponse.usage, request.config.model),
         },
         timing: {
           totalDurationMs: durationMs,
@@ -1458,6 +1491,7 @@ export class Membrane {
         },
         usage: {
           ...usage,
+          estimatedCost: usage.estimatedCost ?? this.estimateCost(usage, request.config.model),
         },
         timing: {
           totalDurationMs: durationMs,
@@ -1497,13 +1531,23 @@ export class Membrane {
     }
   }
 
-  private calculateCacheHitRatio(usage: any): number {
+  private calculateCacheHitRatio(usage: Pick<DetailedUsage, 'inputTokens' | 'cacheReadTokens'>): number {
     const cacheRead = usage.cacheReadTokens ?? 0;
     const total = usage.inputTokens ?? 0;
     if (total === 0) return 0;
     return cacheRead / total;
   }
 
+  private resolvePricing(model: string): import('./types/provider.js').ModelPricing | undefined {
+    return this.registry?.getPricing(model) ?? getDefaultPricing(model);
+  }
+
+  /** Resolve pricing + calculate cost in one call (for one-shot use outside loops). */
+  private estimateCost(usage: import('./utils/cost.js').CostableUsage, model: string): import('./types/response.js').CostBreakdown | undefined {
+    const pricing = this.resolvePricing(model);
+    return pricing ? calculateCost(usage, pricing) : undefined;
+  }
+
   private calculateRetryDelay(attempt: number): number {
     const { retryDelayMs, backoffMultiplier, maxRetryDelayMs } = this.retryConfig;
     const delay = retryDelayMs * Math.pow(backoffMultiplier, attempt - 1);
@@ -1639,7 +1683,8 @@ export class Membrane {
     const formatter = this.formatter;
     const parser = formatter.createStreamParser();
     let toolDepth = 0;
-    let totalUsage: BasicUsage = { inputTokens: 0, outputTokens: 0 };
+    let totalUsage: DetailedUsage = { inputTokens: 0, outputTokens: 0 };
+    const pricing = this.resolvePricing(request.config.model);
     const contentBlocks: ContentBlock[] = [];
     let lastStopReason: StopReason = 'end_turn';
     let lastStopSequence: string | undefined;
@@ -1768,9 +1813,16 @@ export class Membrane {
         lastStopReason = this.mapStopReason(streamResult.stopReason);
         lastStopSequence = streamResult.stopSequence ?? undefined;
 
-        // Accumulate usage
+        // Accumulate usage (including cache metrics)
         totalUsage.inputTokens += streamResult.usage.inputTokens;
         totalUsage.outputTokens += streamResult.usage.outputTokens;
+        if (streamResult.usage.cacheCreationTokens) {
+          totalUsage.cacheCreationTokens = (totalUsage.cacheCreationTokens ?? 0) + streamResult.usage.cacheCreationTokens;
+        }
+        if (streamResult.usage.cacheReadTokens) {
+          totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
+        }
+        if (pricing) totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
         if (emitUsage) {
           stream.emit({ type: 'usage', usage: { ...totalUsage } });
         }
@@ -2075,7 +2127,8 @@ export class Membrane {
     } = options;
 
     let toolDepth = 0;
-    let totalUsage: BasicUsage = { inputTokens: 0, outputTokens: 0 };
+    let totalUsage: DetailedUsage = { inputTokens: 0, outputTokens: 0 };
+    const pricing = this.resolvePricing(request.config.model);
     let lastStopReason: StopReason = 'end_turn';
     let lastStopSequence: string | undefined;
     let rawRequest: unknown;
@@ -2141,9 +2194,16 @@ export class Membrane {
         lastStopReason = this.mapStopReason(streamResult.stopReason);
         lastStopSequence = streamResult.stopSequence ?? undefined;
 
-        // Accumulate usage
+        // Accumulate usage (including cache metrics)
         totalUsage.inputTokens += streamResult.usage.inputTokens;
         totalUsage.outputTokens += streamResult.usage.outputTokens;
+        if (streamResult.usage.cacheCreationTokens) {
+          totalUsage.cacheCreationTokens = (totalUsage.cacheCreationTokens ?? 0) + streamResult.usage.cacheCreationTokens;
+        }
+        if (streamResult.usage.cacheReadTokens) {
+          totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
+        }
+        if (pricing) totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
         if (emitUsage) {
           stream.emit({ type: 'usage', usage: { ...totalUsage } });
         }
@@ -2252,9 +2312,9 @@ export class Membrane {
           },
           cache: {
             markersInRequest: 0,
-            tokensCreated: 0,
-            tokensRead: 0,
-            hitRatio: 0,
+            tokensCreated: totalUsage.cacheCreationTokens ?? 0,
+            tokensRead: totalUsage.cacheReadTokens ?? 0,
+            hitRatio: this.calculateCacheHitRatio(totalUsage),
           },
         },
         raw: {

package/src/providers/anthropic.ts

@@ -178,7 +178,19 @@ export class AnthropicAdapter implements ProviderAdapter {
           const delta = event.delta as { stop_reason?: string; stop_sequence?: string };
           stopReason = delta.stop_reason ?? 'end_turn';
           stopSequence = delta.stop_sequence ?? undefined;
-          outputTokens = (event.usage as { output_tokens: number }).output_tokens ?? 0;
+          const deltaUsage = event.usage as unknown as {
+            output_tokens: number;
+            cache_creation_input_tokens?: number | null;
+            cache_read_input_tokens?: number | null;
+          };
+          outputTokens = deltaUsage.output_tokens ?? 0;
+          // message_delta carries cumulative cache metrics — use as authoritative
+          if (deltaUsage.cache_creation_input_tokens != null) {
+            cacheCreationTokens = deltaUsage.cache_creation_input_tokens;
+          }
+          if (deltaUsage.cache_read_input_tokens != null) {
+            cacheReadTokens = deltaUsage.cache_read_input_tokens;
+          }
           break;
         }
       }

package/src/registry/default-pricing.ts

@@ -0,0 +1,77 @@
+import type { ModelPricing } from '../types/provider.js';
+
+/**
+ * Built-in pricing table for known models.
+ * Prices in USD per million tokens. Last updated: 2025-07.
+ *
+ * Used as fallback when no ModelRegistry is configured.
+ * Registry pricing (if available) takes precedence.
+ */
+const PRICING_TABLE: Array<{ prefix: string; pricing: ModelPricing }> = [
+  // Anthropic — Claude 4.6
+  {
+    prefix: 'claude-opus-4-6',
+    pricing: { inputPerMillion: 15, outputPerMillion: 75, cacheWritePerMillion: 18.75, cacheReadPerMillion: 1.50, currency: 'USD' },
+  },
+  {
+    prefix: 'claude-sonnet-4-6',
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD' },
+  },
+  // Anthropic — Claude 4.5
+  {
+    prefix: 'claude-haiku-4-5',
+    pricing: { inputPerMillion: 0.80, outputPerMillion: 4, cacheWritePerMillion: 1.00, cacheReadPerMillion: 0.08, currency: 'USD' },
+  },
+  // Anthropic — Claude 4
+  {
+    prefix: 'claude-opus-4',
+    pricing: { inputPerMillion: 15, outputPerMillion: 75, cacheWritePerMillion: 18.75, cacheReadPerMillion: 1.50, currency: 'USD' },
+  },
+  {
+    prefix: 'claude-sonnet-4',
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD' },
+  },
+  // Anthropic — Claude 3.5
+  {
+    prefix: 'claude-3-5-sonnet',
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD' },
+  },
+  {
+    prefix: 'claude-3-5-haiku',
+    pricing: { inputPerMillion: 0.80, outputPerMillion: 4, cacheWritePerMillion: 1.00, cacheReadPerMillion: 0.08, currency: 'USD' },
+  },
+  // OpenAI — GPT-4o
+  {
+    prefix: 'gpt-4o-2024',
+    pricing: { inputPerMillion: 2.50, outputPerMillion: 10, cacheReadPerMillion: 1.25, currency: 'USD' },
+  },
+  {
+    prefix: 'gpt-4o',
+    pricing: { inputPerMillion: 2.50, outputPerMillion: 10, cacheReadPerMillion: 1.25, currency: 'USD' },
+  },
+  {
+    prefix: 'gpt-4o-mini',
+    pricing: { inputPerMillion: 0.15, outputPerMillion: 0.60, cacheReadPerMillion: 0.075, currency: 'USD' },
+  },
+  // Google — Gemini 2.5
+  {
+    prefix: 'gemini-2.5-pro',
+    pricing: { inputPerMillion: 1.25, outputPerMillion: 10, currency: 'USD' },
+  },
+  {
+    prefix: 'gemini-2.5-flash',
+    pricing: { inputPerMillion: 0.15, outputPerMillion: 0.60, currency: 'USD' },
+  },
+];
+
+export function getDefaultPricing(modelId: string): ModelPricing | undefined {
+  let best: ModelPricing | undefined;
+  let bestLen = 0;
+  for (const entry of PRICING_TABLE) {
+    if (modelId.startsWith(entry.prefix) && entry.prefix.length > bestLen) {
+      best = entry.pricing;
+      bestLen = entry.prefix.length;
+    }
+  }
+  return best;
+}

package/src/types/yielding-stream.ts

@@ -10,7 +10,7 @@
 
 import type { ContentBlock } from './content.js';
 import type { ToolCall, ToolResult, ToolContext } from './tools.js';
-import type { BasicUsage, NormalizedResponse, StopReason } from './response.js';
+import type { DetailedUsage, NormalizedResponse, StopReason } from './response.js';
 import type { ChunkMeta, BlockEvent } from './streaming.js';
 
 // ============================================================================
@@ -49,7 +49,7 @@ export interface ToolCallsEvent {
  */
 export interface UsageEvent {
   type: 'usage';
-  usage: BasicUsage;
+  usage: DetailedUsage;
 }
 
 /**

package/src/utils/cost.ts

@@ -0,0 +1,29 @@
+import type { CostBreakdown } from '../types/response.js';
+import type { ModelPricing } from '../types/provider.js';
+
+export interface CostableUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationTokens?: number;
+  cacheReadTokens?: number;
+}
+
+export function calculateCost(usage: CostableUsage, pricing: ModelPricing): CostBreakdown {
+  const input = usage.inputTokens * pricing.inputPerMillion / 1_000_000;
+  const output = usage.outputTokens * pricing.outputPerMillion / 1_000_000;
+  const cacheWrite = pricing.cacheWritePerMillion != null
+    ? (usage.cacheCreationTokens ?? 0) * pricing.cacheWritePerMillion / 1_000_000
+    : undefined;
+  const cacheRead = pricing.cacheReadPerMillion != null
+    ? (usage.cacheReadTokens ?? 0) * pricing.cacheReadPerMillion / 1_000_000
+    : undefined;
+
+  return {
+    input,
+    output,
+    cacheWrite,
+    cacheRead,
+    total: input + output + (cacheWrite ?? 0) + (cacheRead ?? 0),
+    currency: pricing.currency,
+  };
+}

package/src/utils/index.ts

@@ -13,3 +13,6 @@ export {
   unescapeXml,
   type ToolDefinitionForPrompt,
 } from './tool-parser.js';
+
+export { calculateCost } from './cost.js';
+export type { CostableUsage } from './cost.js';

package/dist/formatters/pseudo-prefill.d.ts

@@ -1,71 +0,0 @@
-/**
- * Pseudo-Prefill Formatter
- *
- * Recovers prefill-like behavior for models that don't support native
- * assistant message prefill (e.g., Sonnet 4.6, Opus 4.6). Uses a CLI
- * simulation framing trick:
- *
- *   System: "The assistant is in CLI simulation mode..."
- *   User: "<cmd>cut -c 1-N < conversation.txt</cmd>"
- *   Assistant: <the full conversation log, N chars>
- *   User: "<cmd>cat conversation.txt</cmd>"  (or cut -c N+1-)
- *   <model continues from where the cut output ended>
- *
- * Two continuation modes:
- * - 'cat': model repeats full file then continues (reliable, caller strips log)
- * - 'tail-cut': model outputs only new content (efficient, needs simulated stops)
- *
- * IMPORTANT: API-level stop sequences should NOT be used with pseudo-prefill.
- * In 'cat' mode, the model repeats participant names from the log which would
- * trigger stops prematurely. The caller should handle stop sequences post-facto
- * after stripping the repeated log. The stop sequences returned in BuildResult
- * are for the caller's post-facto detection, not for the API.
- *
- * Uses PassthroughParser and native API tools (same as NativeFormatter).
- */
-import type { NormalizedMessage, ContentBlock, ToolCall, ToolResult } from '../types/index.js';
-import type { PrefillFormatter, StreamParser, BuildOptions, BuildResult, FormatterConfig } from './types.js';
-export interface PseudoPrefillFormatterConfig extends FormatterConfig {
-    /**
-     * Filename used in the CLI simulation commands.
-     * Default: 'conversation.txt'
-     */
-    filename?: string;
-    /**
-     * Continuation mode:
-     * - 'cat': `cat filename` — model repeats full file then continues.
-     *   More reliable but uses more output tokens. Caller must strip the
-     *   repeated conversation log from the response.
-     * - 'tail-cut': `cut -c N+1- < filename` — model outputs only new content.
-     *   More efficient but may be less reliable. Caller needs simulated stop
-     *   sequences (only after \n\n, not at position 0).
-     * Default: 'cat'
-     */
-    continuationMode?: 'cat' | 'tail-cut';
-    /**
-     * Maximum participants to include in stop sequences.
-     * Default: 10
-     */
-    maxParticipantsForStop?: number;
-    /**
-     * Message delimiter between participant entries.
-     * Default: '' (none, just newlines)
-     */
-    messageDelimiter?: string;
-}
-export declare class PseudoPrefillFormatter implements PrefillFormatter {
-    readonly name = "pseudo-prefill";
-    readonly usesPrefill = false;
-    private config;
-    constructor(config?: PseudoPrefillFormatterConfig);
-    buildMessages(messages: NormalizedMessage[], options: BuildOptions): BuildResult;
-    formatToolResults(results: ToolResult[]): string;
-    createStreamParser(): StreamParser;
-    parseToolCalls(_content: string): ToolCall[];
-    hasToolUse(_content: string): boolean;
-    parseContentBlocks(content: string): ContentBlock[];
-    private extractContent;
-    private buildStopSequences;
-    private convertToNativeTools;
-}
-//# sourceMappingURL=pseudo-prefill.d.ts.map

package/dist/formatters/pseudo-prefill.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pseudo-prefill.d.ts","sourceRoot":"","sources":["../../src/formatters/pseudo-prefill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EAEZ,QAAQ,EACR,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EAMhB,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,4BAA6B,SAAQ,eAAe;IACnE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAEtC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAqGD,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,WAAW,SAAS;IAE7B,OAAO,CAAC,MAAM,CAAyC;gBAE3C,MAAM,GAAE,4BAAiC;IAerD,aAAa,CAAC,QAAQ,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,WAAW;IA+NhF,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM;IAahD,kBAAkB,IAAI,YAAY;IAIlC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE;IAK5C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKrC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE;IAWnD,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,oBAAoB;CAO7B"}