@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/protocol/receipts/agentsam.receipt.v1.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/schemas/agentsam.receipt.v1.json",
+  "title": "AgentSam Receipt Envelope v1",
+  "type": "object",
+  "required": [
+    "$schema",
+    "schema",
+    "receipt_id",
+    "kind",
+    "status",
+    "retention_class",
+    "identity",
+    "metrics",
+    "evidence",
+    "payload"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://schemas.inneranimalmedia.com/agentsam/schemas/agentsam.receipt.v1.json"
+    },
+    "schema": { "const": "agentsam.receipt.v1" },
+    "receipt_id": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["passed", "failed", "skipped"] },
+    "retention_class": {
+      "enum": ["ephemeral_success", "failure_bundle", "release_proof"]
+    },
+    "identity": {
+      "type": "object",
+      "required": ["account_id"],
+      "properties": {
+        "account_id": { "type": "string", "minLength": 1 },
+        "repository_id": { "type": "string" },
+        "git_sha": { "type": "string" },
+        "run_id": { "type": "string" },
+        "pty_session_id": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "metrics": {
+      "type": "object",
+      "required": [
+        "created_at_unix",
+        "duration_ms",
+        "workspace_byte_size",
+        "receipt_byte_size"
+      ],
+      "properties": {
+        "created_at_unix": { "type": "integer", "minimum": 0 },
+        "duration_ms": { "type": "number", "minimum": 0 },
+        "workspace_byte_size": { "type": "integer", "minimum": 0 },
+        "receipt_byte_size": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["summary", "artifacts"],
+      "properties": {
+        "summary": { "type": "object" },
+        "artifacts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["role", "sha256", "r2_key", "byte_size"],
+            "properties": {
+              "role": { "type": "string", "minLength": 1 },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[a-fA-F0-9]{32,128}$"
+              },
+              "r2_key": {
+                "type": "string",
+                "pattern": "^agentsam/runtime/blobs/sha256/"
+              },
+              "byte_size": { "type": "integer", "minimum": 0 }
+            },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "payload": {
+      "type": "object",
+      "required": ["schema"],
+      "properties": {
+        "schema": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/protocol/rpc/v1/errors.proto

@@ -56,4 +56,5 @@ message ErrorDetail {
   optional uint32 occurrence_count = 26;
   optional string request_id = 27;
   optional uint32 schema_version = 28;
+  optional string native_stage = 29;
 }

package/protocol/runtime/agentsam.runtime.v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/runtime/agentsam.runtime.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/runtime/agentsam.runtime.v1.schema.json",
   "title": "agentsam.runtime.v1",
   "description": "AgentSam Runtime Registry + protocol. Physical D1 tables remain terminal_*; domain nouns are Runtime*. PTY is a capability. transport ≠ adapter.",
   "type": "object",

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/runtime/workspace-fs.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/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",

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/activity.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/activity.v1.schema.json",
   "title": "AgentSamActivityEvent",
   "type": "object",
   "required": ["schema", "run_id", "seq", "timestamp", "phase", "event", "label"],

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/answer.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/answer.v1.schema.json",
   "title": "AgentSamDecisionAnswer",
   "type": "object",
   "required": ["type", "question_id", "value"],

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/calibration.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/calibration.v1.schema.json",
   "title": "AgentSamDecisionCalibration",
   "type": "object",
   "properties": {

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/decision-receipt.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/decision-receipt.v1.schema.json",
   "title": "AgentSamDecisionReceipt",
   "type": "object",
   "required": ["schema", "decision_id", "answers", "created_at"],

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/evaluation.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/evaluation.v1.schema.json",
   "title": "AgentSamDecisionEvaluation",
   "type": "object",
   "required": ["schema", "ok", "answers", "state_hash"],

package/protocol/sam/operation.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/operation.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/operation.schema.json",
   "title": "SamOperation",
   "type": "object",
   "additionalProperties": false,

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/outcome.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/outcome.v1.schema.json",
   "title": "AgentSamDecisionOutcome",
   "type": "object",
   "required": ["schema", "success", "recorded_at"],

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/question.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/question.v1.schema.json",
   "title": "AgentSamDecisionQuestion",
   "type": "object",
   "required": ["id", "type"],

package/protocol/sam/result.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/result.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/result.schema.json",
   "title": "SamResult",
   "type": "object",
   "additionalProperties": false,

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/sam/state.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/sam/state.v1.schema.json",
   "title": "AgentSamDecisionState",
   "type": "object",
   "required": ["schema"],

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentsam.inneranimalmedia.com/protocol/scoring/scorecard.v1.schema.json",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/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",

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.interaction.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/skills/agentsam.interaction.v1.schema.json",
   "title": "AgentSamInteraction",
   "description": "Host-agnostic interaction contract for CLI (Clack), Local Studio, Tauri, and other AgentSam surfaces.",
   "type": "object",

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.skill.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/skills/agentsam.skill.v1.schema.json",
   "title": "AgentSamSkillManifest",
   "description": "Portable AgentSam skill definition. Identity is package/local id — not workspace, tenant, R2 key, or default model.",
   "type": "object",

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.theme-refinery.product-metadata.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/theme-refinery/product-metadata.schema.json",
   "title": "agentsam_products.metadata for theme-refinery provenance",
   "type": "object",
   "additionalProperties": false,

package/protocol/theme-refinery/receipts/products-registry-batch-20260924.json

@@ -10,7 +10,7 @@
     "metadata": {
       "origin": "machine_harvest",
       "donor_name": "New Iberia Church of Christ",
-      "source_path": "/Users/samprimeaux/Library/Mobile Documents/com~apple~CloudDocs/Projects/Cloudflare/NewIberiaChurchofChrist",
+      "source_path": "local-donor://Library/Mobile Documents/com~apple~CloudDocs/Projects/Cloudflare/NewIberiaChurchofChrist",
       "harvest_batch": "theme-harvest-20260924",
       "normalization_state": "portable-preview",
       "source_hash": "0a8ae5de768f874ccdebe92a5e438ad8e4d51b4c5fdae9679c7e09268328fee6",
@@ -57,7 +57,7 @@
     "metadata": {
       "origin": "machine_harvest",
       "donor_name": "Companions of Caddo",
-      "source_path": "/Users/samprimeaux/companionscpas/static",
+      "source_path": "local-donor://companionscpas/static",
       "harvest_batch": "theme-harvest-20260924",
       "normalization_state": "portable-preview",
       "source_hash": "cdad95d1a674b05456a6166f9fc70d86dce106d4215395601164ec40ac161f7b",
@@ -149,7 +149,7 @@
     "metadata": {
       "origin": "machine_harvest",
       "donor_name": "Fuel & Free Time",
-      "source_path": "/Users/samprimeaux/fuelnfreetime/legacy",
+      "source_path": "local-donor://fuelnfreetime/legacy",
       "harvest_batch": "theme-harvest-20260924",
       "normalization_state": "portable-preview",
       "source_hash": "5ea35182b99816b9cb137a15f6ce7c361bfa932010759d3ac5bf74b1083895cf",
@@ -195,7 +195,7 @@
     "metadata": {
       "origin": "machine_harvest",
       "donor_name": "Primeaux Handyman Services",
-      "source_path": "/Users/samprimeaux/worktrees/primeaux-handyman-services-agent/dist",
+      "source_path": "worktree://primeaux-handyman-services-agent/dist",
       "harvest_batch": "theme-harvest-20260924",
       "normalization_state": "portable-preview",
       "source_hash": "36a5a147cd70c0523a50466fad113cc265ee22a571e98b2fd67fde15ee795ea4",
@@ -238,7 +238,7 @@
     "metadata": {
       "origin": "machine_harvest",
       "donor_name": "Chrystal Clear Insurance",
-      "source_path": "/Users/samprimeaux/Projects/client-demos/chrystal-clear-insurance/chrystal-clear-insurance/dist",
+      "source_path": "local-donor://Projects/client-demos/chrystal-clear-insurance/chrystal-clear-insurance/dist",
       "harvest_batch": "theme-harvest-20260924",
       "normalization_state": "portable-preview",
       "source_hash": "1e171081f5a06d7568554aedcc6a17fd17f102b4109e9b543895fca3879606c2",
@@ -281,7 +281,7 @@
     "metadata": {
       "origin": "machine_harvest",
       "donor_name": "Shinshu Solutions",
-      "source_path": "/Users/samprimeaux/IAM-Library/01_Template_Candidates/MEAUXIDERANDOMBUILDS/06_shinshu_static_site_archive/source/shinshu-solutions/static",
+      "source_path": "local-donor://IAM-Library/01_Template_Candidates/MEAUXIDERANDOMBUILDS/06_shinshu_static_site_archive/source/shinshu-solutions/static",
       "harvest_batch": "theme-harvest-20260924",
       "normalization_state": "portable-preview",
       "source_hash": "dbe669910cbee05028a7113c2e1f72d0d964f8898d48130f67c5955fbbbc978e",

package/protocol/theme-refinery/receipts/theme-harvest-20260924.json

@@ -107,7 +107,7 @@
         "metadata": {
           "origin": "machine_harvest",
           "donor_name": "New Iberia Church of Christ",
-          "source_path": "/Users/samprimeaux/Library/Mobile Documents/com~apple~CloudDocs/Projects/Cloudflare/NewIberiaChurchofChrist",
+          "source_path": "local-donor://Library/Mobile Documents/com~apple~CloudDocs/Projects/Cloudflare/NewIberiaChurchofChrist",
           "harvest_batch": "theme-harvest-20260924",
           "normalization_state": "portable-preview",
           "source_hash": "0a8ae5de768f874ccdebe92a5e438ad8e4d51b4c5fdae9679c7e09268328fee6",
@@ -163,7 +163,7 @@
         "metadata": {
           "origin": "machine_harvest",
           "donor_name": "Companions of Caddo",
-          "source_path": "/Users/samprimeaux/companionscpas/static",
+          "source_path": "local-donor://companionscpas/static",
           "harvest_batch": "theme-harvest-20260924",
           "normalization_state": "portable-preview",
           "source_hash": "cdad95d1a674b05456a6166f9fc70d86dce106d4215395601164ec40ac161f7b",
@@ -273,7 +273,7 @@
         "metadata": {
           "origin": "machine_harvest",
           "donor_name": "Fuel & Free Time",
-          "source_path": "/Users/samprimeaux/fuelnfreetime/legacy",
+          "source_path": "local-donor://fuelnfreetime/legacy",
           "harvest_batch": "theme-harvest-20260924",
           "normalization_state": "portable-preview",
           "source_hash": "5ea35182b99816b9cb137a15f6ce7c361bfa932010759d3ac5bf74b1083895cf",
@@ -328,7 +328,7 @@
         "metadata": {
           "origin": "machine_harvest",
           "donor_name": "Primeaux Handyman Services",
-          "source_path": "/Users/samprimeaux/worktrees/primeaux-handyman-services-agent/dist",
+          "source_path": "worktree://primeaux-handyman-services-agent/dist",
           "harvest_batch": "theme-harvest-20260924",
           "normalization_state": "portable-preview",
           "source_hash": "36a5a147cd70c0523a50466fad113cc265ee22a571e98b2fd67fde15ee795ea4",
@@ -380,7 +380,7 @@
         "metadata": {
           "origin": "machine_harvest",
           "donor_name": "Chrystal Clear Insurance",
-          "source_path": "/Users/samprimeaux/Projects/client-demos/chrystal-clear-insurance/chrystal-clear-insurance/dist",
+          "source_path": "local-donor://Projects/client-demos/chrystal-clear-insurance/chrystal-clear-insurance/dist",
           "harvest_batch": "theme-harvest-20260924",
           "normalization_state": "portable-preview",
           "source_hash": "1e171081f5a06d7568554aedcc6a17fd17f102b4109e9b543895fca3879606c2",
@@ -432,7 +432,7 @@
         "metadata": {
           "origin": "machine_harvest",
           "donor_name": "Shinshu Solutions",
-          "source_path": "/Users/samprimeaux/IAM-Library/01_Template_Candidates/MEAUXIDERANDOMBUILDS/06_shinshu_static_site_archive/source/shinshu-solutions/static",
+          "source_path": "local-donor://IAM-Library/01_Template_Candidates/MEAUXIDERANDOMBUILDS/06_shinshu_static_site_archive/source/shinshu-solutions/static",
           "harvest_batch": "theme-harvest-20260924",
           "normalization_state": "portable-preview",
           "source_hash": "dbe669910cbee05028a7113c2e1f72d0d964f8898d48130f67c5955fbbbc978e",

package/protocol/theme-refinery/reconciliation-receipt.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.theme-refinery.reconciliation-receipt.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/theme-refinery/reconciliation-receipt.schema.json",
   "title": "ThemeRefineryReconciliationReceipt",
   "type": "object",
   "required": ["schema_version", "batch_id", "captured_at", "products", "repositories", "relationships", "evidence", "artifacts", "promotions", "failures"],

package/protocol/ui/icon.v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "agentsam.icon.v1",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/ui/icon.v1.schema.json",
   "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",

package/python/README.md

@@ -13,6 +13,26 @@ python3 -m unittest discover -s tests -v
 
 Protocol: [`../protocol/README.md`](../protocol/README.md). Do not advance this tree without mirroring the monorepo (or the reverse).
 
+## Portable lifecycle hooks
+
+`agentsam_sdk.hooks` implements the same `agentsam.hook.v1` envelope as the
+JavaScript/TypeScript, Go, Rust, command, and HTTP adapters. It is stdlib-only:
+
+```python
+from agentsam_sdk.hooks import HookRuntime
+
+hooks = HookRuntime()
+hooks.register("pre_tool_use", lambda envelope: {
+    "permission_decision": "allow"
+})
+result = await hooks.dispatch("pre_tool_use", {
+    "tool_name": "repository.snapshot", "tool_args": {}
+})
+```
+
+See [`../packages/agentsam-hooks/README.md`](../packages/agentsam-hooks/README.md)
+for composition, permission, and subprocess transport rules.
+
 ## Optional sibling packages (not part of stdlib core)
 
 | Package | Path | Notes |

package/python/agentsam_sdk/errors/__init__.py

@@ -0,0 +1,4 @@
+"""Canonical AgentSam error vocabulary."""
+from .vocabulary import ERROR_REASON_ALIASES, ERROR_REASON_POLICY, ERROR_SCHEMA_VERSION, error_policy, normalize_error_reason
+
+__all__ = ["ERROR_REASON_ALIASES", "ERROR_REASON_POLICY", "ERROR_SCHEMA_VERSION", "error_policy", "normalize_error_reason"]