@inneranimalmedia/agentsam-sdk 2.6.2 → 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/theme-refinery/d1-reconciliation.md

@@ -0,0 +1,48 @@
+# D1 reconciliation contract (theme refinery)
+
+Target DB: **inneranimalmedia-business** (live AgentSam product graph).
+
+## Invariant
+
+```sql
+SELECT slug, kind, status, repository_id, canonical_path
+FROM agentsam_products
+ORDER BY kind, name;
+```
+
+must answer current inventory. From any row, `asset_relationships` answers defined_in / sourced_from / depends_on / consumed_by / exposes_tool / provides_workflow. Evidence + artifacts answer what was observed and what preview/QA supports promotion.
+
+## Product UPSERT (pseudocode)
+
+```sql
+INSERT INTO agentsam_products (
+  id, account_id, slug, name, kind, status,
+  repository_id, canonical_path, metadata, updated_at
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, unixepoch())
+ON CONFLICT(account_id, slug) DO UPDATE SET
+  name = excluded.name,
+  kind = excluded.kind,
+  status = excluded.status,
+  repository_id = COALESCE(excluded.repository_id, agentsam_products.repository_id),
+  canonical_path = excluded.canonical_path,
+  metadata = excluded.metadata,
+  updated_at = excluded.updated_at;
+```
+
+- Resolve `repository_id` via `code_repositories` lookup (repo URL / name / path). **Never invent.**
+- Existing triggers emit `defined_in` when `repository_id` is set — do not duplicate manually.
+
+## Relationship UPSERT
+
+Honor uniqueness on `(source_type, source_id, target_type, target_id, relationship_type)`.
+
+## Evidence
+
+Write `agentsam_evidence_snapshots` with `snapshot_type` in (`repository`,`website`,`seo`,`business`), same `account_id` as product/repo.
+
+## Do not
+
+- Dual-write every product into legacy `apps` by default (backfill *from* `apps` only).
+- Register whole sites as `cms_component_templates` or only as `cms_themes`.
+- Stuff giant archaeology JSON or secrets into `agentsam_products.metadata`.
+- Emit tools/workflows/skills/hooks unless formally exposed.

package/protocol/theme-refinery/product-metadata.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentsam.theme-refinery.product-metadata.v1",
+  "title": "agentsam_products.metadata for theme-refinery provenance",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "origin": { "type": "string", "enum": ["machine_harvest", "gallery_mount", "manual", "apps_backfill"] },
+    "donor_name": { "type": "string" },
+    "source_path": { "type": "string", "description": "Local donor path; never secrets" },
+    "harvest_batch": { "type": "string" },
+    "normalization_state": {
+      "type": "string",
+      "enum": ["fingerprinted", "portable", "portable-preview", "normalized", "wired", "promoted"]
+    },
+    "source_hash": { "type": "string" },
+    "app_manifest": { "type": "string" },
+    "help_root": { "type": "string" },
+    "preview_kind": { "type": "string", "enum": ["static", "live", "iframe", "none"] },
+    "package": { "type": "string" },
+    "gallery_path": { "type": "string" },
+    "capabilities": { "type": "array", "items": { "type": "string" } },
+    "latest_evidence_snapshot_id": { "type": ["string", "null"] },
+    "latest_quality_report_id": { "type": ["string", "null"] }
+  },
+  "required": ["origin", "normalization_state"]
+}