@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/packages/agentsam-contracts/src/execution.ts

@@ -0,0 +1,50 @@
+import type { AgentSamErrorEnvelope } from './errors';
+
+export type AgentExecutionStatus =
+  | 'queued'
+  | 'running'
+  | 'retrying'
+  | 'awaiting_input'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'timed_out';
+
+export interface AgentToolInvocation<TInput = unknown> {
+  id: string;
+  toolKey: string;
+  input: TInput;
+  requestedAt: number;
+  accountId?: string;
+  correlationId?: string;
+  causationId?: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentToolExecutionResult<TOutput = unknown> {
+  output?: TOutput;
+  providerRequestId?: string;
+  usage?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentToolExecutionReceipt<TOutput = unknown> {
+  invocationId: string;
+  toolKey: string;
+  status: AgentExecutionStatus;
+  ok: boolean;
+  attempt: number;
+  queuedAt?: number;
+  startedAt?: number;
+  completedAt?: number;
+  durationMs?: number;
+  provider?: string;
+  input?: unknown;
+  output?: TOutput;
+  error?: AgentSamErrorEnvelope;
+  emittedEventIds?: string[];
+  providerRequestId?: string;
+  usage?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/src/hooks.ts

@@ -0,0 +1,40 @@
+export type AgentHookActionType = 'tool' | 'workflow' | 'event';
+
+export interface AgentHookAction {
+  actionId?: string;
+  type: AgentHookActionType;
+  target: string;
+  input?: unknown;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentHookDefinition {
+  hookKey: string;
+  displayName?: string;
+  description?: string;
+  eventKeys: string[];
+  enabled: boolean;
+  filter?: Record<string, unknown>;
+  actions: AgentHookAction[];
+  metadata?: Record<string, unknown>;
+}
+
+export type AgentHookExecutionStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export interface AgentHookExecutionReceipt {
+  executionId: string;
+  hookKey: string;
+  eventId: string;
+  status: AgentHookExecutionStatus;
+  startedAt?: number;
+  completedAt?: number;
+  durationMs?: number;
+  actionExecutionIds?: string[];
+  error?: unknown;
+  metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/src/identity.ts

@@ -0,0 +1,16 @@
+/**
+ * Identity is established outside the workbench. These contracts only carry the
+ * authenticated principal into product authorization and runtime adapters.
+ */
+export interface AgentPrincipal {
+  accountId: string;
+  authUserId: string;
+  displayName?: string;
+  email?: string;
+  claims?: Record<string, unknown>;
+}
+
+export interface AgentIdentityProvider {
+  getPrincipal(): AgentPrincipal | null | Promise<AgentPrincipal | null>;
+  subscribe?(onChange: (principal: AgentPrincipal | null) => void): () => void;
+}

package/packages/agentsam-contracts/src/index.ts

@@ -0,0 +1,14 @@
+export * from './agent';
+export * from './events';
+export * from './tools';
+export * from './authority';
+export * from './execution';
+export * from './providers';
+export * from './hooks';
+export * from './artifacts';
+export * from './context';
+export * from './adapter';
+export * from './models';
+export * from './identity';
+export * from './repository';
+export * from './errors';

package/packages/agentsam-contracts/src/models.ts

@@ -0,0 +1,9 @@
+export interface ModelOption {
+  id: string;
+  label: string;
+  short?: string;
+  description?: string;
+  provider?: string;
+  disabled?: boolean;
+  metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/src/providers.ts

@@ -0,0 +1,33 @@
+import type { AgentAuthorityRequirement, AgentResolvedAuthorityReference } from './authority';
+import type { AgentToolExecutionResult, AgentToolInvocation } from './execution';
+import type { AgentToolDefinition } from './tools';
+
+export interface AgentProviderDefinition {
+  providerKey: string;
+  displayName: string;
+  description?: string;
+  capabilityKeys?: string[];
+  toolKeys?: string[];
+  authority?: AgentAuthorityRequirement[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentProviderExecutionContext {
+  authority?: AgentResolvedAuthorityReference[];
+  accountId?: string;
+  deadlineAt?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Provider adapters implement provider-specific mechanics only.
+ * Generic retries, receipts, hooks, queueing and event dispatch remain execution-plane concerns.
+ */
+export interface AgentProviderAdapter<TContext extends AgentProviderExecutionContext = AgentProviderExecutionContext> {
+  readonly providerKey: string;
+  listTools?(): AgentToolDefinition[] | Promise<AgentToolDefinition[]>;
+  invoke<TInput = unknown, TOutput = unknown>(
+    invocation: AgentToolInvocation<TInput>,
+    context: TContext,
+  ): Promise<AgentToolExecutionResult<TOutput>>;
+}

package/packages/agentsam-contracts/src/repository.ts

@@ -0,0 +1,64 @@
+export const REPOSITORY_STATUSES = ['active', 'archived', 'disabled'] as const;
+export type RepositoryStatus = (typeof REPOSITORY_STATUSES)[number];
+
+export const REPOSITORY_CONTRACT_TYPES = ['api', 'schema', 'runtime', 'cli', 'event', 'receipt', 'package'] as const;
+export type RepositoryContractType = (typeof REPOSITORY_CONTRACT_TYPES)[number];
+
+export const REPOSITORY_CONTRACT_STATUSES = ['active', 'deprecated', 'retired'] as const;
+export type RepositoryContractStatus = (typeof REPOSITORY_CONTRACT_STATUSES)[number];
+
+export const REPOSITORY_DEPENDENCY_TYPES = ['runtime', 'build', 'contract', 'package', 'deploy', 'tool', 'data'] as const;
+export type RepositoryDependencyType = (typeof REPOSITORY_DEPENDENCY_TYPES)[number];
+
+export const REPOSITORY_DEPENDENCY_CRITICALITIES = ['informational', 'compatible', 'strict', 'critical'] as const;
+export type RepositoryDependencyCriticality = (typeof REPOSITORY_DEPENDENCY_CRITICALITIES)[number];
+
+export const REPOSITORY_FAILURE_POLICIES = ['warn', 'block_certification', 'block_deploy', 'degrade'] as const;
+export type RepositoryFailurePolicy = (typeof REPOSITORY_FAILURE_POLICIES)[number];
+
+/** Portable repository identity. Account ownership belongs to the host registry, not this object. */
+export interface RepositoryIdentity {
+  schema_version: 1;
+  repository_id: string;
+  full_name: string;
+  role: string;
+  default_branch: string;
+  canonical_url: string | null;
+  status: RepositoryStatus;
+}
+
+/** Account-bound declaration of one contract provided by a repository. */
+export interface RepositoryContract {
+  schema_version: 1;
+  id: string;
+  account_id: string;
+  repository_id: string;
+  contract_key: string;
+  contract_version: string;
+  contract_type: RepositoryContractType;
+  name: string;
+  description: string | null;
+  manifest_path: string | null;
+  contract_hash: string;
+  status: RepositoryContractStatus;
+  created_at: number | null;
+  updated_at: number | null;
+}
+
+/** Account-bound cross-repository dependency edge. */
+export interface RepositoryDependency {
+  schema_version: 1;
+  id: string;
+  account_id: string;
+  source_repository_id: string;
+  target_repository_id: string;
+  dependency_type: RepositoryDependencyType;
+  contract_id: string | null;
+  criticality: RepositoryDependencyCriticality;
+  required_version: string | null;
+  required_contract_hash: string | null;
+  failure_policy: RepositoryFailurePolicy;
+  description: string | null;
+  created_at: number | null;
+  updated_at: number | null;
+}

package/packages/agentsam-contracts/src/tools.ts

@@ -0,0 +1,98 @@
+import type { AgentAuthorityRequirement } from './authority';
+
+export interface AgentCapability {
+  id: string;
+  label?: string;
+  description?: string;
+  enabled?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export type AgentJsonSchema = Record<string, unknown>;
+
+export type AgentToolSideEffectLevel =
+  | 'none'
+  | 'local_write'
+  | 'external_write'
+  | 'billable_external_write'
+  | 'destructive_possible';
+
+export type AgentToolRiskLevel = 'low' | 'moderate' | 'high' | 'critical';
+
+export type AgentToolReceiptMode = 'full' | 'redacted' | 'metadata_only';
+
+export type AgentToolIdempotencyMode =
+  | 'not_applicable'
+  | 'intrinsic'
+  | 'supported'
+  | 'required';
+
+export type AgentToolHandlerType =
+  | 'local'
+  | 'http'
+  | 'worker_rpc'
+  | 'execos'
+  | 'mcp'
+  | 'custom';
+
+export interface AgentToolHandlerReference {
+  type: AgentToolHandlerType;
+  ref: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentToolRetryPolicy {
+  maxAttempts: number;
+  backoff?: 'none' | 'fixed' | 'exponential';
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  retryableReasons?: string[];
+}
+
+export interface AgentToolDefinition {
+  toolKey: string;
+  displayName: string;
+  description?: string;
+  provider?: string;
+  pluginId?: string;
+  capabilityKey: string;
+  handler?: AgentToolHandlerReference;
+  inputSchema: AgentJsonSchema;
+  outputSchema: AgentJsonSchema;
+  authority?: AgentAuthorityRequirement[];
+  riskLevel: AgentToolRiskLevel;
+  sideEffectLevel: AgentToolSideEffectLevel;
+  idempotencyMode: AgentToolIdempotencyMode;
+  timeoutMs?: number;
+  retryPolicy?: AgentToolRetryPolicy;
+  receiptMode?: AgentToolReceiptMode;
+  sensitiveInputPaths?: string[];
+  sensitiveOutputPaths?: string[];
+  emitsEvents?: string[];
+  active?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export type AgentToolCallStatus =
+  | 'queued'
+  | 'running'
+  | 'retrying'
+  | 'awaiting_input'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'timed_out';
+
+export interface AgentToolCall {
+  id: string;
+  runId?: string;
+  name: string;
+  toolKey?: string;
+  status: AgentToolCallStatus;
+  startedAt?: number;
+  completedAt?: number;
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/test/contracts.test.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFile } from 'node:fs/promises';
+
+test('contracts package stays framework neutral', async () => {
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  assert.equal(pkg.dependencies, undefined);
+  assert.equal(pkg.peerDependencies, undefined);
+});
+
+test('execution-plane contracts are exported as first-class package surfaces', async () => {
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  for (const key of ['./tools', './authority', './execution', './providers', './events', './hooks']) {
+    assert.equal(typeof pkg.exports[key], 'string', `missing contract export: ${key}`);
+  }
+});

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

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import test from 'node:test';
+
+const catalog = JSON.parse(fs.readFileSync(new URL('../../../protocol/errors/error-catalog.json', import.meta.url), 'utf8'));
+
+test('error catalog vocabulary is unique and every reason references valid policy values', () => {
+  const unique = values => assert.equal(new Set(values).size, values.length);
+  unique(catalog.codes.map(row => row.name));
+  unique(catalog.reasons.map(row => row.name));
+  unique(catalog.severities);
+  unique(catalog.source_kinds);
+  unique(catalog.resolution_owners);
+  unique(catalog.remediation_actions);
+  const codes = new Set(catalog.codes.map(row => row.name));
+  const severities = new Set(catalog.severities);
+  const owners = new Set(catalog.resolution_owners);
+  const actions = new Set(catalog.remediation_actions);
+  for (const reason of catalog.reasons) {
+    assert.ok(codes.has(reason.code), `unknown code for ${reason.name}`);
+    assert.ok(severities.has(reason.severity), `unknown severity for ${reason.name}`);
+    assert.ok(owners.has(reason.resolution_owner), `unknown resolution owner for ${reason.name}`);
+    assert.ok(actions.has(reason.remediation_action), `unknown remediation action for ${reason.name}`);
+  }
+});

package/packages/agentsam-contracts/test/repository.test.mjs

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import test from 'node:test';
+
+test('repository graph vocabulary is owned and exported by the contracts package', async () => {
+  const pkg = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  const source = await fs.readFile(new URL('../src/repository.ts', import.meta.url), 'utf8');
+
+  assert.equal(pkg.exports['./repository'], './src/repository.ts');
+  for (const value of [
+    'informational', 'compatible', 'strict', 'critical',
+    'warn', 'block_certification', 'block_deploy', 'degrade',
+  ]) assert.match(source, new RegExp(`['\"]${value}['\"]`));
+
+  assert.match(source, /account_id: string/);
+  assert.match(source, /repository_id: string/);
+  assert.doesNotMatch(source, /tenant_id|workspace_id|owner_user_id/);
+});

package/packages/agentsam-contracts/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/packages/agentsam-errors/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@inneranimalmedia/agentsam-errors",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Canonical AgentSam runtime error normalization, classification, transport, remediation and rendering.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22 <25"
+  }
+}

package/packages/agentsam-errors/src/adapters/anthropic.js

@@ -0,0 +1,15 @@
+import { classifyProviderFailure } from './provider.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyAnthropicFailure(evidence = {}, context = {}) {
+  const type = String(evidence.type || evidence.code || '').toLowerCase();
+  const message = String(evidence.message || '');
+  let reason = context.reason;
+  if (!reason && type === 'overloaded_error') reason = ERROR_REASON.PROVIDER_OVERLOADED;
+  else if (!reason && type === 'rate_limit_error') reason = ERROR_REASON.PROVIDER_RATE_LIMITED;
+  else if (!reason && type === 'authentication_error') reason = ERROR_REASON.PROVIDER_CREDENTIAL_INVALID;
+  else if (!reason && type === 'permission_error') reason = ERROR_REASON.PROVIDER_SCOPE_INSUFFICIENT;
+  else if (!reason && /request too large|context|token limit/i.test(message)) reason = ERROR_REASON.CONTEXT_WINDOW_EXCEEDED;
+  else if (!reason && type === 'invalid_request_error') reason = ERROR_REASON.PROVIDER_REQUEST_INVALID;
+  return classifyProviderFailure('anthropic', evidence, { ...context, reason });
+}

package/packages/agentsam-errors/src/adapters/cad.js

@@ -0,0 +1,109 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { classifyProviderFailure } from './provider.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+function text(evidence) {
+  return `${evidence.code || ''} ${evidence.exception_type || evidence.type || ''} ${evidence.message || ''} ${evidence.stderr || ''}`.toLowerCase();
+}
+
+function commonCadReason(tool, evidence = {}, context = {}) {
+  if (context.reason) return context.reason;
+  if (evidence.available === false || evidence.installed === false) return ERROR_REASON.CAD_TOOL_NOT_INSTALLED;
+  if (evidence.executable === false) return ERROR_REASON.CAD_TOOL_NOT_EXECUTABLE;
+  if (evidence.version_compatible === false) return ERROR_REASON.CAD_TOOL_VERSION_INCOMPATIBLE;
+  if (evidence.component_missing) return ERROR_REASON.CAD_COMPONENT_MISSING;
+  if (evidence.dependency_missing) return ERROR_REASON.CAD_DEPENDENCY_MISSING;
+  if (evidence.dependency_version_compatible === false) return ERROR_REASON.CAD_DEPENDENCY_VERSION_INCOMPATIBLE;
+  if (evidence.output_missing) return ERROR_REASON.CAD_OUTPUT_MISSING;
+  if (evidence.output_invalid) return ERROR_REASON.CAD_OUTPUT_INVALID;
+  if (evidence.warning_escalated) return ERROR_REASON.CAD_WARNING_ESCALATED;
+  if (evidence.timeout) return ERROR_REASON.EXECUTION_TIMEOUT;
+  const value = text(evidence);
+  if (/memoryerror|out of memory|memory exception|bad_alloc/.test(value)) return ERROR_REASON.CAD_MEMORY_EXHAUSTED;
+  if (/unsupported.*format|format.*unsupported/.test(value)) return context.stage === 'export' ? ERROR_REASON.CAD_EXPORT_FORMAT_UNSUPPORTED : ERROR_REASON.CAD_INPUT_FORMAT_UNSUPPORTED;
+  if (/gpu.*(?:unavailable|not found|unsupported)|no compatible gpu/.test(value)) return ERROR_REASON.CAD_GPU_UNAVAILABLE;
+  if (/render engine.*(?:unavailable|not found|unsupported)|unknown render engine/.test(value)) return ERROR_REASON.CAD_RENDER_ENGINE_UNAVAILABLE;
+  if (context.stage === 'render') return ERROR_REASON.CAD_RENDER_FAILED;
+  if (context.stage === 'export') return ERROR_REASON.CAD_EXPORT_FAILED;
+  if (context.stage === 'import') return ERROR_REASON.CAD_IMPORT_FAILED;
+  if (Number.isInteger(evidence.exit_code) && evidence.exit_code !== 0) return ERROR_REASON.CAD_PROCESS_CRASHED;
+  return ERROR_REASON.EXECUTION_FAILED;
+}
+
+function cadEnvelope(tool, evidence = {}, context = {}, reason = commonCadReason(tool, evidence, context)) {
+  return createErrorEnvelope({
+    reason,
+    message: context.message || evidence.message || `${tool} operation failed`,
+    source: context.source || { kind: 'dependency', name: tool, service: context.service || null },
+    resolution_owner: context.resolution_owner,
+    severity: context.severity,
+    remediation: context.remediation,
+    domain: 'cad',
+    tool,
+    stage: context.stage || 'execute',
+    retryable: context.retryable,
+    retry_after_ms: evidence.retry_after_ms,
+    resource: context.resource || null,
+    environment: context.environment || {
+      detected_version: evidence.detected_version || evidence.version || null,
+      required_version: evidence.required_version || null,
+      component: evidence.component || null,
+      runtime: evidence.runtime || null,
+      platform: evidence.platform || null,
+    },
+    native: {
+      code: evidence.code,
+      exception_type: evidence.exception_type || evidence.type,
+      exit_code: evidence.exit_code,
+      signal: evidence.signal,
+      stderr: evidence.stderr,
+      stdout: evidence.stdout,
+      stack: evidence.stack,
+    },
+    details: evidence.details || null,
+  });
+}
+
+export function classifyFreeCadFailure(evidence = {}, context = {}) {
+  const value = text(evidence);
+  let reason = context.reason;
+  if (!reason && /part::booleanexception/.test(value)) reason = ERROR_REASON.CAD_BOOLEAN_FAILED;
+  else if (!reason && /part::nullshapeexception/.test(value)) reason = ERROR_REASON.CAD_NULL_SHAPE;
+  else if (!reason && /base::cadkernelerror/.test(value)) reason = ERROR_REASON.CAD_KERNEL_FAILED;
+  else if (!reason && /base::memoryexception/.test(value)) reason = ERROR_REASON.CAD_MEMORY_EXHAUSTED;
+  else if (!reason && /parsererror|badformaterror/.test(value)) reason = ERROR_REASON.CAD_SOURCE_PARSE_FAILED;
+  else if (!reason && /abortexception/.test(value)) reason = ERROR_REASON.CANCELLED;
+  else if (!reason && context.stage === 'recompute') reason = ERROR_REASON.CAD_MODEL_RECOMPUTE_FAILED;
+  return cadEnvelope('freecad', evidence, context, reason || commonCadReason('freecad', evidence, context));
+}
+
+export function classifyOpenScadFailure(evidence = {}, context = {}) {
+  const value = text(evidence);
+  let reason = context.reason;
+  if (!reason && /parser error|syntax error|parse error/.test(value)) reason = ERROR_REASON.CAD_SOURCE_PARSE_FAILED;
+  else if (!reason && /no top level geometry to render|empty top level object/.test(value)) reason = ERROR_REASON.CAD_GEOMETRY_INVALID;
+  else if (!reason && /warning.*treated as error|hardwarnings/.test(value)) reason = ERROR_REASON.CAD_WARNING_ESCALATED;
+  return cadEnvelope('openscad', evidence, context, reason || commonCadReason('openscad', evidence, context));
+}
+
+export function classifyBlenderFailure(evidence = {}, context = {}) {
+  const value = text(evidence);
+  let reason = context.reason;
+  if (!reason && /python.*(?:exception|traceback)|valueerror|typeerror|runtimeerror/.test(value) && context.stage === 'script') reason = ERROR_REASON.CAD_SCRIPT_FAILED;
+  else if (!reason && /boolean/.test(value) && /fail|error/.test(value)) reason = ERROR_REASON.CAD_BOOLEAN_FAILED;
+  return cadEnvelope('blender', evidence, context, reason || commonCadReason('blender', evidence, context));
+}
+
+export function classifyMeshyFailure(evidence = {}, context = {}) {
+  return classifyProviderFailure('meshy', evidence, { ...context, domain: 'cad', tool: 'meshy' });
+}
+
+export function classifyCadFailure(tool, evidence = {}, context = {}) {
+  switch (String(tool || '').toLowerCase()) {
+    case 'freecad': return classifyFreeCadFailure(evidence, context);
+    case 'openscad': return classifyOpenScadFailure(evidence, context);
+    case 'blender': return classifyBlenderFailure(evidence, context);
+    case 'meshy': return classifyMeshyFailure(evidence, context);
+    default: return cadEnvelope(String(tool || 'cad').toLowerCase(), evidence, context);
+  }
+}

package/packages/agentsam-errors/src/adapters/cloudflare.js

@@ -0,0 +1,21 @@
+import { classifyProviderFailure } from './provider.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyCloudflareFailure(evidence = {}, context = {}) {
+  const status = Number(evidence.status || evidence.http_status || evidence.httpStatus || 0);
+  const cf = Number(evidence.cloudflare_code || evidence.cloudflareCode || evidence.provider_code || evidence.code || 0) || null;
+  const text = `${evidence.message || ''} ${evidence.error || ''}`.toLowerCase();
+  let reason = context.reason;
+  if (!reason && cf === 1033) reason = ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE;
+  else if (!reason && cf === 1102) reason = ERROR_REASON.CLOUDFLARE_WORKERS_CPU_EXHAUSTED;
+  else if (!reason && (status === 521)) reason = ERROR_REASON.TRANSPORT_REFUSED;
+  else if (!reason && (status === 522 || status === 523 || status === 530)) reason = ERROR_REASON.TRANSPORT_UNREACHABLE;
+  else if (!reason && status === 524) reason = ERROR_REASON.TRANSPORT_TIMEOUT;
+  else if (!reason && status === 525) reason = ERROR_REASON.TLS_HANDSHAKE_FAILED;
+  else if (!reason && status === 526) reason = ERROR_REASON.TLS_CERTIFICATE_INVALID;
+  else if (!reason && /service binding/.test(text)) reason = ERROR_REASON.CLOUDFLARE_SERVICE_BINDING_UNAVAILABLE;
+  else if (!reason && /durable object/.test(text)) reason = ERROR_REASON.CLOUDFLARE_DURABLE_OBJECT_UNAVAILABLE;
+  else if (!reason && /\bd1\b/.test(text)) reason = ERROR_REASON.CLOUDFLARE_D1_UNAVAILABLE;
+  else if (!reason && /\br2\b/.test(text)) reason = ERROR_REASON.CLOUDFLARE_R2_UNAVAILABLE;
+  return classifyProviderFailure('cloudflare', { ...evidence, status, code: cf ?? evidence.code }, { ...context, reason, domain: context.domain || 'transport' });
+}

package/packages/agentsam-errors/src/adapters/cursor.js

@@ -0,0 +1,4 @@
+import { classifyProviderFailure } from './provider.js';
+export function classifyCursorFailure(evidence = {}, context = {}) {
+  return classifyProviderFailure('cursor', evidence, context);
+}

package/packages/agentsam-errors/src/adapters/device.js

@@ -0,0 +1,38 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+const STATE_REASON = Object.freeze({
+  not_enrolled: ERROR_REASON.DEVICE_NOT_ENROLLED,
+  credential_missing: ERROR_REASON.DEVICE_CREDENTIAL_MISSING,
+  credential_invalid: ERROR_REASON.DEVICE_CREDENTIAL_INVALID,
+  credential_expired: ERROR_REASON.DEVICE_CREDENTIAL_EXPIRED,
+  registration_missing: ERROR_REASON.DEVICE_REGISTRATION_MISSING,
+  registration_stale: ERROR_REASON.DEVICE_REGISTRATION_STALE,
+  connection_revoked: ERROR_REASON.CONNECTION_REVOKED,
+  connection_disabled: ERROR_REASON.CONNECTION_DISABLED,
+  identity_resolution_failed: ERROR_REASON.IDENTITY_RESOLUTION_FAILED,
+  identity_mismatch: ERROR_REASON.IDENTITY_MISMATCH,
+});
+
+export function classifyDeviceFailure(evidence = {}, context = {}) {
+  const state = String(evidence.state || evidence.code || '').toLowerCase();
+  const reason = context.reason || STATE_REASON[state] || ERROR_REASON.UNKNOWN;
+  const internal = [ERROR_REASON.IDENTITY_RESOLUTION_FAILED, ERROR_REASON.IDENTITY_MISMATCH].includes(reason);
+  return createErrorEnvelope({
+    reason,
+    message: context.message || evidence.message || (internal ? 'AgentSam could not resolve the registered device identity.' : 'This device connection needs attention.'),
+    source: context.source || (internal ? { kind: 'agentsam', name: 'inneranimalmedia', service: 'terminal_control_plane' } : { kind: 'runtime', name: 'execos', service: 'device' }),
+    resolution_owner: internal ? 'agentsam' : context.resolution_owner,
+    severity: internal ? 'blocking_internal' : context.severity,
+    remediation: internal ? { action: 'inspect_platform', message: 'AgentSam must inspect the terminal control plane.' } : context.remediation,
+    domain: 'device',
+    tool: context.tool || 'execos',
+    stage: context.stage || 'authentication',
+    resource: context.resource || { type: 'terminal_device', id: evidence.instance_id || null },
+    provider_code: evidence.provider_code || null,
+    request_id: evidence.request_id || null,
+    trace_id: evidence.trace_id || null,
+    native: { code: evidence.code || state || null, exception_type: evidence.exception_type || null, stack: evidence.stack || null },
+    details: evidence.details || null,
+  });
+}

package/packages/agentsam-errors/src/adapters/docker.js

@@ -0,0 +1,28 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyDockerFailure(evidence = {}, context = {}) {
+  const text = `${evidence.code || ''} ${evidence.message || ''} ${evidence.stderr || ''}`.toLowerCase();
+  let reason = context.reason;
+  if (!reason && /cannot connect to the docker daemon|is the docker daemon running|docker daemon is not running/.test(text)) reason = ERROR_REASON.DOCKER_DAEMON_UNAVAILABLE;
+  else if (!reason && /toomanyrequests|pull rate limit/.test(text)) reason = ERROR_REASON.DOCKER_PULL_RATE_LIMITED;
+  else if (!reason && /unauthorized|authentication required|pull access denied|denied: requested access/.test(text)) reason = ERROR_REASON.DOCKER_REGISTRY_AUTH_FAILED;
+  else if (!reason && /no such image|manifest unknown|image.*not found/.test(text)) reason = ERROR_REASON.DOCKER_IMAGE_NOT_FOUND;
+  else if (!reason && (context.stage === 'build' || /build failed|failed to solve/.test(text))) reason = ERROR_REASON.DOCKER_BUILD_FAILED;
+  else if (!reason && (context.stage === 'run' || context.stage === 'container')) reason = ERROR_REASON.DOCKER_CONTAINER_FAILED;
+  else reason ||= ERROR_REASON.EXECUTION_FAILED;
+  return createErrorEnvelope({
+    reason,
+    message: context.message || evidence.message || evidence.stderr || 'Docker operation failed',
+    source: { kind: 'runtime', name: 'docker', service: context.service || null },
+    domain: context.domain || 'runtime',
+    tool: 'docker',
+    stage: context.stage || 'execute',
+    retry_after_ms: evidence.retry_after_ms,
+    provider: context.provider || (reason === ERROR_REASON.DOCKER_PULL_RATE_LIMITED ? 'docker_registry' : null),
+    native: { code: evidence.code, exit_code: evidence.exit_code, signal: evidence.signal, stderr: evidence.stderr, stdout: evidence.stdout, stack: evidence.stack },
+    environment: context.environment || null,
+    resource: context.resource || null,
+    details: evidence.details || null,
+  });
+}