fix: LangChain/LangGraph parity audit — 40+ correctness fixes across session, cache, tool calling, reasoning, agent loop and local models

docs/modules/harness/cache.md

@@ -107,25 +107,65 @@ stable prefix fingerprint even if the full request changes.
 
 ## Cache Policy
 
+As implemented today (`harness::cache::CachePolicy`):
+
 ```rust
 pub struct CachePolicy {
-    pub enabled: bool,
-    pub ttl: Option<Duration>,
-    pub scope: CacheScope,
-    pub include_tools: bool,
-    pub include_model_responses: bool,
-    pub preserve_provider_prefix: bool,
-    pub stable_prefix_min_tokens: Option<usize>,
+    pub response_cache_enabled: bool,
+    pub protect_prompt_prefix: bool,
+    pub ttl_ms: Option<u64>,
+    pub namespace: Option<String>,
 }
 ```
 
-Cache keys must include every behavior-affecting input: model, messages, tools,
-tool schemas, response format, provider options, and relevant metadata. Unsafe
-or side-effecting tool calls should not be cached by default.
+`ttl_ms` and `namespace` cover the `ttl` / `scope` this spec asks for. The
+remaining aspirational fields (`include_tools`, `include_model_responses`,
+`stable_prefix_min_tokens`) are **not implemented**; tools are always part of
+the key and there is no minimum-prefix threshold.
+
+Unsafe or side-effecting tool calls should not be cached by default.
+
+### Key composition
+
+The key is a two-part composition, never the prompt alone:
 
-The local response cache key is a SHA-256 digest of canonical request JSON.
-Prompt text is not embedded directly in the key, but every serialized
-behavior-affecting request field participates in the digest.
+```text
+scoped_cache_key(cache_key(request), model.cache_identity(), streaming, namespace)
+```
+
+- `cache_key(request)` is a SHA-256 digest over per-message and per-tool frames
+  plus an **explicit allowlist projection** of the behaviour-affecting
+  parameters. The projection destructures `ModelRequest` exhaustively, so adding
+  a request field is a compile error until someone decides whether it belongs in
+  the key. Fields that cannot change the answer — `tags`, `timeout_ms`,
+  `metadata`, `cache_policy`, `prompt_fingerprint`, `cache_segments` — are
+  deliberately excluded; folding them in gave a caller who put a run id in
+  `metadata` a permanent 0% hit rate.
+- `cache_identity()` names the provider family, model id, API base URL, optional
+  scope, and a **fingerprint** of the credential. It is computed *after* model
+  resolution, because the real model is chosen by `ModelRegistry::resolve_request`
+  and the endpoint and credential live inside the `Arc<dyn ChatModel>`, never in
+  the request. Without it one shared cache serves a hosted harness's answer to a
+  local one.
+- `streaming` is a parameter of the call rather than a request field, so it is
+  folded explicitly; a warm streaming run is not served an entry written by a
+  unary run.
+
+Raw credentials never reach a key: `credential_fingerprint` hashes them first.
+
+### Write rules
+
+- Only the **primary** model's answer is written under its own key. When the
+  fallback chain answers, the write is skipped — otherwise the primary's key is
+  poisoned (permanently, absent a TTL) with a different model's response.
+- A cache read or write failure is logged and ignored. The provider call has
+  already succeeded and been paid for; discarding its answer because the cache
+  was unavailable is strictly worse than not caching.
+- A cache hit is stamped `ModelResponse::served_from_cache` so token/cost
+  accounting can tell a replay from a real call and not re-bill it.
+- A cache hit on a **streaming** run is replayed as synthetic `ModelDelta`
+  events (text, then one per tool call) so warm and cold runs are
+  observationally identical.
 
 ## Cache Key Inputs
 
@@ -167,5 +207,25 @@ Every lookup should produce a decision:
 - write skipped
 - write completed
 
+Implemented today: `AgentEvent::CacheHit` / `AgentEvent::CacheMiss` are emitted
+as events, and the "no lookup happened at all" half is reported as a
+`CacheSkipReason` (`no_cache_attached`, `policy_disabled`,
+`multi_turn_transcript`) on a `[cache]`-prefixed debug log. A cache also exposes
+`ResponseCache::stats() -> CacheStats` (hits, misses, writes, evictions,
+expirations, entries, bytes). The remaining decisions are not yet distinct
+events.
+
 The usage feature should record provider prompt-cache hits separately from local
 response-cache hits.
+
+## Backends
+
+- `InMemoryResponseCache` — bounded on **both** an entry count and an
+  approximate byte budget (an entry count alone does not bound memory when
+  responses are long-context). Recency is an ordered map, not a linear scan.
+- `SqliteResponseCache` (feature `sqlite`) — durable, WAL, `(ns, key)` primary
+  key with an `expiry` column and a lazy purge on read. Namespaces do not
+  cross-serve and clear independently.
+- `SingleFlight` — collapses concurrent identical misses into one provider call
+  so N simultaneous callers do not all pay for the same answer. Errors are not
+  shared: a follower whose leader failed runs its own call.

examples/agent_loop_tools.rs

@@ -81,6 +81,7 @@ fn tool_call_response(id: &str, name: &str, arguments: serde_json::Value) -> Mod
         raw: None,
         resolved_model: None,
         continue_turn: None,
+        served_from_cache: false,
     }
 }
 
@@ -98,6 +99,7 @@ fn text_response(text: &str) -> ModelResponse {
         raw: None,
         resolved_model: None,
         continue_turn: None,
+        served_from_cache: false,
     }
 }
 

src/error.rs

@@ -96,6 +96,35 @@ pub enum TinyAgentsError {
     #[error("model error: {0}")]
     Provider(Box<crate::harness::model::ProviderError>),
 
+    /// The request did not fit in the model's context window.
+    ///
+    /// Distinguished from the generic [`TinyAgentsError::Provider`] because the
+    /// remedy is specific and mechanical — compact or drop transcript history
+    /// and retry — where a generic provider failure has none. A caller that can
+    /// summarise its own transcript (see
+    /// [`crate::harness::summarization`]) can match on this variant instead of
+    /// string-matching a provider message that differs per vendor and changes
+    /// without notice. Port of LangChain's `ContextOverflowError`.
+    ///
+    /// # Detection is best-effort, and asymmetric
+    ///
+    /// Hosted providers raise an explicit 400 for this, which
+    /// [`crate::harness::providers::openai::CONTEXT_OVERFLOW_CODE`] classifies.
+    /// **Local servers usually truncate the front of the prompt silently
+    /// instead**, so the absence of this error is not evidence that the prompt
+    /// fitted — pair it with a probed real context window
+    /// ([`crate::harness::providers::openai::LocalProbe`]) rather than relying
+    /// on it alone.
+    #[error("context overflow: {message}")]
+    ContextOverflow {
+        /// Provider family identifier, for example `openai` or `ollama`.
+        provider: String,
+        /// Provider model id, when known.
+        model: Option<String>,
+        /// The provider's own message, preserved verbatim.
+        message: String,
+    },
+
     /// A tool invocation returned an error. The payload describes the failure.
     #[error("tool error: {0}")]
     Tool(String),
@@ -235,6 +264,56 @@ pub enum TinyAgentsError {
     Storage(String),
 }
 
+impl TinyAgentsError {
+    /// Builds the right error for a structured provider failure, promoting a
+    /// recognised context overflow to [`TinyAgentsError::ContextOverflow`].
+    ///
+    /// Provider adapters classify the overflow and stamp
+    /// [`CONTEXT_OVERFLOW_CODE`][code] on
+    /// [`ProviderError::code`][pc]; this is where that code becomes a type. Use
+    /// it in place of `TinyAgentsError::Provider(Box::new(error))` at every
+    /// site that has a `ProviderError` in hand — the generic variant is still
+    /// correct for everything else, and is what this returns when the code is
+    /// absent or unrecognised.
+    ///
+    /// [code]: crate::harness::providers::openai::CONTEXT_OVERFLOW_CODE
+    /// [pc]: crate::harness::model::ProviderError::code
+    pub fn from_provider_error(error: crate::harness::model::ProviderError) -> Self {
+        if error.code.as_deref() == Some(crate::harness::providers::openai::CONTEXT_OVERFLOW_CODE) {
+            tracing::debug!(
+                "[error] promoting provider `{}` context-overflow code to a typed error",
+                error.provider
+            );
+            return Self::ContextOverflow {
+                provider: error.provider,
+                model: error.model,
+                message: error.message,
+            };
+        }
+        Self::Provider(Box::new(error))
+    }
+
+    /// Whether this error means the request did not fit the model's context
+    /// window.
+    ///
+    /// Recognises **both** the typed [`TinyAgentsError::ContextOverflow`] and a
+    /// [`TinyAgentsError::Provider`] still carrying the classification code, so
+    /// a caller's compact-and-retry logic behaves identically no matter which
+    /// construction site produced the error. Call sites are migrating to
+    /// [`Self::from_provider_error`]; until every one has, the two shapes must
+    /// classify the same or the same failure would be handled two ways.
+    pub fn is_context_overflow(&self) -> bool {
+        match self {
+            Self::ContextOverflow { .. } => true,
+            Self::Provider(error) => {
+                error.code.as_deref()
+                    == Some(crate::harness::providers::openai::CONTEXT_OVERFLOW_CODE)
+            }
+            _ => false,
+        }
+    }
+}
+
 /// Converts a raw `rusqlite` failure into [`TinyAgentsError::Storage`] so the
 /// session store and run ledger can use `?` on driver calls directly. Call
 /// sites that have useful context to add should still map explicitly rather