@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/protocol/presets/catalog.json

@@ -6,43 +6,152 @@
       "version": 1,
       "lane": "fullstack",
       "description": "Local-first application with AgentSam runtime, repository primitives, knowledge, and delivery hooks.",
-      "features": ["agent", "knowledge"],
-      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "security.scan", "deploy.receipt"],
-      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+      "features": [
+        "agent",
+        "knowledge"
+      ],
+      "capabilities": [
+        "scaffold.create",
+        "repository.snapshot",
+        "knowledge.index",
+        "knowledge.search",
+        "security.scan",
+        "deploy.receipt"
+      ],
+      "defaults": {
+        "database": "sqlite",
+        "assets": "local",
+        "deploy": "local"
+      }
     },
     "cms": {
       "id": "cms",
-      "version": 1,
+      "version": 2,
       "lane": "cms",
-      "description": "Content-oriented application starting from local CMS primitives with explicit auth/deploy opt-ins.",
-      "features": ["cms", "knowledge"],
-      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "site.scrape", "deploy.receipt"],
-      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+      "description": "Content-oriented application with AgentSam CMS editor, stock heuristic-theme, and explicit auth/deploy opt-ins.",
+      "features": [
+        "cms",
+        "knowledge",
+        "brand",
+        "theme"
+      ],
+      "capabilities": [
+        "scaffold.create",
+        "repository.snapshot",
+        "knowledge.index",
+        "knowledge.search",
+        "site.scrape",
+        "deploy.receipt",
+        "brand.scan",
+        "brand.resolve",
+        "theme.storefront.shell"
+      ],
+      "defaults": {
+        "database": "sqlite",
+        "assets": "local",
+        "deploy": "local",
+        "theme": "heuristic-theme",
+        "composer": "agentsam.mini-composer"
+      },
+      "packages": {
+        "theme": "@inneranimalmedia/heuristic-theme",
+        "composer": "@inneranimalmedia/agentsam-workbench",
+        "analytics": "@inneranimalmedia/commerce-analytics"
+      },
+      "notes": "Fuel & Free Time hosts proving-ground copies; SDK packages are the publish targets."
     },
     "prototype": {
       "id": "prototype",
       "version": 1,
       "lane": "fullstack",
       "description": "Small local prototype with the minimum deterministic AgentSam runtime.",
-      "features": ["agent"],
-      "capabilities": ["scaffold.create", "repository.snapshot", "security.scan"],
-      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+      "features": [
+        "agent"
+      ],
+      "capabilities": [
+        "scaffold.create",
+        "repository.snapshot",
+        "security.scan"
+      ],
+      "defaults": {
+        "database": "sqlite",
+        "assets": "local",
+        "deploy": "local"
+      }
     },
     "data": {
       "id": "data",
       "version": 1,
       "lane": "data",
       "description": "Data-oriented local application with repository knowledge and explicit production storage graduation.",
-      "features": ["knowledge"],
-      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "security.scan"],
-      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+      "features": [
+        "knowledge"
+      ],
+      "capabilities": [
+        "scaffold.create",
+        "repository.snapshot",
+        "knowledge.index",
+        "knowledge.search",
+        "security.scan"
+      ],
+      "defaults": {
+        "database": "sqlite",
+        "assets": "local",
+        "deploy": "local"
+      }
     }
   },
   "addons": {
-    "agent": { "id": "agent", "capabilities": ["scaffold.create"], "description": "AgentSam local runtime selection." },
-    "auth": { "id": "auth", "capabilities": ["identity.init"], "description": "Identity package selection; use `agentsam identity init` when a standalone auth app scaffold is required." },
-    "cms": { "id": "cms", "capabilities": ["site.scrape"], "description": "CMS/content feature selection." },
-    "knowledge": { "id": "knowledge", "capabilities": ["knowledge.index", "knowledge.search"], "description": "Portable repository indexing and retrieval." },
-    "deploy-cloudflare": { "id": "deploy-cloudflare", "capabilities": ["deploy.receipt"], "description": "Select Cloudflare as the intended deploy target; provisioning remains explicit at deploy time." }
+    "agent": {
+      "id": "agent",
+      "capabilities": [
+        "scaffold.create"
+      ],
+      "description": "AgentSam local runtime selection."
+    },
+    "auth": {
+      "id": "auth",
+      "capabilities": [
+        "identity.init"
+      ],
+      "description": "Identity selection (schema_version 2). Records provider_template; use `agentsam identity plan|init|schema` for protocol-driven setup."
+    },
+    "cms": {
+      "id": "cms",
+      "capabilities": [
+        "site.scrape"
+      ],
+      "description": "CMS/content feature selection (stock theme: heuristic-theme via theme.storefront.shell)."
+    },
+    "theme": {
+      "id": "theme",
+      "capabilities": [
+        "theme.storefront.shell"
+      ],
+      "description": "Stock storefront theme selection — default package @inneranimalmedia/heuristic-theme (theme.storefront.shell). Theme is a projection of Brand, not brand authority."
+    },
+    "brand": {
+      "id": "brand",
+      "capabilities": [
+        "brand.scan",
+        "brand.resolve"
+      ],
+      "description": "Deterministic Brand Intelligence — evidence from repository.snapshot; Brand ≠ Theme."
+    },
+    "knowledge": {
+      "id": "knowledge",
+      "capabilities": [
+        "knowledge.index",
+        "knowledge.search"
+      ],
+      "description": "Portable repository indexing and retrieval."
+    },
+    "deploy-cloudflare": {
+      "id": "deploy-cloudflare",
+      "capabilities": [
+        "deploy.receipt"
+      ],
+      "description": "Select Cloudflare as the intended deploy target; provisioning remains explicit at deploy time."
+    }
   }
 }

package/protocol/rpc/v1/errors.proto

@@ -23,6 +23,9 @@ enum ErrorCode {
   ERROR_CODE_UNAUTHENTICATED = 16;
 }
 
+// Transport representation of the canonical AgentSam ErrorEnvelope. String
+// vocabulary is deliberate: SDK reason/severity/source catalogs evolve faster
+// than protobuf enum releases, while code retains the canonical gRPC mapping.
 message ErrorDetail {
   ErrorCode code = 1;
   string message = 2;
@@ -32,4 +35,25 @@ message ErrorDetail {
   optional uint32 retry_after_ms = 6;
   optional string provider = 7;
   optional string provider_code = 8;
+
+  optional string severity = 9;
+  optional string source_kind = 10;
+  optional string source_name = 11;
+  optional string source_service = 12;
+  optional string resolution_owner = 13;
+  optional string domain = 14;
+  optional string tool = 15;
+  optional string stage = 16;
+  optional string remediation_action = 17;
+  optional string remediation_message = 18;
+  optional string fingerprint = 19;
+  optional string trace_id = 20;
+  optional string transport = 21;
+  optional string resource_json = 22;
+  optional string native_json = 23;
+  optional string environment_json = 24;
+  optional string details_json = 25;
+  optional uint32 occurrence_count = 26;
+  optional string request_id = 27;
+  optional uint32 schema_version = 28;
 }

package/protocol/runtime/workspace-fs.v1.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/runtime/workspace-fs.v1.schema.json",
+  "title": "AgentSamWorkspaceFilesystemContract",
+  "description": "Stable browser/WorkspaceAdapter contract. TypeScript local-fs implements today; Go agentsamd may replace the host without changing these operations.",
+  "type": "object",
+  "required": ["schema", "operations"],
+  "properties": {
+    "schema": { "const": "agentsam.workspace-fs.v1" },
+    "engine": {
+      "type": "string",
+      "description": "Implementation id, e.g. agentsam-local-fs-v1 or agentsamd-go-fs-v1"
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "list",
+          "read",
+          "stat",
+          "write",
+          "create",
+          "rename",
+          "remove",
+          "mkdir",
+          "change_events"
+        ]
+      }
+    },
+    "write": {
+      "type": "object",
+      "properties": {
+        "expectedVersion": {
+          "type": ["string", "null"],
+          "description": "Optimistic concurrency — conflict if disk hash differs"
+        },
+        "overwrite": { "type": "boolean" }
+      }
+    },
+    "authority": {
+      "type": "object",
+      "properties": {
+        "binding": { "const": "loopback" },
+        "capability_header": { "const": "x-agentsam-workspace-capability" },
+        "root_claim": { "const": "server_bound_only" }
+      }
+    },
+    "events": {
+      "type": "object",
+      "properties": {
+        "name": { "const": "workspace.file.changed" },
+        "payload": {
+          "type": "object",
+          "properties": {
+            "path": { "type": "string" },
+            "version": { "type": "string" },
+            "workspace_id": { "type": "string" }
+          }
+        }
+      }
+    },
+    "go_replacement": {
+      "type": "object",
+      "description": "Future agentsamd host implements the same HTTP/WS surface; WorkspaceAdapter and Studio contracts stay unchanged.",
+      "properties": {
+        "package": { "const": "apps/agentsam-go-worker" },
+        "status": { "enum": ["documented", "implemented"] }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/activity.v1.schema.json",
+  "title": "AgentSamActivityEvent",
+  "type": "object",
+  "required": ["schema", "run_id", "seq", "timestamp", "phase", "event", "label"],
+  "properties": {
+    "schema": { "const": "agentsam.activity.v1" },
+    "run_id": { "type": "string" },
+    "seq": { "type": "integer", "minimum": 0 },
+    "timestamp": { "type": "string" },
+    "phase": {
+      "enum": ["boot", "observe", "context", "plan", "execute", "verify", "compact", "waiting", "recover", "complete"]
+    },
+    "event": {
+      "enum": [
+        "run.started",
+        "phase.changed",
+        "step.started",
+        "step.progress",
+        "step.completed",
+        "decision.made",
+        "tool.started",
+        "tool.completed",
+        "artifact.created",
+        "file.changed",
+        "approval.required",
+        "input.required",
+        "verification.completed",
+        "run.failed",
+        "run.completed"
+      ]
+    },
+    "step_id": { "type": ["string", "null"] },
+    "parent_id": { "type": ["string", "null"] },
+    "label": { "type": "string" },
+    "detail": { "type": ["string", "null"] },
+    "progress": {
+      "type": ["object", "null"],
+      "properties": {
+        "current": { "type": "number" },
+        "total": { "type": "number" }
+      }
+    },
+    "source": { "type": "object" },
+    "evidence": { "type": ["object", "null"] }
+  }
+}

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

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/answer.v1.schema.json",
+  "title": "AgentSamDecisionAnswer",
+  "type": "object",
+  "required": ["type", "question_id", "value"],
+  "properties": {
+    "schema": { "const": "agentsam.decision-answer.v1" },
+    "type": { "enum": ["choose", "score", "check"] },
+    "question_id": { "type": "string" },
+    "value": {},
+    "scores": { "type": ["object", "null"] },
+    "levels": { "type": ["object", "null"] },
+    "support": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
+    "confidence_estimate": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Distribution concentration — NOT P(correct) unless calibrated"
+    },
+    "probabilities": {
+      "type": ["object", "null"],
+      "description": "Only when evaluator has a defined probabilistic interpretation"
+    },
+    "calibrated_probability": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "calibration_id": { "type": ["string", "null"] },
+    "evaluator": { "type": ["object", "null"] },
+    "evidence": { "type": "array" },
+    "warnings": { "type": "array", "items": { "type": "string" } }
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/calibration.v1.schema.json",
+  "title": "AgentSamDecisionCalibration",
+  "type": "object",
+  "properties": {
+    "schema": { "const": "agentsam.decision-calibration.v1" },
+    "kind": { "enum": ["metrics", "dataset_export", "model_card"] },
+    "ece": { "type": "number" },
+    "reliability": { "type": "array" },
+    "brier": { "type": "number" },
+    "log_loss": { "type": "number" },
+    "calibration_id": { "type": "string" },
+    "training_window": {},
+    "sample_count": { "type": "integer" },
+    "validation_metrics": { "type": "object" },
+    "question_version": {},
+    "rows": { "type": "array" },
+    "note": { "type": "string" }
+  }
+}

package/protocol/sam/decision-receipt.v1.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/decision-receipt.v1.schema.json",
+  "title": "AgentSamDecisionReceipt",
+  "type": "object",
+  "required": ["schema", "decision_id", "answers", "created_at"],
+  "properties": {
+    "schema": { "const": "agentsam.decision-receipt.v1" },
+    "decision_id": { "type": "string" },
+    "run_id": { "type": ["string", "null"] },
+    "step_id": { "type": ["string", "null"] },
+    "action_id": { "type": ["string", "null"] },
+    "outcome_id": { "type": ["string", "null"] },
+    "question_contract": {},
+    "question_ids": { "type": "array", "items": { "type": "string" } },
+    "question_versions": { "type": "object" },
+    "evaluator": { "type": ["object", "null"] },
+    "evaluators": { "type": "array" },
+    "state_hash": { "type": ["string", "null"] },
+    "answers": { "type": "object" },
+    "policy_result": { "type": ["object", "null"] },
+    "evidence": { "type": "array" },
+    "action": {},
+    "outcome": { "type": ["object", "null"] },
+    "created_at": { "type": "string" },
+    "updated_at": { "type": "string" },
+    "why": { "type": "object" }
+  }
+}

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

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/evaluation.v1.schema.json",
+  "title": "AgentSamDecisionEvaluation",
+  "type": "object",
+  "required": ["schema", "ok", "answers", "state_hash"],
+  "properties": {
+    "schema": { "const": "agentsam.decision-evaluation.v1" },
+    "ok": { "type": "boolean" },
+    "state_hash": { "type": "string" },
+    "answers": { "type": "object" },
+    "routing": { "type": "object" },
+    "policy_result": { "type": "object" },
+    "model_used": { "type": "boolean" },
+    "deterministic": { "type": "boolean" },
+    "question_versions": { "type": "object" },
+    "receipt": { "type": "object" }
+  }
+}

package/protocol/sam/operation.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/operation.schema.json",
+  "title": "SamOperation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "version", "module", "action", "summary", "execution", "risk"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]+(\\.[a-z][a-z0-9_-]+)+$",
+      "description": "Canonical operation id, e.g. brand.scan"
+    },
+    "version": { "type": "integer", "minimum": 1 },
+    "module": { "type": "string", "minLength": 1 },
+    "action": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lanes", "model", "network", "sideEffects"],
+      "properties": {
+        "lanes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "enum": ["local", "remote", "sandbox", "platform"] }
+        },
+        "model": { "enum": ["never", "optional", "required"] },
+        "network": { "enum": ["none", "optional", "required"] },
+        "sideEffects": {
+          "enum": ["none", "local_write", "remote_read", "remote_write", "deploy", "billable"]
+        }
+      }
+    },
+    "auth": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "account": { "type": "boolean" },
+        "provider": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "risk": { "enum": ["read_only", "write", "privileged"] },
+    "input_schema": { "type": "string" },
+    "output_schema": { "type": "string" },
+    "capabilities": { "type": "array", "items": { "type": "string" } },
+    "cli": {
+      "type": "object",
+      "properties": {
+        "command": {
+          "type": "array",
+          "items": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "examples": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "status": { "enum": ["stable", "experimental", "stub", "deprecated"] }
+  }
+}

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

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/outcome.v1.schema.json",
+  "title": "AgentSamDecisionOutcome",
+  "type": "object",
+  "required": ["schema", "success", "recorded_at"],
+  "properties": {
+    "schema": { "const": "agentsam.decision-outcome.v1" },
+    "outcome_id": { "type": "string" },
+    "success": { "type": "boolean" },
+    "disposition": {
+      "enum": [
+        "accepted",
+        "rejected",
+        "overridden",
+        "corrected_to",
+        "retry_required",
+        "verification_failed",
+        "user_intervened",
+        "success",
+        "failure"
+      ]
+    },
+    "human_corrected": { "type": "boolean" },
+    "corrected_to": {},
+    "user_override": { "type": "boolean" },
+    "actual_class": {},
+    "duration_ms": { "type": ["number", "null"] },
+    "retries": { "type": ["integer", "null"] },
+    "verification": { "type": "array" },
+    "label_strength": {
+      "enum": ["supervised", "explicit_accept", "weak_passive"]
+    },
+    "recorded_at": { "type": "string" }
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/question.v1.schema.json",
+  "title": "AgentSamDecisionQuestion",
+  "type": "object",
+  "required": ["id", "type"],
+  "properties": {
+    "schema": { "const": "agentsam.decision-question.v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "type": { "enum": ["choose", "score", "check"] },
+    "version": { "type": "integer", "minimum": 1 },
+    "instructions": {
+      "description": "string | object | array | null",
+      "type": ["string", "object", "array", "null"]
+    },
+    "criteria": {
+      "description": "string | object | array | null",
+      "type": ["string", "object", "array", "null"]
+    },
+    "options": { "type": "array", "items": { "type": "string" } },
+    "levels": { "type": "array" },
+    "evaluator_hint": {
+      "enum": ["deterministic", "heuristic", "graph", "semantic", "calibrated-statistical", null]
+    }
+  }
+}