ltcai 3.4.1 → 3.6.0

package/static/v3/js/views/knowledge-graph.js

@@ -1,7 +1,10 @@
 /* ============================================================================
- * View: Knowledge Graph — entity/relation explorer.
- * Renders the graph as an SVG mesh against /api/graph with a live inspector.
- * Missing graph data renders an empty unavailable state.
+ * View: Knowledge Graph — the user's digital brain (v3.6.0 Knowledge Graph First).
+ * Tabs: Explore (entity/relation mesh) · Status (graph + ingestion health) ·
+ * Sources (where every node came from) · Capture (web/URL into the graph) ·
+ * Backup (local export / import / backup). Everything you ingest converges here;
+ * models read this graph; local-first keeps it yours. Missing data renders an
+ * honest unavailable state — never fabricated counters.
  * ========================================================================== */
 
 import { escapeHtml } from "../core/dom.js";
@@ -12,6 +15,8 @@ const TYPE_COLOR = {
   Method: "var(--lt3-pillar-hybrid)",
   Model: "var(--accent-3)",
   File: "var(--faint)",
+  Source: "var(--lt3-pillar-hybrid)",
+  Document: "var(--accent)",
   Decision: "var(--accent-3)",
   Task: "var(--accent-2)",
   Person: "var(--accent-pink)",
@@ -19,27 +24,84 @@ const TYPE_COLOR = {
 };
 const colorFor = (t) => TYPE_COLOR[t] || TYPE_COLOR.default;
 
+const TABS = [
+  { key: "explore", label: "Explore", icon: "chart-dots-3" },
+  { key: "status", label: "Status", icon: "activity-heartbeat" },
+  { key: "sources", label: "Sources", icon: "database" },
+  { key: "capture", label: "Capture", icon: "world-www" },
+  { key: "portability", label: "Backup", icon: "archive" },
+];
+
 export async function render(ctx) {
-  const { h, icon, api, store, c } = ctx;
+  const { h, icon, api, c } = ctx;
+  let active = "explore";
 
-  const state = { selected: null, query: "", data: { nodes: [], edges: [] }, source: "pending" };
+  const tabBar = h("div.lt3-row-2");
+  const panelHost = h("div.lt3-stack-4");
 
-  const canvasHost = h("div", c.loading({ lines: 0, block: true }));
-  const inspectorHost = h("div", c.loading({ lines: 4 }));
-  const statHost = h("div.lt3-statrow", c.loading({ lines: 1 }));
-  const srcSlot = h("span", c.sourceBadge("pending"));
+  function renderTabs() {
+    tabBar.replaceChildren(...TABS.map((t) =>
+      h("button.lt3-btn" + (t.key === active ? ".lt3-btn--primary" : ".lt3-btn--ghost"),
+        { on: { click: () => switchTab(t.key) } }, icon(t.icon), t.label)));
+  }
+
+  function switchTab(key) {
+    if (active === key) return;
+    active = key;
+    renderTabs();
+    renderActive();
+  }
+
+  let exploreNode = null;
+  function renderActive() {
+    if (active === "explore") {
+      if (!exploreNode) exploreNode = buildExplore(ctx);
+      panelHost.replaceChildren(exploreNode);
+    } else if (active === "status") {
+      renderStatus(ctx, panelHost);
+    } else if (active === "sources") {
+      renderSources(ctx, panelHost);
+    } else if (active === "capture") {
+      panelHost.replaceChildren(buildCapture(ctx));
+    } else if (active === "portability") {
+      renderPortability(ctx, panelHost);
+    }
+  }
 
   const root = h("div.lt3-stack-6",
     c.viewHeader({
-      eyebrow: "Retrieval · structure",
+      eyebrow: "Your digital brain",
       title: "Knowledge Graph",
-      sub: "Entities and the relations the workspace extracted between them. Click a node to trace its neighborhood.",
+      sub: "Everything you ingest converges here — files, folders, web pages, browser tabs. Models read this graph; local-first keeps it yours.",
       actions: [
-        srcSlot,
-        h("button.lt3-btn.lt3-btn--ghost", { on: { click: () => load() } }, icon("refresh"), "Rebuild view"),
+        h("button.lt3-btn.lt3-btn--ghost", { on: { click: () => ctx.navigate("files") } }, icon("upload"), "Add sources"),
         h("button.lt3-btn.lt3-btn--primary", { on: { click: () => ctx.navigate("hybrid-search") } }, icon("arrows-join"), "Search graph"),
       ],
     }),
+    tabBar,
+    panelHost,
+  );
+
+  renderTabs();
+  renderActive();
+  return root;
+}
+
+/* ── Explore tab (entity/relation mesh) ─────────────────────────────────── */
+function buildExplore(ctx) {
+  const { h, icon, api, c } = ctx;
+  const state = { selected: null, query: "", data: { nodes: [], edges: [] }, source: "pending" };
+
+  const canvasHost = h("div", c.loading({ lines: 0, block: true }));
+  const inspectorHost = h("div", c.loading({ lines: 4 }));
+  const statHost = h("div.lt3-statrow", c.loading({ lines: 1 }));
+  const srcSlot = h("span", c.sourceBadge("pending"));
+
+  const root = h("div.lt3-stack-3",
+    h("div.lt3-row-2",
+      srcSlot,
+      h("button.lt3-btn.lt3-btn--ghost.lt3-btn--sm", { on: { click: () => load() } }, icon("refresh"), "Rebuild view"),
+    ),
     statHost,
     h("div.lt3-split",
       h("div.lt3-stack-3",
@@ -69,7 +131,7 @@ export async function render(ctx) {
     renderInspector();
   }
 
-  function renderStats(stats, graphData) {
+  function renderStats(stats) {
     const nodes = state.data.nodes.length;
     const edges = state.data.edges.length;
     const types = stats && stats.nodes ? Object.keys(stats.nodes).length : new Set(state.data.nodes.map((n) => n.type)).size;
@@ -185,7 +247,221 @@ export async function render(ctx) {
   return root;
 }
 
+/* ── Status tab (graph + ingestion health) ──────────────────────────────── */
+async function renderStatus(ctx, host) {
+  const { h, icon, api, c } = ctx;
+  host.replaceChildren(c.loading({ lines: 3 }));
+  const [port, gs, idx] = await Promise.all([api.kgPortability(), api.graphStats(), api.indexStatus()]);
+  const p = port.data || {};
+  const prov = p.provenance || {};
+  const nodes = sumCounts((gs.data && gs.data.nodes) || {});
+  const edges = sumCounts((gs.data && gs.data.edges) || {});
+  const pipelines = (idx.data && idx.data.pipelines) || {};
+
+  host.replaceChildren(
+    h("div.lt3-row-2", c.sourceBadge(port.source), h("span.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } },
+      p.graph_schema_version != null ? `Schema v${p.graph_schema_version} · embed dim ${p.embed_dim ?? "—"}` : "Knowledge Graph status")),
+    h("div.lt3-statrow",
+      c.stat({ label: "Entities", value: c.fmtNum(nodes), icon: "circles" }),
+      c.stat({ label: "Relations", value: c.fmtNum(edges), icon: "vector-triangle" }),
+      c.stat({ label: "Ingested items", value: c.fmtNum(prov.total || 0), icon: "package-import" }),
+      c.stat({ label: "Embedded (RAG-ready)", value: c.fmtNum(prov.embedded || 0), icon: "vector" }),
+    ),
+    c.card(
+      h("div.lt3-stack-3",
+        h("div.lt3-eyebrow", "Pipelines"),
+        pipelineRow(ctx, "Knowledge graph", pipelines.knowledge_graph),
+        pipelineRow(ctx, "Vector index", pipelines.vector_index),
+        pipelineRow(ctx, "Hybrid retrieval", pipelines.hybrid),
+      ),
+    ),
+    prov.last_ingested_at
+      ? h("p.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } }, `Last ingestion: ${fmtWhen(prov.last_ingested_at)} · ${prov.duplicates || 0} duplicate(s) linked, not re-stored.`)
+      : c.emptyState({ icon: "package-import", title: "Nothing ingested yet", body: "Add files or capture a page to populate the graph." }),
+  );
+}
+
+function pipelineRow(ctx, label, pipe) {
+  const { h, c } = ctx;
+  const stateStr = (pipe && pipe.state) || "unavailable";
+  const detail = pipe && (pipe.entities != null ? `${pipe.entities} entities` : pipe.vectors != null ? `${pipe.vectors} vectors` : pipe.strategy || "");
+  return h("div.lt3-row-2", { style: { "justify-content": "space-between" } },
+    h("div", label, detail ? h("span.lt3-muted", { style: { "margin-left": "var(--lt3-space-2)", "font-size": "var(--lt3-text-sm)" } }, detail) : null),
+    c.statePill(stateStr),
+  );
+}
+
+/* ── Sources tab (provenance: where every node came from) ────────────────── */
+async function renderSources(ctx, host) {
+  const { h, icon, api, c } = ctx;
+  host.replaceChildren(c.loading({ lines: 3 }));
+  const [port, recent] = await Promise.all([api.kgPortability(), api.kgProvenance(40)]);
+  const bySource = (port.data && port.data.provenance && port.data.provenance.by_source_type) || {};
+  const items = (recent.data && recent.data.items) || [];
+
+  const sourceCards = Object.keys(bySource).length
+    ? h("div.lt3-statrow", Object.entries(bySource).map(([k, v]) =>
+        c.stat({ label: prettySource(k), value: c.fmtNum(v), icon: iconForSource(k) })))
+    : c.emptyState({ icon: "database", title: "No sources yet", body: "Connect a folder, upload a file, or capture a page." });
+
+  const recentList = items.length
+    ? h("div.lt3-stack-2", items.map((it) =>
+        h("div.lt3-entity",
+          h("div.lt3-entity__type", { style: { background: "var(--surface-3)", color: colorFor("Source") } }, icon(iconForSource(it.source_type))),
+          h("div.lt3-entity__body",
+            h("div.lt3-entity__name", it.title || it.source_uri || it.node_id),
+            h("div.lt3-entity__meta", `${prettySource(it.source_type)} · ${fmtWhen(it.created_at)}${it.embedded ? " · embedded" : ""}${it.duplicate ? " · duplicate" : ""}`),
+          ),
+        )))
+    : c.emptyState({ icon: "history", title: "No recent ingestions", body: "Ingested items will appear here with full provenance." });
+
+  host.replaceChildren(
+    h("div.lt3-row-2", c.sourceBadge(port.source), h("span.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } }, "Every node records where it came from (provenance).")),
+    sourceCards,
+    c.card(h("div.lt3-stack-3", h("div.lt3-eyebrow", "Recent ingestions"), recentList)),
+  );
+}
+
+/* ── Capture tab (web/URL into the graph) ───────────────────────────────── */
+function buildCapture(ctx) {
+  const { h, icon, api, c } = ctx;
+  const input = h("input", { type: "url", placeholder: "https://example.com/article", "aria-label": "URL to capture",
+    style: { flex: "1" } });
+  const result = h("div");
+
+  async function run() {
+    const url = (input.value || "").trim();
+    if (!url) { result.replaceChildren(c.banner({ tone: "warn", text: "Enter a URL first." })); return; }
+    result.replaceChildren(c.loading({ lines: 1 }));
+    const res = await api.browserReadUrl(url);
+    const d = res.data || {};
+    if (res.ok && d.status === "ok") {
+      result.replaceChildren(c.banner({ tone: "ok", text: `Added to your Knowledge Graph${d.duplicate ? " (already present — linked)" : ""}. ${d.chunk_count || 0} chunk(s) indexed.` }));
+      ctx.toast && ctx.toast("Page added to Knowledge Graph");
+    } else if (d.status === "empty") {
+      result.replaceChildren(c.banner({ tone: "warn", text: "No readable text was found on that page." }));
+    } else {
+      const detail = d.detail || (res.status === 422 ? "The page is blocked or login-required." : "Could not read that URL.");
+      result.replaceChildren(c.banner({ tone: "err", text: detail }));
+    }
+  }
+
+  return h("div.lt3-stack-4",
+    c.card(h("div.lt3-stack-3",
+      h("div.lt3-eyebrow", "Capture a web page"),
+      h("p.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } }, "The local runtime fetches the page, extracts readable text, and indexes it into your graph as a web source. Nothing is sent to a cloud service."),
+      h("div.lt3-row-2",
+        input,
+        h("button.lt3-btn.lt3-btn--primary", { on: { click: run } }, icon("world-download"), "Read into graph"),
+      ),
+      result,
+    )),
+    c.card(h("div.lt3-stack-2",
+      h("div.lt3-eyebrow", "Browser extension"),
+      h("p.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } }, "Install the local Manifest V3 extension (browser-extension/) to send the current tab to your Knowledge Graph with one click. It posts only to 127.0.0.1 — never to a cloud server."),
+    )),
+  );
+}
+
+/* ── Portability tab (export / import / backup) ─────────────────────────── */
+async function renderPortability(ctx, host) {
+  const { h, icon, api, c } = ctx;
+  host.replaceChildren(c.loading({ lines: 2 }));
+  const port = await api.kgPortability();
+  const status = h("div");
+
+  function note(tone, text) { status.replaceChildren(c.banner({ tone, text })); }
+
+  async function doExport() {
+    note("info", "Exporting…");
+    const res = await api.graphExport();
+    if (!res.ok || !res.data || res.data.raw) { note("err", "Export is unavailable."); return; }
+    try {
+      const blob = new Blob([JSON.stringify(res.data, null, 2)], { type: "application/json" });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url; a.download = "lattice-kg-export.json"; a.click();
+      URL.revokeObjectURL(url);
+      note("ok", `Exported ${(res.data.counts && res.data.counts.nodes) || 0} nodes. Download started.`);
+    } catch (e) { note("err", "Could not build the download."); }
+  }
+
+  async function doBackup() {
+    note("info", "Backing up…");
+    const res = await api.graphBackup();
+    if (res.ok && res.data && res.data.path) {
+      note("ok", `Backup written locally: ${res.data.path}`);
+    } else {
+      note("err", (res.data && (res.data.detail || res.data.error)) || "Backup requires admin and a running runtime.");
+    }
+  }
+
+  const importArea = h("textarea", { rows: 5, placeholder: "Paste a Knowledge Graph export (JSON) to validate, then import…",
+    "aria-label": "Import artifact", style: { width: "100%", "font-family": "var(--lt3-font-mono)", "font-size": "var(--lt3-text-sm)" } });
+
+  async function doImport(dryRun) {
+    let artifact;
+    try { artifact = JSON.parse(importArea.value || ""); }
+    catch { note("err", "That is not valid JSON."); return; }
+    note("info", dryRun ? "Validating…" : "Importing…");
+    const res = await api.graphImport(artifact, "merge", dryRun);
+    if (res.ok && res.data && !res.data.detail) {
+      const d = res.data;
+      note("ok", dryRun
+        ? `Valid — would import ${d.nodes || 0} nodes, ${d.edges || 0} edges.`
+        : `Imported ${d.nodes || 0} nodes, ${d.edges || 0} edges.`);
+    } else {
+      note("err", (res.data && (res.data.detail || res.data.error)) || "Import requires admin.");
+    }
+  }
+
+  const p = port.data || {};
+  host.replaceChildren(
+    h("div.lt3-row-2", c.sourceBadge(port.source), h("span.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } }, "The Knowledge Graph is your durable asset — portable with no cloud.")),
+    c.card(h("div.lt3-stack-3",
+      h("div.lt3-eyebrow", "Export & backup"),
+      h("p.lt3-muted", { style: { "font-size": "var(--lt3-text-sm)" } }, "Export a portable JSON of nodes/edges/provenance, or write a full local binary backup (DB + blobs)."),
+      h("div.lt3-row-2",
+        h("button.lt3-btn.lt3-btn--primary", { on: { click: doExport } }, icon("download"), "Export JSON"),
+        h("button.lt3-btn.lt3-btn--ghost", { on: { click: doBackup } }, icon("archive"), "Backup (admin)"),
+      ),
+    )),
+    c.card(h("div.lt3-stack-3",
+      h("div.lt3-eyebrow", "Import"),
+      importArea,
+      h("div.lt3-row-2",
+        h("button.lt3-btn.lt3-btn--ghost", { on: { click: () => doImport(true) } }, icon("checks"), "Validate (dry-run)"),
+        h("button.lt3-btn.lt3-btn--primary", { on: { click: () => doImport(false) } }, icon("file-import"), "Import (merge, admin)"),
+      ),
+    )),
+    status,
+  );
+}
+
 /* ── helpers ─────────────────────────────────────────────────────────────── */
+function sumCounts(obj) {
+  return Object.values(obj || {}).reduce((a, b) => a + (Number(b) || 0), 0);
+}
+
+function prettySource(k) {
+  return ({ web_url: "Web URL", browser_tab: "Browser tab", file: "Files", local_file: "Local files",
+    note: "Notes", text: "Text", markdown: "Markdown", code: "Code", upload: "Uploads" })[k] || k;
+}
+
+function iconForSource(k) {
+  return ({ web_url: "world", browser_tab: "browser", file: "file", local_file: "folder",
+    note: "note", text: "text-caption", markdown: "markdown", code: "code", upload: "upload" })[k] || "database";
+}
+
+function fmtWhen(iso) {
+  if (!iso) return "—";
+  try {
+    const d = new Date(iso);
+    if (isNaN(d.getTime())) return String(iso);
+    return d.toLocaleString();
+  } catch { return String(iso); }
+}
+
 function normalize(data) {
   const nodes = (data.nodes || []).map((n) => ({
     id: n.id,
@@ -208,7 +484,6 @@ function layout(nodes) {
   if (hasCoords) {
     return nodes.map((n) => ({ ...n, px: Math.round(60 + n.x * (W - 120)), py: Math.round(50 + n.y * (H - 100)) }));
   }
-  // Sunflower (Vogel) spread — even spacing, highest-weight entity centered.
   const order = nodes.map((n, i) => ({ n, i })).sort((a, b) => (b.n.weight || 0) - (a.n.weight || 0));
   const maxR = Math.min(W, H) * 0.42;
   const placed = {};
@@ -226,11 +501,12 @@ function layout(nodes) {
 function truncate(s, n) { s = String(s || ""); return s.length > n ? s.slice(0, n - 1) + "…" : s; }
 
 function iconForType(t) {
-  return ({ Topic: "bulb", Concept: "atom", Method: "function", Model: "cpu", File: "file", Decision: "gavel", Task: "checkbox", Person: "user" })[t] || "point";
+  return ({ Topic: "bulb", Concept: "atom", Method: "function", Model: "cpu", File: "file", Source: "world",
+    Document: "file-text", Decision: "gavel", Task: "checkbox", Person: "user" })[t] || "point";
 }
 
 function buildLegend({ h }) {
-  const types = ["Topic", "Concept", "Method", "Model", "File"];
+  const types = ["Source", "Document", "Concept", "Person", "Decision"];
   return h("div.lt3-graph-legend",
     types.map((t) => h("span", h("i", { style: { background: colorFor(t) } }), t)),
   );

package/static/workspace.css

@@ -873,7 +873,7 @@ main {
   padding: 16px clamp(16px, 2vw, 28px);
   background: color-mix(in srgb, var(--surface-elevated) 94%, transparent);
   border-bottom: 1px solid var(--line);
-  backdrop-filter: blur(18px);
+  backdrop-filter: none; /* glass removed v3.5.0 */
 }
 
 .topbar-subtitle {

package/tools/__init__.py

@@ -0,0 +1,276 @@
+"""Safe local tools for Lattice AI agent mode.
+
+All filesystem operations are confined to LATTICEAI_AGENT_ROOT, defaulting to
+./agent_workspace. Command execution runs without a shell and from inside that
+workspace.
+
+v3.5.0 splits the historical flat ``tools.py`` into focused submodules
+(computer, filesystem, documents, local_files, knowledge, network, commands)
+while keeping the exact import surface: this package re-exports every public name
+and ``execute_tool``/``DEFAULT_TOOL_REGISTRY``, so ``import tools`` and
+``from tools import X`` behave identically to before. ``AGENT_ROOT`` and the path
+helpers live here as the single source of truth (tests monkeypatch
+``tools.AGENT_ROOT``); submodules read it dynamically.
+"""
+
+import base64
+import json
+import os
+import platform
+import re
+import shlex
+import socket
+import subprocess
+import tempfile
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from latticeai.core.tool_registry import ToolRegistry
+from p_reinforce import BRAIN_DIR, STRUCTURE
+
+_PLATFORM = platform.system()  # "Darwin" | "Windows" | "Linux"
+
+
+# ── base: agent-root sandbox, shared constants, path helpers ──────────────────
+AGENT_ROOT = Path(os.getenv("LATTICEAI_AGENT_ROOT") or "agent_workspace").resolve()
+MAX_FILE_BYTES = 512_000
+MAX_COMMAND_SECONDS = 30
+MAX_BUILD_SECONDS = 180
+MAX_DEPLOY_SECONDS = 300
+MAX_COMMAND_OUTPUT = 12_000
+
+BLOCKED_COMMANDS = {
+    "rm",
+    "rmdir",
+    "sudo",
+    "su",
+    "chmod",
+    "chown",
+    "curl",
+    "wget",
+    "ssh",
+    "scp",
+    "rsync",
+    "dd",
+    "mkfs",
+    "diskutil",
+    "launchctl",
+}
+
+ALLOWED_COMMANDS = {
+    "pwd",
+    "ls",
+    "find",
+    "cat",
+    "sed",
+    "head",
+    "tail",
+    "wc",
+    "rg",
+    "python",
+    "python3",
+    "node",
+    "npm",
+    "npx",
+    "git",
+}
+
+BUILD_SCRIPT_NAMES = {"build", "compile", "typecheck", "test"}
+DEPLOY_SCRIPT_NAMES = {
+    "deploy",
+    "preview",
+    "release",
+    "package",
+    "dist",
+    "make",
+    "build:installer",
+    "build:pkg",
+    "build:exe",
+    "package:mac",
+    "package:win",
+}
+
+ALLOWED_GIT_SUBCOMMANDS = {"status", "diff", "log", "show"}
+
+TEXT_EXTENSIONS = {
+    ".css",
+    ".csv",
+    ".html",
+    ".js",
+    ".json",
+    ".jsx",
+    ".md",
+    ".py",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".xml",
+    ".yaml",
+    ".yml",
+}
+
+DOCUMENT_OUTPUT_DIR = "generated_documents"
+PRESENTATION_OUTPUT_DIR = "generated_presentations"
+SPREADSHEET_OUTPUT_DIR = "generated_spreadsheets"
+
+
+class ToolError(ValueError):
+    pass
+
+
+def ensure_agent_root() -> Path:
+    AGENT_ROOT.mkdir(parents=True, exist_ok=True)
+    return AGENT_ROOT
+
+
+def _resolve_path(path: str = "") -> Path:
+    ensure_agent_root()
+    if not path:
+        return AGENT_ROOT
+    candidate = (AGENT_ROOT / path).resolve()
+    if candidate != AGENT_ROOT and AGENT_ROOT not in candidate.parents:
+        raise ToolError("Path escapes the agent workspace.")
+    return candidate
+
+
+def _relative(path: Path) -> str:
+    return str(path.relative_to(AGENT_ROOT))
+
+
+# ── document / local / read constants (shared by submodules) ──────────────────
+PDF_OUTPUT_DIR = "generated_pdfs"
+LOCAL_MAX_FILE_BYTES = 2_000_000  # 2 MB cap for local reads
+
+
+# CJK-capable fonts (Korean + Chinese + Japanese)
+_CJK_FONT_CANDIDATES = [
+    "/System/Library/Fonts/AppleSDGothicNeo.ttc",   # Korean (macOS)
+    "/System/Library/Fonts/STHeiti Light.ttc",       # Chinese (macOS)
+    "/System/Library/Fonts/PingFang.ttc",            # Chinese (macOS)
+    "/Library/Fonts/NanumGothic.ttf",               # Korean
+    "/usr/share/fonts/truetype/nanum/NanumGothic.ttf",
+]
+
+_SUPPORTED_READ_EXTENSIONS = {".pdf", ".docx", ".xlsx", ".pptx", ".txt", ".md", ".csv"}
+DOCUMENT_MAX_READ_BYTES = 10_000_000  # 10 MB
+
+
+# ── focused tool submodules (re-exported flat for import compatibility) ───────
+from tools.computer import *  # noqa: E402,F401,F403
+from tools.filesystem import *  # noqa: E402,F401,F403
+from tools.documents import *  # noqa: E402,F401,F403
+from tools.local_files import *  # noqa: E402,F401,F403
+from tools.knowledge import *  # noqa: E402,F401,F403
+from tools.network import *  # noqa: E402,F401,F403
+from tools.commands import *  # noqa: E402,F401,F403
+
+
+# ── tool registry: the single name → invocation source of truth ───────────────
+def _h_create_xlsx(args: Dict[str, Any]) -> Dict[str, Any]:
+    rows = args.get("rows", [])
+    if isinstance(rows, str):
+        rows = json.loads(rows)
+    return create_xlsx(rows, args.get("filename", "spreadsheet.xlsx"), args.get("sheet_name", "Sheet1"))
+
+
+def _h_create_pptx(args: Dict[str, Any]) -> Dict[str, Any]:
+    slides = args.get("slides", [])
+    if isinstance(slides, str):
+        slides = json.loads(slides)
+    return create_pptx(args.get("title", ""), slides, args.get("filename", "presentation.pptx"))
+
+
+# ── Tool registry: the single source of truth for name → invocation ───────────
+# Each entry binds the args dict to a tool function. ``execute_tool`` is a
+# lookup over this table — adding a tool means adding one entry here, not
+# editing an if/elif chain. server.py's governance map and catalog brief are
+# checked against ``registered_tools()`` so the three never silently drift.
+TOOL_HANDLERS: Dict[str, Callable[[Dict[str, Any]], Dict[str, Any]]] = {
+    # filesystem
+    "list_dir":          lambda a: list_dir(a.get("path", ".")),
+    "workspace_tree":    lambda a: workspace_tree(a.get("path", "."), a.get("max_depth", 3)),
+    "read_file":         lambda a: read_file(a["path"], offset=a.get("offset", 0), limit=a.get("limit", 0), line_numbers=a.get("line_numbers", True)),
+    "write_file":        lambda a: write_file(a["path"], a.get("content", "")),
+    "edit_file":         lambda a: edit_file(a["path"], a["old_string"], a["new_string"], replace_all=bool(a.get("replace_all", False))),
+    "grep":              lambda a: grep(a["pattern"], path=a.get("path", "."), glob=a.get("glob"), max_results=a.get("max_results", 50), case_insensitive=bool(a.get("case_insensitive", False)), context_lines=a.get("context_lines", 0)),
+    "search_files":      lambda a: search_files(a["query"], a.get("path", "."), a.get("max_results", 20)),
+    "inspect_html":      lambda a: inspect_html(a["path"]),
+    "preview_url":       lambda a: preview_url(a.get("path", "index.html")),
+    # planning
+    "todo_read":         lambda a: todo_read(),
+    "todo_write":        lambda a: todo_write(a.get("todos") or []),
+    # documents
+    "create_docx":       lambda a: create_docx(a.get("title", ""), a.get("body", ""), a.get("filename", "document.docx")),
+    "create_xlsx":       _h_create_xlsx,
+    "create_pptx":       _h_create_pptx,
+    "create_pdf":        lambda a: create_pdf(a.get("title", ""), a.get("body", ""), a.get("filename", "document.pdf")),
+    "create_web_project": lambda a: create_web_project(a.get("path", ""), a.get("framework", "react"), a.get("template", "vite")),
+    # local filesystem
+    "local_list":        lambda a: local_list(a["path"]),
+    "local_read":        lambda a: local_read(a["path"]),
+    "local_write":       lambda a: local_write(a["path"], a.get("content", "")),
+    "read_document":     lambda a: read_document(a["path"]),
+    "network_status":    lambda a: network_status(),
+    # computer use
+    "computer_screenshot": lambda a: computer_screenshot(),
+    "computer_open_app": lambda a: computer_open_app(a.get("app", "Google Chrome")),
+    "computer_open_url": lambda a: computer_open_url(a["url"], a.get("app", "Google Chrome")),
+    "computer_click":    lambda a: computer_click(a.get("x", 0), a.get("y", 0), a.get("button", "left"), a.get("double", False)),
+    "computer_type":     lambda a: computer_type(a["text"], a.get("interval", 0.04)),
+    "computer_key":      lambda a: computer_key(a["key"]),
+    "computer_scroll":   lambda a: computer_scroll(a.get("x", 0), a.get("y", 0), a.get("direction", "down"), a.get("clicks", 3)),
+    "computer_move":     lambda a: computer_move(a.get("x", 0), a.get("y", 0)),
+    "computer_drag":     lambda a: computer_drag(a.get("x1", 0), a.get("y1", 0), a.get("x2", 0), a.get("y2", 0)),
+    "computer_status":   lambda a: computer_status(),
+    "chrome_status":     lambda a: desktop_bridge_status(),
+    "computer_use_status": lambda a: desktop_bridge_status(),
+    # knowledge / obsidian
+    "knowledge_save":    lambda a: knowledge_save(a["content"], a.get("folder", "00_Raw"), a.get("title")),
+    "knowledge_search":  lambda a: knowledge_search(a["query"], a.get("max_results", 5)),
+    "knowledge_tree":    lambda a: knowledge_tree(),
+    "obsidian_save":     lambda a: obsidian_save(a["content"], a.get("folder", "00_Raw"), a.get("title")),
+    "obsidian_search":   lambda a: obsidian_search(a["query"], a.get("max_results", 5)),
+    "obsidian_tree":     lambda a: obsidian_tree(),
+    # git (read-only)
+    "git_status":        lambda a: git_status(a.get("cwd")),
+    "git_diff":          lambda a: git_diff(a.get("path"), a.get("cwd")),
+    "git_log":           lambda a: git_log(a.get("max_count", 5), a.get("cwd")),
+    "git_show":          lambda a: git_show(a.get("revision", "HEAD"), a.get("cwd")),
+    # exec
+    "run_command":       lambda a: run_command(a["command"], a.get("cwd")),
+    "build_project":     lambda a: build_project(a.get("cwd"), a.get("script", "build")),
+    "deploy_project":    lambda a: deploy_project(a.get("cwd"), a.get("script", "deploy")),
+}
+
+
+DEFAULT_TOOL_REGISTRY = ToolRegistry(TOOL_HANDLERS)
+
+
+def registered_tools() -> frozenset:
+    """Names dispatchable through ``execute_tool`` — the seam other modules verify against."""
+    return DEFAULT_TOOL_REGISTRY.registered_tools()
+
+
+def execute_tool(action: str, args: Dict[str, Any]) -> Dict[str, Any]:
+    return DEFAULT_TOOL_REGISTRY.execute(action, args, error_cls=ToolError)
+
+
+__all__ = [
+    "AGENT_ROOT", "ToolError", "ensure_agent_root",
+    "list_dir", "workspace_tree", "read_file", "write_file", "edit_file", "grep",
+    "search_files", "inspect_html", "preview_url", "create_web_project",
+    "todo_read", "todo_write",
+    "create_docx", "create_xlsx", "create_pptx", "create_pdf", "read_document",
+    "local_list", "local_read", "local_write", "desktop_bridge_status",
+    "knowledge_save", "knowledge_search", "knowledge_tree",
+    "obsidian_save", "obsidian_search", "obsidian_tree",
+    "network_status",
+    "computer_screenshot", "computer_open_app", "computer_open_url",
+    "computer_click", "computer_type", "computer_key", "computer_scroll",
+    "computer_move", "computer_drag", "computer_status",
+    "run_command", "build_project", "deploy_project",
+    "git_status", "git_diff", "git_log", "git_show",
+    "TOOL_HANDLERS", "DEFAULT_TOOL_REGISTRY", "registered_tools", "execute_tool",
+    "BRAIN_DIR", "STRUCTURE",
+]