ltcai 0.5.1 → 1.0.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/TaeSooPark-PTS/LatticeAI/main/docs/images/logo.svg" alt="Lattice AI" width="280"/>
   <br/>
-  <strong>Local-first AI workspace for your files, chats, folders, and knowledge graph.</strong>
+  <strong>AI Workspace OS for local-first graph, memory, agents, workflows, skills, and timelines.</strong>
   <br/><br/>
 
 [![PyPI](https://img.shields.io/pypi/v/ltcai?label=PyPI&color=blue)](https://pypi.org/project/ltcai/)
@@ -24,18 +24,33 @@
 
 Most AI tools answer one chat at a time. They do not remember your folders, your project history, your previous decisions, or how your files relate to each other.
 
-**Lattice AI turns your local workspace into an AI memory layer.**
+**Lattice AI turns your local workspace into an AI Workspace OS.**
 
-It reads approved local folders, indexes chats and documents, builds a searchable knowledge graph, and lets you ask questions over that graph with local or opt-in cloud models.
+It reads approved local folders, indexes chats and documents, builds a searchable knowledge graph, and connects the graph to snapshots, personal memory, agent runs, workflow history, skills, and an auditable timeline.
 
 ```text
 Local files + chats + folders
           ↓
 Automatic knowledge graph
           ↓
-Graph-aware AI chat, search, document generation, and admin audit
+Graph-aware chat, snapshots, memory, agents, workflows, skills, and timeline
 ```
 
+### New in 1.0.0: AI Workspace OS
+
+- Workspace OS command center at `/workspace`
+- First-run onboarding state API and UI
+- Graph RAG answer traces with sources, nodes, edges, confidence, and jump links
+- Local indexing dashboard with watcher state, success/failure counts, pause/resume/remove
+- Workspace snapshots, Time Machine views, export, and Knowledge Diff
+- Personal memory CRUD/search linked back to the graph
+- Multi-agent graph entities and agent run history
+- Relationship Explorer for inbound, outbound, related entities, and shortest path
+- Local Computer Memory remains OFF by default and requires explicit approval
+- Skill Marketplace registry with install, uninstall, update, enable, disable, and version state
+- Workflow Graph for upload -> summarize -> generate -> export style work histories
+- VS Code commands for Explain Selection, Refactor Selection, Generate Tests, Send To Lattice, and Ask About Current File
+
 ### Built for people who want
 
 - a private AI workspace that runs from their own machine
@@ -76,7 +91,7 @@ LTCAI
 2. Start the local server with `LTCAI`
 3. Press `Cmd+Shift+A` to open the chat panel
 
-**First run:** create an account → the first account becomes admin → choose a model → connect folders → start asking questions.
+**First run:** create an account -> the first account becomes admin -> open `/workspace` -> complete onboarding -> choose a model -> connect folders -> start asking questions.
 
 ---
 
@@ -266,14 +281,16 @@ Supported routes include OpenAI-compatible APIs, OpenRouter, Groq, Together, xAI
 
 ## Current release
 
-**0.4.0** completes the Knowledge Graph v2 read/write cutover:
+**0.6.0** completes the runtime / registry / config extraction sprint:
 
-- graph reads and writes flow through the v2 store, behind the unchanged
-  `KnowledgeGraphStore` interface
-- legacy ↔ v2 result equivalence guaranteed (single read path + reconstruction
-  views), backed by a dedicated equivalence test suite
-- dual-write projection keeps the v2 graph in sync on every write and delete
-- deterministic ordering (`… , id ASC`) so results match across both paths
+- `server.py` is now a thin compatibility entrypoint; FastAPI app assembly lives
+  in `latticeai.server_app`
+- tool dispatch, governance, permission views, MCP descriptions, and prompt
+  catalog metadata are centralized in `ToolRegistry`
+- agent role prompts are split into `latticeai.core.agent_prompts`, while
+  `AgentRuntime` remains the injected state-machine core
+- Python package, npm package, VS Code extension, FastAPI app, and `/health`
+  version metadata are aligned at `0.6.0`
 
 See the full [changelog](docs/CHANGELOG.md).
 

package/docs/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [1.0.0] - 2026-05-31
+
+> AI Workspace OS integration release.
+
+### Added
+
+- **Workspace OS foundation** — new `/workspace` UI and `/workspace/*` API surface
+  organize LatticeAI around Graph, Snapshot, Memory, Agent, Workflow, Skills,
+  and Timeline areas while preserving existing chat, graph, admin, CLI, and MCP
+  compatibility.
+- **First-run onboarding wizard** — reentrant step state, completion API,
+  hardware scan, model recommendations, folder connection state, and recovery
+  from failed/skipped steps.
+- **Graph RAG answer trace** — each generated answer records source files,
+  graph nodes, graph edges, confidence, retrieval metadata, graph jumps, and
+  source jumps.
+- **Local indexing dashboard** — indexed folder status, watcher state, success
+  and failure counts, last scan time, graph node/edge totals, and pause/resume/
+  remove operations.
+- **Workspace snapshots and Time Machine** — immutable snapshots capture graph,
+  chat, settings, indexed folders, and loaded model state. Snapshots can be
+  listed, viewed by area, compared, and exported as ZIP artifacts.
+- **Knowledge Diff** — Snapshot A/B comparison reports nodes added/removed/
+  changed, edges added/removed, and decisions changed.
+- **Personal Memory layer** — per-user preferences, decisions, working style,
+  frequently used tools, and long-term memory with CRUD/search and graph links.
+- **Multi-Agent Graph** — Planner, Executor, Reviewer, Researcher, and Release
+  Agent entities plus agent run history and timeline recording.
+- **Relationship Explorer** — inbound/outbound edge views, related entities, and
+  shortest-path exploration for graph nodes.
+- **Local Computer Memory** — defaults OFF, requires explicit approval, tracks
+  activity summaries only after consent, and links approved records to graph.
+- **Skill Marketplace registry** — install, uninstall, update, enable, disable,
+  version tracking, and metadata state surfaced in Workspace OS.
+- **Workflow Graph** — stores workflow timelines and searchable workflow graphs
+  for repeatable actions such as Upload -> Summarize -> Generate -> Export.
+- **VS Code workflow** — added Refactor Selection, Generate Tests, Send To
+  Lattice, and Ask About Current File while preserving Explain Selection.
+
+### Changed
+
+- Release metadata aligned to `1.0.0` across Python, npm, VS Code extension,
+  FastAPI app metadata, `/health`, README, changelog, and release docs.
+- `KnowledgeGraphStore` gained non-destructive `remove_local_source()` for
+  deleting only derived index/graph data while leaving user files untouched.
+
+### Validation
+
+- Unit, integration, Python build, npm build, VSIX packaging, and package
+  verification were run for this release.
+
+## [0.6.0] - 2026-05-31
+
+> Runtime / registry / config extraction release.
+
+### Changed
+
+- **server.py thin entrypoint** — moved FastAPI app assembly and route wiring to
+  `latticeai.server_app`; `server.py` now preserves the historical `server:app`
+  import path for uvicorn, Docker, CLI scripts, and tests.
+- **ToolRegistry ownership** — centralized tool dispatch, governance policies,
+  permission views, MCP descriptions, prompt catalog text, and file-create
+  metadata in `latticeai.core.tool_registry`. `tools.execute_tool()` delegates
+  through the registry.
+- **Agent prompts separated** — moved planner / executor / critic / memory
+  updater prompts to `latticeai.core.agent_prompts`; `AgentRuntime` remains the
+  injected state-machine core in `latticeai.core.agent`.
+- **Release metadata** — bumped Python package, npm package, VS Code extension,
+  FastAPI app, and `/health` version to `0.6.0`.
+
+### Validation
+
+- Full test suite: 202 passed.
+- Python package build, `twine check`, npm pack, and VSIX package build verified.
+
 ## [0.5.1] - 2026-05-31
 
 > KGStoreV2 정규화 스키마 + 마이그레이션 하드닝 + native API 정리(릴리스).

package/knowledge_graph.py

@@ -1609,6 +1609,39 @@ class KnowledgeGraphStore:
             )
         return {"source_id": source_id, "watch_enabled": bool(enabled)}
 
+    def remove_local_source(self, source_id: str) -> Dict[str, Any]:
+        """Remove one approved local source and its derived graph projection.
+
+        This is intentionally non-destructive for user files: only the LatticeAI
+        index rows, graph nodes, edges, and chunks derived from the source are
+        removed. The original folder and files are never touched.
+        """
+        source_id = str(source_id or "").strip()
+        if not source_id:
+            raise ValueError("source_id required")
+        with self._connect() as conn:
+            source = conn.execute(
+                "SELECT id, root_path FROM knowledge_sources WHERE id=?",
+                (source_id,),
+            ).fetchone()
+            if not source:
+                raise ValueError(f"knowledge source not found: {source_id}")
+            rows = conn.execute(
+                "SELECT graph_node_id FROM local_file_index WHERE source_id=? AND graph_node_id IS NOT NULL",
+                (source_id,),
+            ).fetchall()
+            graph_node_ids = [row["graph_node_id"] for row in rows if row["graph_node_id"]]
+            for graph_node_id in graph_node_ids:
+                self._delete_local_file_graph(conn, graph_node_id)
+            conn.execute("DELETE FROM local_file_index WHERE source_id=?", (source_id,))
+            conn.execute("DELETE FROM knowledge_sources WHERE id=?", (source_id,))
+            self._cleanup_local_graph_orphans(conn, source_id)
+        return {
+            "source_id": source_id,
+            "root_path": source["root_path"],
+            "removed_graph_nodes": len(graph_node_ids),
+        }
+
     def _extract_local_file_text(self, path: Path, category: str, *, include_ocr: bool) -> Tuple[str, Dict[str, Any]]:
         ext = path.suffix.lower()
         meta: Dict[str, Any] = {"parser": _parser_type_for_category(category, ext)}

package/latticeai/__init__.py

@@ -1 +1,3 @@
-"""Lattice AI — modular server package."""
+"""Lattice AI - modular server package."""
+
+__version__ = "1.0.0"

package/latticeai/core/agent.py

@@ -8,13 +8,13 @@ no globals, and no I/O of its own — every collaborator is injected through
 
 Two adapters justify the seam:
 
-* production wires ``AgentDeps`` from server.py's ``LLMRouter``, governance
+* production wires ``AgentDeps`` from ``latticeai.server_app``'s ``LLMRouter``, governance
   map, audit log, and prompts;
 * tests pass fake ports (an LLM that returns canned JSON, a recording tool
   executor) and drive a full PLAN→EXECUTE→VERIFY→DONE cycle without a server.
 
 HTTP concerns — request parsing, chat-history persistence, response shaping,
-scheduling the background memory update — stay in server.py. This module
+scheduling the background memory update — stay in the app layer. This module
 only owns the state machine.
 """
 

package/latticeai/core/agent_prompts.py

@@ -0,0 +1,101 @@
+"""Role prompts for the Lattice multi-role agent runtime."""
+
+from __future__ import annotations
+
+from latticeai.core.tool_registry import TOOL_CATALOG_BRIEF
+
+
+PLANNER_PROMPT = """You are the PLANNER role in Lattice AI's multi-role agent harness.
+Your ONLY job: analyze the request and produce a structured execution plan.
+You do NOT call tools or write code.
+
+Respond with exactly ONE JSON object (no markdown, no fences):
+{
+  "action": "plan",
+  "state": "PLANNING",
+  "goal": "one-sentence goal in the user's language",
+  "steps": [
+    {"id": 1, "description": "what this step does", "action": "expected_tool", "purpose": "why needed"}
+  ],
+  "requires_approval": true,
+  "rollback_strategy": "git",
+  "estimated_steps": 3
+}
+
+Rules:
+- requires_approval = true if ANY step uses write/exec tools (edit_file, write_file, run_command, etc.)
+- rollback_strategy = "git" if steps modify existing files; "none" otherwise
+- Keep steps realistic: 2-4 for simple tasks, up to 10 for complex ones
+- Do NOT specify full tool args -- that is the Executor's job
+
+Available tools:""" + TOOL_CATALOG_BRIEF
+
+
+EXECUTOR_PROMPT = """You are the EXECUTOR role in Lattice AI's multi-role agent harness.
+You have a plan from the Planner. Execute it step by step using exactly one tool per response.
+
+You think and act like a senior software engineer:
+- Read (read_file, grep) BEFORE editing -- never guess at file contents
+- Prefer edit_file over write_file for existing files
+- Keep changes small and precise
+- Verify after changes with build_project or run_command
+
+Respond with exactly ONE JSON object per step:
+{"thoughts": "what you learned / why this next action", "action": "tool_name", "args": {...}}
+
+When the task is fully done AND a tool result in this run confirms it:
+{"thoughts": "verified", "action": "final", "message": "한국어로 무엇을 했고 어디서 검증했는지 요약"}
+
+ANTI-PATTERNS (will halt the loop):
+- Editing without reading first -> read_file + grep BEFORE edit_file
+- Repeating the same action+args -> check the transcript
+- Claiming done without a verification tool result in transcript
+- Hallucinating imports or file paths that were never confirmed by a tool result
+
+Available tools:""" + TOOL_CATALOG_BRIEF
+
+
+CRITIC_PROMPT = """You are the CRITIC / REVIEWER role in Lattice AI's multi-role agent harness.
+Review the execution transcript and determine whether the goal was achieved.
+
+Respond with exactly ONE JSON object:
+{
+  "action": "verdict",
+  "state": "VERIFYING",
+  "verdict": "PASS",
+  "reason": "why you think it passed or failed (cite specific tool results)",
+  "corrections": [],
+  "confidence": 0.95,
+  "next_state": "DONE"
+}
+
+verdict: "PASS" | "FAIL"
+next_state:
+  "DONE"      -- task succeeded; finish
+  "EXECUTING" -- task failed but corrections can fix it (use corrections field for retry)
+  "ROLLBACK"  -- task failed AND file changes should be undone
+
+Criteria for PASS: a tool result in the transcript explicitly confirms success.
+Be strict. Claiming done without evidence = FAIL."""
+
+
+MEMORY_UPDATER_PROMPT = """You are the MEMORY UPDATER role in Lattice AI's multi-role agent harness.
+After a completed task, extract reusable learnings.
+
+Respond with exactly ONE JSON object:
+{
+  "action": "memory",
+  "state": "DONE",
+  "learnings": ["one concise fact about this codebase or task"],
+  "artifacts": ["relative/path/to/created_or_modified_file"],
+  "save_to_knowledge": false
+}
+
+Rules:
+- max 5 learnings, one sentence each
+- save_to_knowledge = true only if learnings are genuinely useful across future sessions
+- artifacts = files the Executor actually created or modified (from transcript)
+"""
+
+
+AGENT_SYSTEM_PROMPT = EXECUTOR_PROMPT

package/latticeai/core/tool_registry.py

@@ -0,0 +1,288 @@
+"""Tool dispatch, governance, and catalog metadata.
+
+The registry is the single ownership point for tool names: one object exposes
+dispatch, policy lookup, prompt catalog text, MCP descriptions, and permission
+views. The actual tool functions still live in the top-level ``tools`` module
+to preserve the public API and keep this module free of filesystem side
+effects at import time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Mapping, Optional, TypedDict
+
+
+class ToolPolicy(TypedDict):
+    risk: str
+    destructive: bool
+    shell: bool
+    network: bool
+    auto_approve: bool
+    sandbox: str
+    rollback: str
+
+
+class ToolPermission(TypedDict):
+    tool: str
+    risk: str
+    requires_approval: bool
+    network: bool
+
+
+TOOL_CATALOG_BRIEF = """
+FILESYSTEM  : list_dir  workspace_tree  read_file  write_file  edit_file  grep  search_files  inspect_html  preview_url
+PLANNING    : todo_read  todo_write
+PROJECT     : run_command  build_project  deploy_project  create_web_project
+GIT (read)  : git_status  git_diff  git_log  git_show
+LOCAL FS    : local_list  local_read  local_write  read_document
+DOCS        : create_docx  create_xlsx  create_pptx  create_pdf
+KNOWLEDGE   : knowledge_save  knowledge_search  knowledge_tree
+COMPUTER    : computer_screenshot  computer_open_app  computer_open_url  computer_click  computer_type  computer_key
+MISC        : network_status  clear_history  final
+"""
+
+FILE_CREATE_ACTIONS = frozenset({
+    "create_docx",
+    "create_xlsx",
+    "create_pptx",
+    "create_pdf",
+    "write_file",
+    "edit_file",
+    "create_web_project",
+})
+
+LOCAL_WRITE_BLOCKED_PREFIXES = (
+    "/etc/",
+    "/usr/",
+    "/bin/",
+    "/sbin/",
+    "/System/",
+    "/private/etc/",
+    "/Library/LaunchDaemons/",
+    "/Library/LaunchAgents/",
+)
+
+RISK_LEVEL_MAP = {
+    "read": "low",
+    "write": "medium",
+    "exec": "high",
+    "destructive": "high",
+}
+
+
+def _r(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="read", destructive=False, shell=False, network=False,
+        auto_approve=True, sandbox=sandbox, rollback=rollback,
+    )
+
+
+def _rs(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="read", destructive=False, shell=True, network=False,
+        auto_approve=True, sandbox=sandbox, rollback=rollback,
+    )
+
+
+def _rn(sandbox: str = "system", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="read", destructive=False, shell=True, network=True,
+        auto_approve=True, sandbox=sandbox, rollback=rollback,
+    )
+
+
+def _w(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="write", destructive=False, shell=False, network=False,
+        auto_approve=False, sandbox=sandbox, rollback=rollback,
+    )
+
+
+def _e(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="exec", destructive=False, shell=True, network=False,
+        auto_approve=False, sandbox=sandbox, rollback=rollback,
+    )
+
+
+def _en(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="exec", destructive=False, shell=True, network=True,
+        auto_approve=False, sandbox=sandbox, rollback=rollback,
+    )
+
+
+def _ec(sandbox: str = "system", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="exec", destructive=False, shell=False, network=False,
+        auto_approve=False, sandbox=sandbox, rollback=rollback,
+    )
+
+
+TOOL_GOVERNANCE: Dict[str, ToolPolicy] = {
+    "list_dir": _r(),
+    "workspace_tree": _r(),
+    "read_file": _r(),
+    "search_files": _r(),
+    "grep": _r(),
+    "inspect_html": _r(),
+    "todo_read": _r(),
+    "local_list": _r(sandbox="home"),
+    "local_read": _r(sandbox="home"),
+    "git_status": _rs(),
+    "git_diff": _rs(),
+    "git_log": _rs(),
+    "git_show": _rs(),
+    "knowledge_search": _r(sandbox="home"),
+    "knowledge_tree": _r(sandbox="home"),
+    "obsidian_search": _r(sandbox="home"),
+    "obsidian_tree": _r(sandbox="home"),
+    "computer_screenshot": _r(sandbox="system"),
+    "computer_status": _r(sandbox="system"),
+    "chrome_status": _r(sandbox="system"),
+    "computer_use_status": _r(sandbox="system"),
+    "network_status": _rn(),
+    "write_file": _w(rollback="git"),
+    "edit_file": _w(rollback="git"),
+    "create_web_project": _w(),
+    "create_docx": _w(),
+    "create_xlsx": _w(),
+    "create_pptx": _w(),
+    "create_pdf": _w(),
+    "preview_url": _w(),
+    "todo_write": _w(),
+    "knowledge_save": _w(sandbox="home"),
+    "obsidian_save": _w(sandbox="home"),
+    "local_write": _w(sandbox="home"),
+    "run_command": _e(),
+    "build_project": _e(),
+    "deploy_project": _en(),
+    "computer_click": _ec(),
+    "computer_type": _ec(),
+    "computer_key": _ec(),
+    "computer_scroll": _ec(),
+    "computer_drag": _ec(),
+    "computer_move": _ec(),
+    "computer_open_app": _ec(),
+    "computer_open_url": ToolPolicy(
+        risk="exec", destructive=False, shell=False, network=True,
+        auto_approve=False, sandbox="system", rollback="none",
+    ),
+}
+
+TOOL_GOVERNANCE_DEFAULT = ToolPolicy(
+    risk="write", destructive=False, shell=False, network=False,
+    auto_approve=False, sandbox="workspace", rollback="none",
+)
+
+MCP_TOOL_DESCRIPTIONS: Dict[str, str] = {
+    "list_dir": "List files in the agent workspace.",
+    "workspace_tree": "Return a recursive workspace tree.",
+    "read_file": "Read a UTF-8 file from the workspace with optional line numbers and offset/limit slicing.",
+    "write_file": "Write a UTF-8 file inside the workspace (new files / full rewrites).",
+    "edit_file": "Precise diff-style edit: replace exact old_string with new_string. Requires unique match unless replace_all=true.",
+    "search_files": "Substring search in text files (legacy).",
+    "grep": "Regex search across the workspace with line numbers and optional context.",
+    "todo_read": "Read the agent's persistent TODO list for the current workspace.",
+    "todo_write": "Replace the agent's TODO list (id, content, status: pending/in_progress/completed).",
+    "clear_history": "Clear chat history to reduce context and speed up responses.",
+    "inspect_html": "Inspect local HTML structure and assets.",
+    "preview_url": "Return a server URL for a workspace file.",
+    "create_docx": "Create a Word DOCX document in the agent workspace.",
+    "create_xlsx": "Create an XLSX spreadsheet in the agent workspace.",
+    "create_pptx": "Create a PPTX presentation deck in the agent workspace.",
+    "create_pdf": "Create a PDF document in the agent workspace.",
+    "local_list": "List any local folder (requires user permission via UI).",
+    "local_read": "Read any local file (requires user permission via UI).",
+    "local_write": "Write any local file (requires user permission via UI).",
+    "read_document": "Extract text from PDF, DOCX, XLSX, PPTX, TXT, MD, CSV files.",
+    "computer_screenshot": "Capture the current Mac screen as base64 PNG.",
+    "computer_open_app": "Open or focus a Mac app, e.g. Google Chrome.",
+    "computer_open_url": "Open a URL in a Mac app, e.g. Google Chrome.",
+    "computer_click": "Click at screen coordinates (x, y).",
+    "computer_type": "Type text at the current focus position.",
+    "computer_key": "Press a keyboard key or shortcut (e.g. 'command+c').",
+    "computer_scroll": "Scroll at screen coordinates.",
+    "computer_move": "Move the mouse to screen coordinates.",
+    "computer_drag": "Drag from (x1,y1) to (x2,y2).",
+    "computer_status": "Check if Mac desktop control (pyautogui) is available.",
+    "chrome_status": "Report Chrome desktop bridge availability.",
+    "computer_use_status": "Report Mac desktop-control bridge availability.",
+    "knowledge_save": "Save a note into the local knowledge garden.",
+    "knowledge_search": "Search the local knowledge garden.",
+    "knowledge_tree": "List local knowledge garden markdown files.",
+    "knowledge_graph_ingest": "Ingest a message, AI answer, or connector event into the SQLite knowledge graph.",
+    "knowledge_graph_search": "Search graph nodes, summaries, and JSON metadata.",
+    "knowledge_graph_graph": "Return Obsidian-style graph nodes and edges.",
+    "knowledge_graph_context": "Return compact graph-backed RAG context for a prompt.",
+    "obsidian_save": "Save a note into the Obsidian-compatible memory vault.",
+    "obsidian_search": "Search the Obsidian-compatible memory vault.",
+    "obsidian_tree": "List Obsidian memory vault markdown files.",
+    "git_status": "Read-only local git status inside the workspace.",
+    "git_diff": "Read-only local git diff inside the workspace.",
+    "git_log": "Read-only local git log inside the workspace.",
+    "git_show": "Read-only local git show --stat inside the workspace.",
+    "network_status": "Get current local/private IP, public IP, hostname, and Wi-Fi info.",
+    "run_command": "Run an allowlisted local command inside the workspace.",
+    "build_project": "Run an allowlisted package.json build/compile/typecheck/test script to verify changes actually work.",
+    "deploy_project": "Run an allowlisted package.json deploy/preview/release/package installer script (pkg/exe).",
+}
+
+
+@dataclass
+class ToolRegistry:
+    handlers: Mapping[str, Callable[[Dict[str, Any]], Dict[str, Any]]]
+    governance: Mapping[str, ToolPolicy] = field(default_factory=lambda: TOOL_GOVERNANCE)
+    default_policy: ToolPolicy = field(default_factory=lambda: TOOL_GOVERNANCE_DEFAULT)
+    descriptions: Mapping[str, str] = field(default_factory=lambda: MCP_TOOL_DESCRIPTIONS)
+    catalog_brief: str = TOOL_CATALOG_BRIEF
+    file_create_actions: frozenset[str] = FILE_CREATE_ACTIONS
+    local_write_blocked_prefixes: tuple[str, ...] = LOCAL_WRITE_BLOCKED_PREFIXES
+    risk_level_map: Mapping[str, str] = field(default_factory=lambda: RISK_LEVEL_MAP)
+
+    @property
+    def admin_only_tools(self) -> frozenset[str]:
+        return frozenset(
+            name for name, policy in self.governance.items()
+            if policy["sandbox"] == "system" or policy["risk"] in {"exec", "destructive"}
+        )
+
+    def registered_tools(self) -> frozenset[str]:
+        return frozenset(self.handlers)
+
+    def execute(self, action: str, args: Dict[str, Any], *, error_cls: type[Exception]) -> Dict[str, Any]:
+        handler = self.handlers.get(action)
+        if handler is None:
+            raise error_cls(f"Unknown action: {action}")
+        return handler(args or {})
+
+    def policy_for(self, action_name: str, args: Optional[dict] = None) -> ToolPolicy:
+        policy = self.governance.get(action_name, self.default_policy)
+        if action_name == "local_write":
+            path = str((args or {}).get("path", ""))
+            if any(path.startswith(prefix) for prefix in self.local_write_blocked_prefixes):
+                return ToolPolicy(
+                    risk="destructive", destructive=True, shell=False, network=False,
+                    auto_approve=False, sandbox="system", rollback="none",
+                )
+        return policy
+
+    def risk_level(self, policy_or_action: ToolPolicy | str, args: Optional[dict] = None) -> str:
+        if isinstance(policy_or_action, str):
+            policy = self.policy_for(policy_or_action, args or {})
+        else:
+            policy = policy_or_action
+        return self.risk_level_map.get(policy["risk"], "medium")
+
+    def permission(self, name: str, args: Optional[dict] = None) -> ToolPermission:
+        policy = self.policy_for(name, args or {})
+        return ToolPermission(
+            tool=name,
+            risk=self.risk_level(policy),
+            requires_approval=not policy["auto_approve"],
+            network=policy["network"],
+        )
+
+    def permissions(self) -> list[ToolPermission]:
+        return [self.permission(name) for name in sorted(self.governance.keys())]