Add versioned knowledge caching and MCP adapter

[saschabuehrle]

Summary

• add immutable, request-scoped knowledge snapshots to Python and TypeScript agents
• propagate the same selected knowledge through direct, draft, verifier, streaming, and tool execution paths
• use content-bound native prompt-cache hints for OpenAI and Anthropic while keeping all other providers correct without cache support
• expose cached input/write token telemetry
• add an optional tool-first MCP server adapter for ChatGPT, Claude, and Claude Desktop
• document the correctness model, cost constraints, and MCP deployment choices

Why

Model cascades could switch providers without an explicit versioned knowledge handoff, creating two failure modes: a verifier starting without the selected knowledge, or a later/concurrent request inheriting stale implicit state. Replaying full histories and knowledge bases also undermines cascadeflow's cost-saving goal.

This change makes knowledge immutable and request-scoped. Every selected model receives the same stable prefix. Provider prompt caches are treated only as a billing/latency optimization, never as the source of correctness.

Provider cache keys include both logical identity and content digest, preventing stale provider-side reuse even after local LRU eviction or process restart. Applications are expected to retrieve only the relevant passages before constructing a snapshot.

MCP integration

The new optional MCP factory resolves knowledge server-side from a key/version. Clients send only the current query and an optional bounded conversation handoff; private knowledge text is not returned in the tool result.

This lets ChatGPT and Claude invoke cascadeflow routing, but it does not replace the host model. The host tool-selection turn remains part of end-to-end cost and latency. The initial adapter is tool-first; a standard MCP Apps routing/savings panel can be layered on later without changing routing logic.

Validation

• Python: 1,320 passed, 91 skipped
• TypeScript: 1,100 passed, 21 skipped
• TypeScript typecheck passed
• TypeScript production build passed
• Ruff passed
• Black passed
• Python compileall passed
• ESLint completed with zero errors (existing repository warnings remain)
• git diff checks passed

API examples

Python:

knowledge = KnowledgeSnapshot(
    key="support-manual",
    version="2026-08-06",
    content=retrieved_text,
    cache_ttl="1h",
)
result = await agent.run("How do I reset it?", knowledge=knowledge)

TypeScript:

const result = await agent.run("How do I reset it?", {
  knowledge: {
    key: "support-manual",
    version: "2026-08-06",
    content: retrievedText,
    cacheTtl: "1h",
  },
});

[saschabuehrle]

Knowledge-cache benchmark follow-up

The benchmark found and fixed an important GPT-5.6 edge: prompt_cache_key alone does not prevent a changing query suffix from becoming a new cache write. Commit eb9ae9b places an explicit breakpoint at the stable knowledge boundary and enables explicit cache mode for GPT-5.6+, across Python and TypeScript, streaming, tools, Responses, and Chat Completions.

Local benchmark:

• stable knowledge prefix: 4,118 tokens; changing query suffix: 32 tokens; 10 requests
• no provider cache: 41,500 normalized input-cost units
• one reused snapshot, 5-minute cache: 9,173.7 (-77.9%)
• one reused snapshot, 1-hour cache: 12,262.2 (-70.5%)
• alternating two snapshots, 5-minute cache: 13,909.4 (-66.5%)
• unique snapshot on every request with forced writes: 51,795 (+24.8%); disable provider caching for one-off knowledge
• framework overhead at ~4K tokens: +22 rendered tokens and 10.7 microseconds median warm preparation
• concurrency stress: 80,000 switches, 0 failures, expected 64-entry LRU bound

These are deterministic payload/token and official-rate-model results, not live billed API calls, because no OpenAI or Anthropic API keys were configured in the test environment. Provider payload shape, read/write telemetry extraction, and cache-boundary behavior are covered by tests.

Commit 4d63adb additionally makes reported result costs cache-aware in both SDKs. OpenAI costs now distinguish uncached input, 0.1x cache reads, and GPT-5.6 1.25x cache writes. Anthropic costs distinguish base input, 0.1x reads, 1.25x five-minute writes, and 2x one-hour writes. The mappings use provider-reported usage categories and recognize current aliases, including vendor-prefixed model IDs.

Validation after the cost-accounting update:

• Python: 1,324 passed, 91 skipped
• TypeScript: 1,111 passed, 21 skipped
• provider-focused Python: 37 passed, 1 skipped
• Python formatting/lint, TypeScript typecheck/build, and diff checks passed