@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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/scoring/README.md

@@ -0,0 +1,10 @@
+# Scoring protocol
+
+`ScoreCard` is a **versioned derived view** over raw evidence.
+
+- Raw evidence (hashes, OBSERVED tokens, usage rows, known-asset ids) is SSOT.
+- Scores are recomputable from evidence + `weights/*.vN.json`.
+- Score families stay independent — never collapse into one `similarity_score`.
+- Human accept/reject calibrates recommendations (Beta / outcome receipts); it does **not** mutate deterministic evidence.
+
+See `@inneranimalmedia/agentsam-scoring` and `docs/content-studio/REVISION_GATE_2026-09-27.md`.

package/protocol/scoring/scorecard.v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/scoring/scorecard.v1.schema.json",
+  "title": "AgentSamScoreCard",
+  "description": "Versioned derived score view. Raw evidence remains SSOT; ScoreCards are recomputable. Independent score families — never one grand similarity_score.",
+  "type": "object",
+  "required": [
+    "id",
+    "kind",
+    "score",
+    "confidence",
+    "algorithm",
+    "weightsVersion",
+    "components",
+    "penalties",
+    "evidenceRefs",
+    "computedAt"
+  ],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "theme-similarity",
+        "brand-affinity",
+        "template-similarity",
+        "section-reuse",
+        "token-consistency",
+        "portability",
+        "package-readiness",
+        "drift",
+        "confidence",
+        "structural-similarity",
+        "reuse"
+      ]
+    },
+    "score": { "type": "number", "minimum": 0, "maximum": 100 },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "algorithm": { "type": "string" },
+    "weightsVersion": { "type": "string" },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["raw", "normalized", "weight", "contribution"],
+        "properties": {
+          "raw": { "type": "number" },
+          "normalized": { "type": "number", "minimum": 0, "maximum": 1 },
+          "weight": { "type": "number", "minimum": 0, "maximum": 1 },
+          "contribution": { "type": "number" }
+        }
+      }
+    },
+    "penalties": {
+      "type": "object",
+      "additionalProperties": { "type": "number" }
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "computedAt": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

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,227 @@
+/**
+ * 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' },
+});
+
+/** @type {Readonly<Record<string, string>>} */
+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;
+  };
+}