@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/packages/agentsam-errors/src/redaction.js

@@ -0,0 +1,52 @@
+const DEFAULT_MAX_DETAIL_CHARS = 12_000;
+const SECRET_KEY = /(?:authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|password|secret|cookie|credential|private[-_]?key)/i;
+const SECRET_VALUE_PATTERNS = [
+  /\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi,
+  /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+  /\baak_[A-Za-z0-9_-]{8,}\b/g,
+  /\bsdk_[A-Za-z0-9_-]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+  /\bAIza[A-Za-z0-9_-]{20,}\b/g,
+];
+
+function bounded(value, maxChars) {
+  const text = String(value ?? '');
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+export function redactString(value, maxChars = DEFAULT_MAX_DETAIL_CHARS) {
+  let text = bounded(value, maxChars);
+  for (const pattern of SECRET_VALUE_PATTERNS) text = text.replace(pattern, '[REDACTED]');
+  return text;
+}
+
+export function redactErrorValue(value, options = {}, depth = 0, key = '') {
+  const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : DEFAULT_MAX_DETAIL_CHARS;
+  if (SECRET_KEY.test(key)) return '[REDACTED]';
+  if (depth > 6) return '[TRUNCATED_DEPTH]';
+  if (value == null || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'string') return redactString(value, maxChars);
+  if (Array.isArray(value)) return value.slice(0, 50).map(item => redactErrorValue(item, options, depth + 1));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [childKey, childValue] of Object.entries(value).slice(0, 80)) {
+      out[childKey] = redactErrorValue(childValue, options, depth + 1, childKey);
+    }
+    return out;
+  }
+  return redactString(String(value), maxChars);
+}
+
+export function sanitizeNativeEvidence(native) {
+  if (!native || typeof native !== 'object') return null;
+  return Object.freeze({
+    code: native.code == null ? null : redactString(native.code, 512),
+    exception_type: native.exception_type == null ? null : redactString(native.exception_type, 512),
+    exit_code: Number.isInteger(native.exit_code) ? native.exit_code : null,
+    signal: native.signal == null ? null : redactString(native.signal, 128),
+    stderr: native.stderr == null ? null : redactString(native.stderr, 12_000),
+    stdout: native.stdout == null ? null : redactString(native.stdout, 4_000),
+    stack: native.stack == null ? null : redactString(native.stack, 12_000),
+  });
+}

package/packages/agentsam-errors/src/render.js

@@ -0,0 +1,16 @@
+import { normalizeError } from './normalize.js';
+
+export function renderError(error) {
+  const d = normalizeError(error);
+  const context = [d.domain, d.tool, d.stage].filter(Boolean).join(' · ');
+  const lines = [`✗ ${d.message}`, `  ${d.code} · ${d.reason}`];
+  if (context) lines.push(`  ${context}`);
+  lines.push(`  severity: ${d.severity} · resolution: ${d.resolution_owner}`);
+  if (d.remediation?.message) lines.push(`  fix: ${d.remediation.message}`);
+  else if (d.remediation?.action && d.remediation.action !== 'none') lines.push(`  remediation: ${d.remediation.action}`);
+  lines.push(`  retry: ${d.retryable ? 'yes' : 'no'}${d.retry_after_ms != null ? ` · after ${d.retry_after_ms}ms` : ''}`);
+  if (d.request_id) lines.push(`  request_id: ${d.request_id}`);
+  if (d.trace_id) lines.push(`  trace_id: ${d.trace_id}`);
+  lines.push(`  fingerprint: ${d.fingerprint}`);
+  return lines.join('\n');
+}

package/packages/agentsam-errors/src/retry.js

@@ -0,0 +1,10 @@
+export function shouldRetry(error) { return Boolean(error?.retryable); }
+
+export function retryDelayMs(error, attempt = 1, options = {}) {
+  if (!shouldRetry(error)) return null;
+  if (Number.isFinite(error?.retry_after_ms) && error.retry_after_ms >= 0) return Math.round(error.retry_after_ms);
+  const baseMs = Number.isFinite(options.baseMs) && options.baseMs > 0 ? options.baseMs : 500;
+  const maxMs = Number.isFinite(options.maxMs) && options.maxMs > 0 ? options.maxMs : 30_000;
+  const n = Math.max(1, Number.isInteger(attempt) ? attempt : 1);
+  return Math.min(maxMs, Math.round(baseMs * (2 ** Math.min(10, n - 1))));
+}

package/packages/agentsam-errors/src/transport.js

@@ -0,0 +1,52 @@
+import { canonicalCodeFromHttpStatus, createErrorEnvelope, isErrorEnvelope, parseError } from './envelope.js';
+import { ERROR_REASON } from './vocabulary.js';
+
+function header(headers, name) {
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return String(headers.get(name) || '');
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) if (String(key).toLowerCase() === wanted) return String(value || '');
+  return '';
+}
+
+export function toHttpError(error) {
+  const envelope = isErrorEnvelope(error) ? error : error?.envelope;
+  if (!envelope) throw new TypeError('toHttpError requires an AgentSam ErrorEnvelope or AgentSamError');
+  return Object.freeze({
+    status: envelope.http_status || 500,
+    headers: Object.freeze({ 'content-type': 'application/json', 'cache-control': 'no-store' }),
+    body: Object.freeze({ error: envelope }),
+  });
+}
+
+export function fromHttpError({ status, body, headers, source, provider, domain = 'transport', stage = 'request' } = {}) {
+  const candidate = body?.error ?? body;
+  if (isErrorEnvelope(candidate)) return parseError(candidate);
+  const code = canonicalCodeFromHttpStatus(status);
+  return createErrorEnvelope({
+    code,
+    reason: code === 'UNAUTHENTICATED' ? ERROR_REASON.AUTH_INVALID
+      : code === 'PERMISSION_DENIED' ? ERROR_REASON.PERMISSION_DENIED
+        : code === 'RESOURCE_EXHAUSTED' ? ERROR_REASON.RATE_LIMITED
+          : code === 'UNAVAILABLE' ? ERROR_REASON.TRANSPORT_UNREACHABLE
+            : code === 'DEADLINE_EXCEEDED' ? ERROR_REASON.TRANSPORT_TIMEOUT
+              : ERROR_REASON.UNKNOWN,
+    message: candidate?.message || candidate?.error || `HTTP ${status || 500} request failed`,
+    retryable: Number(status) === 429 || Number(status) >= 500,
+    retry_after_ms: (() => {
+      const value = header(headers, 'retry-after');
+      if (!value) return null;
+      if (/^\d+(?:\.\d+)?$/.test(value)) return Math.max(0, Math.round(Number(value) * 1000));
+      const when = Date.parse(value);
+      return Number.isFinite(when) ? Math.max(0, when - Date.now()) : null;
+    })(),
+    http_status: Number(status) || null,
+    source: source || { kind: provider ? 'provider' : 'runtime', name: provider || 'http' },
+    provider: provider || null,
+    provider_code: candidate?.code || null,
+    request_id: header(headers, 'x-request-id') || header(headers, 'request-id') || null,
+    domain,
+    stage,
+    details: candidate,
+  });
+}

package/packages/agentsam-errors/src/vocabulary.js

@@ -0,0 +1,320 @@
+// GENERATED by scripts/generate-error-contracts.mjs. Do not edit by hand.
+export const ERROR_SCHEMA_VERSION = 1;
+
+export const ERROR_CODE = Object.freeze({
+  OK: "OK",
+  CANCELLED: "CANCELLED",
+  UNKNOWN: "UNKNOWN",
+  INVALID_ARGUMENT: "INVALID_ARGUMENT",
+  DEADLINE_EXCEEDED: "DEADLINE_EXCEEDED",
+  NOT_FOUND: "NOT_FOUND",
+  ALREADY_EXISTS: "ALREADY_EXISTS",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  RESOURCE_EXHAUSTED: "RESOURCE_EXHAUSTED",
+  FAILED_PRECONDITION: "FAILED_PRECONDITION",
+  ABORTED: "ABORTED",
+  OUT_OF_RANGE: "OUT_OF_RANGE",
+  UNIMPLEMENTED: "UNIMPLEMENTED",
+  INTERNAL: "INTERNAL",
+  UNAVAILABLE: "UNAVAILABLE",
+  DATA_LOSS: "DATA_LOSS",
+  UNAUTHENTICATED: "UNAUTHENTICATED",
+});
+
+export const GRPC_STATUS = Object.freeze({
+  OK: 0,
+  CANCELLED: 1,
+  UNKNOWN: 2,
+  INVALID_ARGUMENT: 3,
+  DEADLINE_EXCEEDED: 4,
+  NOT_FOUND: 5,
+  ALREADY_EXISTS: 6,
+  PERMISSION_DENIED: 7,
+  RESOURCE_EXHAUSTED: 8,
+  FAILED_PRECONDITION: 9,
+  ABORTED: 10,
+  OUT_OF_RANGE: 11,
+  UNIMPLEMENTED: 12,
+  INTERNAL: 13,
+  UNAVAILABLE: 14,
+  DATA_LOSS: 15,
+  UNAUTHENTICATED: 16,
+});
+
+export const DEFAULT_HTTP_STATUS = Object.freeze({
+  OK: 200,
+  CANCELLED: 499,
+  UNKNOWN: 500,
+  INVALID_ARGUMENT: 400,
+  DEADLINE_EXCEEDED: 504,
+  NOT_FOUND: 404,
+  ALREADY_EXISTS: 409,
+  PERMISSION_DENIED: 403,
+  RESOURCE_EXHAUSTED: 429,
+  FAILED_PRECONDITION: 412,
+  ABORTED: 409,
+  OUT_OF_RANGE: 400,
+  UNIMPLEMENTED: 501,
+  INTERNAL: 500,
+  UNAVAILABLE: 503,
+  DATA_LOSS: 500,
+  UNAUTHENTICATED: 401,
+});
+
+export const ERROR_REASON = Object.freeze({
+  UNKNOWN: "unknown",
+  INPUT_INVALID: "input_invalid",
+  INPUT_OUT_OF_RANGE: "input_out_of_range",
+  PRECONDITION_FAILED: "precondition_failed",
+  UNSUPPORTED_OPERATION: "unsupported_operation",
+  AUTH_MISSING: "auth_missing",
+  AUTH_INVALID: "auth_invalid",
+  PERMISSION_DENIED: "permission_denied",
+  USER_PERMISSION_DENIED: "user_permission_denied",
+  PROVIDER_NOT_CONNECTED: "provider_not_connected",
+  PROVIDER_CREDENTIAL_MISSING: "provider_credential_missing",
+  PROVIDER_CREDENTIAL_INVALID: "provider_credential_invalid",
+  PROVIDER_CREDENTIAL_EXPIRED: "provider_credential_expired",
+  PROVIDER_SCOPE_INSUFFICIENT: "provider_scope_insufficient",
+  PROVIDER_BUDGET_EXHAUSTED: "provider_budget_exhausted",
+  PROVIDER_QUOTA_EXHAUSTED: "provider_quota_exhausted",
+  PROVIDER_RATE_LIMITED: "provider_rate_limited",
+  PROVIDER_CAPACITY_EXHAUSTED: "provider_capacity_exhausted",
+  PROVIDER_UNAVAILABLE: "provider_unavailable",
+  PROVIDER_OVERLOADED: "provider_overloaded",
+  PROVIDER_REQUEST_INVALID: "provider_request_invalid",
+  PROVIDER_MODEL_NOT_FOUND: "provider_model_not_found",
+  PROVIDER_REGION_UNSUPPORTED: "provider_region_unsupported",
+  PROVIDER_CONTENT_BLOCKED: "provider_content_blocked",
+  CONTEXT_WINDOW_EXCEEDED: "context_window_exceeded",
+  SERVICE_TIER_UNSUPPORTED: "service_tier_unsupported",
+  CONTINUATION_INVALID: "continuation_invalid",
+  TARGET_NOT_FOUND: "target_not_found",
+  ALREADY_EXISTS: "already_exists",
+  CONFLICT: "conflict",
+  STALE_VERSION: "stale_version",
+  RATE_LIMITED: "rate_limited",
+  QUOTA_EXHAUSTED: "quota_exhausted",
+  CAPACITY_EXHAUSTED: "capacity_exhausted",
+  TRANSPORT_UNREACHABLE: "transport_unreachable",
+  TRANSPORT_REFUSED: "transport_refused",
+  TRANSPORT_TIMEOUT: "transport_timeout",
+  UPSTREAM_INVALID_RESPONSE: "upstream_invalid_response",
+  DNS_UNRESOLVED: "dns_unresolved",
+  TLS_HANDSHAKE_FAILED: "tls_handshake_failed",
+  TLS_CERTIFICATE_INVALID: "tls_certificate_invalid",
+  TUNNEL_CONNECTOR_UNAVAILABLE: "tunnel_connector_unavailable",
+  CANCELLED: "cancelled",
+  DEADLINE_EXCEEDED: "deadline_exceeded",
+  EXECUTION_TIMEOUT: "execution_timeout",
+  EXECUTION_FAILED: "execution_failed",
+  PROCESS_SPAWN_FAILED: "process_spawn_failed",
+  PROCESS_CRASHED: "process_crashed",
+  PROCESS_OUTPUT_LIMIT: "process_output_limit",
+  DEVICE_NOT_ENROLLED: "device_not_enrolled",
+  DEVICE_CREDENTIAL_MISSING: "device_credential_missing",
+  DEVICE_CREDENTIAL_INVALID: "device_credential_invalid",
+  DEVICE_CREDENTIAL_EXPIRED: "device_credential_expired",
+  DEVICE_REGISTRATION_MISSING: "device_registration_missing",
+  DEVICE_REGISTRATION_STALE: "device_registration_stale",
+  CONNECTION_REVOKED: "connection_revoked",
+  CONNECTION_DISABLED: "connection_disabled",
+  IDENTITY_RESOLUTION_FAILED: "identity_resolution_failed",
+  IDENTITY_MISMATCH: "identity_mismatch",
+  REPOSITORY_SCOPE_VIOLATION: "repository_scope_violation",
+  REPOSITORY_CHANGED: "repository_changed",
+  INDEX_STALE: "index_stale",
+  INDEX_FAILED: "index_failed",
+  EMBEDDING_FAILED: "embedding_failed",
+  VECTOR_STORE_FAILED: "vector_store_failed",
+  GITHUB_INSTALLATION_MISSING: "github_installation_missing",
+  GITHUB_REPOSITORY_NOT_FOUND: "github_repository_not_found",
+  GITHUB_RATE_LIMITED: "github_rate_limited",
+  GITHUB_SECONDARY_RATE_LIMITED: "github_secondary_rate_limited",
+  GITHUB_SCOPE_INSUFFICIENT: "github_scope_insufficient",
+  CLOUDFLARE_WORKERS_CPU_EXHAUSTED: "cloudflare_workers_cpu_exhausted",
+  CLOUDFLARE_SERVICE_BINDING_UNAVAILABLE: "cloudflare_service_binding_unavailable",
+  CLOUDFLARE_DURABLE_OBJECT_UNAVAILABLE: "cloudflare_durable_object_unavailable",
+  CLOUDFLARE_D1_UNAVAILABLE: "cloudflare_d1_unavailable",
+  CLOUDFLARE_R2_UNAVAILABLE: "cloudflare_r2_unavailable",
+  DOCKER_DAEMON_UNAVAILABLE: "docker_daemon_unavailable",
+  DOCKER_IMAGE_NOT_FOUND: "docker_image_not_found",
+  DOCKER_BUILD_FAILED: "docker_build_failed",
+  DOCKER_CONTAINER_FAILED: "docker_container_failed",
+  DOCKER_REGISTRY_AUTH_FAILED: "docker_registry_auth_failed",
+  DOCKER_PULL_RATE_LIMITED: "docker_pull_rate_limited",
+  GCP_PROJECT_MISSING: "gcp_project_missing",
+  GCP_API_DISABLED: "gcp_api_disabled",
+  GCP_QUOTA_EXHAUSTED: "gcp_quota_exhausted",
+  GCP_VM_NOT_FOUND: "gcp_vm_not_found",
+  GCP_VM_UNAVAILABLE: "gcp_vm_unavailable",
+  CAD_TOOL_NOT_INSTALLED: "cad_tool_not_installed",
+  CAD_TOOL_NOT_EXECUTABLE: "cad_tool_not_executable",
+  CAD_TOOL_VERSION_INCOMPATIBLE: "cad_tool_version_incompatible",
+  CAD_COMPONENT_MISSING: "cad_component_missing",
+  CAD_DEPENDENCY_MISSING: "cad_dependency_missing",
+  CAD_DEPENDENCY_VERSION_INCOMPATIBLE: "cad_dependency_version_incompatible",
+  CAD_SOURCE_PARSE_FAILED: "cad_source_parse_failed",
+  CAD_INPUT_FORMAT_UNSUPPORTED: "cad_input_format_unsupported",
+  CAD_IMPORT_FAILED: "cad_import_failed",
+  CAD_MODEL_RECOMPUTE_FAILED: "cad_model_recompute_failed",
+  CAD_CONSTRAINT_UNSATISFIED: "cad_constraint_unsatisfied",
+  CAD_GEOMETRY_INVALID: "cad_geometry_invalid",
+  CAD_NULL_SHAPE: "cad_null_shape",
+  CAD_BOOLEAN_FAILED: "cad_boolean_failed",
+  CAD_KERNEL_FAILED: "cad_kernel_failed",
+  CAD_SCRIPT_FAILED: "cad_script_failed",
+  CAD_EXPORT_FORMAT_UNSUPPORTED: "cad_export_format_unsupported",
+  CAD_EXPORT_FAILED: "cad_export_failed",
+  CAD_OUTPUT_MISSING: "cad_output_missing",
+  CAD_OUTPUT_INVALID: "cad_output_invalid",
+  CAD_RENDER_ENGINE_UNAVAILABLE: "cad_render_engine_unavailable",
+  CAD_GPU_UNAVAILABLE: "cad_gpu_unavailable",
+  CAD_RENDER_FAILED: "cad_render_failed",
+  CAD_MEMORY_EXHAUSTED: "cad_memory_exhausted",
+  CAD_PROCESS_CRASHED: "cad_process_crashed",
+  CAD_WARNING_ESCALATED: "cad_warning_escalated",
+  POLICY_BLOCKED: "policy_blocked",
+  COPYRIGHT_BLOCKED: "copyright_blocked",
+  PERSISTENCE_FAILED: "persistence_failed",
+  DATA_CORRUPT: "data_corrupt",
+  DATA_LOSS: "data_loss",
+  INTERNAL: "internal",
+  INTERNAL_INVARIANT_VIOLATION: "internal_invariant_violation",
+  INTERNAL_CONFIGURATION_INVALID: "internal_configuration_invalid",
+  INTERNAL_CONTRACT_VIOLATION: "internal_contract_violation",
+  INTERNAL_ADAPTER_FAILED: "internal_adapter_failed",
+  INTERNAL_DEPENDENCY_FAILED: "internal_dependency_failed",
+});
+
+export const ERROR_SEVERITY = Object.freeze(Object.fromEntries(["transient", "blocking_user_fixable", "blocking_internal", "policy_blocking"].map(value => [value.toUpperCase(), value])));
+export const ERROR_SOURCE_KIND = Object.freeze(Object.fromEntries(["user", "agentsam", "provider", "dependency", "runtime", "policy"].map(value => [value.toUpperCase(), value])));
+export const ERROR_RESOLUTION_OWNER = Object.freeze(Object.fromEntries(["user", "agentsam", "provider", "organization_admin", "policy", "unknown"].map(value => [value.toUpperCase(), value])));
+export const ERROR_DOMAIN = Object.freeze(Object.fromEntries(["runtime", "provider", "auth", "device", "terminal", "transport", "repository", "indexing", "knowledge", "cad", "deployment", "persistence", "policy", "tool"].map(value => [value.toUpperCase(), value])));
+export const REMEDIATION_ACTION = Object.freeze(Object.fromEntries(["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"].map(value => [value.toUpperCase(), value])));
+
+export const ERROR_REASON_POLICY = Object.freeze({
+  "unknown": Object.freeze({"code":"UNKNOWN","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "input_invalid": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "input_out_of_range": Object.freeze({"code":"OUT_OF_RANGE","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "precondition_failed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "unsupported_operation": Object.freeze({"code":"UNIMPLEMENTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "auth_missing": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reauthenticate"}),
+  "auth_invalid": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reauthenticate"}),
+  "permission_denied": Object.freeze({"code":"PERMISSION_DENIED","severity":"policy_blocking","retryable":false,"resolution_owner":"policy","remediation_action":"request_permission"}),
+  "user_permission_denied": Object.freeze({"code":"PERMISSION_DENIED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"request_permission"}),
+  "provider_not_connected": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"connect_provider"}),
+  "provider_credential_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"configure_provider_credential"}),
+  "provider_credential_invalid": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"refresh_provider_credential"}),
+  "provider_credential_expired": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"refresh_provider_credential"}),
+  "provider_scope_insufficient": Object.freeze({"code":"PERMISSION_DENIED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"request_permission"}),
+  "provider_budget_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"add_budget"}),
+  "provider_quota_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"increase_quota"}),
+  "provider_rate_limited": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "provider_capacity_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "provider_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "provider_overloaded": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "provider_request_invalid": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "provider_model_not_found": Object.freeze({"code":"NOT_FOUND","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"select_model"}),
+  "provider_region_unsupported": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_region"}),
+  "provider_content_blocked": Object.freeze({"code":"PERMISSION_DENIED","severity":"policy_blocking","retryable":false,"resolution_owner":"policy","remediation_action":"none"}),
+  "context_window_exceeded": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reduce_scope"}),
+  "service_tier_unsupported": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "continuation_invalid": Object.freeze({"code":"FAILED_PRECONDITION","severity":"transient","retryable":true,"resolution_owner":"agentsam","remediation_action":"retry"}),
+  "target_not_found": Object.freeze({"code":"NOT_FOUND","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "already_exists": Object.freeze({"code":"ALREADY_EXISTS","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "conflict": Object.freeze({"code":"ABORTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "stale_version": Object.freeze({"code":"ABORTED","severity":"transient","retryable":true,"resolution_owner":"user","remediation_action":"retry"}),
+  "rate_limited": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "quota_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"increase_quota"}),
+  "capacity_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "transport_unreachable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "transport_refused": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "transport_timeout": Object.freeze({"code":"DEADLINE_EXCEEDED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "upstream_invalid_response": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "dns_unresolved": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "tls_handshake_failed": Object.freeze({"code":"UNAVAILABLE","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "tls_certificate_invalid": Object.freeze({"code":"UNAVAILABLE","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "tunnel_connector_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"user","remediation_action":"reconnect_service"}),
+  "cancelled": Object.freeze({"code":"CANCELLED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"none"}),
+  "deadline_exceeded": Object.freeze({"code":"DEADLINE_EXCEEDED","severity":"transient","retryable":true,"resolution_owner":"unknown","remediation_action":"retry_later"}),
+  "execution_timeout": Object.freeze({"code":"DEADLINE_EXCEEDED","severity":"transient","retryable":true,"resolution_owner":"unknown","remediation_action":"retry_later"}),
+  "execution_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "process_spawn_failed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"install_dependency"}),
+  "process_crashed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "process_output_limit": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reduce_scope"}),
+  "device_not_enrolled": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "device_credential_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "device_credential_invalid": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "device_credential_expired": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "device_registration_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "device_registration_stale": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "connection_revoked": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reenroll_device"}),
+  "connection_disabled": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reconnect_service"}),
+  "identity_resolution_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "identity_mismatch": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "repository_scope_violation": Object.freeze({"code":"PERMISSION_DENIED","severity":"policy_blocking","retryable":false,"resolution_owner":"policy","remediation_action":"none"}),
+  "repository_changed": Object.freeze({"code":"ABORTED","severity":"transient","retryable":true,"resolution_owner":"user","remediation_action":"retry"}),
+  "index_stale": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"retry"}),
+  "index_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "embedding_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "vector_store_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "github_installation_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"connect_provider"}),
+  "github_repository_not_found": Object.freeze({"code":"NOT_FOUND","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "github_rate_limited": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "github_secondary_rate_limited": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "github_scope_insufficient": Object.freeze({"code":"PERMISSION_DENIED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"request_permission"}),
+  "cloudflare_workers_cpu_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "cloudflare_service_binding_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "cloudflare_durable_object_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "cloudflare_d1_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "cloudflare_r2_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "docker_daemon_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"restart_runtime"}),
+  "docker_image_not_found": Object.freeze({"code":"NOT_FOUND","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "docker_build_failed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "docker_container_failed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "docker_registry_auth_failed": Object.freeze({"code":"UNAUTHENTICATED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"reauthenticate"}),
+  "docker_pull_rate_limited": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "gcp_project_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "gcp_api_disabled": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "gcp_quota_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"increase_quota"}),
+  "gcp_vm_not_found": Object.freeze({"code":"NOT_FOUND","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "gcp_vm_unavailable": Object.freeze({"code":"UNAVAILABLE","severity":"transient","retryable":true,"resolution_owner":"provider","remediation_action":"retry_later"}),
+  "cad_tool_not_installed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"install_dependency"}),
+  "cad_tool_not_executable": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"configure_dependency"}),
+  "cad_tool_version_incompatible": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"upgrade_dependency"}),
+  "cad_component_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"install_dependency"}),
+  "cad_dependency_missing": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"install_dependency"}),
+  "cad_dependency_version_incompatible": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"upgrade_dependency"}),
+  "cad_source_parse_failed": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_input_format_unsupported": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_import_failed": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_model_recompute_failed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_constraint_unsatisfied": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_geometry_invalid": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_null_shape": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_boolean_failed": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_kernel_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "cad_script_failed": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_export_format_unsupported": Object.freeze({"code":"INVALID_ARGUMENT","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "cad_export_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "cad_output_missing": Object.freeze({"code":"DATA_LOSS","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "cad_output_invalid": Object.freeze({"code":"DATA_LOSS","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "cad_render_engine_unavailable": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "cad_gpu_unavailable": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "cad_render_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "cad_memory_exhausted": Object.freeze({"code":"RESOURCE_EXHAUSTED","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_configuration"}),
+  "cad_process_crashed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"unknown","remediation_action":"inspect_platform"}),
+  "cad_warning_escalated": Object.freeze({"code":"FAILED_PRECONDITION","severity":"blocking_user_fixable","retryable":false,"resolution_owner":"user","remediation_action":"change_input"}),
+  "policy_blocked": Object.freeze({"code":"PERMISSION_DENIED","severity":"policy_blocking","retryable":false,"resolution_owner":"policy","remediation_action":"none"}),
+  "copyright_blocked": Object.freeze({"code":"PERMISSION_DENIED","severity":"policy_blocking","retryable":false,"resolution_owner":"policy","remediation_action":"none"}),
+  "persistence_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "data_corrupt": Object.freeze({"code":"DATA_LOSS","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "data_loss": Object.freeze({"code":"DATA_LOSS","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "internal": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "internal_invariant_violation": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "internal_configuration_invalid": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "internal_contract_violation": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "internal_adapter_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+  "internal_dependency_failed": Object.freeze({"code":"INTERNAL","severity":"blocking_internal","retryable":false,"resolution_owner":"agentsam","remediation_action":"inspect_platform"}),
+});

package/packages/agentsam-errors/test/envelope.test.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  AgentSamError,
+  ERROR_CODE,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+  parseError,
+  serializeError,
+} from '../src/index.js';
+
+test('reason policy supplies canonical code severity owner and remediation', () => {
+  const error = createErrorEnvelope({
+    reason: ERROR_REASON.PROVIDER_CREDENTIAL_MISSING,
+    message: 'OpenAI is not configured.',
+    source: { kind: 'user', name: 'project_configuration', service: 'openai' },
+    domain: 'provider',
+    provider: 'openai',
+  });
+  assert.equal(error.code, ERROR_CODE.FAILED_PRECONDITION);
+  assert.equal(error.severity, 'blocking_user_fixable');
+  assert.equal(error.resolution_owner, 'user');
+  assert.equal(error.remediation.action, 'configure_provider_credential');
+  assert.equal(error.retryable, false);
+});
+
+test('known reasons cannot drift to a contradictory canonical code', () => {
+  assert.throws(() => createErrorEnvelope({
+    reason: ERROR_REASON.PROVIDER_CREDENTIAL_MISSING,
+    code: ERROR_CODE.INTERNAL,
+    message: 'wrong',
+  }), /requires canonical code/);
+});
+
+test('blocking internal failures cannot prescribe user infrastructure edits', () => {
+  assert.throws(() => createErrorEnvelope({
+    reason: ERROR_REASON.INTERNAL,
+    message: 'bad internal state',
+    remediation: { action: 'change_configuration' },
+  }), /cannot prescribe user remediation/);
+});
+
+test('canonical envelopes round-trip without semantic loss', () => {
+  const source = createErrorEnvelope({
+    reason: ERROR_REASON.IDENTITY_RESOLUTION_FAILED,
+    message: 'Control plane identity lookup failed.',
+    source: { kind: 'agentsam', name: 'inneranimalmedia', service: 'terminal_control_plane' },
+    domain: 'device',
+    trace_id: 'trace_1',
+  });
+  const roundTrip = parseError(serializeError(source));
+  assert.deepEqual(roundTrip, source);
+});
+
+test('AgentSamError is a throwable view over the immutable envelope', () => {
+  const error = new AgentSamError({ reason: ERROR_REASON.INTERNAL_ADAPTER_FAILED, message: 'adapter failed' });
+  assert.equal(error.code, 'INTERNAL');
+  assert.equal(error.reason, 'internal_adapter_failed');
+  assert.equal(error.envelope.fingerprint, error.fingerprint);
+  assert.equal(Object.isFrozen(error.envelope), true);
+});
+
+test('unknown native Errors normalize to an AgentSam-owned internal failure', () => {
+  const error = normalizeError(Object.assign(new Error('boom'), { code: 'EBOOM' }));
+  assert.equal(error.reason, 'internal');
+  assert.equal(error.source.kind, 'agentsam');
+  assert.equal(error.resolution_owner, 'agentsam');
+  assert.equal(error.native.code, 'EBOOM');
+});