@curatedmcp/tokenshield-core 0.2.0

package/src/processors/pipeline.ts

@@ -0,0 +1,104 @@
+import type { Conversation } from "../providers/types.js";
+import type {
+  Processor,
+  ProcessorContext,
+  ProcessorEffect,
+  PipelineOptions,
+  PipelineRunResult,
+} from "./types.js";
+
+interface BreakerState {
+  failuresInWindow: number;
+  windowStart: number;
+  trippedUntil: number;
+}
+
+/**
+ * Per-process circuit breaker. If a processor throws N times within W ms,
+ * disable it for D ms. Bounded recovery so a transient bug doesn't cost
+ * the user the whole session.
+ */
+class CircuitBreaker {
+  private states = new Map<string, BreakerState>();
+  constructor(
+    private readonly threshold = 3,
+    private readonly windowMs = 60_000,
+    private readonly cooldownMs = 5 * 60_000,
+  ) {}
+
+  isOpen(id: string): boolean {
+    const s = this.states.get(id);
+    return s !== undefined && s.trippedUntil > Date.now();
+  }
+
+  recordFailure(id: string): void {
+    const now = Date.now();
+    let s = this.states.get(id);
+    if (s === undefined) {
+      s = { failuresInWindow: 0, windowStart: now, trippedUntil: 0 };
+      this.states.set(id, s);
+    }
+    if (now - s.windowStart > this.windowMs) {
+      s.windowStart = now;
+      s.failuresInWindow = 0;
+    }
+    s.failuresInWindow++;
+    if (s.failuresInWindow >= this.threshold) {
+      s.trippedUntil = now + this.cooldownMs;
+    }
+  }
+
+  recordSuccess(id: string): void {
+    const s = this.states.get(id);
+    if (s === undefined) return;
+    if (s.failuresInWindow > 0) s.failuresInWindow = Math.max(0, s.failuresInWindow - 1);
+  }
+}
+
+export class Pipeline {
+  private readonly processors: Processor[];
+  private readonly enabled: Set<string>;
+  private readonly breaker = new CircuitBreaker();
+
+  constructor(opts: PipelineOptions) {
+    this.processors = opts.processors;
+    this.enabled = opts.enabled;
+  }
+
+  run(input: Conversation, ctx: ProcessorContext, sizeOf: (c: Conversation) => number): PipelineRunResult {
+    const bytesIn = sizeOf(input);
+    let current = input;
+    const effects: ProcessorEffect[] = [];
+    const errors: Array<{ processor: string; message: string }> = [];
+
+    for (const p of this.processors) {
+      if (!this.enabled.has(p.id)) continue;
+      if (this.breaker.isOpen(p.id)) continue;
+      try {
+        const result = p.onRequest(current, ctx);
+        if (result.conversation !== current) {
+          current = result.conversation;
+        }
+        for (const e of result.effects) effects.push(e);
+        this.breaker.recordSuccess(p.id);
+      } catch (err) {
+        this.breaker.recordFailure(p.id);
+        errors.push({
+          processor: p.id,
+          message: err instanceof Error ? err.message : String(err),
+        });
+        // current is unchanged — fail-open
+      }
+    }
+
+    return {
+      conversation: current,
+      effects,
+      bytesIn,
+      bytesOut: sizeOf(current),
+      errors,
+    };
+  }
+}
+
+export type { Processor, ProcessorContext, ProcessorEffect } from "./types.js";

package/src/processors/response-cache.ts

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { canonicalize } from "../providers/anthropic.js";
+
+interface CacheEntry {
+  status: number;
+  headers: Record<string, string>;
+  body: Buffer;
+  storedAt: number;
+  expiresAt: number;
+  /** Approx response body size in bytes — used for LRU eviction. */
+  bytes: number;
+  /** Usage as reported by upstream when the response was first cached. */
+  usage: { inputTokens: number; outputTokens: number };
+  /** Model from the cached response. */
+  model: string;
+}
+
+export interface CacheHit {
+  status: number;
+  headers: Record<string, string>;
+  body: Buffer;
+  usage: { inputTokens: number; outputTokens: number };
+  model: string;
+  cachedAgoMs: number;
+  cachedBytes: number;
+}
+
+/**
+ * Tiny, conservative response cache for the Anthropic JSON endpoint.
+ *
+ * Caches IFF: temperature === 0 AND stream === false. Anthropic only guarantees
+ * deterministic outputs under these conditions, so caching anything else risks
+ * serving a stale response a user wouldn't expect.
+ *
+ * Bounded by total byte budget (default 64 MB) with LRU eviction.
+ * Default TTL: 10 minutes.
+ */
+export class ResponseCache {
+  private readonly map = new Map<string, CacheEntry>();
+  private currentBytes = 0;
+  private hits = 0;
+  private misses = 0;
+
+  constructor(
+    private readonly maxBytes = 64 * 1024 * 1024,
+    private readonly defaultTtlMs = 10 * 60 * 1000,
+  ) {}
+
+  private static keyFor(body: unknown): string | null {
+    if (!body || typeof body !== "object") return null;
+    const obj = body as Record<string, unknown>;
+    if (obj["stream"] === true) return null;
+    if (obj["temperature"] !== 0) return null;
+    return createHash("sha256")
+      .update(
+        canonicalize({
+          model: obj["model"] ?? null,
+          system: obj["system"] ?? null,
+          tools: obj["tools"] ?? null,
+          tool_choice: obj["tool_choice"] ?? null,
+          messages: obj["messages"] ?? [],
+          max_tokens: obj["max_tokens"] ?? null,
+          temperature: obj["temperature"] ?? null,
+          top_p: obj["top_p"] ?? null,
+          top_k: obj["top_k"] ?? null,
+          stop_sequences: obj["stop_sequences"] ?? null,
+        }),
+      )
+      .digest("hex");
+  }
+
+  /** Returns a hit if the body is cacheable AND fresh; otherwise null. */
+  lookup(body: unknown): CacheHit | null {
+    const key = ResponseCache.keyFor(body);
+    if (key === null) return null;
+    const entry = this.map.get(key);
+    if (entry === undefined) {
+      this.misses++;
+      return null;
+    }
+    const now = Date.now();
+    if (entry.expiresAt < now) {
+      this.evict(key, entry);
+      this.misses++;
+      return null;
+    }
+    // LRU: refresh insertion order
+    this.map.delete(key);
+    this.map.set(key, entry);
+    this.hits++;
+    return {
+      status: entry.status,
+      headers: entry.headers,
+      body: entry.body,
+      usage: entry.usage,
+      model: entry.model,
+      cachedAgoMs: now - entry.storedAt,
+      cachedBytes: entry.bytes,
+    };
+  }
+
+  /** Store a response for a cacheable request. No-op if request isn't cacheable. */
+  store(
+    body: unknown,
+    response: {
+      status: number;
+      headers: Record<string, string>;
+      body: Buffer;
+      usage: { inputTokens: number; outputTokens: number };
+      model: string;
+    },
+    ttlMs?: number,
+  ): void {
+    const key = ResponseCache.keyFor(body);
+    if (key === null) return;
+    // Only cache 2xx; 4xx/5xx are likely transient or user errors
+    if (response.status < 200 || response.status >= 300) return;
+    const bytes = response.body.length;
+    if (bytes > this.maxBytes / 4) return; // skip absurdly large bodies
+    this.evictIfNeeded(bytes);
+    const now = Date.now();
+    const entry: CacheEntry = {
+      status: response.status,
+      headers: { ...response.headers },
+      body: response.body,
+      storedAt: now,
+      expiresAt: now + (ttlMs ?? this.defaultTtlMs),
+      bytes,
+      usage: response.usage,
+      model: response.model,
+    };
+    // Drop pre-existing entry under the same key (refresh)
+    const prior = this.map.get(key);
+    if (prior !== undefined) {
+      this.currentBytes -= prior.bytes;
+      this.map.delete(key);
+    }
+    this.map.set(key, entry);
+    this.currentBytes += bytes;
+  }
+
+  private evictIfNeeded(incomingBytes: number): void {
+    while (this.currentBytes + incomingBytes > this.maxBytes && this.map.size > 0) {
+      const oldest = this.map.keys().next();
+      if (oldest.done === true) break;
+      const key = oldest.value;
+      const e = this.map.get(key);
+      if (e === undefined) break;
+      this.evict(key, e);
+    }
+  }
+
+  private evict(key: string, entry: CacheEntry): void {
+    this.currentBytes -= entry.bytes;
+    this.map.delete(key);
+  }
+
+  stats(): { hits: number; misses: number; entries: number; bytes: number } {
+    return { hits: this.hits, misses: this.misses, entries: this.map.size, bytes: this.currentBytes };
+  }
+}

package/src/processors/types.ts

@@ -0,0 +1,58 @@
+import type { Conversation } from "../providers/types.js";
+import type { ProviderId } from "../providers/types.js";
+
+export interface ProcessorContext {
+  providerId: ProviderId;
+  /** Stable fingerprint of the conversation (system + first user message hash). */
+  conversationFingerprint: string;
+  /** Inbound request raw bytes (read-only). */
+  inboundBytes: number;
+}
+
+export interface ProcessorEffect {
+  /** Stable identifier for accounting (e.g. "conversation-dedup"). */
+  name: string;
+  /** Bytes saved by this processor's modifications. */
+  bytesSaved: number;
+  /** Optional structured detail for the dashboard / diff-mode. */
+  detail?: Record<string, unknown>;
+}
+
+export interface ProcessorResult {
+  /** Updated conversation (may be a new object; processors must return one). */
+  conversation: Conversation;
+  /** Effects applied (zero or one entry per call). */
+  effects: ProcessorEffect[];
+}
+
+/**
+ * A request-side processor inspects + rewrites the conversation BEFORE it goes
+ * upstream. It must be:
+ *   - deterministic: same input → same output, so prompt caching still hits
+ *   - fail-open: any throw is caught by the pipeline; original conversation is preserved
+ *   - bounded: never adds unbounded latency (no network calls in v0.2)
+ */
+export interface Processor {
+  readonly id: string;
+  readonly enabledByDefault: boolean;
+
+  /**
+   * Mutate the conversation if appropriate. MUST return a new conversation
+   * (or the same reference if no change). Any throw is treated as a soft
+   * failure: the pipeline reverts to the input and trips the breaker.
+   */
+  onRequest(conversation: Conversation, ctx: ProcessorContext): ProcessorResult;
+}
+
+export interface PipelineOptions {
+  processors: Processor[];
+  enabled: Set<string>;
+}
+
+export interface PipelineRunResult {
+  conversation: Conversation;
+  effects: ProcessorEffect[];
+  bytesIn: number;
+  bytesOut: number;
+  errors: Array<{ processor: string; message: string }>;
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import type { SSEEvent, UsageCounts } from "../types.js";
+import { emptyUsage } from "../pricing.js";
+import type {
+  Provider,
+  StreamAccumulator,
+  Conversation,
+  ConvMessage,
+  ConvBlock,
+} from "./types.js";
+
+interface AnthropicUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+function fromAnthropic(u: AnthropicUsage | undefined): UsageCounts {
+  if (!u) return emptyUsage();
+  return {
+    inputTokens: u.input_tokens ?? 0,
+    outputTokens: u.output_tokens ?? 0,
+    cacheCreationInputTokens: u.cache_creation_input_tokens ?? 0,
+    cacheReadInputTokens: u.cache_read_input_tokens ?? 0,
+  };
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
+}
+
+function sha256(s: string): string {
+  return createHash("sha256").update(s).digest("hex");
+}
+
+function byteLength(value: unknown): number {
+  if (typeof value === "string") return Buffer.byteLength(value, "utf8");
+  return Buffer.byteLength(JSON.stringify(value ?? ""), "utf8");
+}
+
+class AnthropicStreamAccumulator implements StreamAccumulator {
+  private current: UsageCounts = emptyUsage();
+  private modelFromEvent: string | null = null;
+
+  observe(event: SSEEvent): void {
+    if (event.event !== "message_start" && event.event !== "message_delta") return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (!parsed || typeof parsed !== "object") return;
+    const obj = parsed as Record<string, unknown>;
+
+    if (event.event === "message_start") {
+      const message = obj["message"] as Record<string, unknown> | undefined;
+      if (message) {
+        if (typeof message["model"] === "string") {
+          this.modelFromEvent = message["model"] as string;
+        }
+        this.current = fromAnthropic(message["usage"] as AnthropicUsage | undefined);
+      }
+    } else {
+      const usage = obj["usage"] as AnthropicUsage | undefined;
+      if (usage) {
+        const u = fromAnthropic(usage);
+        this.current = {
+          inputTokens: this.current.inputTokens || u.inputTokens,
+          outputTokens: u.outputTokens,
+          cacheCreationInputTokens:
+            this.current.cacheCreationInputTokens || u.cacheCreationInputTokens,
+          cacheReadInputTokens:
+            this.current.cacheReadInputTokens || u.cacheReadInputTokens,
+        };
+      }
+    }
+  }
+
+  total(): UsageCounts {
+    return { ...this.current };
+  }
+
+  model(): string | null {
+    return this.modelFromEvent;
+  }
+}
+
+function blocksFromAnthropic(content: unknown): ConvBlock[] {
+  // Anthropic accepts string OR array of blocks for message.content
+  if (typeof content === "string") {
+    return [{ kind: "text", text: content }];
+  }
+  if (!Array.isArray(content)) return [{ kind: "other", raw: content }];
+  return content.map((block): ConvBlock => {
+    if (!block || typeof block !== "object") return { kind: "other", raw: block };
+    const b = block as Record<string, unknown>;
+    const type = b["type"];
+    if (type === "text" && typeof b["text"] === "string") {
+      return { kind: "text", text: b["text"] };
+    }
+    if (type === "tool_use" && typeof b["id"] === "string" && typeof b["name"] === "string") {
+      return { kind: "tool_use", id: b["id"], name: b["name"], input: b["input"] };
+    }
+    if (type === "tool_result" && typeof b["tool_use_id"] === "string") {
+      const content = b["content"];
+      const hash = sha256(canonicalize(content));
+      return {
+        kind: "tool_result",
+        tool_use_id: b["tool_use_id"],
+        content,
+        contentHash: hash,
+        contentBytes: byteLength(content),
+      };
+    }
+    return { kind: "other", raw: block };
+  });
+}
+
+function blocksToAnthropic(blocks: ConvBlock[]): unknown {
+  // Preserve array-vs-string shape: if it was originally a single text block from a
+  // string, we still emit an array. Anthropic accepts both.
+  return blocks.map((block) => {
+    switch (block.kind) {
+      case "text":
+        return { type: "text", text: block.text };
+      case "tool_use":
+        return { type: "tool_use", id: block.id, name: block.name, input: block.input };
+      case "tool_result": {
+        if (block.pointer) {
+          const stub =
+            `[tokenshield: identical to tool_result ${block.pointer.priorToolUseId} ` +
+            `at message ${block.pointer.priorMessageIndex}, ` +
+            `sha:${block.contentHash.slice(0, 8)} — ${block.pointer.elidedBytes} bytes elided]`;
+          return { type: "tool_result", tool_use_id: block.tool_use_id, content: stub };
+        }
+        return { type: "tool_result", tool_use_id: block.tool_use_id, content: block.content };
+      }
+      case "other":
+        return block.raw;
+    }
+  });
+}
+
+function extractSystem(body: Record<string, unknown>): string | null {
+  const sys = body["system"];
+  if (typeof sys === "string") return sys;
+  if (Array.isArray(sys)) {
+    return sys
+      .map((b) => (typeof b === "object" && b !== null && typeof (b as Record<string, unknown>)["text"] === "string" ? (b as Record<string, unknown>)["text"] : ""))
+      .join("\n\n");
+  }
+  return null;
+}
+
+export const anthropic: Provider = {
+  id: "anthropic",
+
+  matches(pathname: string): boolean {
+    return pathname.startsWith("/v1/messages") || pathname.startsWith("/v1/complete");
+  },
+
+  extractModel(body: unknown): string {
+    if (!body || typeof body !== "object") return "unknown";
+    const m = (body as Record<string, unknown>)["model"];
+    return typeof m === "string" ? m : "unknown";
+  },
+
+  isStreaming(body: unknown): boolean {
+    if (!body || typeof body !== "object") return false;
+    return (body as Record<string, unknown>)["stream"] === true;
+  },
+
+  usageFromResponseJson(body: unknown): { usage: UsageCounts; model: string | null } {
+    if (!body || typeof body !== "object") return { usage: emptyUsage(), model: null };
+    const obj = body as Record<string, unknown>;
+    return {
+      usage: fromAnthropic(obj["usage"] as AnthropicUsage | undefined),
+      model: typeof obj["model"] === "string" ? (obj["model"] as string) : null,
+    };
+  },
+
+  createStreamAccumulator(): StreamAccumulator {
+    return new AnthropicStreamAccumulator();
+  },
+
+  toConversation(body: unknown): Conversation | null {
+    if (!body || typeof body !== "object") return null;
+    const obj = body as Record<string, unknown>;
+    const rawMessages = obj["messages"];
+    if (!Array.isArray(rawMessages)) return null;
+    const messages: ConvMessage[] = rawMessages
+      .map((m): ConvMessage | null => {
+        if (!m || typeof m !== "object") return null;
+        const msg = m as Record<string, unknown>;
+        const role = msg["role"];
+        if (role !== "user" && role !== "assistant") return null;
+        return { role, blocks: blocksFromAnthropic(msg["content"]) };
+      })
+      .filter((m): m is ConvMessage => m !== null);
+
+    const model = typeof obj["model"] === "string" ? (obj["model"] as string) : "unknown";
+    const tempRaw = obj["temperature"];
+    const temperature = typeof tempRaw === "number" ? tempRaw : null;
+
+    return {
+      model,
+      system: extractSystem(obj),
+      messages,
+      temperature,
+      raw: obj,
+    };
+  },
+
+  applyConversation(body: unknown, conversation: Conversation): unknown {
+    if (!body || typeof body !== "object") return body;
+    const obj = { ...(body as Record<string, unknown>) };
+    obj["messages"] = conversation.messages.map((m) => ({
+      role: m.role,
+      content: blocksToAnthropic(m.blocks),
+    }));
+    return obj;
+  },
+};
+
+// helpers exported for tests
+export { canonicalize, sha256, byteLength };

package/src/providers/registry.ts

@@ -0,0 +1,10 @@
+import type { Provider } from "./types.js";
+import { anthropic } from "./anthropic.js";
+
+const PROVIDERS: Provider[] = [anthropic];
+
+export function providerForPath(pathname: string): Provider | null {
+  return PROVIDERS.find((p) => p.matches(pathname)) ?? null;
+}
+
+export { anthropic };

package/src/providers/types.ts

@@ -0,0 +1,87 @@
+import type { SSEEvent, UsageCounts } from "../types.js";
+
+export type ProviderId = "anthropic" | "openai" | "gemini";
+
+/**
+ * A Provider knows how to:
+ *  - claim a URL path
+ *  - parse usage from streamed SSE events
+ *  - parse usage from non-streaming JSON responses
+ *  - extract the model + stream flag from a request body
+ *
+ * Processors operate on the abstract Conversation/Message model the
+ * provider produces, so the dedup/cache logic doesn't need to know
+ * Anthropic vs OpenAI shapes.
+ */
+export interface Provider {
+  readonly id: ProviderId;
+
+  /** Does this provider handle the given inbound URL path? */
+  matches(pathname: string): boolean;
+
+  /** Extract model name from a parsed request body. Returns "unknown" if absent. */
+  extractModel(body: unknown): string;
+
+  /** Did the request ask for SSE streaming? */
+  isStreaming(body: unknown): boolean;
+
+  /** Parse non-streaming response body (already JSON.parsed). */
+  usageFromResponseJson(body: unknown): { usage: UsageCounts; model: string | null };
+
+  /** Streaming usage accumulator factory — one per request. */
+  createStreamAccumulator(): StreamAccumulator;
+
+  /** Adapt the inbound body into a normalised Conversation for processors. */
+  toConversation(body: unknown): Conversation | null;
+
+  /** Apply processor-modified conversation back into a body shape ready to forward. */
+  applyConversation(body: unknown, conversation: Conversation): unknown;
+}
+
+export interface StreamAccumulator {
+  observe(event: SSEEvent): void;
+  total(): UsageCounts;
+  model(): string | null;
+}
+
+// ─── Normalised model (provider-agnostic) ───────────────────────────────────
+//
+// Processors operate on this shape. Each Provider knows how to translate to/from
+// its native message format. This keeps dedup/cache implementations small.
+
+export interface Conversation {
+  model: string;
+  /** System prompt text (concatenated if provider supports an array). */
+  system: string | null;
+  messages: ConvMessage[];
+  /** Approximate temperature; null when not specified. Used by cache safety check. */
+  temperature: number | null;
+  /** Provider-specific extras forwarded untouched. */
+  raw: Record<string, unknown>;
+}
+
+export interface ConvMessage {
+  role: "user" | "assistant";
+  blocks: ConvBlock[];
+}
+
+export type ConvBlock =
+  | { kind: "text"; text: string }
+  | { kind: "tool_use"; id: string; name: string; input: unknown }
+  | {
+      kind: "tool_result";
+      tool_use_id: string;
+      /** Original content body (string or structured) — kept intact for first-occurrence. */
+      content: unknown;
+      /** Stable hash of `content` after canonicalization. */
+      contentHash: string;
+      /** Approx byte size of original content (for accounting). */
+      contentBytes: number;
+      /** If set, dedup has replaced the content with a pointer; original is "elided". */
+      pointer?: {
+        priorMessageIndex: number;
+        priorToolUseId: string;
+        elidedBytes: number;
+      };
+    }
+  | { kind: "other"; raw: unknown };