ltcai 0.5.1 → 0.6.0

package/README.md

@@ -266,14 +266,16 @@ Supported routes include OpenAI-compatible APIs, OpenRouter, Groq, Together, xAI
 
 ## Current release
 
-**0.4.0** completes the Knowledge Graph v2 read/write cutover:
-
-- 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
+**0.6.0** completes the runtime / registry / config extraction sprint:
+
+- `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,29 @@
 # Changelog
 
+## [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/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())]