jac-coder 0.2.0__tar.gz → 0.2.1__tar.gz

{jac_coder-0.2.0 → jac_coder-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jac-coder
-Version: 0.2.0
+Version: 0.2.1
 Summary: AI coding agent backend for Jac, powered by jac-byllm
 Requires-Python: >=3.12
 Requires-Dist: python-dotenv>=1.0.0

jac_coder-0.2.1/README.md

@@ -0,0 +1,158 @@
+# JacCoder
+
+![JacCoder CLI](assets/cli.png)
+
+AI coding agent for the Jaseci stack, built entirely in [Jac](https://github.com/jaseci-labs/jaseci) using Object-Spatial Programming. Features an orchestrator-worker architecture with compiler-level Jac Intelligence, self-correcting code writes, and in-process SubAgent delegation.
+
+## Architecture
+
+![JacCoder Graph Architecture](assets/graph.png)
+
+## Features
+
+- **Orchestrator-Worker Architecture** — MainAgent (27 tools) handles tasks directly or delegates to focused WorkerAgent / ExplorerAgent walkers
+- **Jac Intelligence** — compiler-level AST analysis via jaclang (`analyze_project`, `find_symbol`)
+- **Skills System** — Claude-Code-compatible `SKILL.md` directories, lazy-loaded so the LLM gets authoritative Jac syntax instead of stale training data
+- **Self-Correcting Writes** — automatic JS-to-Jac sanitization, in-process syntax check, and `.jac-server.log` error monitoring on every write
+- **Browser Validation Loop** — `browser_validate` shells out to agent-browser with cross-turn FAIL escalation (1st: hint → 2nd: warning → 3rd+: mandatory bisect)
+- **In-Process SubAgents** — walkers, not subprocesses; share event stream + cost tracker + graph context
+- **MCP Integration** — built-in `jac-mcp` plus user-added stdio/http/sse servers, configs persisted in the graph
+- **Multi-Provider LLM** — 100+ models via [byllm](https://github.com/jaseci-labs/byllm); per-session model + API-key override is thread-local (no `os.environ` mutation)
+- **Public API** — clean interface for CLI, VS Code extension, JacBuilder, library mode
+- **Context Management** — smart tiered compaction with LLM-summary fallback; mode-aware dynamic prompt assembly
+
+## Prerequisites
+
+- Python 3.12+
+
+```bash
+pip install jac-coder
+# or for development:
+pip install -e .
+```
+
+Dependencies (auto-installed): `jaclang`, `byllm`, `mcp>=1.0.0`, `jac-mcp`, `python-dotenv`.
+
+## Quick Start
+
+```bash
+# Set API key
+export OPENAI_API_KEY="sk-..."
+
+# Interactive REPL
+jac cli.jac
+
+# Single prompt (non-interactive)
+jac cli.jac run "build a hello world jac app at /tmp/myapp"
+
+# Resume a session
+jac cli.jac session <id-prefix>
+```
+
+## Architecture
+
+```
+Root → Session → MainAgent
+                    ├── handles simple tasks directly (read, search, edit, git, browser)
+                    └── spawn_agent() → WorkerAgent (write+run) or ExplorerAgent (read-only)
+                                         └── walker runs in-process, returns result to MainAgent
+```
+
+- **MainAgent (node)** — orchestrator with 27 tools. Handles simple tasks directly, delegates complex work via `spawn_agent`. `max_react_iterations=80`.
+- **WorkerAgent (walker)** — in-process SubAgent with 14 tools (can write/edit/run). For known changes.
+- **ExplorerAgent (walker)** — in-process SubAgent with 10 tools (read-only + web search). For root-cause investigation.
+- **Session (node)** — persistent chat state, history, active files, errors, mode hint.
+- **ProjectMemory (node)** — AST-derived codebase knowledge (nodes, walkers, edges, imports). Backed by `.jaccoder/progress.md` as primary source of truth.
+- **McpRegistry (node)** — persisted MCP server configs.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full picture.
+
+## Tools
+
+MainAgent has 27 tools, grouped by domain:
+
+| Group | Tool | Description |
+|-------|------|-------------|
+| Reason | `think` | Explicit reasoning step (loop-guarded) |
+| Read | `read_file` | Read files with line numbers and pagination |
+| Read | `list_files` | List directory contents |
+| Read | `grep_search` | Regex search across files |
+| Read | `find_files` | Find files by glob pattern |
+| Read | `analyze_project` | Full AST analysis (nodes, walkers, edges, imports) |
+| Read | `find_symbol` | Find symbol definition, fields, usages, exact import |
+| Read | `load_jac_skill` | Load full body of a Jac skill by name |
+| Write | `write_code` | Write file — anti-pattern blocking, auto sanitize, syntax check |
+| Write | `edit_code` | Find-and-replace with the same self-correcting pipeline |
+| Run | `run_command` | Execute shell commands (permission-guarded, auto-detects servers → background) |
+| Run | `jac_run` | Run `.jac` files |
+| Git | `git_status`, `git_diff`, `git_log`, `git_commit` | First-class git ops (`git_commit` is the only sanctioned way to commit) |
+| Web | `web_fetch`, `web_search` | HTTP fetch + DuckDuckGo search |
+| Browser | `browser_open`, `browser_do`, `browser_state`, `browser_validate`, `browser_close` | Visual QA via agent-browser; `browser_validate` is the primary pass/fail check |
+| Delegate | `spawn_agent` | In-process WorkerAgent / ExplorerAgent walker |
+| Interact | `ask_question`, `update_todos` | User prompt + multi-step task tracking |
+| MCP | `mcp_call` | Call any tool from a connected MCP server |
+
+## Public API
+
+External apps import only from `jac_coder.api`:
+
+```python
+from jac_coder.api import initialize, create_session, chat, close_session
+
+initialize("web")
+session = create_session("/path/to/project", title="My App")
+result = chat(session["session_id"], "build a calculator")
+print(result["response"])
+```
+
+## Configuration
+
+Config sources (highest priority first):
+
+1. Environment: `MODEL`, `TEMPERATURE`, `MAX_TOKENS`, `MAX_REACT_ITERATIONS`
+2. Project: `./jaccoder.json`
+3. Global: `~/.jaccoder/config.json`
+
+## Testing
+
+```bash
+python -m pytest tests/ -v    # 10 unit suites
+```
+
+## Project Structure
+
+```
+jac-code/
+├── cli.jac                       # CLI entry point (REPL + subcommands)
+├── jac_coder/                    # Core package
+│   ├── api.jac                   # Public API — the only module external apps import
+│   ├── server.jac                # JSON-RPC stdio server for the VS Code extension
+│   ├── core/
+│   │   ├── nodes.jac             # MainAgent, WorkerAgent, ExplorerAgent, Session, ProjectMemory
+│   │   └── walkers.jac           # interact, new_session, list_sessions, etc.
+│   ├── lib/
+│   │   └── coder.jac             # JacCoder library-mode class (stateless + service modes)
+│   ├── infra/
+│   │   ├── config.jac            # Multi-source config + SessionAwareModel (thread-local LLM override)
+│   │   └── mcp_manager.jac       # MCP server registry (graph-persisted)
+│   ├── runtime/
+│   │   ├── context.jac           # Tiered compaction with LLM-summary fallback
+│   │   ├── events.jac            # Event bus, doom-loop detection, abort signal
+│   │   ├── memory.jac            # AST-first ProjectMemory (LLM fallback)
+│   │   ├── permission.jac        # Permission rule engine (allow / ask / deny)
+│   │   ├── prompt.jac            # Mode-aware dynamic prompt assembly
+│   │   ├── skills.jac            # SKILL.md registry + listing injection
+│   │   └── cost_tracker.jac      # Opt-in token + USD cost tracking
+│   ├── tool/                     # 28 tools organized by domain
+│   │   ├── meta/                 # think, spawn_agent, update_todos, ask_question, validate
+│   │   ├── read/                 # filesystem, search, jac_analyzer, load_jac_skill
+│   │   ├── write/                # checked (write_code/edit_code), scaffold
+│   │   ├── run/                  # shell, guarded, jac_tools
+│   │   ├── net/                  # web, preview (browser_*)
+│   │   ├── git.jac               # git_status, git_diff, git_log, git_commit
+│   │   └── mcp.jac               # mcp_call
+│   └── skills/                   # Bundled SKILL.md directories (Claude-Code-compatible)
+├── tests/                        # 10 unit suites (pytest wrappers + check_*.jac)
+├── vscode-jac-coder/             # VS Code extension (TypeScript)
+└── docs/                         # ARCHITECTURE, ROADMAP, PROGRESS, LIBRARY_MODE
+```

{jac_coder-0.2.0 → jac_coder-0.2.1}/jac_coder/api.impl.jac

@@ -107,9 +107,6 @@ impl create_session(directory: str, title: str = "", agent: str = "main") -> dic
         return {"error": "Failed to create session"};
     }
 
-    # Store in registry so background threads can find it
-    _session_registry[session_id] = session_obj;
-
     return {"session_id": session_id, "title": session_title, "status": "created"};
 }
 
@@ -166,7 +163,6 @@ impl close_session(session_id: str) -> dict {
     }
     matches[0].status = "closed";
     matches[0].updated_at = datetime.now().isoformat();
-    _session_registry.pop(session_id, None);
     return {"status": "closed", "id": matches[0].id};
 }
 
@@ -185,15 +181,9 @@ impl chat(
     edit_mode: str = "auto",
     env_overrides: dict = {}
 ) -> dict {
-    # Find session — try registry first (works across threads), then graph
-    session = _session_registry.get(session_id);
-    if not session {
-        matches = [root()-->][?:Session][?id==session_id];
-        if matches {
-            session = matches[0];
-            _session_registry[session_id] = session;
-        }
-    }
+    # Find session — query the graph directly. The graph is shared across pods
+    # via MongoDB persistence, so this works in single-pod and multi-pod alike.
+    session = _find_session(session_id);
     if not session {
         return {"error": "Session not found", "agent": "error"};
     }
@@ -203,7 +193,6 @@ impl chat(
     try {
         _ = session.id;
     } except Exception {
-        _session_registry.pop(session_id, None);
         return {"error": "Session is stale after a server update. Please close this session and open a new one.", "agent": "error"};
     }
 
@@ -220,8 +209,12 @@ impl chat(
     if env_overrides {
         import from jac_coder.infra.config { set_session_llm }
         import logging as _chatlog;
-        _api_key = str(env_overrides.get("OPENAI_API_KEY", env_overrides.get("ANTHROPIC_API_KEY", "")));
         _model_name = str(env_overrides.get("MODEL", ""));
+        if _model_name.startswith("claude-") {
+            _api_key = str(env_overrides.get("ANTHROPIC_API_KEY", ""));
+        } else {
+            _api_key = str(env_overrides.get("OPENAI_API_KEY", env_overrides.get("ANTHROPIC_API_KEY", "")));
+        }
         _chatlog.getLogger("jac_coder.api").info(f"env_overrides received: model={_model_name} has_key={bool(_api_key)}");
         if _api_key or _model_name {
             import from jac_coder.infra.config { llm as _current_llm }
@@ -292,7 +285,7 @@ impl chat(
             ctx_history.insert(0, {"role": "system", "content": agent_context});
         }
 
-        # Inject available MCP tools into context (cached to avoid rebuilding every turn)
+        # Inject available MCP tools into context (rebuilt every turn)
         mcp_msg = _get_mcp_context_msg();
         if mcp_msg {
             ctx_history.insert(0, mcp_msg);
@@ -557,7 +550,7 @@ impl api_mcp_list() -> list {
 
 
 impl abort_session(session_id: str) -> None {
-    session = _session_registry.get(session_id);
+    session = _find_session(session_id);
     if session {
         session.chat_history.append({
             "role": "assistant",
@@ -567,9 +560,14 @@ impl abort_session(session_id: str) -> None {
 }
 
 
-glob _mcp_ctx_cache: dict = {};  # {"msg": dict, "tool_names": set}
+"""Build MCP tools context message for the LLM system prompt.
 
-"""Build MCP tools context message, cached by tool names."""
+Rebuilt every turn — no module-level cache. The previous in-process cache
+(`_mcp_ctx_cache`) was keyed on `frozenset(tool_names)`, so descriptions or
+inputSchemas could change on another pod without invalidating the cache,
+causing stale system prompts. Rebuild cost is ~50us of string formatting,
+dominated by the LLM call that follows.
+"""
 def _get_mcp_context_msg() -> dict | None {
     try {
         mcp_tools = mcp_get_tools();
@@ -579,12 +577,6 @@ def _get_mcp_context_msg() -> dict | None {
     if not mcp_tools {
         return None;
     }
-    # Check if tools changed since last call
-    current_names = frozenset(f"{t['server']}::{t['name']}" for t in mcp_tools);
-    if _mcp_ctx_cache.get("tool_names") == current_names {
-        return _mcp_ctx_cache.get("msg");
-    }
-    # Rebuild
     lines: list = [
         "Available MCP tools — call via mcp_call(server_name, tool_name, arguments_json):",
         "Check each tool's inputSchema for required arguments before calling."
@@ -600,10 +592,7 @@ def _get_mcp_context_msg() -> dict | None {
         }
         lines.append(f"  - server={t['server']}  tool={t['name']}  {t['description']}{schema_hint}");
     }
-    msg: dict = {"role": "system", "content": "\n".join(lines)};
-    _mcp_ctx_cache["msg"] = msg;
-    _mcp_ctx_cache["tool_names"] = current_names;
-    return msg;
+    return {"role": "system", "content": "\n".join(lines)};
 }
 
 

{jac_coder-0.2.0 → jac_coder-0.2.1}/jac_coder/api.jac

@@ -13,7 +13,7 @@ import from jac_coder.util.tool_output { tool_end }
 import from jac_coder.runtime.permission { permission_engine }
 import from jac_coder.util.sandbox { set_sandbox_root, set_browser_exec }
 import from jac_coder.runtime.context { build_context, ContextConfig }
-import from jac_coder.core.walkers { new_session, ensure_main_agent, _consume_llm_stream }
+import from jac_coder.core.walkers { new_session, ensure_main_agent, _consume_llm_stream, _find_session }
 import from jac_coder.infra.mcp_manager {
     mcp_add_server,
     mcp_disconnect_server,
@@ -43,11 +43,6 @@ import from jac_coder.runtime.events {
 }
 
 
-# Thread-safe session registry — graph root() is per-request in jac-cloud,
-# so background threads can't find sessions via [root()-->]. This dict
-# is module-level and accessible from any thread.
-glob _session_registry: dict = {};
-
 """Initialize jac-coder."""
 def initialize(mode: str = "web") -> None;
 

{jac_coder-0.2.0 → jac_coder-0.2.1}/jac_coder/core/nodes.impl.jac

@@ -106,7 +106,17 @@ Respond to what the user is asking RIGHT NOW. Don't recap. Concise by default, d
 
 ## Delegation
 - Simple (1-2 files, questions, git): handle directly.
-- Multi-file or investigation: spawn_agent(task, mode="worker"|"explorer").
+- Multi-file, investigation, or complex: spawn_agent().
+
+SubAgent cannot see this conversation. Every task string must be fully self-contained.
+
+Before spawning worker: use think + read_file + grep_search until you know the exact change needed. Task string must include: file path:line, function/node name, exact problem, what NOT to touch.
+Good: `Fix delegation.impl.jac:112 — has_errs hardcoded False, extract from result.errors. Don't touch above line 108.`
+Bad: `Fix the error tracking bug` / `Based on what you found, fix it`
+
+Mode: `explorer` = root cause unknown → investigate first, then YOU synthesize findings and spawn `worker`. `worker` = exact file and line known → implement directly.
+
+Never delegate understanding. Task strings must prove you already know what to change.
 """;
 
 
@@ -118,6 +128,7 @@ sem WorkerAgent.do_work = """
 
 Expert Jac coder executing a delegated task. Never edit `.jac/` (compiled output).
 
+
 ## Iteration Budget
 Build breadth-first — get all files written and app running before polishing. If a component fails after 2 fix attempts, write a minimal working version and move on. Never spend 10+ iterations on one file.
 

{jac_coder-0.2.0 → jac_coder-0.2.1}/jac_coder/core/nodes.jac

@@ -9,11 +9,10 @@ import from jac_coder.runtime.events { is_abort_requested }
 
 # MainAgent tools — full orchestrator set
 import from jac_coder.tool.meta.think { think }
-import from jac_coder.tool.meta.delegation { spawn_agent }
+import from jac_coder.tool.meta.delegation { spawn_agent, set_iter_count }
 import from jac_coder.tool.meta.todo { update_todos }
 import from jac_coder.tool.read.load_jac_skill { load_jac_skill }
 import from jac_coder.tool.meta.question { ask_question }
-import from jac_coder.tool.write.scaffold { scaffold_project }
 import from jac_coder.tool.net.web { web_fetch, web_search }
 import from jac_coder.tool.run.guarded { run_command }
 import from jac_coder.tool.run.jac_tools { jac_check, jac_run }
@@ -163,7 +162,6 @@ node MainAgent {
             write_code,
             run_command,
             jac_run,
-            scaffold_project,
             # Git — first-class version control
             git_status,
             git_diff,
@@ -200,8 +198,9 @@ node MainAgent {
 # SubAgent walkers — spawned on MainAgent node for task delegation
 # ---------------------------------------------------------------------------
 
-"""on_iteration callback — checks abort flag between ReAct iterations."""
+"""on_iteration callback — checks abort flag and tracks real iteration count."""
 def _iteration_hook(ctx: IterationContext) -> IterationAction {
+    set_iter_count(ctx.iteration);
     if is_abort_requested() {
         return IterationAction.ABORT;
     }
@@ -217,6 +216,9 @@ walker WorkerAgent {
 
     def do_work(task_str: str) -> str by llm(
         tools=[
+            # Reason
+            think,
+            # Understand
             load_jac_skill,
             analyze_project,
             find_symbol,
@@ -224,26 +226,18 @@ walker WorkerAgent {
             list_files,
             grep_search,
             find_files,
+            # Act
             write_code,
             edit_code,
             run_command,
             jac_run,
-            scaffold_project,
+            # Git — status only, workers don't commit
             git_status,
-            git_diff,
-            git_commit,
-            git_log,
-            web_fetch,
-            web_search,
-            browser_open,
-            browser_do,
-            browser_state,
-            browser_close,
-            browser_validate,
-            mcp_call
+            # Validate
+            browser_validate
         ],
         on_iteration=_iteration_hook,
-        max_react_iterations=60,
+        max_react_iterations=30,
         temperature=0.2,
         max_tokens=8192,
         stream=True,

{jac_coder-0.2.0 → jac_coder-0.2.1}/jac_coder/core/walkers.impl.jac

@@ -46,10 +46,6 @@ impl new_session.create with Root entry {
     here ++> session;
     agent = ensure_main_agent();
     session ++> agent;
-    # Persist the new session and the root→session edge so it survives server restarts
-    save(here);
-    save(session);
-    commit();
     report {"session_id": session.id, "title": session.title, "status": "created"};
 }
 
@@ -103,8 +99,6 @@ impl close_session.close with Root entry {
     if matches {
         matches[0].status = "closed";
         matches[0].updated_at = datetime.now().isoformat();
-        save(matches[0]);
-        commit();
         report {"status": "closed", "id": matches[0].id};
     } else {
         report {"error": "Session not found"};
@@ -183,8 +177,6 @@ impl interact.enter_session with Session entry {
     here.chat_history.append({"role": "user", "content": self.message});
     here.updated_at = datetime.now().isoformat();
     self.chat_history = here.chat_history;
-    save(here);
-    commit();
 
     # Visit MainAgent
     visit [-->][?:MainAgent] else {
@@ -244,8 +236,6 @@ impl _persist_response(
     session.chat_history.append(record);
     session.last_agent = agent_mode;
     session.updated_at = datetime.now().isoformat();
-    save(session);
-    commit();
 }
 
 
@@ -415,8 +405,6 @@ impl _respond_and_persist(agent: MainAgent, ctx: interact) -> None {
         # Save mode hint for next turn's dynamic prompt assembly
         import from jac_coder.runtime.prompt { infer_mode_hint }
         session.last_mode_hint = infer_mode_hint(tools_used, files_modified);
-        save(session);
-        commit();
     }
 
     # If aborted, skip persistence — abort note already persisted by stop_jaccoder

jac_coder-0.2.1/jac_coder/infra/kv.jac

@@ -0,0 +1,111 @@
+"""Cross-pod key-value cache backed by jac-scale's managed Redis.
+
+Used for ephemeral state that must be consistent across horizontally-scaled
+jac-coder pods (e.g. the MCP tool list cache, cross-pod abort signals). Falls
+back to a no-op when Redis is not configured — that case applies to local CLI /
+stdio mode and to dev environments where the kvstore URL isn't set. A no-op
+fallback is correct (just slower, since each pod recomputes); a None return from
+`kv_get` is treated by callers as a cache miss, and `get_kv()` returns a no-op
+stub so B2 abort callers can invoke it unconditionally without None checks.
+
+"""
+
+import sys;
+import threading;
+
+# Lazy singleton — created on first access. None means "Redis unavailable,
+# operate in no-cache mode".
+glob _kv: Any = None;
+glob _kv_init_done: bool = False;
+glob _kv_init_lock: Any = threading.Lock();
+
+
+"""Silent no-op fallback returned by get_kv() when Redis is unavailable.
+Satisfies the .get() / .set_with_ttl() / .delete() interface so B2 abort
+callers never need to check for None."""
+obj _NoOpKv {
+    def set_with_ttl(key: str, value: dict, ttl: int) -> bool { return False; }
+    def get(key: str) -> (dict | None) { return None; }
+    def delete(key: str) -> int { return 0; }
+}
+
+
+"""Initialize the kvstore handle once. Safe to call repeatedly."""
+def _try_init() -> None {
+    global _kv, _kv_init_done;
+    if _kv_init_done {
+        return;
+    }
+    with _kv_init_lock {
+        if _kv_init_done {
+            return;
+        }
+        _kv_init_done = True;
+        try {
+            import from jac_scale.lib { kvstore }
+            _kv = kvstore(db_name="jac_coder", db_type="redis");
+        } except Exception as e {
+            # Redis not configured — common in CLI/stdio mode and local dev.
+            # Cross-pod cache is disabled; callers fall through to recompute.
+            sys.stderr.write(
+                f"[kv] Redis unavailable, cross-pod cache disabled: {e}\n"
+            );
+            _kv = None;
+        }
+    }
+}
+
+
+"""Get a cached dict by key, or None if missing/unavailable."""
+def kv_get(key: str) -> dict | None {
+    _try_init();
+    if _kv is None {
+        return None;
+    }
+    try {
+        return _kv.get(key);
+    } except Exception as e {
+        sys.stderr.write(f"[kv] get({key}) failed: {e}\n");
+        return None;
+    }
+}
+
+
+"""Store a dict under key with TTL in seconds. No-op if Redis unavailable."""
+def kv_set_ttl(key: str, value: dict, ttl: int) -> None {
+    _try_init();
+    if _kv is None {
+        return;
+    }
+    try {
+        _kv.set_with_ttl(key, value, ttl=ttl);
+    } except Exception as e {
+        sys.stderr.write(f"[kv] set_with_ttl({key}) failed: {e}\n");
+    }
+}
+
+
+"""Delete a key. No-op if Redis unavailable or key missing."""
+def kv_delete(key: str) -> None {
+    _try_init();
+    if _kv is None {
+        return;
+    }
+    try {
+        _kv.delete(key);
+    } except Exception as e {
+        sys.stderr.write(f"[kv] delete({key}) failed: {e}\n");
+    }
+}
+
+
+"""Return the kvstore instance or a no-op stub — never returns None.
+Used by B2 (cross-pod abort) in events.jac where callers invoke
+.get() / .set_with_ttl() / .delete() directly without None-checking."""
+def get_kv() -> Any {
+    _try_init();
+    if _kv is None {
+        return _NoOpKv();
+    }
+    return _kv;
+}

{jac_coder-0.2.0 → jac_coder-0.2.1}/jac_coder/infra/mcp_manager.impl.jac

@@ -17,6 +17,7 @@ import from mcp { ClientSession }
 import from mcp.client.stdio { stdio_client, StdioServerParameters }
 import from mcp.client.streamable_http { streamablehttp_client }
 import from mcp.client.sse { sse_client }
+import from jac_coder.infra.kv { kv_get, kv_set_ttl, kv_delete }
 
 # Cached update info for jac-mcp (populated by background thread on startup).
 glob _jac_mcp_update_info: dict = {};
@@ -27,7 +28,7 @@ glob _mgr_thread: Any = None;
 glob _mgr_lock: Any = threading.Lock();
 glob _sessions: dict = {};     # name -> ClientSession (open inside _mgr_loop)
 glob _exit_stacks: dict = {};  # name -> AsyncExitStack (keeps transports alive)
-glob _tools_cache: dict = {};  # {"tools": [...], "ts": float} — cached tool list
+glob _TOOLS_CACHE_KEY: str = "jc:mcp:tools";
 glob _TOOLS_CACHE_TTL: int = 30;  # seconds before tool list is re-fetched
 glob _builtin_names: set = set();  # names registered via mcp_register_builtin
 glob _disconnected_names: set = set();  # names intentionally disconnected by user
@@ -84,8 +85,6 @@ def _load_configs() -> dict {
 def _save_configs(configs: dict) -> None {
     reg = _get_registry();
     reg.servers = configs;
-    save(reg);
-    commit();
 }
 
 
@@ -277,7 +276,7 @@ impl mcp_add_server(name: str, config: dict) -> dict {
     configs = _load_configs();
     configs[name] = config;
     _save_configs(configs);
-    _tools_cache.clear();  # Invalidate cache — new server added
+    kv_delete(_TOOLS_CACHE_KEY);  # Invalidate cross-pod cache — new server added
     return {
         "status": "connected",
         "name": name,
@@ -299,7 +298,7 @@ impl mcp_disconnect_server(name: str) -> dict {
     }
     _disconnected_names.add(name);
     _submit(_close_connection(name));
-    _tools_cache.clear();
+    kv_delete(_TOOLS_CACHE_KEY);
     return {"status": "disconnected", "name": name};
 }
 
@@ -317,7 +316,7 @@ impl mcp_reconnect_server(name: str) -> dict {
     # produces Unknown in the Jac type checker — the for pattern is used
     # consistently throughout this file).
     _submit(_close_connection(name));
-    _tools_cache.clear();
+    kv_delete(_TOOLS_CACHE_KEY);
     for (n, config) in configs.items() {
         if n == name {
             try {
@@ -346,7 +345,7 @@ impl mcp_delete_server(name: str) -> dict {
     _submit(_close_connection(name));
     configs.pop(name);
     _save_configs(configs);
-    _tools_cache.clear();
+    kv_delete(_TOOLS_CACHE_KEY);
     return {"status": "deleted", "name": name};
 }
 
@@ -397,6 +396,7 @@ impl mcp_register_builtin(name: str, config: dict) -> None {
     config["builtin"] = True;
     configs[name] = config;
     _save_configs(configs);
+    kv_delete(_TOOLS_CACHE_KEY);  # Invalidate cross-pod cache — server set changed
     if name == "jac-mcp" {
         threading.Thread(target=_check_jac_mcp_version, daemon=True).start();
     }
@@ -405,9 +405,9 @@ impl mcp_register_builtin(name: str, config: dict) -> None {
 
 """Return a flat list of all tools from all registered servers (cached for 30s)."""
 impl mcp_get_tools() -> list {
-    now = time.time();
-    if _tools_cache and (now - _tools_cache.get("ts", 0)) < _TOOLS_CACHE_TTL {
-        return _tools_cache["tools"];
+    cached = kv_get(_TOOLS_CACHE_KEY);
+    if cached is not None {
+        return cached.get("tools", []);
     }
 
     configs = _load_configs();
@@ -420,8 +420,7 @@ impl mcp_get_tools() -> list {
         }
     }
 
-    _tools_cache["tools"] = all_tools;
-    _tools_cache["ts"] = now;
+    kv_set_ttl(_TOOLS_CACHE_KEY, {"tools": all_tools}, ttl=_TOOLS_CACHE_TTL);
     return all_tools;
 }