@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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

@@ -539,6 +539,140 @@
       "type": "integer",
       "minimum": 1
     },
-    "details": {}
+    "details": {},
+    "failure_class": {
+      "type": "string",
+      "description": "Provider-independent failure dimension; prefer this over exploding ERROR_REASON"
+    },
+    "operation": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "action": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "resource_type": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "resource_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "read_only": {
+          "type": "boolean"
+        },
+        "idempotent": {
+          "type": "boolean"
+        },
+        "side_effect_state": {
+          "enum": [
+            "none",
+            "not_started",
+            "confirmed_not_applied",
+            "confirmed_applied",
+            "partially_applied",
+            "unknown"
+          ]
+        }
+      }
+    },
+    "retry": {
+      "type": "object",
+      "properties": {
+        "allowed": {
+          "type": "boolean"
+        },
+        "strategy": {
+          "type": "string"
+        },
+        "retry_after_ms": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "max_attempts": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "requires_idempotency_key": {
+          "type": "boolean"
+        }
+      }
+    },
+    "fallback": {
+      "type": "object",
+      "properties": {
+        "allowed": {
+          "type": "boolean"
+        },
+        "strategy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "preserve_semantics": {
+          "type": "boolean"
+        },
+        "target": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "notify": {
+      "type": "object",
+      "properties": {
+        "user": {
+          "type": "string"
+        },
+        "operator": {
+          "type": "string"
+        },
+        "agent": {
+          "type": "string"
+        }
+      }
+    },
+    "cause": {},
+    "status": {
+      "enum": [
+        "success",
+        "partial",
+        "failure"
+      ]
+    },
+    "partial": {
+      "type": "object",
+      "properties": {
+        "completed": {
+          "type": "number"
+        },
+        "failed": {
+          "type": "number"
+        },
+        "failures": {
+          "type": "array"
+        }
+      }
+    }
   }
 }

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/errors/recovery.v1.schema.json",
+  "title": "AgentSamRecoveryPlan",
+  "type": "object",
+  "required": ["schema", "disposition", "attempts", "notify", "reason"],
+  "properties": {
+    "schema": { "const": "agentsam.recovery.v1" },
+    "error_fingerprint": { "type": ["string", "null"] },
+    "disposition": {
+      "enum": [
+        "continue",
+        "retry",
+        "reconnect",
+        "resume",
+        "reconcile",
+        "fallback",
+        "replan",
+        "await_user",
+        "abort"
+      ]
+    },
+    "attempts": {
+      "type": "object",
+      "required": ["current", "maximum"],
+      "properties": {
+        "current": { "type": "integer", "minimum": 1 },
+        "maximum": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "delay_ms": { "type": ["number", "null"] },
+    "fallback": {
+      "type": ["object", "null"],
+      "properties": {
+        "kind": { "type": "string" },
+        "target": { "type": ["string", "null"] }
+      }
+    },
+    "notify": {
+      "type": "object",
+      "properties": {
+        "user": { "type": "string" },
+        "operator": { "type": "string" },
+        "agent": { "type": "string" }
+      }
+    },
+    "reason": { "type": "string" },
+    "evidence": { "type": "array", "items": { "type": "string" } }
+  }
+}

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

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/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",
+  "additionalProperties": false,
+  "required": ["schema", "provider", "substrate", "lifecycle", "runtime_adapter", "capabilities"],
+  "properties": {
+    "schema": { "const": "agentsam.runtime.v1" },
+    "provider": {
+      "type": "string",
+      "enum": ["local", "google_cloud", "cloudflare", "aws", "azure", "fly", "custom"]
+    },
+    "substrate": {
+      "type": "string",
+      "enum": ["host", "vm", "container", "sandbox", "workstation", "microvm", "kubernetes"]
+    },
+    "provider_product": {
+      "type": ["string", "null"],
+      "description": "Optional product within provider/substrate (compute_engine, cloud_run, containers, sandbox, docker, …)"
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["persistent", "scale_to_zero", "ephemeral", "job"]
+    },
+    "runtime_adapter": {
+      "type": "string",
+      "enum": ["agentsamd", "execos_legacy", "cloudflare_sandbox", "docker_engine", "ssh", "provider_native"]
+    },
+    "protocol": { "const": "agentsam.runtime.v1" },
+    "architecture": { "type": "string", "enum": ["arm64", "x86_64", "unknown"] },
+    "os": { "type": "string", "enum": ["darwin", "linux", "windows", "macos", "unknown"] },
+    "status": {
+      "type": "string",
+      "enum": ["online", "ready", "sleeping", "starting", "offline", "error", "provisioning", "stopped", "failed", "deleting"]
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": { "type": "boolean" },
+      "properties": {
+        "exec": { "type": "boolean" },
+        "pty": { "type": "boolean" },
+        "filesystem": { "type": "boolean" },
+        "persistent_filesystem": { "type": "boolean" },
+        "process": { "type": "boolean" },
+        "git": { "type": "boolean" },
+        "docker": { "type": "boolean" },
+        "gpu": { "type": "boolean" },
+        "browser": { "type": "boolean" },
+        "gui": { "type": "boolean" },
+        "ports": { "type": "boolean" },
+        "snapshot": { "type": "boolean" }
+      }
+    },
+    "transport": {
+      "type": "string",
+      "enum": [
+        "direct_https",
+        "direct_wss",
+        "cloudflare_tunnel",
+        "vpc_service",
+        "vpc_network",
+        "service_binding",
+        "local_socket",
+        "provider_api",
+        "ssh"
+      ]
+    },
+    "auth_mode": {
+      "type": "string",
+      "enum": ["connection_token", "platform_bridge", "bridge_key", "service_binding"]
+    }
+  }
+}

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]
+    }
+  }
+}