toolrecall 0.3.2__tar.gz

toolrecall-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Schultka (robka.de)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolrecall-0.3.2/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: toolrecall
+Version: 0.3.2
+Summary: The Deterministic Tool Cache for LLM Agents — no LLM decides what to cache. SQLite FTS5, zero deps, MCP multiplexer, zero-trust WAF.
+Author-email: Robin Schultka <robin@robka.de>
+License: MIT
+Project-URL: Homepage, https://github.com/whiskybeer/toolrecall
+Project-URL: Repository, https://github.com/whiskybeer/toolrecall
+Project-URL: Documentation, https://github.com/whiskybeer/toolrecall#readme
+Keywords: tool-cache,llm,agent,token-savings,sqlite,fts5
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: toml-write
+Requires-Dist: tomli-w>=1.0; extra == "toml-write"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Dynamic: license-file
+
+# ToolRecall — The Deterministic Tool Cache for LLM Agents
+
+**No LLM decides what to cache. No second agent. No misclassification. Only you do.**
+
+ToolRecall is a **deterministic** middleware layer for autonomous AI agents. It sits between the agent and the OS, catching tool executions and managing MCP servers via Unix Domain Sockets.
+
+Unlike caching frameworks that use a second LLM ("Cache Planner") to classify tools as cacheable or not — introducing hallucination risk, extra API cost, and cold-start latency — ToolRecall is purely deterministic: files invalidate on mtime, commands expire by explicit TTL, and `ttl=0` guarantees a tool **always** executes live. No guesses. No grey zones. No data loss from a bad LLM classification.
+
+| What ToolRecall IS | What ToolRecall IS NOT |
+|---|---|
+| ✅ **Deterministic** — byte-exact tool output cache from SQLite, no LLM in the caching loop | ❌ Not an LLM-driven Cache Planner — no second agent deciding what to cache |
+| ✅ **MCP Multiplexer** — single daemon manages all external MCP servers | ❌ Not a chronological call-graph — mtime handles staleness without state tracking |
+| ✅ **Zero-Trust WAF** — path sandboxing, secret air-gapping, read-only mode | ❌ Not a vector database — no embeddings, no GPU, no semantic search |
+| ✅ **FTS5 Knowledge Base** — zero-dep full-text search over docs and notes | ❌ Not a distributed cache — single-node SQLite, no Redis/Cluster |
+| ✅ **Deterministic replay** — freeze OS state for 100% reproducible agent runs | ❌ Not a replacement for real-time data — use `ttl=0` for dynamic endpoints |
+
+---
+
+## Why Not an LLM-Powered Cache?
+
+Some caching frameworks use a second LLM — a "Cache Planner" — to classify tools by cacheability: STATIC (cache forever), TRANSIENT (expire by TTL), or NONE (never cache). That sounds intelligent, but introduces failure modes ToolRecall eliminates by design — because ToolRecall is **deterministic**, not heuristic:
+
+| Failure mode | LLM-Driven Cache | ToolRecall (Deterministic) |
+|---|---|---|
+| **Misclassification** | LLM guesses `send_message()` is STATIC → messages silently dropped | `ttl=0` means NEVER cache. Binary, deterministic, no AI middleman. |
+| **Extra API cost** | Every new tool needs an LLM call to classify | $0 — SQLite FTS5, no embeddings, no API calls |
+| **Cold-start latency** | Must analyze tool metadata before first cache decision | First call executes live, cached on return — zero overhead |
+| **Side-effect blindness** | Relies on tool name/description text, not actual behavior | mtime-based auto-invalidation — file edited? next read is fresh. |
+| **Reproducibility** | Non-deterministic — LLM may classify same tool differently on different runs | Always byte-identical for same args + same mtime. 100% reproducible. |
+
+**The principle:** *Intelligent caching doesn't need an intelligence. It needs a filesystem, a clock, and the honesty to say "I don't know — execute it live."*
+
+If you want an LLM to decide what to cache, you're adding a second agent that can hallucinate, costs money per decision, and can silently break your workflow. ToolRecall caches yes/no based on explicit TTLs and file modification times. **Deterministic by default.**
+
+---
+
+## The Core Problem: The Context Snowball
+
+LLM context windows are stateless. Every time an agent reads a 10,000-token file, those 10,000 tokens enter the history. Over 100 turns, that's 1,000,000 billed input tokens for the same file — the O(N²) context snowball.
+
+**ToolRecall's solution (Micro-RAG):**
+1. Agents read the file once.
+2. The agent drops the dump from its active context window.
+3. Hours later if needed again, ToolRecall serves the exact bytes from SQLite — 1.5ms, no API call.
+4. File edited? `mtime` invalidates the entry. Next read is fresh.
+
+**The paradigm shift:** Cost and latency are eliminated from sessions. The *only* reason to end a session now is attention degradation (topic drift), not token bills or wait time.
+
+---
+
+## Universal Agent Compatibility (Drop-In MCP)
+
+ToolRecall exposes a standard `stdio` MCP interface (`toolrecall mcp`). It works out-of-the-box with **any** agent — Claude Code, Cursor, Cline, Hermes:
+
+```bash
+claude mcp add toolrecall toolrecall mcp
+```
+
+No custom plugins. No SDK changes. 100% Day-1 ecosystem penetration.
+
+---
+
+## Security Architecture (The WAF)
+
+ToolRecall doesn't cure an LLM of being prompt-injected — it cages the agent to neutralize the consequences:
+
+- **Daemon-based IPC:** Unix Domain Sockets only. No open TCP ports (immune to SSRF).
+- **Cryptographic path resolution:** `os.path.realpath` blocks `../../../etc/shadow` before the OS is touched.
+- **Execution blackholes:** `allow_terminal = false` drops RCE attempts into a void.
+- **Air-gapped secrets:** API keys in `~/.toolrecall/.env` — the LLM never sees them.
+- **Read-only sandbox:** `read_only_sandbox = true` drops any tool containing `write`, `delete`, `push`.
+
+---
+
+## The Five Axes (Breaking the Iron Triangle)
+
+1. **Faster:** Tool execution drops from ~1.5s to <0.1ms on cache hits — ~85 minutes saved in a 13-hour session.
+2. **Cheaper:** Deterministic byte-exact responses qualify for 90% server-side prompt caching discount. 81% fewer input tokens.
+3. **Deterministic:** Freeze OS state. 100% reproducible agent runs. No OS flakiness, no network jitter.
+4. **Safer:** Zero-Trust WAF, path sandboxing, secret air-gapping.
+5. **Universal:** Standard `stdio` MCP — any agent, any framework.
+
+---
+
+## The Hourglass Architecture
+
+```
+  [ Claude Code ]   [ Cursor IDE ]   [ Hermes Agent ]
+         \                |                /
+          \               |               /
+        +───────────────────────────────────+
+        │  Standard stdio Protocol (Bridge) │  <- Client Layer
+        +─────────────────┬─────────────────+
+                          │ Unix Domain Socket
+        +─────────────────▼─────────────────+
+        │         ToolRecall Daemon         │  <- Gateway Layer
+        │  ┌─────────────────────────────┐  │
+        │  │   In-Memory LRU (L1 Cache)  │  │
+        │  └──────────────┬──────────────┘  │
+        │  ┌──────────────▼──────────────┐  │
+        │  │   SQLite WAL (Persistent)   │  │
+        │  └─────────────────────────────┘  │
+        │  ┌─────────────────────────────┐  │
+        │  │   MCP Server Multiplexer    │  │
+        │  └──────────────┬──────────────┘  │
+        +─────────────────┼─────────────────+
+                          │ Lazy-Loaded stdio Subprocesses
+        +─────────────────▼─────────────────+
+        │ [ Downstream MCP: GitHub / Time ] │  <- Execution Layer
+        +───────────────────────────────────+
+```
+
+---
+
+## Features
+
+### Byte-Exact Tool Caching
+- **File Cache:** Invalidates on file modification (`mtime`) — no stale reads.
+- **Terminal Cache:** Caches read-only commands by TTL (`git status` for 30s, `hostname` for 1h).
+- **Script & Code Cache:** `cached_run`, `cached_exec` with explicit `ttl=0` bypass for state-changing operations.
+- **MCP Cache:** TTL-based caching for external MCP tool responses (13.5× speedup measured).
+
+### MCP Multiplexer (AI Gateway)
+- One daemon manages all your MCP servers (GitHub, Brave Search, time, fetch, ...).
+- **Lazy loading:** Servers boot in 0.01s only when first called.
+- **Idle timeout:** Killed after 15min inactivity — daemon drops from 130MB to 11MB RAM.
+- Agents connect to **one** server: `toolrecall mcp`. Session startup: ~0.01s instead of ~1.7s.
+
+### FTS5 Knowledge Base
+Zero-dependency full-text search over docs, notes, Hermes memory, Obsidian vaults. BM25 ranking, Porter stemming, source-filtered queries. No embeddings, no GPU, no API calls.
+
+### Data Engine (RLHF / SFT Trajectories)
+```bash
+toolrecall export-dataset ~/trajectories.jsonl
+```
+Exact (Action → State) pairs mined from agent sessions. Zero-cost SFT/DPO dataset generation.
+
+---
+
+## Quickstart
+
+**Requirements:** Python 3.11+, standard SQLite.
+
+```bash
+# 1. Install
+pip install toolrecall
+
+# 2. Init config + .env
+toolrecall init
+
+# 3. Start daemon
+toolrecall daemon &
+```
+
+### Claude Code
+```bash
+claude mcp add toolrecall toolrecall mcp
+```
+
+### Direct Python
+```python
+from toolrecall import cached_read
+
+result = cached_read("README.md")
+print(f"Cached: {result['cached']}")
+```
+
+---
+
+## Configuration
+
+TOML (default, zero deps via stdlib `tomllib`) or YAML (optional, requires `pyyaml`).
+
+```toml
+[mcp]
+allowed_paths = ["~/projects", "~/.hermes/skills"]
+allow_terminal = false
+default_ttl = 60
+
+[mcp_multiplex]
+enabled = true
+idle_minutes = 15
+
+[mcp_multiplex.servers_config]
+github = { command = "npx", args = ["-y", "@modelcontextprotocol/server-github"], ttl = 60 }
+```
+
+`TOOLRECALL_*` environment variables override TOML (for CI/CD, multi-agent setups).
+
+---
+
+## Status
+
+**Experimental.** Used in heavy autonomous agent workflows. Before production CI/CD: ensure your allowlist is strictly scoped.
+
+---
+
+## Roadmap
+
+- Live cache dashboard (`toolrecall dashboard`)
+- Tool-calling profiler (latency breakdown per MCP call)
+- Active cache invalidation on mutation tools (write_file, POST, git push)
+- Container sandbox for `cached_run` (Docker backend)
+- Webhook-triggered invalidation (CI/events POST to purge keys)
+
+---
+
+## Documentation
+
+- [The Bottleneck Solved](docs/BOTTLENECK_SOLVED.md) — O(N²) context theory
+- [Knowledge DB](docs/KNOWLEDGE_DB.md) — FTS5 indexing guide
+- [Docker Deployment](docs/DOCKER.md) — containerized stack
+- [Security Architecture](SECURITY.md) — WAF details
+- [Enterprise Scale](docs/ENTERPRISE_SCALE.md) — L1 cache metaphor
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common fixes

toolrecall-0.3.2/README.md

@@ -0,0 +1,215 @@
+# ToolRecall — The Deterministic Tool Cache for LLM Agents
+
+**No LLM decides what to cache. No second agent. No misclassification. Only you do.**
+
+ToolRecall is a **deterministic** middleware layer for autonomous AI agents. It sits between the agent and the OS, catching tool executions and managing MCP servers via Unix Domain Sockets.
+
+Unlike caching frameworks that use a second LLM ("Cache Planner") to classify tools as cacheable or not — introducing hallucination risk, extra API cost, and cold-start latency — ToolRecall is purely deterministic: files invalidate on mtime, commands expire by explicit TTL, and `ttl=0` guarantees a tool **always** executes live. No guesses. No grey zones. No data loss from a bad LLM classification.
+
+| What ToolRecall IS | What ToolRecall IS NOT |
+|---|---|
+| ✅ **Deterministic** — byte-exact tool output cache from SQLite, no LLM in the caching loop | ❌ Not an LLM-driven Cache Planner — no second agent deciding what to cache |
+| ✅ **MCP Multiplexer** — single daemon manages all external MCP servers | ❌ Not a chronological call-graph — mtime handles staleness without state tracking |
+| ✅ **Zero-Trust WAF** — path sandboxing, secret air-gapping, read-only mode | ❌ Not a vector database — no embeddings, no GPU, no semantic search |
+| ✅ **FTS5 Knowledge Base** — zero-dep full-text search over docs and notes | ❌ Not a distributed cache — single-node SQLite, no Redis/Cluster |
+| ✅ **Deterministic replay** — freeze OS state for 100% reproducible agent runs | ❌ Not a replacement for real-time data — use `ttl=0` for dynamic endpoints |
+
+---
+
+## Why Not an LLM-Powered Cache?
+
+Some caching frameworks use a second LLM — a "Cache Planner" — to classify tools by cacheability: STATIC (cache forever), TRANSIENT (expire by TTL), or NONE (never cache). That sounds intelligent, but introduces failure modes ToolRecall eliminates by design — because ToolRecall is **deterministic**, not heuristic:
+
+| Failure mode | LLM-Driven Cache | ToolRecall (Deterministic) |
+|---|---|---|
+| **Misclassification** | LLM guesses `send_message()` is STATIC → messages silently dropped | `ttl=0` means NEVER cache. Binary, deterministic, no AI middleman. |
+| **Extra API cost** | Every new tool needs an LLM call to classify | $0 — SQLite FTS5, no embeddings, no API calls |
+| **Cold-start latency** | Must analyze tool metadata before first cache decision | First call executes live, cached on return — zero overhead |
+| **Side-effect blindness** | Relies on tool name/description text, not actual behavior | mtime-based auto-invalidation — file edited? next read is fresh. |
+| **Reproducibility** | Non-deterministic — LLM may classify same tool differently on different runs | Always byte-identical for same args + same mtime. 100% reproducible. |
+
+**The principle:** *Intelligent caching doesn't need an intelligence. It needs a filesystem, a clock, and the honesty to say "I don't know — execute it live."*
+
+If you want an LLM to decide what to cache, you're adding a second agent that can hallucinate, costs money per decision, and can silently break your workflow. ToolRecall caches yes/no based on explicit TTLs and file modification times. **Deterministic by default.**
+
+---
+
+## The Core Problem: The Context Snowball
+
+LLM context windows are stateless. Every time an agent reads a 10,000-token file, those 10,000 tokens enter the history. Over 100 turns, that's 1,000,000 billed input tokens for the same file — the O(N²) context snowball.
+
+**ToolRecall's solution (Micro-RAG):**
+1. Agents read the file once.
+2. The agent drops the dump from its active context window.
+3. Hours later if needed again, ToolRecall serves the exact bytes from SQLite — 1.5ms, no API call.
+4. File edited? `mtime` invalidates the entry. Next read is fresh.
+
+**The paradigm shift:** Cost and latency are eliminated from sessions. The *only* reason to end a session now is attention degradation (topic drift), not token bills or wait time.
+
+---
+
+## Universal Agent Compatibility (Drop-In MCP)
+
+ToolRecall exposes a standard `stdio` MCP interface (`toolrecall mcp`). It works out-of-the-box with **any** agent — Claude Code, Cursor, Cline, Hermes:
+
+```bash
+claude mcp add toolrecall toolrecall mcp
+```
+
+No custom plugins. No SDK changes. 100% Day-1 ecosystem penetration.
+
+---
+
+## Security Architecture (The WAF)
+
+ToolRecall doesn't cure an LLM of being prompt-injected — it cages the agent to neutralize the consequences:
+
+- **Daemon-based IPC:** Unix Domain Sockets only. No open TCP ports (immune to SSRF).
+- **Cryptographic path resolution:** `os.path.realpath` blocks `../../../etc/shadow` before the OS is touched.
+- **Execution blackholes:** `allow_terminal = false` drops RCE attempts into a void.
+- **Air-gapped secrets:** API keys in `~/.toolrecall/.env` — the LLM never sees them.
+- **Read-only sandbox:** `read_only_sandbox = true` drops any tool containing `write`, `delete`, `push`.
+
+---
+
+## The Five Axes (Breaking the Iron Triangle)
+
+1. **Faster:** Tool execution drops from ~1.5s to <0.1ms on cache hits — ~85 minutes saved in a 13-hour session.
+2. **Cheaper:** Deterministic byte-exact responses qualify for 90% server-side prompt caching discount. 81% fewer input tokens.
+3. **Deterministic:** Freeze OS state. 100% reproducible agent runs. No OS flakiness, no network jitter.
+4. **Safer:** Zero-Trust WAF, path sandboxing, secret air-gapping.
+5. **Universal:** Standard `stdio` MCP — any agent, any framework.
+
+---
+
+## The Hourglass Architecture
+
+```
+  [ Claude Code ]   [ Cursor IDE ]   [ Hermes Agent ]
+         \                |                /
+          \               |               /
+        +───────────────────────────────────+
+        │  Standard stdio Protocol (Bridge) │  <- Client Layer
+        +─────────────────┬─────────────────+
+                          │ Unix Domain Socket
+        +─────────────────▼─────────────────+
+        │         ToolRecall Daemon         │  <- Gateway Layer
+        │  ┌─────────────────────────────┐  │
+        │  │   In-Memory LRU (L1 Cache)  │  │
+        │  └──────────────┬──────────────┘  │
+        │  ┌──────────────▼──────────────┐  │
+        │  │   SQLite WAL (Persistent)   │  │
+        │  └─────────────────────────────┘  │
+        │  ┌─────────────────────────────┐  │
+        │  │   MCP Server Multiplexer    │  │
+        │  └──────────────┬──────────────┘  │
+        +─────────────────┼─────────────────+
+                          │ Lazy-Loaded stdio Subprocesses
+        +─────────────────▼─────────────────+
+        │ [ Downstream MCP: GitHub / Time ] │  <- Execution Layer
+        +───────────────────────────────────+
+```
+
+---
+
+## Features
+
+### Byte-Exact Tool Caching
+- **File Cache:** Invalidates on file modification (`mtime`) — no stale reads.
+- **Terminal Cache:** Caches read-only commands by TTL (`git status` for 30s, `hostname` for 1h).
+- **Script & Code Cache:** `cached_run`, `cached_exec` with explicit `ttl=0` bypass for state-changing operations.
+- **MCP Cache:** TTL-based caching for external MCP tool responses (13.5× speedup measured).
+
+### MCP Multiplexer (AI Gateway)
+- One daemon manages all your MCP servers (GitHub, Brave Search, time, fetch, ...).
+- **Lazy loading:** Servers boot in 0.01s only when first called.
+- **Idle timeout:** Killed after 15min inactivity — daemon drops from 130MB to 11MB RAM.
+- Agents connect to **one** server: `toolrecall mcp`. Session startup: ~0.01s instead of ~1.7s.
+
+### FTS5 Knowledge Base
+Zero-dependency full-text search over docs, notes, Hermes memory, Obsidian vaults. BM25 ranking, Porter stemming, source-filtered queries. No embeddings, no GPU, no API calls.
+
+### Data Engine (RLHF / SFT Trajectories)
+```bash
+toolrecall export-dataset ~/trajectories.jsonl
+```
+Exact (Action → State) pairs mined from agent sessions. Zero-cost SFT/DPO dataset generation.
+
+---
+
+## Quickstart
+
+**Requirements:** Python 3.11+, standard SQLite.
+
+```bash
+# 1. Install
+pip install toolrecall
+
+# 2. Init config + .env
+toolrecall init
+
+# 3. Start daemon
+toolrecall daemon &
+```
+
+### Claude Code
+```bash
+claude mcp add toolrecall toolrecall mcp
+```
+
+### Direct Python
+```python
+from toolrecall import cached_read
+
+result = cached_read("README.md")
+print(f"Cached: {result['cached']}")
+```
+
+---
+
+## Configuration
+
+TOML (default, zero deps via stdlib `tomllib`) or YAML (optional, requires `pyyaml`).
+
+```toml
+[mcp]
+allowed_paths = ["~/projects", "~/.hermes/skills"]
+allow_terminal = false
+default_ttl = 60
+
+[mcp_multiplex]
+enabled = true
+idle_minutes = 15
+
+[mcp_multiplex.servers_config]
+github = { command = "npx", args = ["-y", "@modelcontextprotocol/server-github"], ttl = 60 }
+```
+
+`TOOLRECALL_*` environment variables override TOML (for CI/CD, multi-agent setups).
+
+---
+
+## Status
+
+**Experimental.** Used in heavy autonomous agent workflows. Before production CI/CD: ensure your allowlist is strictly scoped.
+
+---
+
+## Roadmap
+
+- Live cache dashboard (`toolrecall dashboard`)
+- Tool-calling profiler (latency breakdown per MCP call)
+- Active cache invalidation on mutation tools (write_file, POST, git push)
+- Container sandbox for `cached_run` (Docker backend)
+- Webhook-triggered invalidation (CI/events POST to purge keys)
+
+---
+
+## Documentation
+
+- [The Bottleneck Solved](docs/BOTTLENECK_SOLVED.md) — O(N²) context theory
+- [Knowledge DB](docs/KNOWLEDGE_DB.md) — FTS5 indexing guide
+- [Docker Deployment](docs/DOCKER.md) — containerized stack
+- [Security Architecture](SECURITY.md) — WAF details
+- [Enterprise Scale](docs/ENTERPRISE_SCALE.md) — L1 cache metaphor
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common fixes

toolrecall-0.3.2/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68.0", "packaging", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toolrecall"
+version = "0.3.2"
+description = "The Deterministic Tool Cache for LLM Agents — no LLM decides what to cache. SQLite FTS5, zero deps, MCP multiplexer, zero-trust WAF."
+readme = "README.md"
+authors = [
+    {name = "Robin Schultka", email = "robin@robka.de"},
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["tool-cache", "llm", "agent", "token-savings", "sqlite", "fts5"]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+yaml = ["pyyaml >= 6.0"]
+toml-write = ["tomli-w >= 1.0"]
+dev = ["pytest >= 7.0", "flake8 >= 6.0"]
+
+[project.urls]
+Homepage = "https://github.com/whiskybeer/toolrecall"
+Repository = "https://github.com/whiskybeer/toolrecall"
+Documentation = "https://github.com/whiskybeer/toolrecall#readme"
+
+[project.scripts]
+toolrecall = "toolrecall.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["toolrecall*"]

toolrecall-0.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toolrecall-0.3.2/tests/test_cache_safety.py

@@ -0,0 +1,114 @@
+import os
+import sys
+import unittest
+import tempfile
+import time
+import shutil
+
+# Force a clean, isolated test database path before loading toolrecall
+test_db_dir = tempfile.mkdtemp()
+test_db_path = os.path.join(test_db_dir, "test_cache.db")
+os.environ["TOOLRECALL_CACHE_DB"] = test_db_path
+
+# Add current path to sys.path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from toolrecall.cache import cached_exec, cached_run, cached_terminal, DEFAULT_CACHEABLE
+
+
+class TestCacheSafety(unittest.TestCase):
+    def setUp(self):
+        # Ensure database is clean for each test
+        if os.path.exists(test_db_path):
+            os.remove(test_db_path)
+        from toolrecall.cache import _init
+        _init()
+
+    def tearDown(self):
+        if os.path.exists(test_db_path):
+            os.remove(test_db_path)
+
+    @classmethod
+    def tearDownClass(cls):
+        shutil.rmtree(test_db_dir, ignore_errors=True)
+
+    def test_cached_exec_default_ttl_zero(self):
+        """Verify cached_exec default TTL is 0 (or disabled), meaning it executes fresh every time."""
+        code = "import time; print(time.time())"
+        
+        # Run first time
+        res1 = cached_exec(code)
+        # Run second time
+        res2 = cached_exec(code)
+        
+        self.assertFalse(res1.get("cached"), "First run should not be cached")
+        self.assertFalse(res2.get("cached"), "Second run with default TTL=0 should not be cached")
+        self.assertNotEqual(res1.get("output"), res2.get("output"), "Output of dynamic code should be different without cache")
+
+    def test_cached_exec_explicit_ttl(self):
+        """Verify cached_exec with explicit TTL does cache."""
+        code = "print('hello_exec')"
+        
+        res1 = cached_exec(code, ttl=10)
+        res2 = cached_exec(code, ttl=10)
+        
+        self.assertFalse(res1.get("cached"), "First run should not be cached")
+        self.assertTrue(res2.get("cached"), "Second run with explicit TTL should be cached")
+        self.assertEqual(res1.get("output"), res2.get("output"), "Cached output should match")
+
+    def test_cached_run_default_ttl_zero(self):
+        """Verify cached_run default TTL is 0, executing fresh every time."""
+        # Create a temporary script to execute
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
+            f.write("#!/usr/bin/env python3\nimport time; print(time.time())\n")
+            script_path = f.name
+        os.chmod(script_path, 0o755)
+            
+        try:
+            # Run first time
+            res1 = cached_run(script_path)
+            time.sleep(0.01) # Ensure time would advance if it runs fresh
+            # Run second time
+            res2 = cached_run(script_path)
+            
+            self.assertFalse(res1.get("cached"), "First run should not be cached")
+            self.assertFalse(res2.get("cached"), "Second run with default TTL=0 should not be cached")
+            self.assertNotEqual(res1.get("output"), res2.get("output"), "Output of dynamic script should be different without cache")
+        finally:
+            os.remove(script_path)
+
+    def test_cached_run_explicit_ttl(self):
+        """Verify cached_run with explicit TTL does cache."""
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
+            f.write("#!/usr/bin/env python3\nprint('hello_run')\n")
+            script_path = f.name
+        os.chmod(script_path, 0o755)
+            
+        try:
+            res1 = cached_run(script_path, ttl=10)
+            res2 = cached_run(script_path, ttl=10)
+            
+            self.assertFalse(res1.get("cached"), "First run should not be cached")
+            self.assertTrue(res2.get("cached"), "Second run with explicit TTL should be cached")
+            self.assertEqual(res1.get("output"), res2.get("output"), "Cached output should match")
+        finally:
+            os.remove(script_path)
+
+    def test_dynamic_commands_not_in_default_cacheable(self):
+        """Verify dynamic state-sensing commands are NOT in DEFAULT_CACHEABLE."""
+        unsafe_cmds = ["git status", "ls -la", "git branch", "git diff --stat", "ls", "git diff"]
+        for cmd in unsafe_cmds:
+            self.assertNotIn(cmd, DEFAULT_CACHEABLE, f"Unsafe command '{cmd}' must not be in DEFAULT_CACHEABLE")
+
+    def test_cached_terminal_does_not_cache_dynamic_commands(self):
+        """Verify cached_terminal does not cache dynamic commands like git status by default."""
+        # Even if we don't have a git repo, cached_terminal should bypass cache for 'git status'
+        res1 = cached_terminal("git status")
+        res2 = cached_terminal("git status")
+        
+        self.assertFalse(res1.get("cached"), "Dynamic command first run should not be cached")
+        self.assertFalse(res2.get("cached"), "Dynamic command second run should not be cached")
+
+
+if __name__ == "__main__":
+    unittest.main()