@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/protocol/ui/icon-registry.mjs

@@ -0,0 +1,226 @@
+/**
+ * agentsam.icon.v1 — semantic vocabulary registry (additive-only).
+ * Persist keys only. Renderer packages map keys → Lucide / CLI glyphs / native.
+ */
+
+/** @type {readonly string[]} */
+export const AGENTSAM_ICON_KEYS = Object.freeze([
+  'generic',
+  'agent',
+  'app',
+  'project',
+  'package',
+  'plugin',
+  'inspect',
+  'search',
+  'code',
+  'terminal',
+  'browser',
+  'workflow',
+  'database',
+  'storage',
+  'vector',
+  'data',
+  'repository',
+  'file',
+  'folder',
+  'document',
+  'artifact',
+  'image',
+  'memory',
+  'model',
+  'provider',
+  'tool',
+  'skill',
+  'integration',
+  'connection',
+  'api',
+  'identity',
+  'key',
+  'security',
+  'network',
+  'cloud',
+  'deploy',
+  'brand',
+  'theme',
+  'settings',
+  'metrics',
+  'logs',
+]);
+
+/** @type {Readonly<Record<string, string>>} */
+export const ICON_ALIASES = Object.freeze({
+  db: 'database',
+  repo: 'repository',
+  repos: 'repository',
+  files: 'file',
+  dirs: 'folder',
+  directories: 'folder',
+  docs: 'document',
+  doc: 'document',
+  img: 'image',
+  media: 'image',
+  auth: 'identity',
+  secret: 'key',
+  secrets: 'key',
+  vault: 'key',
+  embeddings: 'vector',
+  vectors: 'vector',
+  sql: 'database',
+  d1: 'database',
+  config: 'settings',
+});
+
+/** @type {Readonly<Record<string, { category: string, label: string }>>} */
+export const ICON_CATALOG = Object.freeze({
+  generic: { category: 'system', label: 'Generic' },
+  agent: { category: 'runtime', label: 'Agent' },
+  app: { category: 'product', label: 'App' },
+  project: { category: 'product', label: 'Project' },
+  package: { category: 'product', label: 'Package' },
+  plugin: { category: 'product', label: 'Plugin' },
+  inspect: { category: 'runtime', label: 'Inspect' },
+  search: { category: 'runtime', label: 'Search' },
+  code: { category: 'runtime', label: 'Code' },
+  terminal: { category: 'runtime', label: 'Terminal' },
+  browser: { category: 'runtime', label: 'Browser' },
+  workflow: { category: 'runtime', label: 'Workflow' },
+  database: { category: 'data', label: 'Database' },
+  storage: { category: 'data', label: 'Storage' },
+  vector: { category: 'data', label: 'Vector' },
+  data: { category: 'data', label: 'Data' },
+  repository: { category: 'product', label: 'Repository' },
+  file: { category: 'product', label: 'File' },
+  folder: { category: 'product', label: 'Folder' },
+  document: { category: 'product', label: 'Document' },
+  artifact: { category: 'product', label: 'Artifact' },
+  image: { category: 'product', label: 'Image' },
+  memory: { category: 'ai', label: 'Memory' },
+  model: { category: 'ai', label: 'Model' },
+  provider: { category: 'ai', label: 'Provider' },
+  tool: { category: 'runtime', label: 'Tool' },
+  skill: { category: 'runtime', label: 'Skill' },
+  integration: { category: 'connectivity', label: 'Integration' },
+  connection: { category: 'connectivity', label: 'Connection' },
+  api: { category: 'connectivity', label: 'API' },
+  identity: { category: 'security', label: 'Identity' },
+  key: { category: 'security', label: 'Key' },
+  security: { category: 'security', label: 'Security' },
+  network: { category: 'connectivity', label: 'Network' },
+  cloud: { category: 'connectivity', label: 'Cloud' },
+  deploy: { category: 'runtime', label: 'Deploy' },
+  brand: { category: 'design', label: 'Brand' },
+  theme: { category: 'design', label: 'Theme' },
+  settings: { category: 'system', label: 'Settings' },
+  metrics: { category: 'observability', label: 'Metrics' },
+  logs: { category: 'observability', label: 'Logs' },
+});
+
+export const CLI_ICON_GLYPHS = Object.freeze({
+  generic: '●',
+  inspect: '◇',
+  search: '⌕',
+  code: '›_',
+  terminal: '›',
+  database: '▦',
+  storage: '▦',
+  vector: '◎',
+  data: '▦',
+  package: '□',
+  deploy: '↑',
+  security: '◆',
+  identity: '◆',
+  key: '◆',
+  workflow: '↳',
+  skill: '●',
+  agent: '●',
+  app: '□',
+  project: '□',
+  repository: '□',
+  file: '□',
+  folder: '□',
+  document: '□',
+  artifact: '□',
+  image: '□',
+  settings: '◇',
+  brand: '◇',
+  theme: '◇',
+  metrics: '⌕',
+  logs: '⌕',
+  connection: '⌕',
+  integration: '⌕',
+  api: '⌕',
+  network: '⌕',
+  cloud: '⌕',
+  browser: '⌕',
+  tool: '›',
+  plugin: '□',
+  memory: '◇',
+  model: '◎',
+  provider: '◎',
+});
+
+/**
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function normalizeIconKey(raw) {
+  const input = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^lucide[-_]/, '')
+    .replace(/^heroicons?[-_]/, '');
+  if (!input) return 'generic';
+  const aliased = ICON_ALIASES[input] || input;
+  if (AGENTSAM_ICON_KEYS.includes(aliased)) return aliased;
+  return 'generic';
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {boolean}
+ */
+export function isAgentsamIconKey(raw) {
+  const k = String(raw ?? '')
+    .trim()
+    .toLowerCase();
+  return AGENTSAM_ICON_KEYS.includes(k);
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function resolveCliIconGlyph(raw) {
+  const key = normalizeIconKey(raw);
+  return CLI_ICON_GLYPHS[key] || CLI_ICON_GLYPHS.generic;
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ key: string, category: string, label: string }}
+ */
+export function resolveIconMeta(raw) {
+  const key = normalizeIconKey(raw);
+  const meta = ICON_CATALOG[key] || ICON_CATALOG.generic;
+  return { key, category: meta.category, label: meta.label };
+}
+
+/**
+ * @template T
+ * @param {Partial<Record<string, T>>} mapping
+ * @param {T} genericFallback
+ * @returns {(raw: unknown) => T}
+ */
+export function createIconRenderer(mapping, genericFallback) {
+  return (raw) => {
+    const key = normalizeIconKey(raw);
+    if (Object.prototype.hasOwnProperty.call(mapping, key) && mapping[key] != null) {
+      return /** @type {T} */ (mapping[key]);
+    }
+    if (Object.prototype.hasOwnProperty.call(mapping, 'generic') && mapping.generic != null) {
+      return /** @type {T} */ (mapping.generic);
+    }
+    return genericFallback;
+  };
+}

package/protocol/ui/icon.v1.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentsam.icon.v1",
+  "title": "AgentSamSemanticIconKey",
+  "description": "Stable semantic icon key used by AgentSam registries and manifests. Persist semantic meaning only; renderer-specific icon library identifiers, emoji, SVG paths, and asset URLs are not valid values. Vocabulary is additive-only: never rename a shipped key; alias on ingest if needed.",
+  "type": "string",
+  "enum": [
+    "generic",
+    "agent",
+    "app",
+    "project",
+    "package",
+    "plugin",
+    "inspect",
+    "search",
+    "code",
+    "terminal",
+    "browser",
+    "workflow",
+    "database",
+    "storage",
+    "vector",
+    "data",
+    "repository",
+    "file",
+    "folder",
+    "document",
+    "artifact",
+    "image",
+    "memory",
+    "model",
+    "provider",
+    "tool",
+    "skill",
+    "integration",
+    "connection",
+    "api",
+    "identity",
+    "key",
+    "security",
+    "network",
+    "cloud",
+    "deploy",
+    "brand",
+    "theme",
+    "settings",
+    "metrics",
+    "logs"
+  ],
+  "examples": ["database", "skill", "identity", "theme", "vector"]
+}

package/services/cad/server.py

@@ -37,6 +37,8 @@ TOOL_COMMANDS = {
 }
 
 OPENSCAD_FORMATS = {"stl", "3mf", "dxf", "svg", "csg", "off", "amf"}
+FREECAD_FORMATS = {"step", "stp", "iges", "brep", "stl"}
+BLENDER_FORMATS = {"glb", "stl", "obj", "png"}
 FORBIDDEN_OPENSCAD = [
     (re.compile(r"\binclude\s*<", re.I), "include directives are disabled"),
     (re.compile(r"\buse\s*<", re.I), "use directives are disabled"),
@@ -83,8 +85,8 @@ def _capabilities() -> dict[str, Any]:
         "tools": tools,
         "endpoints": {
             "openscad_compile": tools["openscad"]["installed"],
-            "freecad_execute": False,
-            "blender_execute": False,
+            "freecad_execute": tools["freecad"]["installed"],
+            "blender_execute": tools["blender"]["installed"],
         },
         "limits": {
             "max_source_chars": MAX_SOURCE_CHARS,
@@ -202,6 +204,245 @@ def _compile_openscad(payload: dict[str, Any]) -> dict[str, Any]:
         }
 
 
+def _find_freecad_adapter() -> Path:
+    candidates = [
+        Path("/srv/freecad/adapter.py"),
+        Path("/srv/services/cad/freecad/adapter.py"),
+        Path(__file__).parent / "freecad" / "adapter.py",
+        Path(__file__).parent / "freecad_adapter.py",
+    ]
+    for c in candidates:
+        if c.exists():
+            return c
+    raise RuntimeError("FreeCAD adapter script not found in CAD service container")
+
+
+def _find_blender_adapter() -> Path:
+    candidates = [
+        Path("/srv/blender/adapter.py"),
+        Path("/srv/services/cad/blender/adapter.py"),
+        Path(__file__).parent / "blender" / "adapter.py",
+        Path(__file__).parent / "blender_adapter.py",
+    ]
+    for c in candidates:
+        if c.exists():
+            return c
+    raise RuntimeError("Blender adapter script not found in CAD service container")
+
+
+def _freecad_command(adapter_path: Path, request_path: Path, operation: str = "build") -> list[str]:
+    for cmd in ["FreeCADCmd", "freecadcmd", "/usr/lib/freecad/bin/FreeCADCmd"]:
+        binary = shutil.which(cmd)
+        if binary or Path(cmd).exists():
+            return [binary or cmd, str(adapter_path), "--operation", operation, "--request", str(request_path)]
+    for py in ["/usr/lib/freecad/bin/python", "python3"]:
+        binary = shutil.which(py)
+        if binary or Path(py).exists():
+            return [binary or py, str(adapter_path), "--operation", operation, "--request", str(request_path)]
+    raise RuntimeError("FreeCAD runtime binary not found in container")
+
+
+def _blender_command(adapter_path: Path, request_path: Path, operation: str = "build") -> list[str]:
+    for cmd in ["blender", "/usr/bin/blender", "/usr/local/bin/blender"]:
+        binary = shutil.which(cmd)
+        if binary or Path(cmd).exists():
+            return [binary or cmd, "-b", "--python", str(adapter_path), "--", "--operation", operation, "--request", str(request_path)]
+    raise RuntimeError("Blender runtime binary not found in container")
+
+
+def _execute_freecad(payload: dict[str, Any]) -> dict[str, Any]:
+    adapter_path = _find_freecad_adapter()
+    operations = payload.get("operations") or (payload.get("recipe", {}).get("operations") if isinstance(payload.get("recipe"), dict) else None)
+    if not isinstance(operations, list) or len(operations) == 0:
+        raise ValueError("operations must be a non-empty list of modeling operations")
+    if len(operations) > 256:
+        raise ValueError("operations list exceeds maximum limit of 256")
+
+    output_format = str(payload.get("format", "step")).lower().lstrip(".")
+    if output_format not in FREECAD_FORMATS:
+        raise ValueError(f"unsupported FreeCAD format: {output_format}")
+
+    timeout = payload.get("timeout_seconds", 30)
+    try:
+        timeout = int(timeout)
+    except (TypeError, ValueError):
+        timeout = 30
+    timeout = max(1, min(timeout, MAX_TIMEOUT_SECONDS))
+
+    filename = str(payload.get("filename") or f"model.{output_format}")
+    filename = re.sub(r"[^A-Za-z0-9._-]+", "_", Path(filename).name)[:160] or f"model.{output_format}"
+    if not filename.lower().endswith(f".{output_format}"):
+        filename += f".{output_format}"
+
+    WORK_ROOT.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="freecad-", dir=WORK_ROOT) as temp:
+        temp_path = Path(temp)
+        output_path = temp_path / filename
+        request_path = temp_path / "request.json"
+
+        request_data = {
+            "schema_version": 1,
+            "output": str(output_path),
+            "format": output_format,
+            "operations": operations,
+        }
+        request_path.write_text(json.dumps(request_data, indent=2), encoding="utf-8")
+
+        command = _freecad_command(adapter_path, request_path, operation="build")
+        env = os.environ.copy()
+        env.setdefault("QT_QPA_PLATFORM", "offscreen")
+        env.setdefault("PYTHONPATH", "/usr/lib/freecad/lib")
+
+        try:
+            proc = subprocess.run(
+                command,
+                cwd=temp,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(f"FreeCAD execution exceeded {timeout}s") from exc
+
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        logs = (stdout + "\n" + stderr).strip()
+
+        result_envelope = None
+        for line in reversed(stdout.splitlines()):
+            if line.startswith("AGENTSAM_RESULT="):
+                try:
+                    result_envelope = json.loads(line[len("AGENTSAM_RESULT="):])
+                    break
+                except json.JSONDecodeError:
+                    pass
+
+        if not result_envelope or not result_envelope.get("ok"):
+            err_msg = result_envelope.get("error") if result_envelope else f"exit {proc.returncode}"
+            raise RuntimeError(f"FreeCAD modeling failed ({err_msg}): {logs[-4000:]}")
+
+        if not output_path.exists():
+            raise RuntimeError(f"FreeCAD failed to produce output file {filename}")
+
+        artifact = output_path.read_bytes()
+        if len(artifact) > MAX_ARTIFACT_BYTES:
+            raise RuntimeError(f"artifact is {len(artifact)} bytes; exceeds {MAX_ARTIFACT_BYTES} bytes")
+
+        digest = hashlib.sha256(artifact).hexdigest()
+
+        return {
+            "ok": True,
+            "tool": "freecad",
+            "format": output_format,
+            "filename": filename,
+            "size_bytes": len(artifact),
+            "sha256": digest,
+            "artifact_base64": base64.b64encode(artifact).decode("ascii"),
+            "metrics": result_envelope.get("metrics", {}),
+            "logs": logs[-8000:],
+        }
+
+
+def _execute_blender(payload: dict[str, Any]) -> dict[str, Any]:
+    adapter_path = _find_blender_adapter()
+    operation = str(payload.get("operation") or "build").lower()
+    if operation not in ("build", "inspect", "render_preview", "export"):
+        raise ValueError(f"unsupported Blender operation: {operation}")
+
+    recipe = payload.get("recipe")
+    if recipe is None and "operations" in payload:
+        recipe = {"schema_version": 1, "operations": payload["operations"]}
+    if not isinstance(recipe, dict):
+        raise ValueError("recipe must be an object")
+
+    output_format = str(payload.get("format", "glb")).lower().lstrip(".")
+    if output_format not in BLENDER_FORMATS:
+        raise ValueError(f"unsupported Blender format: {output_format}")
+
+    timeout = payload.get("timeout_seconds", 30)
+    try:
+        timeout = int(timeout)
+    except (TypeError, ValueError):
+        timeout = 30
+    timeout = max(1, min(timeout, MAX_TIMEOUT_SECONDS))
+
+    filename = str(payload.get("filename") or f"model.{output_format}")
+    filename = re.sub(r"[^A-Za-z0-9._-]+", "_", Path(filename).name)[:160] or f"model.{output_format}"
+    if not filename.lower().endswith(f".{output_format}"):
+        filename += f".{output_format}"
+
+    WORK_ROOT.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="blender-", dir=WORK_ROOT) as temp:
+        temp_path = Path(temp)
+        output_path = temp_path / filename
+        request_path = temp_path / "request.json"
+
+        request_data = {
+            "schema_version": 1,
+            "output": str(output_path),
+            "format": output_format,
+            **recipe,
+        }
+        request_path.write_text(json.dumps(request_data, indent=2), encoding="utf-8")
+
+        command = _blender_command(adapter_path, request_path, operation=operation)
+        env = os.environ.copy()
+        env.setdefault("HOME", "/tmp/home")
+
+        try:
+            proc = subprocess.run(
+                command,
+                cwd=temp,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(f"Blender execution exceeded {timeout}s") from exc
+
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        logs = (stdout + "\n" + stderr).strip()
+
+        result_envelope = None
+        for line in reversed(stdout.splitlines()):
+            if line.startswith("AGENTSAM_RESULT="):
+                try:
+                    result_envelope = json.loads(line[len("AGENTSAM_RESULT="):])
+                    break
+                except json.JSONDecodeError:
+                    pass
+
+        if not result_envelope or not result_envelope.get("ok"):
+            err_msg = result_envelope.get("error") if result_envelope else f"exit {proc.returncode}"
+            raise RuntimeError(f"Blender execution failed ({err_msg}): {logs[-4000:]}")
+
+        artifact = b""
+        if output_path.exists():
+            artifact = output_path.read_bytes()
+            if len(artifact) > MAX_ARTIFACT_BYTES:
+                raise RuntimeError(f"artifact is {len(artifact)} bytes; exceeds {MAX_ARTIFACT_BYTES} bytes")
+
+        digest = hashlib.sha256(artifact).hexdigest() if artifact else None
+
+        return {
+            "ok": True,
+            "tool": "blender",
+            "operation": operation,
+            "format": output_format,
+            "filename": filename if artifact else None,
+            "size_bytes": len(artifact),
+            "sha256": digest,
+            "artifact_base64": base64.b64encode(artifact).decode("ascii") if artifact else None,
+            "result": result_envelope,
+            "logs": logs[-8000:],
+        }
+
+
 class Handler(BaseHTTPRequestHandler):
     server_version = "AgentSamCAD/1"
 
@@ -262,6 +503,12 @@ class Handler(BaseHTTPRequestHandler):
             if self.path == "/v1/openscad/compile":
                 self._json(HTTPStatus.OK, _compile_openscad(payload))
                 return
+            if self.path == "/v1/freecad/execute":
+                self._json(HTTPStatus.OK, _execute_freecad(payload))
+                return
+            if self.path == "/v1/blender/execute":
+                self._json(HTTPStatus.OK, _execute_blender(payload))
+                return
             self._json(HTTPStatus.NOT_FOUND, {"ok": False, "error": "not_found"})
         except ValueError as exc:
             self._json(HTTPStatus.BAD_REQUEST, {"ok": False, "error": str(exc)})

package/skills/README.md

@@ -4,18 +4,31 @@ Portable, on-demand AgentSam behavior modules. Skills keep specialized guidance
 out of the permanent system prompt and load deeper `references/` only when the
 current task calls for them.
 
-## Canonical skills
+## Canonical portable skills (`skills/catalog.json`)
 
-- `agentsam-jr-dev/` — explain, inspect, build, and revise real software using
-  beginner-friendly language grounded in the actual repository and runtime.
+| id | Status | Use when |
+|----|--------|----------|
+| `agentsam-jr-dev` | **current** | Teach/inspect/build with beginner-friendly, evidence-grounded language |
+| `agentsam-app-fundamentals` | **current** | Contracts, credentials, graphs, AST, Merkle — application laws |
+| `agentsam-progression-guard` | **current** | Local → CI → deploy → postdeploy gates; no silent regress |
+| `agentsam-cloudflare-workers` | **current** | Wrangler-native ops, observability, CPU profiling |
+| `agentsam-codebaseindex` | **current** | Guided ingest / `codebaseindex.ingest` / Vectorize+pgvector+local lanes |
 
-- `agentsam-app-fundamentals/` — quick application-building laws for trust,
-  contracts, credentials, dependency graphs, AST evidence, and Merkle evidence.
-- `agentsam-progression-guard/` — checkpoint/hook discipline for local work, CI,
-  deploy, postdeploy verification, promotion, runtime observation, and rollback.
+List or open them with `agentsam skills`; aliases such as `quick-bytes`, `no-regress`,
+`ingest` are intentionally short enough for terminal use.
 
-List or open them with `agentsam skills`; aliases such as `quick-bytes` and
-`no-regress` are intentionally short enough for terminal use.
+## Not portable (host / app scoped)
+
+`apps/local-studio/.grok/skills/*` (game/UI/sprite/xAI packs) are **Local Studio
+Grok host skills**. They do not belong in the SDK portable catalog and must not
+be confused with D1 `agentsam_skill` rows or `agentsam_tools`.
+
+## D1 registries (normalize for new users)
+
+| Table | Owns | New-user requirement |
+|-------|------|----------------------|
+| `agentsam_skill` (+ revision/invocation) | Dashboard Skills CRUD / slash triggers | Ship schema + seed portable skill metadata that mirrors `skills/catalog.json` |
+| `agentsam_tools` (+ capabilities/call log) | Callable tools: AST retrieve, merkle, D1, Vectorize, … | Ship schema migrations under `migrations/d1/` + optional seed of filesystem/code AST tools so scaffolds match IAM host |
 
 Apps may contain host-specific skill directories of their own. Those do not
 replace the portable SDK skills in this directory.