open-agents-ai 0.187.590 → 0.187.592

package/README.md

@@ -69,6 +69,7 @@ An autonomous multi-turn tool-calling agent that reads your code, makes changes,
 - [Architecture](#architecture)
 - [Failure-Mode Defense Stack — How Small Models Stay Productive](#failure-mode-defense-stack--how-small-models-stay-productive)
 - [Context Engineering](#context-engineering)
+  - [3-Layer Deduplication](#3-layer-deduplication)
 - [Model-Tier Awareness](#model-tier-awareness)
   - [Small Model Optimization (Research-Backed)](#small-model-optimization-research-backed)
   - [Tool Nesting for Small Models](#tool-nesting-for-small-models)
@@ -1909,12 +1910,28 @@ Key design decisions grounded in research:
 - **Retrieval-augmented context** — Reciprocal Rank Fusion merges lexical search, semantic search, and graph expansion into a single ranked result set. Token-budgeted snippet packing ensures relevant code reaches the model without overflow
 - **Proactive quality guidance** — instead of banning tools after repeated use, the agent receives contextual next-step suggestions appended to tool output, preserving tool availability while steering toward productive actions
 - **Tiered system prompts** — large (>=30B), medium (8-29B), and small (<=7B) models get appropriately sized instruction sets, balancing capability with context budget
+- **3-layer deduplication** — proactive context pruning uses three complementary layers to prevent redundant tool outputs from consuming context budget: (1) **Exact fingerprint** — full tool name + all arguments hashed; catches identical repeated calls. (2) **Semantic resource key** — normalizes cross-tool access to the same resource (e.g., `file_read("foo.ts")` + `shell("cat foo.ts")` both map to `resource:file:foo.ts`); for `file_read`, the key includes offset/limit (`resource:file:big.ts@10:50` vs `resource:file:big.ts@200:50`) to prevent false positives when reading different sections of large files. (3) **Aged file eviction** — files not accessed in N turns are pruned regardless of uniqueness. Together these layers keep context lean without losing distinct information
 - **Context composition tracing** — every context assembly emits a structured event showing section labels and token estimates for eval observability
 
 Research provenance: grounded in "A Survey of Context Engineering for LLMs" (context assembly equation), "Modular Prompt Optimization" (section-local textual gradients), "Reasoning Up the Instruction Ladder" (priority hierarchy), "GEPA" (reflective prompt evolution), "Prompt Flow Integrity" (least-privilege context passing), [RepoMaster](https://arxiv.org/abs/2505.21577) (8K token budget validation), and [RIG](https://arxiv.org/abs/2601.10112) (flat graph format).
 
+### 3-Layer Deduplication
 
+<a name="3-layer-deduplication"></a>
 
+<div align="right"><a href="#top">back to top</a></div>
+
+The `proactivePrune()` system in the agentic runner uses three complementary deduplication layers to prevent redundant tool outputs from consuming the context budget:
+
+| Layer | Mechanism | What It Catches | False-Positive Safe |
+|-------|-----------|-----------------|---------------------|
+| **1. Exact fingerprint** | Hash of tool name + all arguments | Identical repeated calls (`file_read("foo.ts")` called twice with same args) | ✅ Fully safe — only prunes byte-identical calls |
+| **2. Semantic resource key** | Normalized resource identifier across tools | Cross-tool duplicates (`file_read("foo.ts")` + `shell("cat foo.ts")`); repeated reads of the same file range | ✅ Safe — `file_read` keys include offset/limit (`resource:file:big.ts@10:50` vs `resource:file:big.ts@200:50`), so different sections of large files are never conflated |
+| **3. Aged file eviction** | Turn-count since last access | Stale file contents no longer needed | ✅ Safe — only evicts files not accessed in N turns |
+
+**Why offset/limit matters (REG-67):** Without line-range awareness in the resource key, reading different sections of a large file would map to the same key (`resource:file:big.ts`), causing the older section to be pruned — a false positive that loses unique information. The fix includes offset and limit in the key, so `file_read("big.ts", offset=10, limit=50)` → `resource:file:big.ts@10:50` and `file_read("big.ts", offset=200, limit=50)` → `resource:file:big.ts@200:50` are treated as distinct resources.
+
+**Why semantic dedup was dead code (REG-62):** The `seenResource` Map and `_buildResourceKey()` method were declared but never called from `proactivePrune()`. The entire cross-tool dedup layer was inert until wired in v0.103.10. See [dedup-false-positive-meta-analysis.md](docs/dedup-false-positive-meta-analysis.md) for the full root-cause analysis.
 
 ## Model-Tier Awareness