@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/commands/tunnel.js

@@ -7,7 +7,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { authenticateViaBrowser } from '../lib/auth.js';
 import { postJson } from '../lib/core-client.js';
-import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
+import { resolveAccountSdkKey } from '../lib/account-session.js';
 
 const DEFAULT_PORT = 3099;
 
@@ -51,7 +51,7 @@ function ensureCloudflared() {
 }
 
 async function resolveToken() {
-  const existing = resolveSdkKey(process.env);
+  const existing = resolveAccountSdkKey({ env: process.env }).value;
   if (existing.startsWith('sdk_')) return existing;
   const session = await authenticateViaBrowser();
   const tok = String(session?.access_token || '').trim();

package/src/commands/whoami.js

@@ -0,0 +1,86 @@
+import { getJson } from '../lib/core-client.js';
+import { resolveAccountSdkKey } from '../lib/account-session.js';
+import { listProviderCredentialStatus } from '../lib/provider-credentials.js';
+
+function writeLine(write, value = '') { write(`${value}\n`); }
+
+export async function collectWhoami(options = {}) {
+  const env = options.env || process.env;
+  const sdk = resolveAccountSdkKey({ env, explicit: options.token || '', home: options.home });
+  const token = sdk.value;
+  const credentials = listProviderCredentialStatus({ env, home: options.home });
+  if (!token) return {
+    schema_version: 1,
+    authenticated: false,
+    authority: 'iam',
+    identity: null,
+    sdk_credential: { configured: false, source: null },
+    provider_credentials: credentials,
+  };
+  try {
+    const loader = options.contextLoader || ((sdkKey) => getJson('/api/sdk/context', sdkKey));
+    const context = await loader(token);
+    return {
+      schema_version: 1,
+      authenticated: true,
+      authority: 'iam',
+      identity: {
+        user_id: context?.user_id || null,
+        account_id: context?.account_id || null,
+        email: context?.email || context?.user?.email || null,
+      },
+      sdk_credential: { configured: true, source: sdk.source, valid: true },
+      provider_credentials: credentials,
+      cloudflare_connected: context?.cloudflare?.ok === true,
+      byok: context?.byok && typeof context.byok === 'object'
+        ? Object.fromEntries(Object.entries(context.byok).map(([key, value]) => [key, { configured: value?.configured === true }]))
+        : {},
+    };
+  } catch (error) {
+    return {
+      schema_version: 1,
+      authenticated: false,
+      authority: 'iam',
+      identity: null,
+      sdk_credential: { configured: true, source: sdk.source, valid: false, error: error?.message || String(error) },
+      provider_credentials: credentials,
+    };
+  }
+}
+
+export function renderWhoami(status) {
+  const lines = ['', '  Agent Sam · whoami', ''];
+  if (status.authenticated) {
+    lines.push('  authenticated  yes');
+    lines.push(`  authority      ${status.authority}`);
+    if (status.identity?.email) lines.push(`  email          ${status.identity.email}`);
+    if (status.identity?.account_id) lines.push(`  account        ${status.identity.account_id}`);
+    if (status.identity?.user_id) lines.push(`  user           ${status.identity.user_id}`);
+  } else {
+    lines.push('  authenticated  no');
+    lines.push(`  SDK key        ${status.sdk_credential?.configured ? 'present but not validated' : 'not configured'}`);
+    if (status.sdk_credential?.error) lines.push(`  error          ${status.sdk_credential.error}`);
+  }
+  lines.push('');
+  lines.push('  Provider credentials');
+  for (const row of status.provider_credentials || []) {
+    const state = row.configured ? 'available' : row.error ? `blocked (${row.error})` : 'not configured';
+    const source = row.source ? ` · ${row.source}` : '';
+    lines.push(`  ${String(row.provider).padEnd(12)} ${state}${source}`);
+  }
+  lines.push('');
+  lines.push('  Secret values are never printed by whoami.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function runWhoami(argv = [], options = {}) {
+  const allowed = new Set(['--json']);
+  const unknown = argv.filter((arg) => !allowed.has(arg));
+  if (unknown.length) throw new Error(`unknown whoami option: ${unknown[0]}`);
+  const status = await collectWhoami(options);
+  const write = options.write || ((text) => process.stdout.write(text));
+  if (argv.includes('--json')) writeLine(write, JSON.stringify(status, null, 2));
+  else write(renderWhoami(status));
+  return status;
+}

package/src/context/budget.js

@@ -19,18 +19,51 @@ function positiveInteger(value, label) {
   return value;
 }
 
+function nullablePositiveInteger(value, label) {
+  if (value == null) return null;
+  return positiveInteger(value, label);
+}
+
 export function createContextBudget(options = {}) {
   const windowTokens = positiveInteger(options.windowTokens, 'windowTokens');
   const charsPerToken = positiveNumber(options.charsPerToken ?? DEFAULT_CONTEXT_RATIOS.charsPerToken, 'charsPerToken');
-  const targetInputRatio = ratio(options.targetInputRatio ?? DEFAULT_CONTEXT_RATIOS.targetInputRatio, 'targetInputRatio');
-  const hardInputRatio = ratio(options.hardInputRatio ?? DEFAULT_CONTEXT_RATIOS.hardInputRatio, 'hardInputRatio');
+  const targetInputRatio = ratio(
+    options.targetInputRatio ?? (options.targetInputTokens ? options.targetInputTokens / windowTokens : DEFAULT_CONTEXT_RATIOS.targetInputRatio),
+    'targetInputRatio',
+  );
+  const hardInputRatio = ratio(
+    options.hardInputRatio ?? options.hardWindowRatio ?? (options.hardInputTokens ? options.hardInputTokens / windowTokens : DEFAULT_CONTEXT_RATIOS.hardInputRatio),
+    'hardInputRatio',
+  );
   if (targetInputRatio >= hardInputRatio) throw new RangeError('targetInputRatio must be lower than hardInputRatio');
 
   const windowChars = Math.floor(windowTokens * charsPerToken);
-  const targetInputTokens = Math.floor(windowTokens * targetInputRatio);
-  const hardInputTokens = Math.floor(windowTokens * hardInputRatio);
-  const targetInputChars = Math.floor(windowChars * targetInputRatio);
-  const hardInputChars = Math.floor(windowChars * hardInputRatio);
+  const targetInputTokens = positiveInteger(options.targetInputTokens ?? Math.floor(windowTokens * targetInputRatio), 'targetInputTokens');
+  const hardInputTokens = positiveInteger(options.hardInputTokens ?? Math.floor(windowTokens * hardInputRatio), 'hardInputTokens');
+  if (targetInputTokens >= hardInputTokens) throw new RangeError('targetInputTokens must be lower than hardInputTokens');
+
+  const maxNormalInputTokens = positiveInteger(options.maxNormalInputTokens ?? hardInputTokens, 'maxNormalInputTokens');
+  if (maxNormalInputTokens > hardInputTokens) throw new RangeError('maxNormalInputTokens must not exceed hardInputTokens');
+  const compactAtTokens = positiveInteger(
+    options.compactAtTokens ?? Math.floor(targetInputTokens + ((maxNormalInputTokens - targetInputTokens) * 0.4)),
+    'compactAtTokens',
+  );
+  const interveneAtTokens = positiveInteger(
+    options.interveneAtTokens ?? Math.floor(targetInputTokens + ((maxNormalInputTokens - targetInputTokens) * 0.72)),
+    'interveneAtTokens',
+  );
+  if (!(targetInputTokens <= compactAtTokens && compactAtTokens <= interveneAtTokens && interveneAtTokens <= maxNormalInputTokens)) {
+    throw new RangeError('context policy must satisfy target <= compactAt <= interveneAt <= maxNormal');
+  }
+
+  const pricingThresholdTokens = nullablePositiveInteger(options.pricingThresholdTokens, 'pricingThresholdTokens');
+  const safetyMarginTokens = Number.isInteger(options.safetyMarginTokens) && options.safetyMarginTokens >= 0
+    ? options.safetyMarginTokens
+    : pricingThresholdTokens && pricingThresholdTokens > maxNormalInputTokens
+      ? pricingThresholdTokens - maxNormalInputTokens
+      : 0;
+  const targetInputChars = Math.floor(targetInputTokens * charsPerToken);
+  const hardInputChars = Math.floor(hardInputTokens * charsPerToken);
 
   return Object.freeze({
     windowTokens,
@@ -38,8 +71,14 @@ export function createContextBudget(options = {}) {
     charsPerToken,
     targetInputRatio,
     hardInputRatio,
+    hardWindowRatio: hardInputRatio,
     targetInputTokens,
+    compactAtTokens,
+    interveneAtTokens,
+    maxNormalInputTokens,
     hardInputTokens,
+    pricingThresholdTokens,
+    safetyMarginTokens,
     targetInputChars,
     hardInputChars,
     maxSystemChars: positiveInteger(options.maxSystemChars ?? Math.max(4_000, Math.min(60_000, Math.floor(windowChars * 0.05))), 'maxSystemChars'),
@@ -56,3 +95,26 @@ export function estimateContextTokens(chars, charsPerToken = DEFAULT_CONTEXT_RAT
   if (!Number.isFinite(charsPerToken) || charsPerToken <= 0) throw new RangeError('charsPerToken must be positive');
   return Math.ceil(chars / charsPerToken);
 }
+
+export function assessContextUsage(tokens, budget) {
+  const inputTokens = Number(tokens);
+  if (!Number.isFinite(inputTokens) || inputTokens < 0) throw new RangeError('tokens must be a non-negative number');
+  if (!budget?.windowTokens) throw new TypeError('context budget is required');
+  let stage = 'normal';
+  if (inputTokens >= budget.hardInputTokens) stage = 'hard';
+  else if (inputTokens >= budget.maxNormalInputTokens) stage = 'max-normal';
+  else if (inputTokens >= budget.interveneAtTokens) stage = 'intervene';
+  else if (inputTokens >= budget.compactAtTokens) stage = 'compact';
+  else if (inputTokens >= budget.targetInputTokens) stage = 'target';
+  const pricingThresholdTokens = budget.pricingThresholdTokens ?? null;
+  return Object.freeze({
+    inputTokens: Math.ceil(inputTokens),
+    stage,
+    utilizationRatio: inputTokens / budget.windowTokens,
+    pricingThresholdTokens,
+    tokensUntilPricingThreshold: pricingThresholdTokens == null ? null : pricingThresholdTokens - Math.ceil(inputTokens),
+    pricingThresholdCrossed: pricingThresholdTokens == null ? false : inputTokens > pricingThresholdTokens,
+    shouldCompact: inputTokens >= budget.compactAtTokens,
+    shouldIntervene: inputTokens >= budget.interveneAtTokens,
+  });
+}

package/src/context/index.js

@@ -1,5 +1,7 @@
-export { DEFAULT_CONTEXT_RATIOS, createContextBudget, estimateContextTokens } from './budget.js';
+export { DEFAULT_CONTEXT_RATIOS, createContextBudget, estimateContextTokens, assessContextUsage } from './budget.js';
 export { DEFAULT_RESULT_POLICY, RESULT_DETAIL_ORDER, normalizeResultPolicy, truncateResultText, boundResultItems } from './result-policy.js';
 export { CONTEXT_ITEM_KINDS, normalizeContextItem, resolveContext, resolveProjectContext } from './resolve.js';
 export { PROJECT_RULES_FILENAME, DEFAULT_PROJECT_RULES_MAX_CHARS, defaultProjectRules, ensureProjectRules, findProjectRules, loadProjectRules } from '../lib/project-rules.js';
+export { AGENT_RUNTIME_FILENAME, AGENT_INSTRUCTION_PRECEDENCE, findAgentRuntimeContract, compileAgentInstructions } from '../lib/agent-instructions.js';
 export { DEFAULT_CONSUMED_CONTEXT_CHARS, compactContextItem, compactConsumedToolResult } from './compact.js';
+export { rehydrateContextRef } from './rehydrate.js';

package/src/context/rehydrate.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { normalizeContextItem } from './resolve.js';
+
+function sha256(value) { return `sha256:${createHash('sha256').update(String(value)).digest('hex')}`; }
+
+export async function rehydrateContextRef(ref, adapter, options = {}) {
+  const sourceRef = String(ref || '').trim();
+  if (!sourceRef) throw new TypeError('rehydrate ref is required');
+  const read = typeof adapter === 'function' ? adapter : adapter?.read?.bind(adapter);
+  if (typeof read !== 'function') throw new TypeError('rehydration adapter must provide read(ref, options)');
+  const maxChars = Number(options.maxChars ?? 64_000);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('rehydration maxChars must be a positive integer');
+
+  const raw = await read(sourceRef, { maxChars, signal: options.signal });
+  if (raw == null) throw new Error(`rehydration_source_not_found:${sourceRef}`);
+  const value = typeof raw === 'string' ? { content: raw } : raw;
+  const content = String(value.content ?? '');
+  const computedHash = sha256(content);
+  const expectedHash = String(options.expectedHash || value.hash || '').trim();
+  if (expectedHash && expectedHash.startsWith('sha256:') && expectedHash !== computedHash) {
+    throw new Error(`rehydration_hash_mismatch:${sourceRef}`);
+  }
+  const bounded = content.length > maxChars ? `${content.slice(0, Math.max(0, maxChars - 1))}…` : content;
+  const item = normalizeContextItem({
+    ref: sourceRef,
+    kind: options.kind || value.kind || 'artifact',
+    hash: expectedHash || computedHash,
+    priority: Number.isFinite(options.priority) ? options.priority : Number(value.priority || 0),
+    content: bounded,
+    chars: bounded.length,
+    truncated: bounded.length < content.length,
+    source_chars: content.length > bounded.length ? content.length : undefined,
+  });
+  return Object.freeze({ ...item, truncated: bounded.length < content.length });
+}

package/src/context/resolve.js

@@ -1,9 +1,10 @@
-import { createContextBudget, estimateContextTokens } from './budget.js';
-import { loadProjectRules } from '../lib/project-rules.js';
+import { assessContextUsage, createContextBudget, estimateContextTokens } from './budget.js';
+import { compileAgentInstructions } from '../lib/agent-instructions.js';
 
 export const CONTEXT_ITEM_KINDS = Object.freeze(['file', 'symbol', 'memory', 'tool_result', 'repo', 'artifact']);
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
+function nonNegativeInteger(value) { return Number.isInteger(value) && value >= 0 ? value : 0; }
 
 export function normalizeContextItem(value = {}) {
   const ref = clean(value.ref);
@@ -13,7 +14,17 @@ export function normalizeContextItem(value = {}) {
   const content = value.content == null ? '' : String(value.content);
   const chars = Number.isInteger(value.chars) && value.chars >= 0 ? value.chars : content.length;
   const priority = Number.isFinite(value.priority) ? Number(value.priority) : 0;
-  return Object.freeze({ ref, kind, chars, hash: clean(value.hash) || undefined, priority, content });
+  return Object.freeze({
+    ref,
+    kind,
+    chars,
+    hash: clean(value.hash) || undefined,
+    priority,
+    content,
+    ...(value.truncated === true ? { truncated: true } : {}),
+    ...(value.compacted === true ? { compacted: true } : {}),
+    ...(Number.isInteger(value.source_chars) && value.source_chars >= chars ? { source_chars: value.source_chars } : {}),
+  });
 }
 
 function capForKind(item, budget) {
@@ -35,29 +46,38 @@ export function resolveContext(options = {}) {
   const candidates = (options.items || []).map((item, index) => ({ item: normalizeContextItem(item), index }));
   candidates.sort((a, b) => (b.item.priority - a.item.priority) || (a.index - b.index));
 
-  let evidenceChars = 0;
+  let selectedChars = 0;
   let fileChars = 0;
   const included = [];
   const deferred = [];
 
   for (const row of candidates) {
     const item = row.item;
-    const remainingEvidence = budget.maxEvidenceChars - evidenceChars;
+    const remainingEvidence = budget.maxEvidenceChars - selectedChars;
     if (remainingEvidence <= 0) { deferred.push(item.ref); continue; }
     const kindCap = capForKind(item, budget);
     const remainingFile = item.kind === 'file' ? budget.maxFileCharsPerTurn - fileChars : Number.POSITIVE_INFINITY;
     const allowed = Math.floor(Math.min(kindCap, remainingEvidence, remainingFile));
     if (allowed <= 0) { deferred.push(item.ref); continue; }
     const clipped = truncate(item.content, allowed);
-    const next = Object.freeze({ ...item, content: clipped.content, chars: clipped.content.length, truncated: clipped.truncated || item.chars > clipped.content.length });
+    const next = Object.freeze({ ...item, content: clipped.content, chars: clipped.content.length, truncated: clipped.truncated || item.truncated === true || item.chars > clipped.content.length });
     included.push(next);
-    evidenceChars += next.chars;
+    selectedChars += next.chars;
     if (item.kind === 'file') fileChars += next.chars;
     if (clipped.truncated) deferred.push(`${item.ref}#remainder`);
   }
 
-  const systemChars = options.rules?.content ? String(options.rules.content).length : 0;
-  const totalChars = systemChars + evidenceChars;
+  const ruleChars = options.rules?.content ? String(options.rules.content).length : 0;
+  const instructionChars = ruleChars + nonNegativeInteger(options.instructionChars);
+  const toolSchemaChars = nonNegativeInteger(options.toolSchemaChars);
+  const historyChars = nonNegativeInteger(options.historyChars);
+  const toolResultChars = included.filter((item) => item.kind === 'tool_result').reduce((sum, item) => sum + item.chars, 0);
+  const evidenceChars = selectedChars - toolResultChars;
+  const totalChars = instructionChars + toolSchemaChars + historyChars + evidenceChars + toolResultChars;
+  const estimatedInputTokens = estimateContextTokens(totalChars, budget.charsPerToken);
+  const pressure = assessContextUsage(estimatedInputTokens, budget);
+  const rehydratable = [...new Set(included.filter((item) => item.ref).map((item) => item.ref))];
+
   return Object.freeze({
     objective,
     refs: Object.freeze(refs),
@@ -66,19 +86,31 @@ export function resolveContext(options = {}) {
     budget,
     receipt: Object.freeze({
       chars: totalChars,
+      system_chars: instructionChars,
+      instruction_chars: instructionChars,
+      tool_schema_chars: toolSchemaChars,
+      history_chars: historyChars,
       evidence_chars: evidenceChars,
-      system_chars: systemChars,
-      estimated_tokens: estimateContextTokens(totalChars, budget.charsPerToken),
+      tool_result_chars: toolResultChars,
+      estimated_tokens: estimatedInputTokens,
+      estimated_input_tokens: estimatedInputTokens,
+      window_tokens: budget.windowTokens,
+      utilization_ratio: pressure.utilizationRatio,
+      pricing_threshold_tokens: pressure.pricingThresholdTokens,
+      tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
+      pressure: pressure.stage,
+      estimate_kind: 'local',
       sources_considered: candidates.length,
       sources_included: included.length,
       sources_deferred: deferred.length,
       deferred_refs: Object.freeze(deferred),
+      rehydratable_refs: Object.freeze(rehydratable),
     }),
   });
 }
 
 export function resolveProjectContext(options = {}) {
   const budget = options.budget?.windowTokens ? options.budget : createContextBudget(options.budget || {});
-  const rules = loadProjectRules(options.cwd || process.cwd(), { maxChars: Math.min(24_000, budget.maxSystemChars) });
+  const rules = compileAgentInstructions(options.cwd || process.cwd(), { maxChars: Math.min(24_000, budget.maxSystemChars) });
   return resolveContext({ ...options, budget, rules });
 }

package/src/errors/contract.js

@@ -0,0 +1,236 @@
+export const ERROR_SCHEMA_VERSION = 1;
+
+// Mirrors google.rpc.Code / gRPC canonical status names without importing a Node gRPC runtime.
+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,
+});
+
+// Stable AgentSam-specific reasons. Add reasons deliberately; callers should not branch on messages.
+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',
+  IDENTITY_MISSING: 'identity_missing',
+  PERMISSION_DENIED: 'permission_denied',
+
+  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',
+
+  PROVIDER_UNAVAILABLE: 'provider_unavailable',
+  MODEL_NOT_FOUND: 'model_not_found',
+  POLICY_BLOCKED: 'policy_blocked',
+  COPYRIGHT_BLOCKED: 'copyright_blocked',
+
+  PERSISTENCE_FAILED: 'persistence_failed',
+  DATA_CORRUPT: 'data_corrupt',
+  DATA_LOSS: 'data_loss',
+
+  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',
+
+  CAD_CONSTRAINT_UNSATISFIED: 'cad_constraint_unsatisfied',
+  CAD_GEOMETRY_INVALID: 'cad_geometry_invalid',
+  CAD_KERNEL_FAILED: 'cad_kernel_failed',
+  CAD_EXPORT_FAILED: 'cad_export_failed',
+  CAD_RENDER_FAILED: 'cad_render_failed',
+
+  INTERNAL: 'internal',
+});
+
+const DEFAULT_HTTP_STATUS = Object.freeze({
+  [ERROR_CODE.CANCELLED]: 499,
+  [ERROR_CODE.UNKNOWN]: 500,
+  [ERROR_CODE.INVALID_ARGUMENT]: 400,
+  [ERROR_CODE.DEADLINE_EXCEEDED]: 504,
+  [ERROR_CODE.NOT_FOUND]: 404,
+  [ERROR_CODE.ALREADY_EXISTS]: 409,
+  [ERROR_CODE.PERMISSION_DENIED]: 403,
+  [ERROR_CODE.RESOURCE_EXHAUSTED]: 429,
+  [ERROR_CODE.FAILED_PRECONDITION]: 400,
+  [ERROR_CODE.ABORTED]: 409,
+  [ERROR_CODE.OUT_OF_RANGE]: 400,
+  [ERROR_CODE.UNIMPLEMENTED]: 501,
+  [ERROR_CODE.INTERNAL]: 500,
+  [ERROR_CODE.UNAVAILABLE]: 503,
+  [ERROR_CODE.DATA_LOSS]: 500,
+  [ERROR_CODE.UNAUTHENTICATED]: 401,
+});
+
+const HTTP_CODE_OVERRIDES = Object.freeze({
+  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 GRPC_CODE_BY_NUMBER = new Map(Object.entries(GRPC_STATUS).map(([name, value]) => [value, ERROR_CODE[name]]));
+
+export function canonicalCodeFromHttpStatus(status) {
+  return HTTP_CODE_OVERRIDES[Number(status)] || (Number(status) >= 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 classifyCloudflareFailure({ httpStatus, cloudflareCode } = {}) {
+  const status = Number(httpStatus || 0) || null;
+  const cf = Number(cloudflareCode || 0) || null;
+  if (cf === 1033) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE, retryable: true };
+  if (status === 521) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TRANSPORT_REFUSED, retryable: true };
+  if (status === 522 || status === 523) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TRANSPORT_UNREACHABLE, retryable: true };
+  if (status === 524) return { code: ERROR_CODE.DEADLINE_EXCEEDED, reason: ERROR_REASON.TRANSPORT_TIMEOUT, retryable: true };
+  if (status === 525) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TLS_HANDSHAKE_FAILED, retryable: false };
+  if (status === 526) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TLS_CERTIFICATE_INVALID, retryable: false };
+  if (status === 520 || status === 502) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.UPSTREAM_INVALID_RESPONSE, retryable: true };
+  if (status === 530) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TRANSPORT_UNREACHABLE, retryable: true };
+  return { code: canonicalCodeFromHttpStatus(status), reason: ERROR_REASON.UNKNOWN, retryable: status != null && status >= 500 };
+}
+
+export function classifyOAuthFailure(error) {
+  switch (String(error || '').toLowerCase()) {
+    case 'invalid_client': return { code: ERROR_CODE.UNAUTHENTICATED, reason: ERROR_REASON.AUTH_INVALID, retryable: false };
+    case 'invalid_grant': return { code: ERROR_CODE.UNAUTHENTICATED, reason: ERROR_REASON.AUTH_INVALID, retryable: false };
+    case 'unauthorized_client':
+    case 'access_denied': return { code: ERROR_CODE.PERMISSION_DENIED, reason: ERROR_REASON.PERMISSION_DENIED, retryable: false };
+    case 'invalid_scope':
+    case 'invalid_request':
+    case 'unsupported_grant_type': return { code: ERROR_CODE.INVALID_ARGUMENT, reason: ERROR_REASON.INPUT_INVALID, retryable: false };
+    default: return { code: ERROR_CODE.UNKNOWN, reason: ERROR_REASON.UNKNOWN, retryable: false };
+  }
+}
+
+export function createErrorEnvelope({
+  code = ERROR_CODE.UNKNOWN,
+  reason = ERROR_REASON.UNKNOWN,
+  message = 'Operation failed',
+  retryable = false,
+  retry_after_ms = null,
+  http_status = null,
+  grpc_status = null,
+  provider = null,
+  provider_code = null,
+  transport = null,
+  request_id = null,
+  trace_id = null,
+  resource = null,
+  details = null,
+} = {}) {
+  if (!Object.values(ERROR_CODE).includes(code)) throw new TypeError(`Unknown AgentSam error code: ${code}`);
+  if (!Object.values(ERROR_REASON).includes(reason)) throw new TypeError(`Unknown AgentSam error reason: ${reason}`);
+  const effectiveHttp = http_status == null ? defaultHttpStatusForCode(code) : Number(http_status);
+  const effectiveGrpc = grpc_status == null ? grpcStatusForCode(code) : Number(grpc_status);
+  return Object.freeze({
+    ok: false,
+    schema_version: ERROR_SCHEMA_VERSION,
+    code,
+    reason,
+    message: String(message || 'Operation failed'),
+    retryable: Boolean(retryable),
+    retry_after_ms: retry_after_ms == null ? null : Math.max(0, Number(retry_after_ms)),
+    http_status: Number.isInteger(effectiveHttp) ? effectiveHttp : null,
+    grpc_status: Number.isInteger(effectiveGrpc) ? effectiveGrpc : null,
+    provider: provider || null,
+    provider_code: provider_code || null,
+    transport: transport || null,
+    request_id: request_id || null,
+    trace_id: trace_id || null,
+    resource: resource || null,
+    details: details || null,
+  });
+}