@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

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

@@ -2,11 +2,15 @@ import {
   DEFAULT_HTTP_STATUS,
   ERROR_CODE,
   ERROR_DOMAIN,
+  ERROR_FAILURE_BEHAVIOR,
+  ERROR_FAILURE_CLASS,
   ERROR_REASON_POLICY,
   ERROR_RESOLUTION_OWNER,
   ERROR_SCHEMA_VERSION,
   ERROR_SEVERITY,
+  ERROR_SIDE_EFFECT_STATE,
   ERROR_SOURCE_KIND,
+  ERROR_STAGE,
   GRPC_STATUS,
   REMEDIATION_ACTION,
 } from './vocabulary.js';
@@ -20,7 +24,19 @@ 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 FAILURE_CLASS_VALUES = VALUES(ERROR_FAILURE_CLASS);
+const STAGE_VALUES = VALUES(ERROR_STAGE);
+const FAILURE_BEHAVIOR_VALUES = VALUES(ERROR_FAILURE_BEHAVIOR);
+const SIDE_EFFECT_STATE_VALUES = VALUES(ERROR_SIDE_EFFECT_STATE);
 const ACTION_VALUES = VALUES(REMEDIATION_ACTION);
+const FEATURE_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const STAGE_ALIASES = new Map([
+  ['discovery', 'discover'], ['configuration', 'configure'], ['request', 'execute'], ['run', 'execute'],
+  ['dispatch', 'execute'], ['adapter', 'execute'], ['spawn', 'start'], ['parse', 'transform'],
+  ['render', 'transform'], ['compaction', 'transform'], ['persistence', 'persist'],
+  ['persistence_read', 'load'], ['persistence_write', 'persist'], ['search', 'discover'],
+  ['inventory', 'discover'], ['approve', 'authorize'],
+]);
 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],
@@ -51,6 +67,11 @@ const USER_ACTIONS = new Set([
   REMEDIATION_ACTION.SELECT_MODEL,
   REMEDIATION_ACTION.CHANGE_REGION,
   REMEDIATION_ACTION.RESTART_RUNTIME,
+  REMEDIATION_ACTION.RESTART_SERVICE,
+  REMEDIATION_ACTION.REPAIR_SCHEMA,
+  REMEDIATION_ACTION.RUN_MIGRATION,
+  REMEDIATION_ACTION.UPDATE_LOCKFILE,
+  REMEDIATION_ACTION.REINSTALL_WORKSPACE,
 ]);
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
@@ -107,6 +128,21 @@ export function canonicalCodeFromGrpcStatus(status) { return GRPC_CODE_BY_NUMBER
 export function defaultHttpStatusForCode(code) { return DEFAULT_HTTP_STATUS[code] ?? 500; }
 export function grpcStatusForCode(code) { return GRPC_STATUS[code] ?? GRPC_STATUS.UNKNOWN; }
 
+function normalizeStage(value, fallback) {
+  const requested = clean(value);
+  if (!requested) return { stage: fallback, nativeStage: null };
+  if (STAGE_VALUES.has(requested)) return { stage: requested, nativeStage: null };
+  const generic = STAGE_ALIASES.get(requested);
+  return { stage: generic || fallback, nativeStage: requested };
+}
+
+function vocabularyValue(value, allowed, label, fallback = null) {
+  const normalized = clean(value || fallback);
+  if (!normalized && fallback == null) return null;
+  if (!allowed.has(normalized)) throw new TypeError(`Unknown AgentSam error ${label}: ${normalized}`);
+  return normalized;
+}
+
 export function createErrorEnvelope(input = {}) {
   const reason = clean(input.reason || 'unknown');
   if (!REASON_PATTERN.test(reason)) throw new TypeError(`Invalid AgentSam error reason: ${reason}`);
@@ -121,8 +157,19 @@ export function createErrorEnvelope(input = {}) {
   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 domain = vocabularyValue(input.domain, DOMAIN_VALUES, 'domain', policy.domain || ERROR_DOMAIN.RUNTIME);
+  const failureClass = vocabularyValue(input.failure_class, FAILURE_CLASS_VALUES, 'failure class', policy.failure_class || 'internal');
+  const normalizedStage = normalizeStage(input.stage, policy.default_stage || ERROR_STAGE.EXECUTE);
+  const nativeStage = optional(input.native_stage, 256) || normalizedStage.nativeStage;
+  const feature = optional(input.feature, 256);
+  if (feature && !FEATURE_PATTERN.test(feature)) throw new TypeError(`Invalid AgentSam error feature: ${feature}`);
+  const failureBehavior = vocabularyValue(input.failure_behavior, FAILURE_BEHAVIOR_VALUES, 'failure behavior');
+  const sideEffectState = vocabularyValue(
+    input.side_effect_state || input.operation?.side_effect_state,
+    SIDE_EFFECT_STATE_VALUES,
+    'side effect state',
+    input.operation ? ERROR_SIDE_EFFECT_STATE.UNKNOWN : ERROR_SIDE_EFFECT_STATE.NONE,
+  );
   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) {
@@ -139,14 +186,22 @@ export function createErrorEnvelope(input = {}) {
     schema_version: ERROR_SCHEMA_VERSION,
     code,
     reason,
+    domain,
+    failure_class: failureClass,
+    stage: normalizedStage.stage,
+    native_stage: nativeStage,
+    feature,
+    failure_behavior: failureBehavior,
     severity,
-    source,
+    retryable,
+    side_effect_state: sideEffectState,
     resolution_owner: resolutionOwner,
-    domain,
+    source,
+    adapter: optional(input.adapter, 256),
+    protocol: optional(input.protocol, 256),
+    transport: optional(input.transport, 256),
     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),
@@ -154,7 +209,6 @@ export function createErrorEnvelope(input = {}) {
     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),
@@ -167,9 +221,7 @@ export function createErrorEnvelope(input = {}) {
   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);
+  // Optional recovery plans remain orthogonal to the canonical v2 failure dimensions.
   if (input.operation && typeof input.operation === 'object') {
     envelope.operation = Object.freeze({
       kind: optional(input.operation.kind, 256),
@@ -178,7 +230,7 @@ export function createErrorEnvelope(input = {}) {
       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',
+      side_effect_state: sideEffectState,
     });
   }
   if (input.retry && typeof input.retry === 'object') {

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

@@ -11,8 +11,14 @@ export class AgentSamError extends Error {
     this.diagnostic = normalized;
     this.code = normalized.code;
     this.reason = normalized.reason;
+    this.domain = normalized.domain;
+    this.failure_class = normalized.failure_class;
+    this.stage = normalized.stage;
+    this.feature = normalized.feature;
+    this.failure_behavior = normalized.failure_behavior;
     this.severity = normalized.severity;
     this.retryable = normalized.retryable;
+    this.side_effect_state = normalized.side_effect_state;
     this.status = normalized.http_status;
     this.fingerprint = normalized.fingerprint;
   }

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

@@ -10,8 +10,16 @@ function stableFields(value = {}) {
     value.source?.service,
     value.resolution_owner,
     value.domain,
-    value.tool,
+    value.failure_class,
     value.stage,
+    value.native_stage,
+    value.feature,
+    value.failure_behavior,
+    value.side_effect_state,
+    value.adapter,
+    value.protocol,
+    value.transport,
+    value.tool,
     value.provider,
     value.provider_code,
     value.native?.code,

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

@@ -1,8 +1,47 @@
 import { AgentSamError } from './error.js';
 import { canonicalCodeFromHttpStatus, createErrorEnvelope, isErrorEnvelope } from './envelope.js';
-import { ERROR_REASON } from './vocabulary.js';
+import { ERROR_REASON, ERROR_REASON_ALIASES, ERROR_REASON_POLICY } from './vocabulary.js';
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
+function token(value) { return clean(value).split(':', 1)[0]; }
+
+/**
+ * Resolves canonical reasons and legacy/native aliases without discarding the
+ * original evidence. Adapter context disambiguates old generic hook codes.
+ */
+export function canonicalizeErrorReason(value, context = {}) {
+  const values = value && typeof value === 'object'
+    ? [value.reason, value.code, value.message]
+    : [value];
+  for (const raw of values) {
+    const candidate = token(raw);
+    if (!candidate) continue;
+    if (ERROR_REASON_POLICY[candidate]) return candidate;
+    const lowered = candidate.toLowerCase();
+    if (ERROR_REASON_POLICY[lowered]) return lowered;
+    if (candidate === 'AGENTSAM_HOOK_TIMEOUT' && context.adapter) {
+      const specific = `hook_${clean(context.adapter).toLowerCase()}_timeout`;
+      if (ERROR_REASON_POLICY[specific]) return specific;
+    }
+    const alias = ERROR_REASON_ALIASES[candidate] || ERROR_REASON_ALIASES[lowered] || ERROR_REASON_ALIASES[candidate.toUpperCase()];
+    if (alias) return alias;
+  }
+  return null;
+}
+
+function reasonFromHttpStatus(status) {
+  if (status === 400 || status === 422) return ERROR_REASON.INPUT_INVALID;
+  if (status === 401) return ERROR_REASON.AUTH_INVALID;
+  if (status === 403) return ERROR_REASON.PERMISSION_DENIED;
+  if (status === 404) return ERROR_REASON.TARGET_NOT_FOUND;
+  if (status === 408 || status === 504) return ERROR_REASON.TRANSPORT_TIMEOUT;
+  if (status === 409) return ERROR_REASON.CONFLICT;
+  if (status === 412) return ERROR_REASON.PRECONDITION_FAILED;
+  if (status === 429) return ERROR_REASON.RATE_LIMITED;
+  if (status === 501) return ERROR_REASON.UNSUPPORTED_OPERATION;
+  if ([502, 503, 520, 521, 522, 523, 525, 526, 530].includes(status)) return ERROR_REASON.TRANSPORT_UNREACHABLE;
+  return ERROR_REASON.INTERNAL;
+}
 
 export function normalizeError(error, context = {}) {
   if (isErrorEnvelope(error)) return error;
@@ -10,11 +49,17 @@ export function normalizeError(error, context = {}) {
   if (isErrorEnvelope(error?.envelope)) return error.envelope;
   if (isErrorEnvelope(error?.error)) return error.error;
   const status = Number(error?.status || error?.http_status || context.http_status || 0) || null;
-  const canonical = clean(context.code) || (status ? canonicalCodeFromHttpStatus(status) : undefined);
+  const recoveredReason = canonicalizeErrorReason(context.reason, context)
+    || canonicalizeErrorReason(error, context);
+  const reason = recoveredReason || (status ? reasonFromHttpStatus(status) : ERROR_REASON.INTERNAL);
+  // A known reason owns its broad canonical code. HTTP status only selects a
+  // broad fallback reason when no machine reason or alias was recovered.
+  const canonical = clean(context.code)
+    || (ERROR_REASON_POLICY[reason] ? undefined : (status ? canonicalCodeFromHttpStatus(status) : undefined));
   return createErrorEnvelope({
     ...context,
     code: canonical,
-    reason: context.reason || ERROR_REASON.INTERNAL,
+    reason,
     message: context.message || error?.message || String(error || 'Unknown error'),
     http_status: status,
     native: context.native || {
@@ -23,8 +68,8 @@ export function normalizeError(error, context = {}) {
       stack: error?.stack || null,
     },
     source: context.source || { kind: 'agentsam', name: 'agentsam-sdk' },
-    resolution_owner: context.resolution_owner || 'agentsam',
-    severity: context.severity || 'blocking_internal',
-    remediation: context.remediation || { action: 'inspect_platform' },
+    resolution_owner: context.resolution_owner,
+    severity: context.severity,
+    remediation: context.remediation,
   });
 }

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

@@ -1,3 +1,5 @@
+import { ERROR_FAILURE_CLASS, ERROR_SIDE_EFFECT_STATE } from './vocabulary.js';
+
 /**
  * Recovery policy — separates "what failed" from "what to do".
  *
@@ -6,39 +8,10 @@
  * Critical rule: unknown side_effect_state ⇒ reconcile before retry.
  */
 
-export const FAILURE_CLASS = Object.freeze({
-  INPUT: 'input',
-  AUTHENTICATION: 'authentication',
-  AUTHORIZATION: 'authorization',
-  POLICY: 'policy',
-  DISCOVERY: 'discovery',
-  RESOLUTION: 'resolution',
-  TRANSPORT: 'transport',
-  PROTOCOL: 'protocol',
-  TIMEOUT: 'timeout',
-  RATE_LIMIT: 'rate_limit',
-  CAPACITY: 'capacity',
-  RESOURCE: 'resource',
-  FILESYSTEM: 'filesystem',
-  PERSISTENCE: 'persistence',
-  CONSISTENCY: 'consistency',
-  CONFLICT: 'conflict',
-  DEPENDENCY: 'dependency',
-  PROCESS: 'process',
-  IPC: 'ipc',
-  DATA_INTEGRITY: 'data_integrity',
-  CANCELLED: 'cancelled',
-  UNKNOWN: 'unknown',
-});
-
-export const SIDE_EFFECT_STATE = Object.freeze({
-  NONE: 'none',
-  NOT_STARTED: 'not_started',
-  CONFIRMED_NOT_APPLIED: 'confirmed_not_applied',
-  CONFIRMED_APPLIED: 'confirmed_applied',
-  PARTIALLY_APPLIED: 'partially_applied',
-  UNKNOWN: 'unknown',
-});
+// Compatibility names now project the generated v2 vocabulary instead of
+// maintaining a second recovery-only taxonomy.
+export const FAILURE_CLASS = ERROR_FAILURE_CLASS;
+export const SIDE_EFFECT_STATE = ERROR_SIDE_EFFECT_STATE;
 
 export const RECOVERY_SCHEMA = 'agentsam.recovery.v1';
 
@@ -85,6 +58,7 @@ export function inferFailureClass(error = {}) {
  * @param {object} [operationContext]
  */
 export function inferSideEffectState(error = {}, operationContext = {}) {
+  if (error.side_effect_state && Object.values(SIDE_EFFECT_STATE).includes(error.side_effect_state)) return error.side_effect_state;
   const op = error.operation || operationContext.operation || {};
   if (op.side_effect_state) return op.side_effect_state;
   if (op.read_only === true || op.side_effect_state === SIDE_EFFECT_STATE.NONE) {
@@ -148,7 +122,7 @@ export function planRecovery(error = {}, operationContext = {}) {
   };
 
   // Cancellations are not defects
-  if (failure_class === FAILURE_CLASS.CANCELLED) {
+  if (failure_class === FAILURE_CLASS.CANCELLED || failure_class === FAILURE_CLASS.CANCELLATION) {
     return freezePlan({
       ...plan,
       disposition: 'abort',
@@ -195,7 +169,7 @@ export function planRecovery(error = {}, operationContext = {}) {
     });
   }
 
-  if (failure_class === FAILURE_CLASS.INPUT || failure_class === FAILURE_CLASS.CONFLICT) {
+  if ([FAILURE_CLASS.INPUT, FAILURE_CLASS.VALIDATION, FAILURE_CLASS.CONFLICT].includes(failure_class)) {
     const disposition = failure_class === FAILURE_CLASS.CONFLICT && error.retryable
       ? 'retry'
       : 'await_user';

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

@@ -30,7 +30,12 @@ export function fromHttpError({ status, body, headers, source, provider, domain
         : code === 'RESOURCE_EXHAUSTED' ? ERROR_REASON.RATE_LIMITED
           : code === 'UNAVAILABLE' ? ERROR_REASON.TRANSPORT_UNREACHABLE
             : code === 'DEADLINE_EXCEEDED' ? ERROR_REASON.TRANSPORT_TIMEOUT
-              : ERROR_REASON.UNKNOWN,
+              : code === 'INTERNAL' ? ERROR_REASON.INTERNAL
+                : code === 'INVALID_ARGUMENT' ? ERROR_REASON.INPUT_INVALID
+                  : code === 'NOT_FOUND' ? ERROR_REASON.TARGET_NOT_FOUND
+                    : code === 'FAILED_PRECONDITION' ? ERROR_REASON.PRECONDITION_FAILED
+                      : code === 'UNIMPLEMENTED' ? ERROR_REASON.UNSUPPORTED_OPERATION
+                        : ERROR_REASON.UNKNOWN,
     message: candidate?.message || candidate?.error || `HTTP ${status || 500} request failed`,
     retryable: Number(status) === 429 || Number(status) >= 500,
     retry_after_ms: (() => {