@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.10

package/packages/agentsam-errors/test/catalog-v2.test.mjs

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import {
+  ERROR_REASON_POLICY,
+  FAILURE_CLASS,
+  canonicalizeErrorReason,
+  createErrorEnvelope,
+  normalizeError,
+  planRecovery,
+} from '../src/index.js';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const catalog = JSON.parse(fs.readFileSync(path.join(root, 'protocol/errors/error-catalog.json'), 'utf8'));
+
+test('v2 keeps broad codes stable while preserving adapter-specific timeout reasons', () => {
+  assert.equal(catalog.codes.length, 17);
+  assert.equal(catalog.schema_version, 2);
+  const cases = [
+    ['http', 'AGENTSAM_HOOK_TIMEOUT', 'hook_http_timeout'],
+    ['mcp', 'hook_mcp_timeout:server', 'hook_mcp_timeout'],
+    ['lsp', 'hook_lsp_timeout:rust', 'hook_lsp_timeout'],
+    ['command', 'hook_command_timeout:node', 'hook_command_timeout'],
+  ];
+  for (const [adapter, native, reason] of cases) {
+    const error = normalizeError(Object.assign(new Error(native), { code: native.split(':')[0] }), {
+      adapter,
+      feature: `hooks.${adapter}`,
+      failure_behavior: 'fail_closed',
+      side_effect_state: 'not_started',
+    });
+    assert.equal(error.code, 'DEADLINE_EXCEEDED');
+    assert.equal(error.reason, reason);
+    assert.equal(error.adapter, adapter);
+    assert.equal(error.feature, `hooks.${adapter}`);
+  }
+});
+
+test('v2 dimensions use generic stages and retain subsystem-native stages separately', () => {
+  const error = createErrorEnvelope({
+    reason: 'schema_contract_mismatch',
+    stage: 'constraint_solve',
+    feature: 'database.migrate',
+    failure_behavior: 'abort',
+    side_effect_state: 'confirmed_not_applied',
+    message: 'portable schema ownership differs',
+  });
+  assert.equal(error.domain, 'schema');
+  assert.equal(error.failure_class, 'schema');
+  assert.equal(error.stage, 'validate');
+  assert.equal(error.native_stage, 'constraint_solve');
+  assert.equal(error.feature, 'database.migrate');
+  assert.equal(error.side_effect_state, 'confirmed_not_applied');
+  assert.throws(() => createErrorEnvelope({ reason: 'input_invalid', feature: 'Not a dotted ID' }), /Invalid AgentSam error feature/);
+});
+
+test('recovery consumes the generated failure and side-effect vocabularies', () => {
+  assert.equal(FAILURE_CLASS.VALIDATION, 'validation');
+  const error = createErrorEnvelope({
+    reason: 'input_invalid', message: 'bad input', side_effect_state: 'confirmed_not_applied',
+  });
+  const recovery = planRecovery(error);
+  assert.equal(recovery.disposition, 'await_user');
+  assert.equal(recovery.reason, 'invalid_input');
+});
+
+test('every harvested legacy hook alias resolves to its catalog reason', () => {
+  for (const row of catalog.reasons.filter((reason) => reason.domain === 'hook' || reason.aliases?.some((alias) => /hook|mcp|lsp|capability|agent/i.test(alias)))) {
+    for (const alias of row.aliases || []) {
+      assert.equal(canonicalizeErrorReason(`${alias}:native detail`), row.name, alias);
+    }
+  }
+});
+
+test('generated JS, Go, Rust, Python, and packed catalog policies retain parity', () => {
+  const packedCatalog = JSON.parse(fs.readFileSync(path.join(root, 'packages/agentsam-errors/protocol/error-catalog.json'), 'utf8'));
+  assert.deepEqual(packedCatalog, catalog);
+  const expected = Object.fromEntries(catalog.reasons.map((row) => [row.name, {
+    code: row.code,
+    domain: row.domain,
+    failure_class: row.failure_class,
+    severity: row.severity,
+    retryable: row.retryable,
+    resolution_owner: row.resolution_owner,
+    remediation_action: row.remediation_action,
+    default_stage: row.default_stage,
+  }]));
+  assert.deepEqual(ERROR_REASON_POLICY, expected);
+
+  const python = JSON.parse(execFileSync('python3', ['-c', [
+    'import json',
+    'from agentsam_sdk.errors import ERROR_REASON_POLICY',
+    'print(json.dumps(ERROR_REASON_POLICY, sort_keys=True))',
+  ].join(';')], { cwd: root, env: { ...process.env, PYTHONPATH: path.join(root, 'python') }, encoding: 'utf8' }));
+  assert.deepEqual(python, expected);
+
+  const go = fs.readFileSync(path.join(root, 'packages/agentsam-hooks/bindings/go/errors_generated.go'), 'utf8');
+  const rust = fs.readFileSync(path.join(root, 'packages/agentsam-hooks/bindings/rust/src/errors_generated.rs'), 'utf8');
+  for (const row of catalog.reasons) {
+    assert.ok(go.includes(`${JSON.stringify(row.name)}: {Code: ${JSON.stringify(row.code)}`), `Go policy missing ${row.name}`);
+    assert.ok(rust.includes(`reason: ${JSON.stringify(row.name)}, code: ${JSON.stringify(row.code)}`), `Rust policy missing ${row.name}`);
+  }
+});

package/packages/agentsam-errors/types/index.d.ts

@@ -0,0 +1,157 @@
+// GENERATED by scripts/generate-error-contracts.mjs. Do not edit by hand.
+
+export const ERROR_SCHEMA_VERSION: 2;
+
+export type AgentSamErrorCode = "OK" | "CANCELLED" | "UNKNOWN" | "INVALID_ARGUMENT" | "DEADLINE_EXCEEDED" | "NOT_FOUND" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "RESOURCE_EXHAUSTED" | "FAILED_PRECONDITION" | "ABORTED" | "OUT_OF_RANGE" | "UNIMPLEMENTED" | "INTERNAL" | "UNAVAILABLE" | "DATA_LOSS" | "UNAUTHENTICATED";
+export type AgentSamErrorReason = "unknown" | "input_invalid" | "input_out_of_range" | "precondition_failed" | "unsupported_operation" | "auth_missing" | "auth_invalid" | "permission_denied" | "user_permission_denied" | "provider_not_connected" | "provider_credential_missing" | "provider_credential_invalid" | "provider_credential_expired" | "provider_scope_insufficient" | "provider_budget_exhausted" | "provider_quota_exhausted" | "provider_rate_limited" | "provider_capacity_exhausted" | "provider_unavailable" | "provider_overloaded" | "provider_request_invalid" | "provider_model_not_found" | "provider_region_unsupported" | "provider_content_blocked" | "context_window_exceeded" | "service_tier_unsupported" | "continuation_invalid" | "target_not_found" | "already_exists" | "conflict" | "stale_version" | "rate_limited" | "quota_exhausted" | "capacity_exhausted" | "transport_unreachable" | "transport_refused" | "transport_timeout" | "upstream_invalid_response" | "dns_unresolved" | "tls_handshake_failed" | "tls_certificate_invalid" | "tunnel_connector_unavailable" | "cancelled" | "deadline_exceeded" | "execution_timeout" | "execution_failed" | "process_spawn_failed" | "process_crashed" | "process_output_limit" | "device_not_enrolled" | "device_credential_missing" | "device_credential_invalid" | "device_credential_expired" | "device_registration_missing" | "device_registration_stale" | "connection_revoked" | "connection_disabled" | "identity_resolution_failed" | "identity_mismatch" | "repository_scope_violation" | "repository_changed" | "index_stale" | "index_failed" | "embedding_failed" | "vector_store_failed" | "github_installation_missing" | "github_repository_not_found" | "github_rate_limited" | "github_secondary_rate_limited" | "github_scope_insufficient" | "cloudflare_workers_cpu_exhausted" | "cloudflare_service_binding_unavailable" | "cloudflare_durable_object_unavailable" | "cloudflare_d1_unavailable" | "cloudflare_r2_unavailable" | "docker_daemon_unavailable" | "docker_image_not_found" | "docker_build_failed" | "docker_container_failed" | "docker_registry_auth_failed" | "docker_pull_rate_limited" | "gcp_project_missing" | "gcp_api_disabled" | "gcp_quota_exhausted" | "gcp_vm_not_found" | "gcp_vm_unavailable" | "cad_tool_not_installed" | "cad_tool_not_executable" | "cad_tool_version_incompatible" | "cad_component_missing" | "cad_dependency_missing" | "cad_dependency_version_incompatible" | "cad_source_parse_failed" | "cad_input_format_unsupported" | "cad_import_failed" | "cad_model_recompute_failed" | "cad_constraint_unsatisfied" | "cad_geometry_invalid" | "cad_null_shape" | "cad_boolean_failed" | "cad_kernel_failed" | "cad_script_failed" | "cad_export_format_unsupported" | "cad_export_failed" | "cad_output_missing" | "cad_output_invalid" | "cad_render_engine_unavailable" | "cad_gpu_unavailable" | "cad_render_failed" | "cad_memory_exhausted" | "cad_process_crashed" | "cad_warning_escalated" | "policy_blocked" | "copyright_blocked" | "persistence_failed" | "data_corrupt" | "data_loss" | "internal" | "internal_invariant_violation" | "internal_configuration_invalid" | "internal_contract_violation" | "internal_adapter_failed" | "internal_dependency_failed" | "hook_definition_invalid" | "hook_duplicate_id" | "hook_not_found" | "hook_disabled" | "hook_event_unsupported" | "hook_configuration_invalid" | "hook_adapter_unknown" | "hook_adapter_unavailable" | "hook_handler_unavailable" | "hook_handler_timeout" | "hook_handler_failed" | "hook_output_invalid" | "hook_output_limit_exceeded" | "hook_output_field_unsupported" | "hook_http_timeout" | "hook_http_request_failed" | "hook_http_response_invalid" | "hook_http_response_limit_exceeded" | "hook_http_protocol_unsupported" | "hook_http_credentials_forbidden" | "hook_mcp_timeout" | "hook_mcp_server_unavailable" | "hook_mcp_capability_missing" | "hook_mcp_capability_duplicate" | "hook_mcp_response_invalid" | "hook_mcp_transport_failed" | "hook_lsp_timeout" | "hook_lsp_server_unavailable" | "hook_lsp_language_required" | "hook_lsp_capability_unsupported" | "hook_lsp_initialize_failed" | "hook_lsp_response_invalid" | "hook_command_required" | "hook_command_timeout" | "hook_command_spawn_failed" | "hook_command_exit_nonzero" | "hook_command_output_limit_exceeded" | "hook_command_output_invalid" | "hook_permission_denied" | "hook_capability_unavailable" | "hook_capability_duplicate" | "hook_error_handling_invalid" | "hook_error_handling_unsupported" | "hook_retry_limit_exceeded" | "hook_stop_decision_invalid" | "package_manifest_invalid" | "package_export_missing" | "package_file_missing" | "package_unwanted_file_included" | "package_dependency_missing" | "package_dependency_version_mismatch" | "lockfile_missing" | "lockfile_stale" | "lockfile_incompatible" | "workspace_not_installed" | "workspace_resolution_failed" | "workspace_boundary_invalid" | "build_dependency_missing" | "build_failed" | "build_output_missing" | "build_output_stale" | "pack_failed" | "pack_contents_invalid" | "pack_provenance_violation" | "distribution_artifact_missing" | "distribution_identity_mismatch" | "distribution_version_mismatch" | "distribution_install_failed" | "distribution_smoke_failed" | "release_train_misaligned" | "published_artifact_stale" | "published_artifact_missing" | "schema_invalid" | "schema_version_unsupported" | "schema_contract_mismatch" | "schema_pack_missing" | "schema_pack_dependency_missing" | "schema_pack_dependency_cycle" | "schema_pack_ownership_conflict" | "migration_missing" | "migration_failed" | "migration_checksum_mismatch" | "migration_order_invalid" | "migration_already_applied_conflict" | "migration_requires_manual_repair" | "database_unreachable" | "database_driver_unsupported" | "database_authority_unresolved" | "database_authorization_failed" | "database_schema_drift" | "model_discovery_failed" | "model_catalog_stale" | "model_snapshot_missing" | "model_snapshot_stale" | "model_capability_unknown" | "model_capability_unsupported" | "model_provider_mismatch" | "model_identity_conflict" | "model_probe_failed" | "model_probe_partial" | "runtime_not_installed" | "runtime_not_running" | "runtime_version_incompatible" | "runtime_capability_missing" | "runtime_protocol_mismatch" | "runtime_connection_unresolved" | "runtime_connection_revoked" | "pty_create_failed" | "pty_attach_failed" | "pty_session_not_found" | "pty_session_expired" | "pty_replay_cursor_invalid" | "transport_not_configured" | "transport_auth_failed" | "transport_attach_failed" | "sidecar_missing" | "sidecar_start_failed" | "sidecar_health_failed" | "tool_not_found" | "tool_disabled" | "tool_handler_unavailable" | "tool_execution_failed" | "tool_timeout" | "tool_output_invalid" | "tool_permission_denied" | "mcp_timeout" | "mcp_server_unavailable" | "mcp_capability_unsupported" | "mcp_response_invalid" | "mcp_transport_failed" | "lsp_timeout" | "lsp_server_unavailable" | "lsp_capability_unsupported" | "lsp_response_invalid" | "lsp_transport_failed" | "mcp_call_failed" | "lsp_request_failed";
+export type AgentSamErrorSeverity = "transient" | "blocking_user_fixable" | "blocking_internal" | "policy_blocking";
+export type AgentSamErrorSourceKind = "user" | "agentsam" | "provider" | "dependency" | "runtime" | "policy";
+export type AgentSamErrorResolutionOwner = "user" | "agentsam" | "provider" | "organization_admin" | "policy" | "unknown";
+export type AgentSamErrorDomain = "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";
+export type AgentSamErrorFailureClass = "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";
+export type AgentSamErrorStage = "discover" | "resolve" | "load" | "configure" | "validate" | "authorize" | "connect" | "prepare" | "install" | "build" | "start" | "execute" | "transform" | "persist" | "migrate" | "verify" | "publish" | "attach" | "detach" | "cleanup" | "shutdown";
+export type AgentSamErrorFailureBehavior = "fail_closed" | "fail_open" | "observe_only" | "retry_bounded" | "skip" | "abort" | "no_replay";
+export type AgentSamRemediationAction = "none" | "retry" | "retry_later" | "reauthenticate" | "connect_provider" | "configure_provider_credential" | "refresh_provider_credential" | "request_permission" | "reenroll_device" | "reconnect_service" | "install_dependency" | "upgrade_dependency" | "configure_dependency" | "change_configuration" | "change_input" | "reduce_scope" | "increase_quota" | "add_budget" | "select_model" | "change_region" | "restart_runtime" | "inspect_platform" | "contact_provider" | "contact_agentsam" | "contact_organization_admin" | "restart_service" | "repair_schema" | "run_migration" | "regenerate_artifact" | "update_lockfile" | "reinstall_workspace" | "republish_artifact";
+export type AgentSamErrorSideEffectState = "none" | "not_started" | "confirmed_not_applied" | "confirmed_applied" | "partially_applied" | "unknown";
+export type AgentSamErrorOutcomeStatus = "success" | "partial" | "failure";
+
+export interface AgentSamErrorSource { kind: AgentSamErrorSourceKind; name: string; service: string | null; }
+export interface AgentSamErrorRemediation { action: AgentSamRemediationAction; message: string | null; automatic: boolean; command: string | null; url: string | null; }
+export interface AgentSamErrorResource { type: string; id: string | null; name: string | null; }
+export interface AgentSamNativeErrorEvidence { code: string | null; exception_type: string | null; exit_code: number | null; signal: string | null; stderr: string | null; stdout: string | null; stack: string | null; }
+export interface AgentSamEnvironmentEvidence { detected_version: string | null; required_version: string | null; component: string | null; runtime: string | null; platform: string | null; }
+export interface AgentSamErrorOperation { kind?: string | null; action?: string | null; resource_type?: string | null; resource_id?: string | null; read_only?: boolean; idempotent?: boolean; side_effect_state?: AgentSamErrorSideEffectState; }
+export interface AgentSamErrorRetry { allowed?: boolean; strategy?: string; retry_after_ms?: number | null; max_attempts?: number | null; requires_idempotency_key?: boolean; }
+export interface AgentSamErrorFallback { allowed?: boolean; strategy?: string | null; preserve_semantics?: boolean; target?: string | null; }
+export interface AgentSamErrorNotification { user?: string; operator?: string; agent?: string; }
+export interface AgentSamErrorPartialResult { completed?: number; failed?: number; failures?: unknown[]; }
+
+export interface AgentSamErrorEnvelope {
+  ok: false;
+  schema_version: typeof ERROR_SCHEMA_VERSION;
+  code: AgentSamErrorCode;
+  reason: AgentSamErrorReason | (string & {});
+  domain: AgentSamErrorDomain;
+  failure_class: AgentSamErrorFailureClass;
+  stage: AgentSamErrorStage;
+  native_stage: string | null;
+  feature: string | null;
+  failure_behavior: AgentSamErrorFailureBehavior | null;
+  severity: AgentSamErrorSeverity;
+  retryable: boolean;
+  side_effect_state: AgentSamErrorSideEffectState;
+  resolution_owner: AgentSamErrorResolutionOwner;
+  source: AgentSamErrorSource;
+  adapter: string | null;
+  protocol: string | null;
+  transport: string | null;
+  tool: string | null;
+  message: string;
+  retry_after_ms: number | null;
+  remediation: AgentSamErrorRemediation;
+  resource: AgentSamErrorResource | null;
+  native: AgentSamNativeErrorEvidence | null;
+  environment: AgentSamEnvironmentEvidence | null;
+  http_status: number | null;
+  grpc_status: number | null;
+  provider: string | null;
+  provider_code: string | null;
+  request_id: string | null;
+  trace_id: string | null;
+  fingerprint: string;
+  occurrence_count: number;
+  details: unknown;
+  operation?: AgentSamErrorOperation;
+  retry?: AgentSamErrorRetry;
+  fallback?: AgentSamErrorFallback;
+  notify?: AgentSamErrorNotification;
+  cause?: unknown;
+  status?: AgentSamErrorOutcomeStatus;
+  partial?: AgentSamErrorPartialResult;
+}
+
+export const ERROR_CODE: Readonly<Record<string, AgentSamErrorCode>>;
+export const GRPC_STATUS: Readonly<Record<AgentSamErrorCode, number>>;
+export const DEFAULT_HTTP_STATUS: Readonly<Record<AgentSamErrorCode, number>>;
+export const ERROR_REASON: Readonly<Record<string, AgentSamErrorReason>>;
+export const ERROR_SEVERITY: Readonly<Record<string, AgentSamErrorSeverity>>;
+export const ERROR_SOURCE_KIND: Readonly<Record<string, AgentSamErrorSourceKind>>;
+export const ERROR_RESOLUTION_OWNER: Readonly<Record<string, AgentSamErrorResolutionOwner>>;
+export const ERROR_DOMAIN: Readonly<Record<string, AgentSamErrorDomain>>;
+export const ERROR_FAILURE_CLASS: Readonly<Record<string, AgentSamErrorFailureClass>>;
+export const ERROR_STAGE: Readonly<Record<string, AgentSamErrorStage>>;
+export const ERROR_FAILURE_BEHAVIOR: Readonly<Record<string, AgentSamErrorFailureBehavior>>;
+export const ERROR_SIDE_EFFECT_STATE: Readonly<Record<string, AgentSamErrorSideEffectState>>;
+export const REMEDIATION_ACTION: Readonly<Record<string, AgentSamRemediationAction>>;
+export const ERROR_REASON_POLICY: Readonly<Record<AgentSamErrorReason, { code: AgentSamErrorCode; domain: AgentSamErrorDomain; failure_class: AgentSamErrorFailureClass; severity: AgentSamErrorSeverity; retryable: boolean; resolution_owner: AgentSamErrorResolutionOwner; remediation_action: AgentSamRemediationAction; default_stage: AgentSamErrorStage }>>;
+export const ERROR_REASON_ALIASES: Readonly<Record<string, AgentSamErrorReason>>;
+
+export function createErrorEnvelope(input?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function isErrorEnvelope(value: unknown): value is AgentSamErrorEnvelope;
+export function assertErrorEnvelope(value: unknown): Readonly<AgentSamErrorEnvelope>;
+export function serializeError(value: unknown): string;
+export function parseError(value: string | unknown): Readonly<AgentSamErrorEnvelope>;
+export function canonicalCodeFromHttpStatus(status: number): AgentSamErrorCode;
+export function canonicalCodeFromGrpcStatus(status: number): AgentSamErrorCode;
+export function defaultHttpStatusForCode(code: AgentSamErrorCode): number;
+export function grpcStatusForCode(code: AgentSamErrorCode): number;
+export function canonicalizeErrorReason(value: unknown, context?: Record<string, unknown>): AgentSamErrorReason | null;
+export function normalizeError(error: unknown, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function fingerprintError(value?: Record<string, unknown>): string;
+export function redactString(value: unknown, maxChars?: number): string;
+export function redactErrorValue(value: unknown, options?: Record<string, unknown>): unknown;
+export function sanitizeNativeEvidence(value: unknown): AgentSamNativeErrorEvidence | null;
+export function shouldRetry(error: unknown): boolean;
+export function retryDelayMs(error: unknown, attempt?: number, options?: Record<string, unknown>): number;
+export function renderError(error: unknown): string;
+export function toHttpError(error: unknown): { status: number; headers: Readonly<Record<string, string>>; body: { error: AgentSamErrorEnvelope } };
+export function fromHttpError(input?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function createToolErrorEnvelope(input?: Record<string, unknown>, options?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function createToolError(input?: Record<string, unknown>, options?: Record<string, unknown>): AgentSamError;
+export function inferFailureClass(error?: Record<string, unknown>): string;
+export function inferSideEffectState(error?: Record<string, unknown>, operationContext?: Record<string, unknown>): string;
+export function planRecovery(error?: Record<string, unknown>, operationContext?: Record<string, unknown>): Record<string, unknown>;
+export const FAILURE_CLASS: Readonly<Record<string, string>>;
+export const SIDE_EFFECT_STATE: Readonly<Record<string, string>>;
+export const RECOVERY_SCHEMA: 'agentsam.recovery.v1';
+
+export class AgentSamError extends Error {
+  constructor(envelope: Record<string, unknown> | AgentSamErrorEnvelope, options?: { cause?: unknown });
+  readonly envelope: Readonly<AgentSamErrorEnvelope>;
+  readonly diagnostic: Readonly<AgentSamErrorEnvelope>;
+  readonly code: AgentSamErrorCode;
+  readonly reason: string;
+  readonly domain: AgentSamErrorDomain;
+  readonly failure_class: AgentSamErrorFailureClass;
+  readonly stage: AgentSamErrorStage;
+  readonly feature: string | null;
+  readonly failure_behavior: AgentSamErrorFailureBehavior | null;
+  readonly severity: AgentSamErrorSeverity;
+  readonly retryable: boolean;
+  readonly side_effect_state: AgentSamErrorSideEffectState;
+  readonly status: number | null;
+  readonly fingerprint: string;
+}
+export function asAgentSamError(value: unknown, options?: { cause?: unknown }): AgentSamError;
+
+export function classifyFailure(source: string, evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyProviderFailure(provider: string, evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function reasonFromGenericEvidence(evidence?: Record<string, unknown>): AgentSamErrorReason;
+export function classifyOpenAIFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyAnthropicFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyGoogleAIFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyGeminiFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyCursorFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyGitHubFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyCloudflareFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyDockerFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyGcpFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyProcessFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyDeviceFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyInternalFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyFreeCadFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyOpenScadFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyBlenderFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyMeshyFailure(evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyOAuthFailure(error: unknown, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;
+export function classifyCadFailure(tool: string, evidence?: Record<string, unknown>, context?: Record<string, unknown>): Readonly<AgentSamErrorEnvelope>;

package/packages/agentsam-goap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-goap",
-  "version": "2.6.8",
+  "version": "2.6.10",
   "description": "Portable AgentSam GOAP control-plane contracts and adapters over existing blackboard, ticket, workflow, execution, approval, queue, runtime, and evidence stores.",
   "type": "module",
   "main": "./src/index.js",
@@ -20,7 +20,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@inneranimalmedia/agentsam-errors": "2.6.8"
+    "@inneranimalmedia/agentsam-errors": "2.6.10"
   },
   "engines": {
     "node": ">=22 <25"

package/packages/agentsam-hooks/README.md

@@ -0,0 +1,206 @@
+# `@inneranimalmedia/agentsam-hooks`
+
+Portable lifecycle policy and observability for AgentSam runtimes.
+
+AgentSam Hooks is not tied to one model vendor, CLI, machine layout, or application account. The in-process JavaScript API and the JSON wire protocol share the same `agentsam.hook.v1` envelope. A hook can therefore be implemented in JavaScript/TypeScript, Python, Go, Rust, or any process or HTTP service that reads and writes JSON.
+
+## What ships
+
+- ordered callback runtime with explicit fail-open, fail-closed, and propagate-error behavior;
+- pre/post model and tool adapters without provider wire-format assumptions;
+- command and HTTP adapters for cross-language hooks;
+- portable `agentsam.hooks.json` / `.agentsam/hooks.json` config discovery;
+- bounded subprocess execution (timeout, output ceiling, no shell interpolation, minimal inherited environment);
+- hook receipts that record timing and field names without persisting raw prompts, credentials, tool arguments, or model results;
+- MCP, LSP, sub-agent, and composite capability adapters;
+- TypeScript declarations plus Python, Go, and Rust protocol bindings;
+- a small `agentsam-hooks` CLI for validation, inspection, and JSON invocation.
+
+The package does **not** make hook output authoritative over AgentSam authorization, capability discovery, manifests, or verification receipts. Hooks may narrow or request permission. The trusted host still resolves identity and grants.
+
+## JavaScript / TypeScript
+
+```js
+import {
+  AgentSamHooks,
+  createHookedCapabilityAdapter,
+  createHookedProviderAdapter,
+} from '@inneranimalmedia/agentsam-hooks';
+
+const hooks = new AgentSamHooks({
+  hooks: {
+    pre_tool_use: {
+      id: 'workspace-policy',
+      failure_mode: 'closed',
+      handler: async ({ input }) => {
+        if (input.tool_name === 'terminal.exec' && input.tool_args?.dangerous === true) {
+          return {
+            permission_decision: 'ask',
+            permission_decision_reason: 'This command requires an explicit host approval.',
+          };
+        }
+        return { permission_decision: 'allow' };
+      },
+    },
+    post_tool_use: async ({ input }) => ({
+      modified_result: redactForModel(input.tool_result),
+    }),
+  },
+});
+
+const capabilityAdapter = createHookedCapabilityAdapter(tools, {
+  hookRuntime: hooks,
+  requestPermission: showApprovalDialog,
+  invocation: { session_id: session.id, run_id: run.id },
+});
+const provider = createHookedProviderAdapter(modelProvider, {
+  hookRuntime: hooks,
+  invocation: { session_id: session.id, run_id: run.id },
+});
+```
+
+Handlers receive one canonical envelope:
+
+```json
+{
+  "schema": "agentsam.hook.v1",
+  "hook": "pre_tool_use",
+  "timestamp": 1790899200000,
+  "cwd": "/portable/project",
+  "invocation": { "session_id": "session-local", "run_id": "run-local" },
+  "input": {
+    "tool_name": "repository.snapshot",
+    "tool_args": { "include_untracked": false }
+  }
+}
+```
+
+Canonical wire fields use `snake_case`. JavaScript hook outputs also accept the common camel-case spellings, but command/HTTP integrations should emit the canonical form.
+
+## Cross-language command hook
+
+`.agentsam/hooks.json`:
+
+```json
+{
+  "schema": "agentsam.hooks.config.v1",
+  "adapters": {
+    "project-policy": {
+      "type": "command",
+      "command": "python3",
+      "args": ["hooks/project_policy.py"],
+      "timeout_ms": 3000
+    }
+  },
+  "hooks": {
+    "pre_tool_use": [
+      {
+        "id": "project-policy",
+        "adapter": "project-policy",
+        "failure_mode": "closed"
+      }
+    ]
+  }
+}
+```
+
+The executable reads one invocation envelope from stdin and writes one hook output JSON object to stdout. Diagnostic logs belong on stderr. The last non-empty stdout line is parsed as the response.
+
+```python
+import json, sys
+
+envelope = json.load(sys.stdin)
+tool = envelope["input"]["tool_name"]
+if tool == "terminal.exec":
+    print(json.dumps({
+        "permission_decision": "ask",
+        "permission_decision_reason": "Terminal access needs approval"
+    }))
+else:
+    print(json.dumps({"permission_decision": "allow"}))
+```
+
+The command adapter does not invoke a shell. Relative command and cwd paths are resolved from the config directory, command cwd cannot escape that directory by default, output is bounded, and only portable process variables are inherited unless `inherit_environment` is explicitly enabled. Secrets can be referenced as `env:VARIABLE_NAME` in configured headers/environment values; values are resolved at runtime and do not belong in config.
+
+## CLI
+
+```sh
+agentsam-hooks validate .agentsam/hooks.json
+agentsam-hooks list .agentsam/hooks.json
+printf '%s\n' '{"tool_name":"repository.snapshot","tool_args":{}}' \
+  | agentsam-hooks invoke pre_tool_use .agentsam/hooks.json
+```
+
+`invoke` is useful for conformance tests and host runtimes. It is not a permission bypass: the host must still enforce the returned decision.
+
+The full AgentSam CLI also exposes the merged code/config/stored view and its
+execution evidence:
+
+```sh
+agentsam hooks status
+agentsam hooks list
+agentsam hooks executions
+```
+
+## Portable storage pack
+
+`schema/manifest.json` describes the optional `agentsam.hooks` schema pack. Its
+SQLite/D1-compatible migration creates only `agentsam_hook` and
+`agentsam_hook_execution`. Portable ownership is an opaque `owner_id` plus an
+optional `scope_type`/`scope_ref`; it does not require tenant, workspace, user,
+workflow, or credential tables.
+
+```js
+import { createHookStore, createHookRuntime, registerStoredHooks } from '@inneranimalmedia/agentsam-hooks';
+
+const store = createHookStore(db, { ownerId: accountId });
+const runtime = createHookRuntime({ onReceipt: receipt => store.recordExecution(receipt) });
+await registerStoredHooks(runtime, store, {
+  cwd: projectRoot,
+  context: { project_root: projectRoot, session_id: sessionId },
+});
+```
+
+Receipts retain ids, timing, input/output **keys**, status, and redacted errors;
+they do not retain prompt, model response, tool argument, or tool result values.
+Handler secrets must remain host-owned references. Config `match` and stored
+`match_json` use the same portable partial-object matcher with exact values plus
+`$eq`, `$in`, `$exists`, and `$contains`; unmatched hooks are not invoked and do
+not emit execution receipts.
+
+## Composition semantics
+
+Hooks run by ascending `priority`, then ID. Modifications are passed into the next hook. Additional context is appended in order. Suppression is sticky. A `deny`, `ask`, or agent-stop `block` decision ends that hook chain.
+
+Failure modes:
+
+| Mode | Behavior |
+| --- | --- |
+| `open` | Record the failure and continue. Default for observational/post hooks. |
+| `closed` | Record the failure and return a deny decision. Default for pre-tool and pre-model hooks. |
+| `error` | Raise `HookExecutionError` to the host. |
+
+Tool/model wrappers support bounded retries only when an `error_occurred` hook explicitly returns `error_handling: "retry"`. The host cap defaults to three. Hooks cannot create an unbounded retry loop.
+
+## MCP, LSP, and sub-agents
+
+The capability adapters depend on narrow host ports rather than a particular transport package:
+
+- `createMcpCapabilityAdapter({ servers, listTools, callTool })`
+- `createLspCapabilityAdapter({ languages, request })`
+- `createAgentCapabilityAdapter({ agents, runAgent, hookRuntime })`
+- `createCompositeCapabilityAdapter([...adapters])`
+
+This lets an application use stdio MCP, remote MCP, an embedded language server, or a remote agent scheduler without changing the model loop. Discovery happens before capability schemas are presented to a model; authorization and execution remain host-owned.
+
+## Protocol and bindings
+
+JSON Schemas are owned once by the repository authority at `protocol/hooks/` and copied into the package artifact by its `prepack` gate. Bindings are included under `bindings/go` and `bindings/rust`; the Python package exposes `agentsam_sdk.hooks`. These bindings model the same envelope/output rather than introducing language-specific lifecycle semantics.
+
+## Security defaults
+
+- Do not place credential values in hook input, config, receipts, or logs.
+- Treat argument/result modification as trusted-code behavior.
+- Use `closed` for permission and policy hooks.
+- Keep post hooks fast; move analytics persistence behind a queue if needed.
+- Use explicit project config. This package does not silently load another user's home-directory plugins or machine-specific setup.

package/packages/agentsam-hooks/bin/agentsam-hooks.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { createHookRuntimeFromConfig, findHookConfig, loadHookConfig } from '../src/index.js';
+
+function usage() {
+  return `AgentSam Hooks\n\nUsage:\n  agentsam-hooks validate [config]\n  agentsam-hooks list [config]\n  agentsam-hooks invoke <hook> [config]\n\n'invoke' reads one JSON object from stdin and writes one JSON dispatch result.\nConfig discovery checks agentsam.hooks.json and .agentsam/hooks.json from cwd upward.\n`;
+}
+
+function resolveConfig(argument) {
+  const filename = argument || findHookConfig(process.cwd());
+  if (!filename) throw new Error('No AgentSam hook config found. Pass a config path or create .agentsam/hooks.json.');
+  return filename;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return {};
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const text = Buffer.concat(chunks).toString('utf8').trim();
+  return text ? JSON.parse(text) : {};
+}
+
+async function main(argv) {
+  const [command, ...args] = argv;
+  if (!command || ['help', '--help', '-h'].includes(command)) {
+    process.stdout.write(usage());
+    return;
+  }
+  if (command === 'validate') {
+    const filename = resolveConfig(args[0]);
+    const config = loadHookConfig(filename);
+    process.stdout.write(`${JSON.stringify({ ok: true, schema: config.schema, source: config.source, adapters: Object.keys(config.adapters).length, hooks: Object.values(config.hooks).reduce((sum, rows) => sum + rows.length, 0) }, null, 2)}\n`);
+    return;
+  }
+  if (command === 'list') {
+    const filename = resolveConfig(args[0]);
+    const { runtime, config } = createHookRuntimeFromConfig(filename);
+    process.stdout.write(`${JSON.stringify({ schema: config.schema, source: config.source, hooks: runtime.list() }, null, 2)}\n`);
+    return;
+  }
+  if (command === 'invoke') {
+    const hook = args[0];
+    if (!hook) throw new Error('invoke requires a hook event');
+    const filename = resolveConfig(args[1]);
+    fs.accessSync(filename, fs.constants.R_OK);
+    const { runtime } = createHookRuntimeFromConfig(filename);
+    const payload = await readStdin();
+    const isEnvelope = payload?.schema === 'agentsam.hook.v1';
+    const result = await runtime.dispatch(
+      hook,
+      isEnvelope ? payload.input || {} : payload,
+      isEnvelope ? payload.invocation || {} : {},
+      { cwd: isEnvelope ? payload.cwd : process.cwd() },
+    );
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  throw new Error(`Unknown command '${command}'.\n\n${usage()}`);
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`agentsam-hooks: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/packages/agentsam-hooks/bindings/go/command.go

@@ -0,0 +1,55 @@
+package agentsamhooks
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+type CommandOptions struct {
+	Command            string
+	Args               []string
+	CWD                string
+	Environment        map[string]string
+	InheritEnvironment bool
+	MaxOutputBytes     int
+}
+
+var portableEnvironmentKeys = []string{"PATH", "Path", "PATHEXT", "SYSTEMROOT", "WINDIR", "HOME", "USERPROFILE", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL"}
+
+func commandEnvironment(options CommandOptions) []string {
+	values := map[string]string{}
+	if options.InheritEnvironment {
+		for _, row := range os.Environ() { key, value, ok := strings.Cut(row, "="); if ok { values[key] = value } }
+	} else {
+		for _, key := range portableEnvironmentKeys { if value, ok := os.LookupEnv(key); ok { values[key] = value } }
+	}
+	for key, value := range options.Environment { values[key] = value }
+	output := make([]string, 0, len(values)); for key, value := range values { output = append(output, key+"="+value) }; return output
+}
+
+// CommandHandler starts one process per invocation. It never invokes a shell.
+// The process reads one envelope from stdin and writes one output JSON object.
+func CommandHandler(options CommandOptions) Handler {
+	return func(ctx context.Context, envelope Envelope) (*Output, error) {
+		if strings.TrimSpace(options.Command) == "" { return nil, fmt.Errorf("hook_command_required") }
+		limit := options.MaxOutputBytes; if limit <= 0 { limit = 1_048_576 }
+		payload, err := json.Marshal(envelope); if err != nil { return nil, err }
+		command := exec.CommandContext(ctx, options.Command, options.Args...)
+		command.Dir = options.CWD; if command.Dir == "" { command.Dir = envelope.CWD }
+		command.Env = commandEnvironment(options); command.Stdin = bytes.NewReader(append(payload, '\n'))
+		var stdout, stderr bytes.Buffer; command.Stdout = &stdout; command.Stderr = &stderr
+		if err := command.Run(); err != nil { return nil, fmt.Errorf("hook_command_failed:%s:%w:%s", options.Command, err, stderr.String()) }
+		if stdout.Len()+stderr.Len() > limit { return nil, fmt.Errorf("hook_command_output_limit_exceeded:%d", limit) }
+		lines := strings.Split(strings.TrimSpace(stdout.String()), "\n"); if len(lines) == 0 || strings.TrimSpace(lines[len(lines)-1]) == "" { return nil, nil }
+		output := &Output{}
+		decoder := json.NewDecoder(strings.NewReader(lines[len(lines)-1]))
+		decoder.DisallowUnknownFields()
+		if err := decoder.Decode(output); err != nil { return nil, fmt.Errorf("hook_command_invalid_json:%w", err) }
+		return output, nil
+	}
+}