@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/protocol/sam/registry.seed.json

@@ -0,0 +1,153 @@
+{
+  "schema_version": 1,
+  "package": "@inneranimalmedia/agentsam-sdk",
+  "sam": "Systems Automation Machinery",
+  "note": "Seed registry — canonical operation IDs. CLI aliases are projections, not authority.",
+  "operations": [
+    {
+      "id": "repository.inspect",
+      "module": "repository",
+      "action": "inspect",
+      "summary": "Inspect repository structure and semantic evidence.",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "never",
+        "network": "none",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["repository.snapshot"],
+      "cli": { "command": [["inspect"]] },
+      "status": "stable"
+    },
+    {
+      "id": "brand.scan",
+      "module": "brand",
+      "action": "scan",
+      "summary": "Inspect repository material and derive brand evidence.",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "never",
+        "network": "none",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["brand.scan"],
+      "cli": { "command": [["brand", "scan"]] },
+      "status": "stable"
+    },
+    {
+      "id": "security.scan",
+      "module": "security",
+      "action": "scan",
+      "summary": "Scan project dependencies and trust boundary (SCA).",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "never",
+        "network": "optional",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["security.scan"],
+      "cli": { "command": [["security", "scan"], ["sca", "scan"]] },
+      "status": "stable"
+    },
+    {
+      "id": "terminal.exec",
+      "module": "terminal",
+      "action": "exec",
+      "summary": "Execute a bounded argv process inside the project root.",
+      "execution": {
+        "lanes": ["local", "sandbox"],
+        "model": "never",
+        "network": "optional",
+        "sideEffects": "local_write"
+      },
+      "risk": "write",
+      "capabilities": ["terminal.exec"],
+      "cli": { "command": [] },
+      "status": "stable"
+    },
+    {
+      "id": "cad.blender.inspect",
+      "module": "cad",
+      "action": "blender.inspect",
+      "summary": "Inspect an existing Blender source (.blend).",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "never",
+        "network": "none",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["blender.inspect"],
+      "cli": { "command": [["cad", "blender", "inspect"]] },
+      "status": "stable"
+    },
+    {
+      "id": "codebaseindex.ingest",
+      "module": "codebaseindex",
+      "action": "ingest",
+      "summary": "Ingest repository and/or dropped materials into the knowledge index.",
+      "execution": {
+        "lanes": ["local", "remote", "platform"],
+        "model": "optional",
+        "network": "optional",
+        "sideEffects": "local_write"
+      },
+      "risk": "write",
+      "capabilities": ["knowledge.index"],
+      "cli": { "command": [["codebaseindex"], ["ingest"]] },
+      "pipeline": "sam.codebaseindex.index.run",
+      "status": "stable"
+    },
+    {
+      "id": "planning.astar",
+      "module": "planning",
+      "action": "astar",
+      "summary": "Deterministic A* planner (f = g + h).",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "never",
+        "network": "none",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["planning.astar"],
+      "cli": { "command": [] },
+      "status": "stable"
+    },
+    {
+      "id": "planning.goap",
+      "module": "planning",
+      "action": "goap",
+      "summary": "GOAP adapter over A* with preconditions and effects.",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "never",
+        "network": "none",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["planning.goap", "planning.astar"],
+      "cli": { "command": [] },
+      "status": "stable"
+    },
+    {
+      "id": "decision.evaluate",
+      "module": "decision",
+      "action": "evaluate",
+      "summary": "Evaluate choose/score/check questions against a SAM decision state.",
+      "execution": {
+        "lanes": ["local", "remote", "sandbox"],
+        "model": "optional",
+        "network": "optional",
+        "sideEffects": "none"
+      },
+      "risk": "read_only",
+      "capabilities": ["decision.evaluate"],
+      "cli": { "command": [] },
+      "status": "stable"
+    }
+  ]
+}

package/protocol/sam/result.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/result.schema.json",
+  "title": "SamResult",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "operation", "ok", "data", "receipt"],
+  "properties": {
+    "schema": { "const": "agentsam.result.v1" },
+    "operation": { "type": "string" },
+    "ok": { "type": "boolean" },
+    "data": {},
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "operation", "started_at", "completed_at", "execution", "status"],
+      "properties": {
+        "id": { "type": "string" },
+        "operation": { "type": "string" },
+        "module": { "type": "string" },
+        "started_at": { "type": "string" },
+        "completed_at": { "type": "string" },
+        "execution": {
+          "type": "object",
+          "required": ["lane", "deterministic", "model_used"],
+          "properties": {
+            "lane": { "enum": ["local", "remote", "sandbox", "platform"] },
+            "deterministic": { "type": "boolean" },
+            "model_used": { "type": "boolean" }
+          }
+        },
+        "side_effects": { "type": "array", "items": { "type": "string" } },
+        "input_hash": { "type": ["string", "null"] },
+        "output_hash": { "type": ["string", "null"] },
+        "status": { "enum": ["completed", "failed", "cancelled"] }
+      }
+    },
+    "evidence": { "type": "array" },
+    "artifacts": { "type": "array" },
+    "usage": {
+      "type": "object",
+      "properties": {
+        "provider_calls": { "type": "integer", "minimum": 0 },
+        "input_tokens": { "type": "integer" },
+        "output_tokens": { "type": "integer" },
+        "cost_usd": { "type": "number" }
+      }
+    },
+    "warnings": { "type": "array" },
+    "diagnostics": { "type": "array" },
+    "error": {}
+  }
+}

package/protocol/sam/state.v1.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/state.v1.schema.json",
+  "title": "AgentSamDecisionState",
+  "type": "object",
+  "required": ["schema"],
+  "properties": {
+    "schema": { "const": "agentsam.decision-state.v1" },
+    "intent": {},
+    "goal": {},
+    "repository": { "type": ["object", "null"] },
+    "code": { "type": ["object", "null"] },
+    "runtime": { "type": ["object", "null"] },
+    "tools": {},
+    "skills": {},
+    "models": {},
+    "constraints": { "type": ["object", "null"] },
+    "evidence": { "type": "array" },
+    "history": {},
+    "metadata": { "type": "object" },
+    "facts": { "type": "object" }
+  }
+}

package/protocol/skills/agentsam.interaction.v1.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentsam.interaction.v1",
+  "title": "AgentSamInteraction",
+  "description": "Host-agnostic interaction contract for CLI (Clack), Local Studio, Tauri, and other AgentSam surfaces.",
+  "type": "object",
+  "required": ["status"],
+  "additionalProperties": false,
+  "properties": {
+    "status": {
+      "enum": ["ready", "needs_input", "needs_approval", "blocked", "complete"]
+    },
+    "prompt": {
+      "type": "object",
+      "required": ["kind", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": ["info", "text", "select", "multiselect", "confirm", "error"]
+        },
+        "code": { "type": "string" },
+        "title": { "type": "string" },
+        "message": { "type": "string" },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "type": "string" },
+              "label": { "type": "string" },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "label"],
+            "properties": {
+              "id": { "type": "string" },
+              "label": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/protocol/skills/agentsam.skill.v1.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentsam.skill.v1",
+  "title": "AgentSamSkillManifest",
+  "description": "Portable AgentSam skill definition. Identity is package/local id — not workspace, tenant, R2 key, or default model.",
+  "type": "object",
+  "required": ["schema", "id", "name", "instructions"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "agentsam.skill.v1" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "icon": {
+      "type": "string",
+      "description": "Semantic agentsam.icon.v1 key only"
+    },
+    "version": { "type": "string" },
+    "package": { "type": "string" },
+    "slash": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "suggested": {
+          "type": "string",
+          "pattern": "^/[a-z0-9][a-z0-9-]{0,63}$",
+          "description": "Suggested trigger at install time. Not globally reserved."
+        }
+      }
+    },
+    "instructions": {
+      "type": "object",
+      "required": ["source"],
+      "additionalProperties": false,
+      "properties": {
+        "source": {
+          "enum": ["inline", "local_file", "package_file", "database", "object_store"]
+        },
+        "ref": { "type": "string" },
+        "inline": { "type": "string" }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "const": "turn" },
+        "tools": { "type": "array", "items": { "type": "string" } },
+        "operations": { "type": "array", "items": { "type": "string" } },
+        "capabilities": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

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/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.