@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/protocol/errors/error-envelope.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/errors/error-envelope.schema.json",
-  "title": "AgentSam ErrorEnvelope v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/errors/agentsam.error.v2.schema.json",
+  "title": "AgentSam ErrorEnvelope v2",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -9,14 +9,22 @@
     "schema_version",
     "code",
     "reason",
+    "domain",
+    "failure_class",
+    "stage",
+    "native_stage",
+    "feature",
+    "failure_behavior",
     "severity",
-    "source",
+    "retryable",
+    "side_effect_state",
     "resolution_owner",
-    "domain",
+    "source",
+    "adapter",
+    "protocol",
+    "transport",
     "tool",
-    "stage",
     "message",
-    "retryable",
     "retry_after_ms",
     "remediation",
     "resource",
@@ -24,7 +32,6 @@
     "environment",
     "http_status",
     "grpc_status",
-    "transport",
     "provider",
     "provider_code",
     "request_id",
@@ -38,7 +45,7 @@
       "const": false
     },
     "schema_version": {
-      "const": 1
+      "const": 2
     },
     "code": {
       "enum": [
@@ -64,6 +71,137 @@
       "type": "string",
       "pattern": "^[a-z][a-z0-9_]{0,127}$"
     },
+    "domain": {
+      "enum": [
+        "runtime",
+        "provider",
+        "auth",
+        "identity",
+        "device",
+        "terminal",
+        "transport",
+        "repository",
+        "indexing",
+        "knowledge",
+        "cad",
+        "hook",
+        "model",
+        "configuration",
+        "schema",
+        "migration",
+        "database",
+        "package",
+        "build",
+        "distribution",
+        "deployment",
+        "workflow",
+        "persistence",
+        "policy",
+        "tool"
+      ]
+    },
+    "failure_class": {
+      "enum": [
+        "input",
+        "validation",
+        "authentication",
+        "authorization",
+        "policy",
+        "discovery",
+        "resolution",
+        "availability",
+        "transport",
+        "protocol",
+        "timeout",
+        "rate_limit",
+        "capacity",
+        "resource",
+        "configuration",
+        "dependency",
+        "filesystem",
+        "persistence",
+        "consistency",
+        "conflict",
+        "process",
+        "ipc",
+        "data_integrity",
+        "cancellation",
+        "cancelled",
+        "build",
+        "distribution",
+        "migration",
+        "schema",
+        "identity",
+        "execution",
+        "internal",
+        "unknown"
+      ]
+    },
+    "stage": {
+      "enum": [
+        "discover",
+        "resolve",
+        "load",
+        "configure",
+        "validate",
+        "authorize",
+        "connect",
+        "prepare",
+        "install",
+        "build",
+        "start",
+        "execute",
+        "transform",
+        "persist",
+        "migrate",
+        "verify",
+        "publish",
+        "attach",
+        "detach",
+        "cleanup",
+        "shutdown"
+      ]
+    },
+    "native_stage": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "feature": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$",
+          "maxLength": 256
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "failure_behavior": {
+      "anyOf": [
+        {
+          "enum": [
+            "fail_closed",
+            "fail_open",
+            "observe_only",
+            "retry_bounded",
+            "skip",
+            "abort",
+            "no_replay"
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "severity": {
       "enum": [
         "transient",
@@ -72,6 +210,29 @@
         "policy_blocking"
       ]
     },
+    "retryable": {
+      "type": "boolean"
+    },
+    "side_effect_state": {
+      "enum": [
+        "none",
+        "not_started",
+        "confirmed_not_applied",
+        "confirmed_applied",
+        "partially_applied",
+        "unknown"
+      ]
+    },
+    "resolution_owner": {
+      "enum": [
+        "user",
+        "agentsam",
+        "provider",
+        "organization_admin",
+        "policy",
+        "unknown"
+      ]
+    },
     "source": {
       "type": "object",
       "additionalProperties": false,
@@ -108,35 +269,27 @@
         }
       }
     },
-    "resolution_owner": {
-      "enum": [
-        "user",
-        "agentsam",
-        "provider",
-        "organization_admin",
-        "policy",
-        "unknown"
+    "adapter": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
       ]
     },
-    "domain": {
-      "enum": [
-        "runtime",
-        "provider",
-        "auth",
-        "device",
-        "terminal",
-        "transport",
-        "repository",
-        "indexing",
-        "knowledge",
-        "cad",
-        "deployment",
-        "persistence",
-        "policy",
-        "tool"
+    "protocol": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
       ]
     },
-    "tool": {
+    "transport": {
       "anyOf": [
         {
           "type": "string"
@@ -146,7 +299,7 @@
         }
       ]
     },
-    "stage": {
+    "tool": {
       "anyOf": [
         {
           "type": "string"
@@ -161,9 +314,6 @@
       "minLength": 1,
       "maxLength": 4000
     },
-    "retryable": {
-      "type": "boolean"
-    },
     "retry_after_ms": {
       "anyOf": [
         {
@@ -212,7 +362,14 @@
             "inspect_platform",
             "contact_provider",
             "contact_agentsam",
-            "contact_organization_admin"
+            "contact_organization_admin",
+            "restart_service",
+            "repair_schema",
+            "run_migration",
+            "regenerate_artifact",
+            "update_lockfile",
+            "reinstall_workspace",
+            "republish_artifact"
           ]
         },
         "message": {
@@ -481,16 +638,6 @@
         }
       ]
     },
-    "transport": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
     "provider": {
       "anyOf": [
         {
@@ -540,10 +687,6 @@
       "minimum": 1
     },
     "details": {},
-    "failure_class": {
-      "type": "string",
-      "description": "Provider-independent failure dimension; prefer this over exploding ERROR_REASON"
-    },
     "operation": {
       "type": "object",
       "properties": {

package/protocol/errors/recovery.v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/errors/recovery.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/errors/recovery.v1.schema.json",
   "title": "AgentSamRecoveryPlan",
   "type": "object",
   "required": ["schema", "disposition", "attempts", "notify", "reason"],

package/protocol/features/agentsam.feature.v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.dev/protocol/features/agentsam.feature.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/features/agentsam.feature.v1.schema.json",
   "title": "AgentSam Feature Capsule",
   "description": "Vertical product capability that a host APP can activate. npm install is inert; AgentSam activates after plan + approval. Not a full APP \u2014 use agentsam.app.v1 / .agentsam/app.json for runnable compositions.",
   "type": "object",

package/protocol/hooks/README.md

@@ -0,0 +1,18 @@
+# AgentSam Hooks protocol
+
+`agentsam.hook.v1` is the language-neutral lifecycle boundary for AgentSam hosts.
+
+- `agentsam.hook.v1.schema.json`: invocation envelope.
+- `agentsam.hook.output.v1.schema.json`: handler response.
+- `agentsam.hooks.config.v1.schema.json`: explicit command/HTTP wiring.
+- `agentsam.hook.receipt.v1.schema.json`: value-free execution evidence with canonical AgentSam error dimensions and separately redacted native evidence.
+
+The wire format uses snake_case and Unix epoch milliseconds. Event-specific data stays under `input`; host-owned correlation IDs stay under `invocation`. Providers, MCP transports, LSP clients, runtimes, and agent schedulers adapt into this boundary rather than adding provider fields to the lifecycle contract.
+
+Hooks are policy and transformation ports, not identity or capability authorities. Hosts must enforce permission decisions and continue to own authorization, grants, retries, persistence, and receipts. Unknown output properties are rejected so a misspelled decision cannot silently become an allow. `session_start.modified_config` is a composable patch: patches merge in priority order, and each host explicitly allowlists which host-scoped session settings it applies.
+
+The optional portable registry is owned by `migrations/runtime/0005_agentsam_hooks.sql`; package lifecycle scripts generate the standalone schema-pack copy from that authority. It uses `owner_id` plus `scope_type`/`scope_ref`, not required tenant/workspace tables.
+
+Cross-language bindings live in `packages/agentsam-hooks`. Its `sync:protocol` pretest/prepack gate generates distributable schema copies from this authority; a package test verifies that those generated artifacts are byte-identical.
+
+Failed receipts do not invent a hook-only error taxonomy. They store `error_code`, `reason`, `domain`, `failure_class`, `stage`, `feature`, `failure_behavior`, `retryable`, `side_effect_state`, and `fingerprint` from `protocol/errors/error-catalog.json`. Adapter, protocol, and transport remain separate dimensions. Redacted native code/type/message evidence is stored in `native_evidence`. A failed post-tool or post-model hook records the already-applied side effect and is never routed back through the tool/model replay path.

package/protocol/hooks/agentsam.hook.output.v1.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/hooks/agentsam.hook.output.v1.schema.json",
+  "title": "AgentSam hook output",
+  "type": "object",
+  "properties": {
+    "permission_decision": { "enum": ["allow", "deny", "ask"] },
+    "permission_decision_reason": { "type": "string" },
+    "modified_args": { "type": "object" },
+    "modified_request": { "type": "object" },
+    "modified_result": {},
+    "modified_prompt": { "type": "string" },
+    "modified_transformed_prompt": { "type": "string" },
+    "modified_config": { "type": "object" },
+    "additional_context": { "type": "string" },
+    "suppress_output": { "type": "boolean" },
+    "error_handling": { "enum": ["retry", "skip", "abort"] },
+    "retry_count": { "type": "integer", "minimum": 0, "maximum": 10 },
+    "user_notification": { "type": "string" },
+    "decision": { "enum": ["allow", "block"] },
+    "reason": { "type": "string" },
+    "cleanup_actions": { "type": "array", "items": { "type": "string" } },
+    "session_summary": { "type": "string" },
+    "metadata": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/protocol/hooks/agentsam.hook.receipt.v1.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/hooks/agentsam.hook.receipt.v1.schema.json",
+  "title": "AgentSam hook execution receipt",
+  "type": "object",
+  "required": ["schema", "hook_id", "hook", "status", "started_at", "completed_at", "duration_ms", "input_keys", "output_keys"],
+  "properties": {
+    "schema": { "const": "agentsam.hook.receipt.v1" },
+    "hook_id": { "type": "string", "minLength": 1 },
+    "hook": {
+      "enum": [
+        "session_start", "session_end", "user_prompt_submitted", "user_prompt_transformed",
+        "pre_model_use", "post_model_use", "pre_tool_use", "post_tool_use",
+        "post_tool_use_failure", "error_occurred", "agent_stop", "subagent_start", "subagent_stop"
+      ]
+    },
+    "invocation": { "type": "object" },
+    "status": { "enum": ["completed", "failed"] },
+    "started_at": { "type": "number", "minimum": 0 },
+    "completed_at": { "type": "number", "minimum": 0 },
+    "duration_ms": { "type": "number", "minimum": 0 },
+    "input_keys": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "output_keys": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "error": {
+      "type": "object",
+      "required": [
+        "error_code", "reason", "domain", "failure_class", "stage", "feature",
+        "failure_behavior", "retryable", "side_effect_state", "adapter", "protocol",
+        "transport", "fingerprint", "message"
+      ],
+      "properties": {
+        "error_code": { "type": "string", "pattern": "^[A-Z][A-Z_]{1,63}$" },
+        "reason": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,127}$" },
+        "domain": { "type": "string", "minLength": 1 },
+        "failure_class": { "type": "string", "minLength": 1 },
+        "stage": { "type": "string", "minLength": 1 },
+        "feature": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" },
+        "failure_behavior": { "enum": ["fail_closed", "fail_open", "observe_only", "retry_bounded", "skip", "abort", "no_replay"] },
+        "retryable": { "type": "boolean" },
+        "side_effect_state": { "enum": ["none", "not_started", "confirmed_not_applied", "confirmed_applied", "partially_applied", "unknown"] },
+        "adapter": { "type": ["string", "null"] },
+        "protocol": { "type": ["string", "null"] },
+        "transport": { "type": ["string", "null"] },
+        "fingerprint": { "type": "string", "pattern": "^err_[A-Za-z0-9_-]{8,128}$" },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "native_evidence": {
+      "type": "object",
+      "required": ["code", "exception_type", "message"],
+      "properties": {
+        "code": { "type": ["string", "null"] },
+        "exception_type": { "type": ["string", "null"] },
+        "message": { "type": "string", "maxLength": 512 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/protocol/hooks/agentsam.hook.v1.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/hooks/agentsam.hook.v1.schema.json",
+  "title": "AgentSam hook invocation envelope",
+  "type": "object",
+  "required": ["schema", "hook", "timestamp", "cwd", "invocation", "input"],
+  "properties": {
+    "schema": { "const": "agentsam.hook.v1" },
+    "hook": {
+      "enum": [
+        "session_start", "session_end", "user_prompt_submitted", "user_prompt_transformed",
+        "pre_model_use", "post_model_use", "pre_tool_use", "post_tool_use",
+        "post_tool_use_failure", "error_occurred", "agent_stop", "subagent_start", "subagent_stop"
+      ]
+    },
+    "timestamp": { "type": "number", "minimum": 0, "description": "Unix epoch milliseconds." },
+    "cwd": { "type": "string" },
+    "invocation": {
+      "type": "object",
+      "properties": {
+        "session_id": { "type": "string" },
+        "run_id": { "type": "string" },
+        "turn_id": { "type": "string" },
+        "message_id": { "type": "string" },
+        "agent_id": { "type": "string" },
+        "parent_agent_id": { "type": "string" },
+        "source": { "type": "string" },
+        "metadata": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "input": { "type": "object", "description": "Event-specific, provider-neutral payload." }
+  },
+  "additionalProperties": false
+}

package/protocol/hooks/agentsam.hooks.config.v1.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/hooks/agentsam.hooks.config.v1.schema.json",
+  "title": "AgentSam portable hook configuration",
+  "type": "object",
+  "required": ["schema", "adapters", "hooks"],
+  "properties": {
+    "schema": { "const": "agentsam.hooks.config.v1" },
+    "adapters": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["type", "command"],
+            "properties": {
+              "type": { "const": "command" },
+              "command": { "type": "string", "minLength": 1 },
+              "args": { "type": "array", "items": { "type": "string" } },
+              "cwd": { "type": "string" },
+              "env": { "type": "object", "additionalProperties": { "type": "string" } },
+              "inherit_environment": { "type": "boolean" },
+              "timeout_ms": { "type": "integer", "minimum": 1, "maximum": 600000 },
+              "max_output_bytes": { "type": "integer", "minimum": 1, "maximum": 16777216 }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["type", "url"],
+            "properties": {
+              "type": { "const": "http" },
+              "url": { "type": "string", "format": "uri" },
+              "headers": { "type": "object", "additionalProperties": { "type": "string" } },
+              "timeout_ms": { "type": "integer", "minimum": 1, "maximum": 600000 },
+              "max_response_bytes": { "type": "integer", "minimum": 1, "maximum": 16777216 }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "propertyNames": {
+        "enum": [
+          "session_start", "session_end", "user_prompt_submitted", "user_prompt_transformed",
+          "pre_model_use", "post_model_use", "pre_tool_use", "post_tool_use",
+          "post_tool_use_failure", "error_occurred", "agent_stop", "subagent_start", "subagent_stop"
+        ]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "required": ["adapter"],
+              "properties": {
+                "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+                "adapter": { "type": "string" },
+                "priority": { "type": "number" },
+                "timeout_ms": { "type": "integer", "minimum": 1, "maximum": 600000 },
+                "failure_mode": { "enum": ["open", "closed", "error"] },
+                "enabled": { "type": "boolean" },
+                "match": { "type": "object" },
+                "metadata": { "type": "object" }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/protocol/local-engine/benchmark.v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.engine.benchmark.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/local-engine/benchmark.v1.schema.json",
   "type": "object",
   "required": ["schema_version", "engine_id", "runs", "summary"],
   "properties": {

package/protocol/local-engine/engine.v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.local-engine.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/local-engine/engine.v1.schema.json",
   "type": "object",
   "required": ["schema_version", "engine_id", "status", "capabilities"],
   "properties": {

package/protocol/models/README.md

@@ -371,3 +371,6 @@ What exact models can this account use?
 What does the provider currently say each model can do and cost?
 What exact provider/model/reasoning/tier actually handled this run?
 ```
+
+<!-- agentsam:trademark-notice -->
+> Independent project. Not affiliated with, endorsed by, or sponsored by Cloudflare, Inc. or by any other company whose products are named here. Cloudflare is a registered trademark of Cloudflare, Inc. Other names are trademarks of their respective owners. See [TRADEMARKS](https://github.com/SamPrimeaux/agentsam-sdk/blob/main/TRADEMARKS.md).

package/protocol/models/model-inventory-v2.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://inneranimalmedia.com/protocol/models/model-inventory-v2.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/models/model-inventory-v2.schema.json",
   "title": "AgentSam Model Inventory v2",
   "type": "object",
   "additionalProperties": false,

package/protocol/models/provider-model-snapshot.v1.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/models/provider-model-snapshot.v1.schema.json",
+  "title": "AgentSam credential-scoped provider model snapshot",
+  "description": "Compact metadata_json payload for an agentsam_plugins AI installation. This is availability evidence, not the global model catalog and never contains credential material.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "provider", "model_ids", "model_count", "models_hash", "fetched_at_unix"],
+  "properties": {
+    "schema": { "const": "agentsam.provider-model-snapshot.v1" },
+    "provider": { "type": "string", "minLength": 1 },
+    "model_ids": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "model_count": { "type": "integer", "minimum": 0 },
+    "models_hash": { "type": "string", "pattern": "^fnv1a32:[0-9a-f]{8}$" },
+    "fetched_at_unix": { "type": "integer", "minimum": 0 },
+    "authority": { "const": "credential_scoped_provider_discovery" }
+  }
+}