@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

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/diagnostic.js

@@ -0,0 +1,160 @@
+const DEFAULT_MAX_DETAIL_CHARS = 12_000;
+const SECRET_KEY = /(?:authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|password|secret|cookie|credential)/i;
+const SECRET_VALUE_PATTERNS = [
+  /\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi,
+  /\bsk-[A-Za-z0-9_-]{12,}\b/g,
+  /\bsdk_[A-Za-z0-9_-]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+];
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function bounded(value, maxChars = DEFAULT_MAX_DETAIL_CHARS) {
+  const text = String(value ?? '');
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function redactString(value, maxChars) {
+  let text = bounded(value, maxChars);
+  for (const pattern of SECRET_VALUE_PATTERNS) text = text.replace(pattern, '[REDACTED]');
+  return text;
+}
+
+export function redactDiagnosticValue(value, options = {}, depth = 0, key = '') {
+  const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : DEFAULT_MAX_DETAIL_CHARS;
+  if (SECRET_KEY.test(key)) return '[REDACTED]';
+  if (depth > 6) return '[TRUNCATED_DEPTH]';
+  if (value == null || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'string') return redactString(value, maxChars);
+  if (Array.isArray(value)) return value.slice(0, 50).map((item) => redactDiagnosticValue(item, options, depth + 1));
+  if (typeof value === 'object') {
+    const result = {};
+    for (const [childKey, childValue] of Object.entries(value).slice(0, 80)) {
+      result[childKey] = redactDiagnosticValue(childValue, options, depth + 1, childKey);
+    }
+    return result;
+  }
+  return redactString(String(value), maxChars);
+}
+
+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) {
+  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;
+}
+
+const OPENAI_NON_RETRY_CODES = new Set([
+  'credit_balance_exhausted',
+  'organization_spend_limit_exceeded',
+  'project_spend_limit_exceeded',
+  'organization_usage_limit_exceeded',
+]);
+
+export function classifyOpenAIError({ status, type, code, message, param } = {}) {
+  const httpStatus = Number(status || 0);
+  const normalizedType = clean(type).toLowerCase();
+  const normalizedCode = clean(code).toLowerCase();
+  const diagnosticText = `${normalizedCode} ${normalizedType} ${clean(param).toLowerCase()} ${clean(message).toLowerCase()}`;
+  if (normalizedCode === 'previous_response_not_found') return { category: 'continuation', retriable: true, retry_strategy: 'retry_full_context' };
+  if (normalizedCode === 'websocket_connection_limit_reached') return { category: 'connection_lifetime', retriable: true, retry_strategy: 'reconnect' };
+  if (OPENAI_NON_RETRY_CODES.has(normalizedCode)) return { category: 'billing_or_quota', retriable: false, retry_strategy: 'operator_action' };
+  if (httpStatus === 400 && /service[_ -]?tier/.test(diagnosticText)) return { category: 'service_tier', retriable: false, retry_strategy: 'change_configuration' };
+  if (httpStatus === 400) return { category: 'invalid_request', retriable: false, retry_strategy: 'change_request' };
+  if (httpStatus === 401) return { category: 'authentication', retriable: false, retry_strategy: 'fix_credentials' };
+  if (httpStatus === 403) return { category: 'authorization_or_region', retriable: false, retry_strategy: 'operator_action' };
+  if (httpStatus === 429 && normalizedCode === 'slow_down') return { category: 'ramp_rate', retriable: true, retry_strategy: 'retry_after_backoff' };
+  if (httpStatus === 429) return { category: 'rate_limit', retriable: true, retry_strategy: 'retry_after_backoff' };
+  if (httpStatus === 500) return { category: 'provider_server', retriable: true, retry_strategy: 'retry_backoff' };
+  if (httpStatus === 503 || normalizedCode === 'server_is_overloaded') return { category: 'provider_overload', retriable: true, retry_strategy: 'retry_after_backoff' };
+  return { category: 'provider_error', retriable: false, retry_strategy: 'inspect_error' };
+}
+
+export class AgentSamDiagnosticError extends Error {
+  constructor(diagnostic, options = {}) {
+    super(clean(diagnostic?.message) || clean(options.message) || 'AgentSam operation failed', options.cause ? { cause: options.cause } : undefined);
+    this.name = 'AgentSamDiagnosticError';
+    this.diagnostic = Object.freeze({ schema_version: 1, ...diagnostic });
+    this.code = diagnostic?.code || diagnostic?.kind || 'agentsam_error';
+    this.status = diagnostic?.http_status ?? diagnostic?.status ?? null;
+  }
+}
+
+export function createOpenAIHttpError({ status, body, headers, requestedServiceTier, rawText } = {}) {
+  const payload = body && typeof body === 'object' ? body : {};
+  const providerError = payload.error && typeof payload.error === 'object' ? payload.error : payload;
+  const type = clean(providerError.type) || null;
+  const code = clean(providerError.code) || null;
+  const message = clean(providerError.message || payload.message || rawText) || `OpenAI API returned HTTP ${status}`;
+  const classification = classifyOpenAIError({ status, type, code, message, param: providerError.param });
+  const diagnostic = {
+    source: 'openai',
+    kind: 'provider_http_error',
+    http_status: Number(status || 0) || null,
+    type,
+    code,
+    param: clean(providerError.param) || null,
+    message: redactString(message, 4_000),
+    category: classification.category,
+    retriable: classification.retriable,
+    retry_strategy: classification.retry_strategy,
+    retry_after_ms: retryAfterMs(headers),
+    request_id: header(headers, 'x-request-id') || header(headers, 'openai-request-id') || header(headers, 'request-id') || null,
+    ray_id: header(headers, 'cf-ray') || null,
+    requested_service_tier: clean(requestedServiceTier) || null,
+    details: redactDiagnosticValue(payload, { maxChars: DEFAULT_MAX_DETAIL_CHARS }),
+  };
+  return new AgentSamDiagnosticError(diagnostic);
+}
+
+export function createProcessDiagnosticError({ code, message, command, args, cwd, exitCode, signal, stderr, stdout, cause, retriable = false } = {}) {
+  return new AgentSamDiagnosticError({
+    source: 'process',
+    kind: 'process_error',
+    code: clean(code) || 'process_failed',
+    message: clean(message) || 'Process failed',
+    retriable: Boolean(retriable),
+    retry_strategy: retriable ? 'retry_after_inspection' : 'inspect_error',
+    command: clean(command) || null,
+    args: Array.isArray(args) ? args.slice(0, 64).map((value) => redactString(value, 1_000)) : [],
+    cwd: clean(cwd) || null,
+    exit_code: Number.isInteger(exitCode) ? exitCode : null,
+    signal: clean(signal) || null,
+    stderr: redactString(stderr || '', 12_000) || null,
+    stdout: redactString(stdout || '', 4_000) || null,
+  }, { cause });
+}
+
+export function diagnosticFromError(error, fallback = {}) {
+  if (error?.diagnostic) return error.diagnostic;
+  return Object.freeze({
+    schema_version: 1,
+    source: fallback.source || 'agentsam',
+    kind: fallback.kind || 'runtime_error',
+    code: clean(error?.code || fallback.code) || 'runtime_error',
+    message: redactString(error?.message || error || fallback.message || 'Unknown error', 4_000),
+    http_status: Number(error?.status || fallback.status || 0) || null,
+    retriable: Boolean(fallback.retriable),
+    retry_strategy: fallback.retry_strategy || 'inspect_error',
+  });
+}
+
+export function renderDiagnosticError(error) {
+  const d = diagnosticFromError(error);
+  const identity = [d.source, d.http_status ? `HTTP ${d.http_status}` : '', d.type, d.code].filter(Boolean).join(' · ');
+  const lines = [`✗ ${d.message}`, identity ? `  ${identity}` : ''];
+  if (d.request_id) lines.push(`  request_id: ${d.request_id}`);
+  if (d.ray_id) lines.push(`  ray_id: ${d.ray_id}`);
+  if (d.retry_after_ms != null) lines.push(`  retry_after_ms: ${d.retry_after_ms}`);
+  if (d.retry_strategy) lines.push(`  retry: ${d.retriable ? 'yes' : 'no'} · ${d.retry_strategy}`);
+  return lines.filter(Boolean).join('\n');
+}

package/src/errors/index.js

@@ -0,0 +1,9 @@
+export {
+  AgentSamDiagnosticError,
+  classifyOpenAIError,
+  createOpenAIHttpError,
+  createProcessDiagnosticError,
+  diagnosticFromError,
+  redactDiagnosticValue,
+  renderDiagnosticError,
+} from './diagnostic.js';