ltcai 3.0.1 → 3.2.0

package/latticeai/services/memory_service.py

@@ -0,0 +1,324 @@
+"""Long-Term Memory platform + Memory Manager (v3.2.0).
+
+Parts 7, 8 and 13. Lattice AI already persists memory in several real stores;
+before this service they were unrelated. ``MemoryService`` unifies them behind
+one façade and adds a Memory Manager that reports usage / sources / health /
+size / type and supports recall / inspect / prune / compact / rebuild / clear.
+
+Memory tiers and their real backing store (nothing is fabricated — a tier with
+no backing reports ``unavailable``):
+
+* **workspace**     — personal workspace memories (``WorkspaceOS`` memories)
+* **project**       — memories scoped to a non-personal (organization) workspace
+* **agent**         — agent memory snapshots captured during runs
+* **conversation**  — chat history conversations
+* **graph**         — Knowledge Graph nodes (entities + relations)
+* **vector**        — local embedding vector index
+
+The service never invents counts or health: every number is read from the
+underlying store, and missing stores surface as ``unavailable``.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+# Personal workspace memory kinds (from WorkspaceOS.MEMORY_KINDS).
+WORKSPACE_KINDS = (
+    "short_term",
+    "workspace",
+    "preferences",
+    "decisions",
+    "working_style",
+    "frequently_used_tools",
+    "long_term",
+)
+
+TIERS = ("workspace", "project", "agent", "conversation", "graph", "vector")
+
+
+def _now() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def _file_size(path: Path) -> int:
+    try:
+        return path.stat().st_size if path.exists() else 0
+    except Exception:
+        return 0
+
+
+class MemoryService:
+    def __init__(
+        self,
+        *,
+        store: Any,
+        data_dir: Path,
+        knowledge_graph: Any = None,
+        enable_graph: bool = True,
+        history_file: Optional[Path] = None,
+    ):
+        self._store = store
+        self._kg = knowledge_graph
+        self._enable_graph = bool(enable_graph and knowledge_graph is not None)
+        self._data_dir = Path(data_dir)
+        self._history_file = Path(history_file) if history_file else (self._data_dir / "chat_history.json")
+
+    # ── helpers over the underlying stores ────────────────────────────────
+    def _workspace_memories(self, *, user_email: Optional[str], workspace_id: Optional[str]) -> List[Dict[str, Any]]:
+        try:
+            return list(self._store.list_memories(user_email=user_email, workspace_id=workspace_id).get("memories", []))
+        except Exception:
+            return []
+
+    def _all_memories(self) -> List[Dict[str, Any]]:
+        try:
+            return list(self._store.list_memories().get("memories", []))
+        except Exception:
+            return []
+
+    def _snapshots(self, *, workspace_id: Optional[str]) -> List[Dict[str, Any]]:
+        try:
+            return list(self._store.list_memory_snapshots(workspace_id=workspace_id, limit=200).get("snapshots", []))
+        except Exception:
+            return []
+
+    def _conversations(self) -> List[Dict[str, Any]]:
+        if not self._history_file.exists():
+            return []
+        try:
+            with open(self._history_file, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+        except Exception:
+            return []
+        if isinstance(data, dict):
+            convs = data.get("conversations")
+            if isinstance(convs, list):
+                return convs
+            return [{"id": k, **(v if isinstance(v, dict) else {"messages": v})} for k, v in data.items()]
+        if isinstance(data, list):
+            return data
+        return []
+
+    def _kg_stats(self) -> Optional[Dict[str, Any]]:
+        if not self._enable_graph:
+            return None
+        try:
+            return self._kg.stats()
+        except Exception:
+            return None
+
+    def _kg_index(self) -> Optional[Dict[str, Any]]:
+        if not self._enable_graph:
+            return None
+        try:
+            return self._kg.index_status()
+        except Exception:
+            return None
+
+    # ── Memory Manager: sources / usage / health ──────────────────────────
+    def manager(self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None) -> Dict[str, Any]:
+        ws_mem = self._workspace_memories(user_email=user_email, workspace_id="personal")
+        project_mem = [m for m in self._all_memories() if (m.get("workspace_id") or "personal") != "personal"]
+        snaps = self._snapshots(workspace_id=workspace_id)
+        convs = self._conversations()
+        kg_stats = self._kg_stats()
+        kg_index = self._kg_index()
+
+        ws_bytes = _file_size(self._data_dir / "workspace_os.json")
+        kg_bytes = _file_size(self._data_dir / "knowledge_graph.sqlite")
+        conv_bytes = _file_size(self._history_file)
+
+        node_total = sum((kg_stats or {}).get("nodes", {}).values()) if kg_stats else None
+        edge_total = sum((kg_stats or {}).get("edges", {}).values()) if kg_stats else None
+        vector_total = None
+        if kg_index and isinstance(kg_index.get("vector_counts"), dict):
+            vector_total = sum(kg_index["vector_counts"].values())
+        elif kg_index:
+            vector_total = kg_index.get("indexed") or kg_index.get("ready")
+
+        sources = [
+            {
+                "id": "workspace", "type": "workspace", "label": "Workspace Memory",
+                "count": len(ws_mem), "size_bytes": ws_bytes if ws_mem else 0,
+                "health": "ok", "detail": "Personal workspace knowledge, by kind.",
+            },
+            {
+                "id": "project", "type": "project", "label": "Project Memory",
+                "count": len(project_mem), "size_bytes": 0,
+                "health": "ok", "detail": "Memory scoped to organization workspaces.",
+            },
+            {
+                "id": "agent", "type": "agent", "label": "Agent Memory",
+                "count": len(snaps), "size_bytes": 0,
+                "health": "ok", "detail": "Per-run agent memory snapshots.",
+            },
+            {
+                "id": "conversation", "type": "conversation", "label": "Conversation Memory",
+                "count": len(convs), "size_bytes": conv_bytes,
+                "health": "ok" if self._history_file.exists() else "empty",
+                "detail": "Historical interaction memory from chat.",
+            },
+            {
+                "id": "graph", "type": "graph", "label": "Graph Memory",
+                "count": node_total, "size_bytes": kg_bytes,
+                "health": "ok" if kg_stats else "unavailable",
+                "detail": "Knowledge Graph entities and relations." if kg_stats else "Knowledge graph disabled or unavailable.",
+                "edges": edge_total,
+            },
+            {
+                "id": "vector", "type": "vector", "label": "Vector Memory",
+                "count": vector_total, "size_bytes": 0,
+                "health": "ok" if kg_index else "unavailable",
+                "detail": "Local embedding vector index." if kg_index else "Vector index unavailable.",
+            },
+        ]
+        total_items = sum((s["count"] or 0) for s in sources)
+        total_bytes = ws_bytes + kg_bytes + conv_bytes
+        healthy = sum(1 for s in sources if s["health"] == "ok")
+        overall = "ok" if healthy >= 4 else "degraded" if healthy >= 1 else "unavailable"
+        return {
+            "sources": sources,
+            "tiers": list(TIERS),
+            "usage": {"total_items": total_items, "total_bytes": total_bytes, "sources": len(sources)},
+            "health": overall,
+            "graph_enabled": self._enable_graph,
+            "generated_at": _now(),
+        }
+
+    def tiers(self) -> Dict[str, Any]:
+        return {"tiers": list(TIERS), "workspace_kinds": list(WORKSPACE_KINDS)}
+
+    # ── recall (unified retrieval over the memory tiers) ───────────────────
+    def recall(
+        self,
+        query: str,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        limit: int = 20,
+    ) -> Dict[str, Any]:
+        q = str(query or "").strip()
+        results: List[Dict[str, Any]] = []
+
+        try:
+            mem = self._store.search_memories(q, user_email=user_email, limit=limit, workspace_id=workspace_id).get("memories", [])
+        except Exception:
+            mem = []
+        for m in mem:
+            results.append({
+                "source": "workspace",
+                "id": m.get("id"),
+                "title": (m.get("kind") or "memory"),
+                "snippet": str(m.get("content") or "")[:240],
+                "kind": m.get("kind"),
+                "score": 0.6,
+                "tags": m.get("tags") or [],
+            })
+
+        if self._enable_graph and q:
+            try:
+                hits = self._kg.search(q, limit).get("results", [])
+            except Exception:
+                hits = []
+            for hsit in hits[:limit]:
+                results.append({
+                    "source": "graph",
+                    "id": hsit.get("id") or hsit.get("node_id"),
+                    "title": hsit.get("title") or hsit.get("name") or "node",
+                    "snippet": str(hsit.get("summary") or hsit.get("content") or "")[:240],
+                    "kind": hsit.get("type") or "node",
+                    "score": float(hsit.get("score") or 0.5),
+                })
+
+        results.sort(key=lambda r: r.get("score", 0), reverse=True)
+        return {"query": q, "results": results[: max(1, min(limit, 100))], "count": len(results), "source": "live"}
+
+    # ── inspect a single tier ─────────────────────────────────────────────
+    def inspect(self, source: str, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
+        if source == "workspace":
+            items = self._workspace_memories(user_email=user_email, workspace_id="personal")[:limit]
+            return {"source": source, "items": items, "count": len(items)}
+        if source == "project":
+            items = [m for m in self._all_memories() if (m.get("workspace_id") or "personal") != "personal"][:limit]
+            return {"source": source, "items": items, "count": len(items)}
+        if source == "agent":
+            items = self._snapshots(workspace_id=workspace_id)[:limit]
+            return {"source": source, "items": items, "count": len(items)}
+        if source == "conversation":
+            convs = self._conversations()
+            items = [{"id": c.get("id"), "title": c.get("title") or c.get("id"), "messages": len(c.get("messages") or [])} for c in convs[:limit]]
+            return {"source": source, "items": items, "count": len(convs)}
+        if source == "graph":
+            return {"source": source, "stats": self._kg_stats() or {}, "available": bool(self._kg_stats())}
+        if source == "vector":
+            return {"source": source, "index": self._kg_index() or {}, "available": bool(self._kg_index())}
+        raise KeyError(source)
+
+    # ── mutating operations ───────────────────────────────────────────────
+    def prune(self, *, ids: Optional[List[str]] = None, kind: Optional[str] = None, user_email: Optional[str] = None) -> Dict[str, Any]:
+        removed: List[str] = []
+        target_ids = list(ids or [])
+        if kind:
+            for m in self._workspace_memories(user_email=user_email, workspace_id=None):
+                if m.get("kind") == kind and m.get("id"):
+                    target_ids.append(m["id"])
+        for mid in target_ids:
+            try:
+                self._store.delete_memory(mid)
+                removed.append(mid)
+            except Exception:
+                continue
+        return {"removed": removed, "count": len(removed)}
+
+    def compact(self, *, user_email: Optional[str] = None) -> Dict[str, Any]:
+        """Dedupe workspace memories with identical (kind, content)."""
+        seen: set = set()
+        removed: List[str] = []
+        # Oldest first so the first occurrence (oldest) is kept.
+        memories = list(reversed(self._workspace_memories(user_email=user_email, workspace_id=None)))
+        for m in memories:
+            key = (m.get("kind"), str(m.get("content") or "").strip())
+            if key in seen:
+                if m.get("id"):
+                    try:
+                        self._store.delete_memory(m["id"])
+                        removed.append(m["id"])
+                    except Exception:
+                        continue
+            else:
+                seen.add(key)
+        return {"compacted": len(removed), "removed": removed, "remaining": len(seen)}
+
+    def rebuild(self, target: str = "vector") -> Dict[str, Any]:
+        if target in {"vector", "index", "vector_index"}:
+            if not self._enable_graph:
+                return {"status": "unavailable", "detail": "Knowledge graph / vector index disabled."}
+            try:
+                result = self._kg.rebuild_vector_index()
+                return {"status": "ok", "target": "vector_index", "result": result}
+            except Exception as exc:
+                return {"status": "error", "detail": str(exc)}
+        return {"status": "error", "detail": f"Unknown rebuild target: {target}"}
+
+    def clear(self, *, scope: str, confirm: bool = False, user_email: Optional[str] = None) -> Dict[str, Any]:
+        if not confirm:
+            raise ValueError("clear requires confirm=true")
+        if scope in WORKSPACE_KINDS:
+            result = self.prune(kind=scope, user_email=user_email)
+            return {"cleared": scope, **result}
+        if scope == "workspace":
+            ids = [m["id"] for m in self._workspace_memories(user_email=user_email, workspace_id=None) if m.get("id")]
+            result = self.prune(ids=ids, user_email=user_email)
+            return {"cleared": "workspace", **result}
+        if scope == "graph":
+            if not self._enable_graph:
+                return {"status": "unavailable", "detail": "Knowledge graph disabled."}
+            try:
+                return {"cleared": "graph", "result": self._kg.clear_all()}
+            except Exception as exc:
+                return {"status": "error", "detail": str(exc)}
+        raise ValueError(f"unsupported clear scope: {scope}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Lattice AI v3 local-first AI workspace platform with knowledge graph, vector index, hybrid search, agents, and workspace modes.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -17,9 +17,10 @@
   "scripts": {
     "start": "LTCAI",
     "dev": "python3 ltcai_cli.py --reload",
-    "build": "npm run build:python",
+    "build": "npm run build:assets && npm run build:python",
+    "build:assets": "node scripts/build_v3_assets.mjs",
     "build:python": "python3 -m build",
-    "check:python": "python3 -m py_compile ltcai_cli.py server.py latticeai/server_app.py latticeai/api/chat.py latticeai/api/computer_use.py latticeai/api/deps.py latticeai/api/garden.py latticeai/api/local_files.py latticeai/api/permissions.py latticeai/api/setup.py latticeai/api/static_routes.py latticeai/api/tools.py latticeai/api/plugins.py latticeai/api/workflow_designer.py latticeai/api/agents.py latticeai/api/realtime.py latticeai/api/marketplace.py latticeai/api/search.py latticeai/services/search_service.py latticeai/core/local_embeddings.py latticeai/core/embedding_providers.py latticeai/services/agent_runtime.py latticeai/core/config.py latticeai/api/admin.py latticeai/services/app_context.py latticeai/services/model_runtime.py latticeai/services/model_catalog.py latticeai/services/model_recommendation.py latticeai/services/tool_dispatch.py latticeai/services/upload_service.py latticeai/core/tool_registry.py latticeai/core/enterprise.py latticeai/core/enterprise_admin.py latticeai/core/agent_prompts.py latticeai/core/workspace_os.py latticeai/core/plugins.py latticeai/core/marketplace.py latticeai/core/workflow_engine.py latticeai/core/multi_agent.py latticeai/core/realtime.py knowledge_graph.py knowledge_graph_api.py local_knowledge_api.py llm_router.py p_reinforce.py telegram_bot.py tools.py codex_telegram_bot.py",
+    "check:python": "python3 -m py_compile ltcai_cli.py server.py latticeai/server_app.py latticeai/api/auth.py latticeai/api/chat.py latticeai/api/computer_use.py latticeai/api/deps.py latticeai/api/garden.py latticeai/api/local_files.py latticeai/api/permissions.py latticeai/api/setup.py latticeai/api/static_routes.py latticeai/api/tools.py latticeai/api/plugins.py latticeai/api/workflow_designer.py latticeai/api/agents.py latticeai/api/realtime.py latticeai/api/marketplace.py latticeai/api/search.py latticeai/services/search_service.py latticeai/core/local_embeddings.py latticeai/core/embedding_providers.py latticeai/services/agent_runtime.py latticeai/core/config.py latticeai/api/admin.py latticeai/services/app_context.py latticeai/services/model_runtime.py latticeai/services/model_catalog.py latticeai/services/model_recommendation.py latticeai/services/tool_dispatch.py latticeai/services/upload_service.py latticeai/core/tool_registry.py latticeai/core/enterprise.py latticeai/core/enterprise_admin.py latticeai/core/agent_prompts.py latticeai/core/workspace_os.py latticeai/core/plugins.py latticeai/core/marketplace.py latticeai/core/workflow_engine.py latticeai/core/multi_agent.py latticeai/core/realtime.py latticeai/api/mcp.py latticeai/core/hooks.py latticeai/api/hooks.py latticeai/core/agent_registry.py latticeai/api/agent_registry.py latticeai/services/memory_service.py latticeai/api/memory.py knowledge_graph.py knowledge_graph_api.py local_knowledge_api.py llm_router.py p_reinforce.py telegram_bot.py tools.py codex_telegram_bot.py",
     "lint": "node --check static/scripts/account.js && node --check static/scripts/admin.js && node --check static/scripts/chat.js && node --check static/scripts/graph.js && node --check static/scripts/platform.js && node --check static/scripts/ux.js && node --check static/scripts/workspace.js && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:v3",
     "lint:v3": "node scripts/lint_v3.mjs",
     "typecheck": "cd vscode-extension && npm run build",
@@ -32,7 +33,7 @@
     "capture:skills": "node scripts/capture/capture_skills.js",
     "capture:enterprise": "node scripts/capture/capture_enterprise.js",
     "capture:onboarding": "node scripts/capture/capture_onboarding.js",
-    "release:artifacts": "npm run build:python && npm pack && cd vscode-extension && npm run package:vsix",
+    "release:artifacts": "npm run build:assets && npm run build:python && npm pack && cd vscode-extension && npm run package:vsix",
     "release:validate": "python3 scripts/validate_release_artifacts.py $npm_package_version --require-vsix --require-tgz",
     "publish:npm": "npm pack && npm publish ltcai-$npm_package_version.tgz --access public",
     "publish:pypi": "npm run build:python && python3 -m twine upload --skip-existing dist/ltcai-$npm_package_version.tar.gz dist/ltcai-$npm_package_version-py3-none-any.whl",
@@ -93,7 +94,11 @@
     "static/v3/",
     "static/icons/",
     "plugins/",
+    "scripts/",
     "docs/",
+    "!docs/images/tmp_frames/",
+    "!**/__pycache__/",
+    "!**/*.pyc",
     "requirements.txt",
     "README.md"
   ],

package/scripts/build_v3_assets.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/*
+ * Build the v3 browser asset manifest.
+ *
+ * The source files stay importable in development. This script writes hashed
+ * siblings next to each runtime asset, rewrites ES-module imports to those
+ * hashed siblings, and emits static/v3/asset-manifest.json for /app.
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, extname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const staticRoot = join(repoRoot, "static");
+const manifestPath = join(staticRoot, "v3", "asset-manifest.json");
+
+const cssSources = [
+  "static/css/tokens.css",
+  "static/v3/css/lattice.tokens.css",
+  "static/v3/css/lattice.base.css",
+  "static/v3/css/lattice.components.css",
+  "static/v3/css/lattice.shell.css",
+  "static/v3/css/lattice.views.css",
+];
+
+const moduleRoot = join(staticRoot, "v3", "js");
+const entry = "static/v3/js/app.js";
+
+function posix(p) {
+  return p.replaceAll("\\", "/");
+}
+
+function sha(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 8);
+}
+
+function repoPath(abs) {
+  return posix(relative(repoRoot, abs));
+}
+
+function publicUrl(repoRel) {
+  return "/" + posix(repoRel);
+}
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walk(p));
+    else if (name.endsWith(".js")) out.push(p);
+  }
+  return out;
+}
+
+function removeGenerated(dir, ext) {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) removeGenerated(p, ext);
+    else if (new RegExp(`\\.[0-9a-f]{8}\\${ext}$`).test(name)) rmSync(p);
+  }
+}
+
+removeGenerated(join(staticRoot, "css"), ".css");
+removeGenerated(join(staticRoot, "v3", "css"), ".css");
+removeGenerated(moduleRoot, ".js");
+
+const modules = new Map();
+for (const abs of walk(moduleRoot)) {
+  modules.set(repoPath(abs), {
+    abs,
+    rel: repoPath(abs),
+    source: readFileSync(abs, "utf8"),
+    deps: [],
+  });
+}
+
+const importFromRe = /\b(?:import|export)\s+(?:[^"'()]*?\s+from\s*)?["']([^"']+\.js)["']/g;
+for (const mod of modules.values()) {
+  const deps = [];
+  let match;
+  while ((match = importFromRe.exec(mod.source))) {
+    const spec = match[1];
+    if (!spec.startsWith(".")) continue;
+    const depRel = repoPath(join(dirname(mod.abs), spec));
+    if (modules.has(depRel)) deps.push(depRel);
+  }
+  mod.deps = deps;
+}
+
+const hashMemo = new Map();
+function moduleHash(rel, stack = []) {
+  if (hashMemo.has(rel)) return hashMemo.get(rel);
+  if (stack.includes(rel)) return sha(modules.get(rel).source);
+  const mod = modules.get(rel);
+  const depHashes = mod.deps
+    .sort()
+    .map((dep) => `${dep}:${moduleHash(dep, [...stack, rel])}`)
+    .join("\n");
+  const h = sha(`${mod.source}\n/* dependency-hashes */\n${depHashes}`);
+  hashMemo.set(rel, h);
+  return h;
+}
+
+for (const rel of modules.keys()) moduleHash(rel);
+
+function hashedRel(rel, hash) {
+  const ext = extname(rel);
+  return posix(join(dirname(rel), `${basename(rel, ext)}.${hash}${ext}`));
+}
+
+const assets = {};
+
+for (const sourceRel of cssSources) {
+  const abs = join(repoRoot, sourceRel);
+  const source = readFileSync(abs, "utf8");
+  const outRel = hashedRel(sourceRel, sha(source));
+  writeFileSync(join(repoRoot, outRel), source, "utf8");
+  assets[sourceRel] = publicUrl(outRel);
+}
+
+function rewriteModule(mod) {
+  return mod.source.replace(importFromRe, (full, spec) => {
+    if (!spec.startsWith(".")) return full;
+    const depRel = repoPath(join(dirname(mod.abs), spec));
+    const depHash = hashMemo.get(depRel);
+    if (!depHash) return full;
+    const depOutAbs = join(repoRoot, hashedRel(depRel, depHash));
+    const nextSpec = posix(relative(dirname(join(repoRoot, hashedRel(mod.rel, hashMemo.get(mod.rel)))), depOutAbs));
+    const normalized = nextSpec.startsWith(".") ? nextSpec : `./${nextSpec}`;
+    return full.replace(spec, normalized);
+  });
+}
+
+for (const mod of modules.values()) {
+  const outRel = hashedRel(mod.rel, hashMemo.get(mod.rel));
+  mkdirSync(dirname(join(repoRoot, outRel)), { recursive: true });
+  writeFileSync(join(repoRoot, outRel), rewriteModule(mod), "utf8");
+  assets[mod.rel] = publicUrl(outRel);
+}
+
+const manifest = {
+  version: "3.2.0",
+  generated_at: "deterministic",
+  entrypoints: {
+    app: assets[entry],
+    styles: cssSources.map((rel) => assets[rel]),
+  },
+  assets,
+};
+
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+console.log(`wrote ${repoPath(manifestPath)} with ${Object.keys(assets).length} assets`);

package/scripts/capture/README.md

@@ -0,0 +1,28 @@
+# Screenshot Capture
+
+Reproducible Playwright capture scripts for release screenshots.
+
+Prerequisites:
+
+```bash
+npm ci
+npx playwright install chromium
+LTCAI
+```
+
+Optional environment:
+
+- `LTCAI_CAPTURE_BASE_URL` defaults to `http://localhost:4825`
+- `SESSION_TOKEN` or `LTCAI_SESSION_TOKEN` injects an authenticated session cookie
+- `LTCAI_CAPTURE_OUT` defaults to `docs/images`
+- `LTCAI_CAPTURE_HEADED=1` runs with a visible browser
+
+Commands:
+
+```bash
+npm run capture:workspace
+npm run capture:graph
+npm run capture:skills
+npm run capture:enterprise
+npm run capture:onboarding
+```

package/scripts/capture/capture_enterprise.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { capturePage } = require("./capture_page");
+
+capturePage({ path: "/admin#enterprise", waitFor: "#enterprise-capability-status", filename: "enterprise.png" })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/scripts/capture/capture_graph.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { capturePage } = require("./capture_page");
+
+capturePage({ path: "/graph", waitFor: "#graph", filename: "graph.png", settleMs: 1400 })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/scripts/capture/capture_onboarding.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { capturePage } = require("./capture_page");
+
+capturePage({ path: "/onboarding", waitFor: "#onboarding-steps", filename: "onboarding.png" })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/scripts/capture/capture_page.js

@@ -0,0 +1,43 @@
+const fs = require("fs");
+const path = require("path");
+
+async function loadPlaywright() {
+  try {
+    return require("@playwright/test");
+  } catch (_) {
+    return require("playwright");
+  }
+}
+
+async function capturePage(options) {
+  const { chromium } = await loadPlaywright();
+  const baseURL = process.env.LTCAI_CAPTURE_BASE_URL || "http://localhost:4825";
+  const outDir = path.resolve(process.env.LTCAI_CAPTURE_OUT || path.join(__dirname, "..", "..", "docs", "images"));
+  const sessionToken = process.env.SESSION_TOKEN || process.env.LTCAI_SESSION_TOKEN || "";
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const browser = await chromium.launch({ headless: process.env.LTCAI_CAPTURE_HEADED !== "1" });
+  const context = await browser.newContext({
+    viewport: { width: Number(process.env.LTCAI_CAPTURE_WIDTH || 1440), height: Number(process.env.LTCAI_CAPTURE_HEIGHT || 920) },
+    deviceScaleFactor: Number(process.env.LTCAI_CAPTURE_SCALE || 2),
+  });
+  if (sessionToken) {
+    const host = new URL(baseURL).hostname;
+    await context.addCookies([{ name: "session_token", value: sessionToken, domain: host, path: "/", httpOnly: true, secure: false }]);
+  }
+
+  const page = await context.newPage();
+  const target = new URL(options.path, baseURL).toString();
+  await page.goto(target, { waitUntil: "networkidle", timeout: Number(process.env.LTCAI_CAPTURE_TIMEOUT || 30_000) });
+  if (options.hash) await page.evaluate((hash) => { location.hash = hash; }, options.hash);
+  if (options.waitFor) await page.waitForSelector(options.waitFor, { timeout: 15_000 });
+  await page.waitForTimeout(Number(process.env.LTCAI_CAPTURE_SETTLE_MS || options.settleMs || 900));
+
+  const outPath = path.join(outDir, options.filename);
+  await page.screenshot({ path: outPath, fullPage: Boolean(options.fullPage) });
+  await browser.close();
+  console.log(outPath);
+  return outPath;
+}
+
+module.exports = { capturePage };