@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

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

@@ -0,0 +1,14 @@
+import { classifyProviderFailure } from './provider.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyGcpFailure(evidence = {}, context = {}) {
+  const statusName = String(evidence.status_name || evidence.type || evidence.code || '').toUpperCase();
+  const text = `${evidence.message || ''} ${evidence.error || ''}`.toLowerCase();
+  let reason = context.reason;
+  if (!reason && (evidence.project_state === 'missing' || /project.*(?:missing|not set|not specified)/.test(text))) reason = ERROR_REASON.GCP_PROJECT_MISSING;
+  else if (!reason && /api.*(?:disabled|not enabled)|has not been used.*before/.test(text)) reason = ERROR_REASON.GCP_API_DISABLED;
+  else if (!reason && (statusName === 'RESOURCE_EXHAUSTED' || /quota/.test(text))) reason = ERROR_REASON.GCP_QUOTA_EXHAUSTED;
+  else if (!reason && (statusName === 'NOT_FOUND' || Number(evidence.status) === 404) && (context.resource?.type === 'vm' || /instance|vm/.test(text))) reason = ERROR_REASON.GCP_VM_NOT_FOUND;
+  else if (!reason && (statusName === 'UNAVAILABLE' || Number(evidence.status) === 503)) reason = ERROR_REASON.GCP_VM_UNAVAILABLE;
+  return classifyProviderFailure('gcp', evidence, { ...context, reason, domain: context.domain || 'runtime', tool: context.tool || 'gcp' });
+}

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

@@ -0,0 +1,22 @@
+import { classifyProviderFailure } from './provider.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 classifyGitHubFailure(evidence = {}, context = {}) {
+  const status = Number(evidence.status || 0);
+  const text = `${evidence.code || ''} ${evidence.message || ''}`.toLowerCase();
+  let reason = context.reason;
+  if (!reason && evidence.installation_state === 'missing') reason = ERROR_REASON.GITHUB_INSTALLATION_MISSING;
+  else if (!reason && status === 403 && (header(evidence.headers, 'x-ratelimit-remaining') === '0' || /rate limit exceeded/.test(text))) reason = ERROR_REASON.GITHUB_RATE_LIMITED;
+  else if (!reason && status === 403 && /secondary rate limit|abuse detection/.test(text)) reason = ERROR_REASON.GITHUB_SECONDARY_RATE_LIMITED;
+  else if (!reason && status === 403) reason = ERROR_REASON.GITHUB_SCOPE_INSUFFICIENT;
+  else if (!reason && status === 404 && (context.resource?.type === 'repository' || /repository/.test(text))) reason = ERROR_REASON.GITHUB_REPOSITORY_NOT_FOUND;
+  return classifyProviderFailure('github', evidence, { ...context, reason, domain: context.domain || 'repository' });
+}

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

@@ -0,0 +1,17 @@
+import { classifyProviderFailure } from './provider.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyGoogleAIFailure(evidence = {}, context = {}) {
+  const statusName = String(evidence.status_name || evidence.type || evidence.code || '').toUpperCase();
+  const message = String(evidence.message || '');
+  let reason = context.reason;
+  if (!reason && /API key not valid|invalid API key/i.test(message)) reason = ERROR_REASON.PROVIDER_CREDENTIAL_INVALID;
+  else if (!reason && statusName === 'UNAUTHENTICATED') reason = ERROR_REASON.PROVIDER_CREDENTIAL_INVALID;
+  else if (!reason && statusName === 'PERMISSION_DENIED') reason = ERROR_REASON.PROVIDER_SCOPE_INSUFFICIENT;
+  else if (!reason && statusName === 'RESOURCE_EXHAUSTED') reason = /billing|budget/i.test(message) ? ERROR_REASON.PROVIDER_BUDGET_EXHAUSTED : ERROR_REASON.PROVIDER_QUOTA_EXHAUSTED;
+  else if (!reason && statusName === 'UNAVAILABLE') reason = ERROR_REASON.PROVIDER_UNAVAILABLE;
+  else if (!reason && statusName === 'INVALID_ARGUMENT') reason = ERROR_REASON.PROVIDER_REQUEST_INVALID;
+  return classifyProviderFailure(context.provider || 'google_ai', evidence, { ...context, reason });
+}
+
+export const classifyGeminiFailure = (evidence = {}, context = {}) => classifyGoogleAIFailure(evidence, { ...context, provider: 'gemini' });

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

@@ -0,0 +1,55 @@
+export { classifyProviderFailure, reasonFromGenericEvidence } from './provider.js';
+export { classifyOpenAIFailure } from './openai.js';
+export { classifyAnthropicFailure } from './anthropic.js';
+export { classifyGoogleAIFailure, classifyGeminiFailure } from './google.js';
+export { classifyCursorFailure } from './cursor.js';
+export { classifyGitHubFailure } from './github.js';
+export { classifyCloudflareFailure } from './cloudflare.js';
+export { classifyDockerFailure } from './docker.js';
+export { classifyGcpFailure } from './gcp.js';
+export { classifyProcessFailure } from './process.js';
+export { classifyOAuthFailure } from './oauth.js';
+export { classifyCadFailure, classifyFreeCadFailure, classifyOpenScadFailure, classifyBlenderFailure, classifyMeshyFailure } from './cad.js';
+export { classifyDeviceFailure } from './device.js';
+export { classifyInternalFailure } from './internal.js';
+
+import { classifyOpenAIFailure } from './openai.js';
+import { classifyAnthropicFailure } from './anthropic.js';
+import { classifyGoogleAIFailure, classifyGeminiFailure } from './google.js';
+import { classifyCursorFailure } from './cursor.js';
+import { classifyGitHubFailure } from './github.js';
+import { classifyCloudflareFailure } from './cloudflare.js';
+import { classifyDockerFailure } from './docker.js';
+import { classifyGcpFailure } from './gcp.js';
+import { classifyCadFailure } from './cad.js';
+import { classifyDeviceFailure } from './device.js';
+import { classifyInternalFailure } from './internal.js';
+import { classifyProviderFailure } from './provider.js';
+
+export function classifyFailure(source, evidence = {}, context = {}) {
+  const key = String(source || '').toLowerCase();
+  switch (key) {
+    case 'openai': return classifyOpenAIFailure(evidence, context);
+    case 'anthropic': return classifyAnthropicFailure(evidence, context);
+    case 'google':
+    case 'google_ai': return classifyGoogleAIFailure(evidence, context);
+    case 'gemini': return classifyGeminiFailure(evidence, context);
+    case 'cursor': return classifyCursorFailure(evidence, context);
+    case 'github': return classifyGitHubFailure(evidence, context);
+    case 'cloudflare': return classifyCloudflareFailure(evidence, context);
+    case 'docker': return classifyDockerFailure(evidence, context);
+    case 'gcp':
+    case 'google_cloud': return classifyGcpFailure(evidence, context);
+    case 'freecad':
+    case 'openscad':
+    case 'blender':
+    case 'meshy': return classifyCadFailure(key, evidence, context);
+    case 'device':
+    case 'execos_device': return classifyDeviceFailure(evidence, context);
+    case 'agentsam':
+    case 'agentsam-sdk':
+    case 'inneranimalmedia':
+    case 'execos': return classifyInternalFailure(evidence, { ...context, system: key });
+    default: return classifyProviderFailure(key || 'provider', evidence, context);
+  }
+}

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

@@ -0,0 +1,40 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+const INTERNAL_REASONS = new Set([
+  ERROR_REASON.INTERNAL,
+  ERROR_REASON.INTERNAL_INVARIANT_VIOLATION,
+  ERROR_REASON.INTERNAL_CONFIGURATION_INVALID,
+  ERROR_REASON.INTERNAL_CONTRACT_VIOLATION,
+  ERROR_REASON.INTERNAL_ADAPTER_FAILED,
+  ERROR_REASON.INTERNAL_DEPENDENCY_FAILED,
+  ERROR_REASON.IDENTITY_RESOLUTION_FAILED,
+  ERROR_REASON.IDENTITY_MISMATCH,
+  ERROR_REASON.PERSISTENCE_FAILED,
+  ERROR_REASON.DATA_CORRUPT,
+  ERROR_REASON.DATA_LOSS,
+]);
+
+export function classifyInternalFailure(evidence = {}, context = {}) {
+  const reason = context.reason && INTERNAL_REASONS.has(context.reason) ? context.reason : ERROR_REASON.INTERNAL;
+  return createErrorEnvelope({
+    reason,
+    message: context.message || evidence.message || 'AgentSam encountered an internal failure.',
+    source: context.source || { kind: 'agentsam', name: context.system || 'agentsam-sdk', service: context.service || null },
+    resolution_owner: 'agentsam',
+    severity: 'blocking_internal',
+    retryable: false,
+    remediation: { action: 'inspect_platform', message: context.remediation_message || 'AgentSam must inspect this platform failure.' },
+    domain: context.domain || 'runtime',
+    tool: context.tool || null,
+    stage: context.stage || 'execute',
+    resource: context.resource || null,
+    provider: context.provider || null,
+    provider_code: evidence.provider_code || evidence.code || null,
+    request_id: evidence.request_id || null,
+    trace_id: evidence.trace_id || context.trace_id || null,
+    native: { code: evidence.code, exception_type: evidence.exception_type || evidence.name, exit_code: evidence.exit_code, signal: evidence.signal, stderr: evidence.stderr, stdout: evidence.stdout, stack: evidence.stack },
+    environment: context.environment || null,
+    details: evidence.details || null,
+  });
+}

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

@@ -0,0 +1,24 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyOAuthFailure(error, context = {}) {
+  const code = String(error?.code || error || '').toLowerCase();
+  let reason = context.reason;
+  if (!reason && ['invalid_client','invalid_grant'].includes(code)) reason = ERROR_REASON.PROVIDER_CREDENTIAL_INVALID;
+  else if (!reason && ['unauthorized_client','access_denied'].includes(code)) reason = ERROR_REASON.USER_PERMISSION_DENIED;
+  else if (!reason && ['invalid_scope'].includes(code)) reason = ERROR_REASON.PROVIDER_SCOPE_INSUFFICIENT;
+  else if (!reason && ['invalid_request','unsupported_grant_type'].includes(code)) reason = ERROR_REASON.INPUT_INVALID;
+  else reason ||= ERROR_REASON.UNKNOWN;
+  return createErrorEnvelope({
+    reason,
+    message: context.message || error?.message || `OAuth failure: ${code || 'unknown'}`,
+    source: context.source || { kind: context.provider ? 'provider' : 'runtime', name: context.provider || 'oauth' },
+    domain: 'auth',
+    tool: context.provider || 'oauth',
+    stage: context.stage || 'oauth',
+    provider: context.provider || null,
+    provider_code: code || null,
+    native: { code },
+    details: error?.details || null,
+  });
+}

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

@@ -0,0 +1,17 @@
+import { classifyProviderFailure } from './provider.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+const BUDGET_CODES = new Set(['credit_balance_exhausted','organization_spend_limit_exceeded','project_spend_limit_exceeded','organization_usage_limit_exceeded']);
+
+export function classifyOpenAIFailure(evidence = {}, context = {}) {
+  const code = String(evidence.code || evidence.provider_code || '').toLowerCase();
+  const message = String(evidence.message || '');
+  let reason = context.reason;
+  if (!reason && BUDGET_CODES.has(code)) reason = ERROR_REASON.PROVIDER_BUDGET_EXHAUSTED;
+  else if (!reason && (code === 'insufficient_quota' || /quota/i.test(message))) reason = ERROR_REASON.PROVIDER_QUOTA_EXHAUSTED;
+  else if (!reason && code === 'previous_response_not_found') reason = ERROR_REASON.CONTINUATION_INVALID;
+  else if (!reason && code === 'websocket_connection_limit_reached') reason = ERROR_REASON.PROVIDER_CAPACITY_EXHAUSTED;
+  else if (!reason && (code === 'server_is_overloaded' || /overload/i.test(message))) reason = ERROR_REASON.PROVIDER_OVERLOADED;
+  else if (!reason && /service[_ -]?tier/i.test(message)) reason = ERROR_REASON.SERVICE_TIER_UNSUPPORTED;
+  return classifyProviderFailure('openai', evidence, { ...context, reason });
+}

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

@@ -0,0 +1,35 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+export function classifyProcessFailure(evidence = {}, context = {}) {
+  const code = String(evidence.code || '').toUpperCase();
+  let reason = context.reason;
+  if (!reason && (evidence.cancelled || code === 'ABORT_ERR' || code === 'PROCESS_CANCELLED')) reason = ERROR_REASON.CANCELLED;
+  else if (!reason && (evidence.timeout || code === 'ETIMEDOUT' || code === 'PROCESS_TIMEOUT')) reason = ERROR_REASON.EXECUTION_TIMEOUT;
+  else if (!reason && (evidence.output_limit || code === 'PROCESS_OUTPUT_LIMIT')) reason = ERROR_REASON.PROCESS_OUTPUT_LIMIT;
+  else if (!reason && (code === 'ENOENT' || code === 'EACCES' || evidence.spawn_failed)) reason = ERROR_REASON.PROCESS_SPAWN_FAILED;
+  else if (!reason && Number.isInteger(evidence.exit_code) && evidence.exit_code !== 0) reason = ERROR_REASON.PROCESS_CRASHED;
+  else reason ||= ERROR_REASON.EXECUTION_FAILED;
+  let severity = context.severity;
+  let remediation = context.remediation;
+  if (context.retryable === false && !severity && reason === ERROR_REASON.EXECUTION_TIMEOUT) {
+    severity = 'blocking_user_fixable';
+    remediation = remediation || { action: 'change_configuration', message: 'Increase process timeout or inspect execution.' };
+  }
+  return createErrorEnvelope({
+    reason,
+    message: context.message || evidence.message || 'Process failed',
+    source: context.source || { kind: 'runtime', name: context.tool || 'process' },
+    resolution_owner: context.resolution_owner,
+    severity,
+    remediation,
+    domain: context.domain || 'runtime',
+    tool: context.tool || null,
+    stage: context.stage || 'execute',
+    retryable: context.retryable,
+    resource: context.resource || null,
+    environment: context.environment || null,
+    native: { code: evidence.code, exception_type: evidence.exception_type, exit_code: evidence.exit_code, signal: evidence.signal, stderr: evidence.stderr, stdout: evidence.stdout, stack: evidence.stack },
+    details: evidence.details || null,
+  });
+}

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

@@ -0,0 +1,114 @@
+import { createErrorEnvelope } from '../envelope.js';
+import { ERROR_REASON } from '../vocabulary.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function lower(...values) { return values.map(clean).join(' ').toLowerCase(); }
+function header(headers, name) {
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return clean(headers.get(name));
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) if (String(key).toLowerCase() === wanted) return clean(value);
+  return '';
+}
+function retryAfterMs(headers, explicit) {
+  if (Number.isFinite(explicit) && explicit >= 0) return Math.round(explicit);
+  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;
+}
+function requestId(headers, explicit) {
+  return clean(explicit) || header(headers, 'x-request-id') || header(headers, 'request-id') || header(headers, 'cf-ray') || null;
+}
+
+function reasonFromGenericEvidence(evidence = {}) {
+  const status = Number(evidence.status || evidence.http_status || 0);
+  const code = clean(evidence.code || evidence.provider_code).toLowerCase();
+  const type = clean(evidence.type).toLowerCase();
+  const text = lower(code, type, evidence.message, evidence.error);
+  if (evidence.connected === false) return ERROR_REASON.PROVIDER_NOT_CONNECTED;
+  if (evidence.credential_state === 'missing') return ERROR_REASON.PROVIDER_CREDENTIAL_MISSING;
+  if (evidence.credential_state === 'expired') return ERROR_REASON.PROVIDER_CREDENTIAL_EXPIRED;
+  if (evidence.credential_state === 'invalid') return ERROR_REASON.PROVIDER_CREDENTIAL_INVALID;
+  if (/credit|billing|spend[_ -]?limit|budget|payment required/.test(text)) return ERROR_REASON.PROVIDER_BUDGET_EXHAUSTED;
+  if (/quota|resource[_ -]?exhausted|usage[_ -]?limit/.test(text)) return ERROR_REASON.PROVIDER_QUOTA_EXHAUSTED;
+  if (/context.{0,20}(too long|limit|window|length)|max(?:imum)?[_ -]?tokens|request too large/.test(text)) return ERROR_REASON.CONTEXT_WINDOW_EXCEEDED;
+  if (/service[_ -]?tier/.test(text) && /(unsupported|invalid|not available)/.test(text)) return ERROR_REASON.SERVICE_TIER_UNSUPPORTED;
+  if (/region|country|location/.test(text) && /(unsupported|not available|restricted)/.test(text)) return ERROR_REASON.PROVIDER_REGION_UNSUPPORTED;
+  if (/content[_ -]?(filter|policy|blocked)|safety|moderation/.test(text)) return ERROR_REASON.PROVIDER_CONTENT_BLOCKED;
+  if (/model/.test(text) && /(not found|unknown|does not exist|unsupported)/.test(text)) return ERROR_REASON.PROVIDER_MODEL_NOT_FOUND;
+  if (status === 401 || /invalid[_ -]?(api[_ -]?)?key|authentication_error|unauthenticated/.test(text)) return ERROR_REASON.PROVIDER_CREDENTIAL_INVALID;
+  if (status === 403 || /permission|forbidden|scope/.test(text)) return ERROR_REASON.PROVIDER_SCOPE_INSUFFICIENT;
+  if (status === 429 || /rate[_ -]?limit|too many requests|slow[_ -]?down/.test(text)) return ERROR_REASON.PROVIDER_RATE_LIMITED;
+  if (status === 529 || /overload|overloaded|capacity/.test(text)) return ERROR_REASON.PROVIDER_OVERLOADED;
+  if (status >= 500) return ERROR_REASON.PROVIDER_UNAVAILABLE;
+  if (status === 404) return ERROR_REASON.TARGET_NOT_FOUND;
+  if (status === 400 || status === 409 || status === 422) return ERROR_REASON.PROVIDER_REQUEST_INVALID;
+  return ERROR_REASON.UNKNOWN;
+}
+
+export function classifyProviderFailure(provider, evidence = {}, context = {}) {
+  const name = clean(provider || context.provider || 'provider').toLowerCase();
+  const reason = context.reason || reasonFromGenericEvidence(evidence);
+  const providerCode = clean(evidence.code || evidence.provider_code || evidence.type) || null;
+  const requestOrigin = clean(context.request_origin || evidence.request_origin).toLowerCase();
+  const configuredOwner = clean(context.credential_owner || context.account_owner || context.configuration_owner).toLowerCase();
+  const internalRequestFailure = reason === ERROR_REASON.PROVIDER_REQUEST_INVALID && requestOrigin === 'agentsam';
+  const ownerSensitiveFailure = [
+    ERROR_REASON.PROVIDER_NOT_CONNECTED,
+    ERROR_REASON.PROVIDER_CREDENTIAL_MISSING,
+    ERROR_REASON.PROVIDER_CREDENTIAL_INVALID,
+    ERROR_REASON.PROVIDER_CREDENTIAL_EXPIRED,
+    ERROR_REASON.PROVIDER_SCOPE_INSUFFICIENT,
+    ERROR_REASON.PROVIDER_BUDGET_EXHAUSTED,
+    ERROR_REASON.PROVIDER_QUOTA_EXHAUSTED,
+  ].includes(reason);
+  const platformOwnedFailure = ownerSensitiveFailure && ['agentsam','inneranimalmedia','platform'].includes(configuredOwner);
+  const organizationOwnedFailure = ownerSensitiveFailure && ['organization','organization_admin','org'].includes(configuredOwner);
+  const localConfigurationFailure = [ERROR_REASON.PROVIDER_NOT_CONNECTED, ERROR_REASON.PROVIDER_CREDENTIAL_MISSING].includes(reason);
+  const resolutionOwner = internalRequestFailure || platformOwnedFailure
+    ? 'agentsam'
+    : organizationOwnedFailure
+      ? 'organization_admin'
+      : context.resolution_owner;
+  const severity = internalRequestFailure || platformOwnedFailure ? 'blocking_internal' : context.severity;
+  const remediation = internalRequestFailure || platformOwnedFailure
+    ? { action: 'inspect_platform', message: 'AgentSam must inspect its provider integration or platform-owned credential.' }
+    : organizationOwnedFailure
+      ? { action: 'contact_organization_admin', message: 'An organization administrator must update this provider connection or account.' }
+      : context.remediation;
+  const source = context.source || (localConfigurationFailure
+    ? platformOwnedFailure
+      ? { kind: 'agentsam', name: 'inneranimalmedia', service: name }
+      : { kind: 'user', name: organizationOwnedFailure ? 'organization_configuration' : 'project_configuration', service: name }
+    : { kind: 'provider', name, service: clean(context.service || evidence.service) || null });
+  return createErrorEnvelope({
+    reason,
+    message: context.message || evidence.message || evidence.error || `${name} request failed`,
+    source,
+    resolution_owner: resolutionOwner,
+    severity,
+    remediation,
+    domain: context.domain || 'provider',
+    tool: context.tool || name,
+    stage: context.stage || 'request',
+    retryable: context.retryable,
+    retry_after_ms: retryAfterMs(evidence.headers, evidence.retry_after_ms),
+    http_status: Number(evidence.status || evidence.http_status || 0) || undefined,
+    provider: name,
+    provider_code: providerCode,
+    request_id: requestId(evidence.headers, evidence.request_id),
+    trace_id: evidence.trace_id || context.trace_id || null,
+    resource: context.resource || null,
+    environment: context.environment || null,
+    native: {
+      code: providerCode,
+      exception_type: evidence.type || evidence.exception_type || null,
+      stack: evidence.stack || null,
+    },
+    details: evidence.details ?? evidence.body ?? null,
+  });
+}
+
+export { reasonFromGenericEvidence };

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

@@ -0,0 +1,239 @@
+import {
+  DEFAULT_HTTP_STATUS,
+  ERROR_CODE,
+  ERROR_DOMAIN,
+  ERROR_REASON_POLICY,
+  ERROR_RESOLUTION_OWNER,
+  ERROR_SCHEMA_VERSION,
+  ERROR_SEVERITY,
+  ERROR_SOURCE_KIND,
+  GRPC_STATUS,
+  REMEDIATION_ACTION,
+} from './vocabulary.js';
+import { fingerprintError } from './fingerprint.js';
+import { redactErrorValue, redactString, sanitizeNativeEvidence } from './redaction.js';
+
+const REASON_PATTERN = /^[a-z][a-z0-9_]{0,127}$/;
+const VALUES = object => new Set(Object.values(object));
+const CODE_VALUES = VALUES(ERROR_CODE);
+const SEVERITY_VALUES = VALUES(ERROR_SEVERITY);
+const SOURCE_VALUES = VALUES(ERROR_SOURCE_KIND);
+const OWNER_VALUES = VALUES(ERROR_RESOLUTION_OWNER);
+const DOMAIN_VALUES = VALUES(ERROR_DOMAIN);
+const ACTION_VALUES = VALUES(REMEDIATION_ACTION);
+const GRPC_CODE_BY_NUMBER = new Map(Object.entries(GRPC_STATUS).map(([name, value]) => [value, ERROR_CODE[name]]));
+const HTTP_OVERRIDES = new Map([
+  [400, ERROR_CODE.INVALID_ARGUMENT], [401, ERROR_CODE.UNAUTHENTICATED], [403, ERROR_CODE.PERMISSION_DENIED],
+  [404, ERROR_CODE.NOT_FOUND], [408, ERROR_CODE.DEADLINE_EXCEEDED], [409, ERROR_CODE.ABORTED],
+  [412, ERROR_CODE.FAILED_PRECONDITION], [413, ERROR_CODE.RESOURCE_EXHAUSTED], [415, ERROR_CODE.INVALID_ARGUMENT],
+  [422, ERROR_CODE.INVALID_ARGUMENT], [429, ERROR_CODE.RESOURCE_EXHAUSTED], [499, ERROR_CODE.CANCELLED],
+  [500, ERROR_CODE.INTERNAL], [501, ERROR_CODE.UNIMPLEMENTED], [502, ERROR_CODE.UNAVAILABLE],
+  [503, ERROR_CODE.UNAVAILABLE], [504, ERROR_CODE.DEADLINE_EXCEEDED], [520, ERROR_CODE.UNAVAILABLE],
+  [521, ERROR_CODE.UNAVAILABLE], [522, ERROR_CODE.UNAVAILABLE], [523, ERROR_CODE.UNAVAILABLE],
+  [524, ERROR_CODE.DEADLINE_EXCEEDED], [525, ERROR_CODE.UNAVAILABLE], [526, ERROR_CODE.UNAVAILABLE],
+  [530, ERROR_CODE.UNAVAILABLE],
+]);
+const USER_ACTIONS = new Set([
+  REMEDIATION_ACTION.REAUTHENTICATE,
+  REMEDIATION_ACTION.CONNECT_PROVIDER,
+  REMEDIATION_ACTION.CONFIGURE_PROVIDER_CREDENTIAL,
+  REMEDIATION_ACTION.REFRESH_PROVIDER_CREDENTIAL,
+  REMEDIATION_ACTION.REQUEST_PERMISSION,
+  REMEDIATION_ACTION.REENROLL_DEVICE,
+  REMEDIATION_ACTION.INSTALL_DEPENDENCY,
+  REMEDIATION_ACTION.UPGRADE_DEPENDENCY,
+  REMEDIATION_ACTION.CONFIGURE_DEPENDENCY,
+  REMEDIATION_ACTION.CHANGE_CONFIGURATION,
+  REMEDIATION_ACTION.CHANGE_INPUT,
+  REMEDIATION_ACTION.REDUCE_SCOPE,
+  REMEDIATION_ACTION.INCREASE_QUOTA,
+  REMEDIATION_ACTION.ADD_BUDGET,
+  REMEDIATION_ACTION.SELECT_MODEL,
+  REMEDIATION_ACTION.CHANGE_REGION,
+  REMEDIATION_ACTION.RESTART_RUNTIME,
+]);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function optional(value, max = 512) { const text = clean(value); return text ? redactString(text, max) : null; }
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+function normalizeSource(source, fallbackName = 'agentsam-sdk') {
+  const input = source && typeof source === 'object' ? source : {};
+  const kind = clean(input.kind || ERROR_SOURCE_KIND.AGENTSAM);
+  if (!SOURCE_VALUES.has(kind)) throw new TypeError(`Unknown AgentSam error source kind: ${kind}`);
+  return Object.freeze({
+    kind,
+    name: optional(input.name || fallbackName, 256) || fallbackName,
+    service: optional(input.service, 256),
+  });
+}
+function normalizeRemediation(remediation, policy) {
+  const input = remediation && typeof remediation === 'object' ? remediation : {};
+  const action = clean(input.action || policy.remediation_action || REMEDIATION_ACTION.NONE);
+  if (!ACTION_VALUES.has(action)) throw new TypeError(`Unknown AgentSam remediation action: ${action}`);
+  return Object.freeze({
+    action,
+    message: optional(input.message, 2_000),
+    automatic: input.automatic === true,
+    command: optional(input.command, 1_000),
+    url: optional(input.url, 2_000),
+  });
+}
+function normalizeResource(resource) {
+  if (!resource || typeof resource !== 'object') return null;
+  const type = optional(resource.type, 128);
+  if (!type) return null;
+  return Object.freeze({ type, id: optional(resource.id, 512), name: optional(resource.name, 512) });
+}
+function normalizeEnvironment(environment) {
+  if (!environment || typeof environment !== 'object') return null;
+  return Object.freeze({
+    detected_version: optional(environment.detected_version, 512),
+    required_version: optional(environment.required_version, 512),
+    component: optional(environment.component, 512),
+    runtime: optional(environment.runtime, 512),
+    platform: optional(environment.platform, 512),
+  });
+}
+
+export function canonicalCodeFromHttpStatus(status) {
+  const value = Number(status || 0);
+  return HTTP_OVERRIDES.get(value) || (value >= 500 ? ERROR_CODE.INTERNAL : ERROR_CODE.UNKNOWN);
+}
+export function canonicalCodeFromGrpcStatus(status) { return GRPC_CODE_BY_NUMBER.get(Number(status)) || ERROR_CODE.UNKNOWN; }
+export function defaultHttpStatusForCode(code) { return DEFAULT_HTTP_STATUS[code] ?? 500; }
+export function grpcStatusForCode(code) { return GRPC_STATUS[code] ?? GRPC_STATUS.UNKNOWN; }
+
+export function createErrorEnvelope(input = {}) {
+  const reason = clean(input.reason || 'unknown');
+  if (!REASON_PATTERN.test(reason)) throw new TypeError(`Invalid AgentSam error reason: ${reason}`);
+  const policy = ERROR_REASON_POLICY[reason] || ERROR_REASON_POLICY.unknown;
+  const code = clean(input.code || policy.code);
+  if (!CODE_VALUES.has(code) || code === ERROR_CODE.OK) throw new TypeError(`Unknown AgentSam error code: ${code}`);
+  if (ERROR_REASON_POLICY[reason] && code !== policy.code) {
+    throw new TypeError(`AgentSam error reason ${reason} requires canonical code ${policy.code}, received ${code}`);
+  }
+  const severity = clean(input.severity || policy.severity);
+  if (!SEVERITY_VALUES.has(severity)) throw new TypeError(`Unknown AgentSam error severity: ${severity}`);
+  const retryable = input.retryable == null ? Boolean(policy.retryable) : Boolean(input.retryable);
+  const resolutionOwner = clean(input.resolution_owner || policy.resolution_owner);
+  if (!OWNER_VALUES.has(resolutionOwner)) throw new TypeError(`Unknown AgentSam error resolution owner: ${resolutionOwner}`);
+  const domain = clean(input.domain || ERROR_DOMAIN.RUNTIME);
+  if (!DOMAIN_VALUES.has(domain)) throw new TypeError(`Unknown AgentSam error domain: ${domain}`);
+  const remediation = normalizeRemediation(input.remediation, policy);
+  if (severity === ERROR_SEVERITY.TRANSIENT && !retryable) throw new TypeError('transient AgentSam errors must be retryable');
+  if ((remediation.action === REMEDIATION_ACTION.RETRY || remediation.action === REMEDIATION_ACTION.RETRY_LATER) && !retryable) {
+    throw new TypeError(`${remediation.action} remediation requires retryable=true`);
+  }
+  if (severity === ERROR_SEVERITY.BLOCKING_INTERNAL && USER_ACTIONS.has(remediation.action)) {
+    throw new TypeError(`blocking_internal errors cannot prescribe user remediation action ${remediation.action}`);
+  }
+  const source = normalizeSource(input.source);
+  const native = sanitizeNativeEvidence(input.native);
+  const environment = normalizeEnvironment(input.environment);
+  const envelope = {
+    ok: false,
+    schema_version: ERROR_SCHEMA_VERSION,
+    code,
+    reason,
+    severity,
+    source,
+    resolution_owner: resolutionOwner,
+    domain,
+    tool: optional(input.tool, 256),
+    stage: optional(input.stage, 256),
+    message: redactString(input.message || 'Operation failed', 4_000),
+    retryable,
+    retry_after_ms: input.retry_after_ms == null ? null : Math.max(0, Math.round(Number(input.retry_after_ms) || 0)),
+    remediation,
+    resource: normalizeResource(input.resource),
+    native,
+    environment,
+    http_status: input.http_status == null ? defaultHttpStatusForCode(code) : Number(input.http_status),
+    grpc_status: input.grpc_status == null ? grpcStatusForCode(code) : Number(input.grpc_status),
+    transport: optional(input.transport, 256),
+    provider: optional(input.provider, 256),
+    provider_code: optional(input.provider_code, 512),
+    request_id: optional(input.request_id, 512),
+    trace_id: optional(input.trace_id, 512),
+    fingerprint: '',
+    occurrence_count: Number.isInteger(input.occurrence_count) && input.occurrence_count > 0 ? input.occurrence_count : 1,
+    details: input.details == null ? null : redactErrorValue(input.details),
+  };
+  if (!Number.isInteger(envelope.http_status) || envelope.http_status < 100 || envelope.http_status > 599) envelope.http_status = null;
+  if (!Number.isInteger(envelope.grpc_status) || envelope.grpc_status < 0 || envelope.grpc_status > 16) envelope.grpc_status = null;
+  envelope.fingerprint = optional(input.fingerprint, 128) || fingerprintError(envelope);
+
+  // Optional recovery dimensions (v1-compatible extras — orthogonal to reason enum)
+  const failureClass = input.failure_class || null;
+  if (failureClass) envelope.failure_class = clean(failureClass);
+  if (input.operation && typeof input.operation === 'object') {
+    envelope.operation = Object.freeze({
+      kind: optional(input.operation.kind, 256),
+      action: optional(input.operation.action, 256),
+      resource_type: optional(input.operation.resource_type, 128),
+      resource_id: optional(input.operation.resource_id, 512),
+      read_only: input.operation.read_only === true,
+      idempotent: input.operation.idempotent === true,
+      side_effect_state: optional(input.operation.side_effect_state, 64) || 'unknown',
+    });
+  }
+  if (input.retry && typeof input.retry === 'object') {
+    envelope.retry = Object.freeze({
+      allowed: input.retry.allowed == null ? retryable : Boolean(input.retry.allowed),
+      strategy: optional(input.retry.strategy, 64) || (retryable ? 'exponential_backoff' : 'none'),
+      retry_after_ms: input.retry.retry_after_ms == null ? envelope.retry_after_ms : Math.max(0, Math.round(Number(input.retry.retry_after_ms) || 0)),
+      max_attempts: Number.isInteger(input.retry.max_attempts) ? input.retry.max_attempts : null,
+      requires_idempotency_key: input.retry.requires_idempotency_key === true,
+    });
+  }
+  if (input.fallback && typeof input.fallback === 'object') {
+    envelope.fallback = Object.freeze({
+      allowed: Boolean(input.fallback.allowed),
+      strategy: optional(input.fallback.strategy, 64),
+      preserve_semantics: input.fallback.preserve_semantics !== false,
+      target: optional(input.fallback.target, 256),
+    });
+  }
+  if (input.notify && typeof input.notify === 'object') {
+    envelope.notify = Object.freeze({
+      user: optional(input.notify.user, 64) || 'immediately',
+      operator: optional(input.notify.operator, 64) || 'never',
+      agent: optional(input.notify.agent, 64) || 'stop',
+    });
+  }
+  if (input.cause && typeof input.cause === 'object') {
+    envelope.cause = input.cause;
+  }
+  if (input.status === 'partial' || input.status === 'success' || input.status === 'failure') {
+    envelope.status = input.status;
+  }
+  if (input.completed != null || input.failed != null) {
+    envelope.partial = Object.freeze({
+      completed: Number(input.completed) || 0,
+      failed: Number(input.failed) || 0,
+      failures: Array.isArray(input.failures) ? input.failures : [],
+    });
+  }
+
+  return deepFreeze(envelope);
+}
+
+export function isErrorEnvelope(value) {
+  return Boolean(value && typeof value === 'object' && value.ok === false && value.schema_version === ERROR_SCHEMA_VERSION && CODE_VALUES.has(value.code) && typeof value.reason === 'string');
+}
+
+export function assertErrorEnvelope(value) {
+  if (!isErrorEnvelope(value)) throw new TypeError('Expected an AgentSam ErrorEnvelope');
+  return createErrorEnvelope(value);
+}
+
+export function serializeError(value) { return JSON.stringify(assertErrorEnvelope(value)); }
+export function parseError(value) {
+  const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+  if (parsed?.schema_version !== ERROR_SCHEMA_VERSION) throw new TypeError(`Unsupported AgentSam error schema version: ${parsed?.schema_version ?? 'missing'}`);
+  return createErrorEnvelope(parsed);
+}

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

@@ -0,0 +1,24 @@
+import { createErrorEnvelope, isErrorEnvelope } from './envelope.js';
+
+export class AgentSamError extends Error {
+  constructor(envelope, options = {}) {
+    const normalized = isErrorEnvelope(envelope) ? envelope : createErrorEnvelope(envelope);
+    super(normalized.message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'AgentSamError';
+    this.envelope = normalized;
+    // Compatibility alias for pre-v1 callers. It points at the canonical
+    // envelope; it is not a second diagnostic vocabulary.
+    this.diagnostic = normalized;
+    this.code = normalized.code;
+    this.reason = normalized.reason;
+    this.severity = normalized.severity;
+    this.retryable = normalized.retryable;
+    this.status = normalized.http_status;
+    this.fingerprint = normalized.fingerprint;
+  }
+}
+
+export function asAgentSamError(value, options = {}) {
+  if (value instanceof AgentSamError) return value;
+  return new AgentSamError(value, options);
+}

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

@@ -0,0 +1,35 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+function stableFields(value = {}) {
+  return [
+    value.code,
+    value.reason,
+    value.severity,
+    value.source?.kind,
+    value.source?.name,
+    value.source?.service,
+    value.resolution_owner,
+    value.domain,
+    value.tool,
+    value.stage,
+    value.provider,
+    value.provider_code,
+    value.native?.code,
+    value.native?.exception_type,
+    value.environment?.component,
+    value.environment?.runtime,
+  ].map(clean).join('\u001f');
+}
+
+// FNV-1a 64-bit: deterministic, dependency-free, Worker/Node safe. This is an
+// operational grouping key, not a cryptographic integrity primitive.
+export function fingerprintError(value = {}) {
+  const text = stableFields(value);
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= BigInt(text.charCodeAt(i));
+    hash = BigInt.asUintN(64, hash * prime);
+  }
+  return `err_${hash.toString(16).padStart(16, '0')}`;
+}