@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

package/src/providers/openai-responses.js

@@ -0,0 +1,275 @@
+import { calculateModelCost, getModelRecord } from '../models/index.js';
+import { createAgentEvent, createUsageSnapshot } from '../telemetry/index.js';
+import { createOpenAIHttpError, diagnosticFromError } from '../errors/index.js';
+
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function integer(value) { const n = Number(value ?? 0); return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0; }
+
+function normalizeServiceTier(value, requested = 'default') {
+  const tier = clean(value).toLowerCase();
+  if (tier === 'priority') return 'fast';
+  if (tier === 'auto' || !tier) return requested === 'auto' ? 'default' : requested;
+  return tier;
+}
+
+export function extractOpenAIOutputText(response = {}) {
+  if (typeof response.output_text === 'string') return response.output_text;
+  const chunks = [];
+  for (const item of response.output || []) {
+    if (item?.type !== 'message') continue;
+    for (const content of item.content || []) {
+      if (content?.type === 'output_text' && typeof content.text === 'string') chunks.push(content.text);
+    }
+  }
+  return chunks.join('');
+}
+
+export function extractOpenAIFunctionCalls(response = {}) {
+  return (response.output || []).filter((item) => item?.type === 'function_call').map((item) => Object.freeze({
+    id: item.id || null,
+    call_id: item.call_id,
+    name: item.name,
+    arguments: item.arguments || '{}',
+    status: item.status || null,
+  }));
+}
+
+function usageParts(response = {}) {
+  const usage = response.usage || {};
+  return {
+    input_tokens: integer(usage.input_tokens),
+    cached_input_tokens: integer(usage.input_tokens_details?.cached_tokens),
+    cache_write_tokens: integer(usage.input_tokens_details?.cache_write_tokens),
+    output_tokens: integer(usage.output_tokens),
+    reasoning_tokens: integer(usage.output_tokens_details?.reasoning_tokens),
+  };
+}
+
+function errorMessage(body, status) {
+  return body?.error?.message || body?.message || `OpenAI Responses API returned HTTP ${status}`;
+}
+
+function optionalSignal(timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return undefined;
+  if (typeof AbortSignal?.timeout !== 'function') return undefined;
+  return AbortSignal.timeout(Math.floor(timeoutMs));
+}
+
+function normalizeTools(tools = []) {
+  if (!Array.isArray(tools)) throw new TypeError('tools must be an array');
+  return tools.map((tool) => {
+    if (tool?.type !== 'function' || !clean(tool.name)) throw new TypeError('OpenAI adapter tools must be Responses function tool descriptors');
+    return {
+      type: 'function',
+      name: clean(tool.name),
+      description: clean(tool.description) || undefined,
+      parameters: tool.parameters || { type: 'object', properties: {} },
+      strict: tool.strict !== false,
+      ...(tool.async === true ? { async: true } : {}),
+    };
+  });
+}
+
+function assertRuntimeConfig(model, reasoningEffort, serviceTier) {
+  const record = getModelRecord(model);
+  if (!record || record.provider !== 'openai') throw new RangeError(`unsupported OpenAI model catalog entry: ${model}`);
+  if (!record.reasoning_efforts.includes(reasoningEffort)) throw new RangeError(`unsupported reasoning effort for ${record.provider_model_id}: ${reasoningEffort}`);
+  if (!record.service_tiers.includes(serviceTier)) throw new RangeError(`unsupported service tier for ${record.provider_model_id}: ${serviceTier}`);
+  return record;
+}
+
+function emitEvent(emit, type, payload, meta = {}) {
+  if (typeof emit !== 'function') return;
+  emit(createAgentEvent(type, payload, meta));
+}
+
+export function createOpenAIResponsesAdapter(options = {}) {
+  const apiKey = clean(options.apiKey || process.env.OPENAI_API_KEY);
+  const baseUrl = clean(options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+  const fetchImpl = options.fetchImpl || fetch;
+  const defaultEmit = options.emit;
+  const timeoutMs = options.timeoutMs;
+
+  async function request(pathname, body, runtime = {}) {
+    if (!apiKey) throw new Error('OPENAI_API_KEY is required for OpenAI Responses execution');
+    const response = await fetchImpl(`${baseUrl}${pathname}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: optionalSignal(runtime.timeoutMs ?? timeoutMs),
+    });
+    let rawText = '';
+    let parsed = null;
+    if (typeof response.text === 'function') {
+      try { rawText = await response.text(); } catch { rawText = ''; }
+      if (rawText) {
+        try { parsed = JSON.parse(rawText); } catch { parsed = null; }
+      }
+    } else if (typeof response.json === 'function') {
+      try {
+        parsed = await response.json();
+        rawText = JSON.stringify(parsed ?? null);
+      } catch {
+        parsed = null;
+        rawText = '';
+      }
+    }
+    if (!response.ok) {
+      throw createOpenAIHttpError({
+        status: response.status,
+        body: parsed,
+        rawText,
+        headers: response.headers,
+        requestedServiceTier: body?.service_tier,
+      });
+    }
+    return Object.freeze({
+      data: parsed ?? {},
+      http: Object.freeze({
+        status: response.status,
+        request_id: clean(response.headers?.get?.('x-request-id') || response.headers?.get?.('openai-request-id')) || null,
+        ray_id: clean(response.headers?.get?.('cf-ray')) || null,
+      }),
+    });
+  }
+
+  async function create(params = {}) {
+    const modelRecord = getModelRecord(params.model);
+    const model = modelRecord?.provider_model_id || clean(params.model);
+    const reasoningEffort = clean(params.reasoningEffort || params.reasoning_effort || 'low');
+    const serviceTier = clean(params.serviceTier || params.service_tier || 'default');
+    const record = assertRuntimeConfig(model, reasoningEffort, serviceTier);
+    const emit = params.emit || defaultEmit;
+    const meta = { runId: params.runId, sequence: params.sequence };
+    const tools = normalizeTools(params.tools || []);
+    const body = {
+      model,
+      input: params.input ?? '',
+      reasoning: { effort: reasoningEffort },
+      service_tier: serviceTier,
+      store: params.store !== false,
+      truncation: 'disabled',
+      parallel_tool_calls: params.parallelToolCalls !== false,
+      ...(clean(params.instructions) ? { instructions: String(params.instructions) } : {}),
+      ...(tools.length ? { tools } : {}),
+      ...(clean(params.previousResponseId) ? { previous_response_id: clean(params.previousResponseId) } : {}),
+      ...(Number.isInteger(params.maxOutputTokens) && params.maxOutputTokens > 0 ? { max_output_tokens: params.maxOutputTokens } : {}),
+      ...(clean(params.promptCacheKey) ? { prompt_cache_key: clean(params.promptCacheKey) } : {}),
+      ...(params.promptCacheOptions ? { prompt_cache_options: params.promptCacheOptions } : {}),
+      ...(params.metadata ? { metadata: params.metadata } : {}),
+      ...(params.background === true ? { background: true } : {}),
+    };
+
+    emitEvent(emit, 'model.started', {
+      provider: 'openai', model, reasoning_effort: reasoningEffort, requested_service_tier: serviceTier,
+    }, meta);
+
+    let response;
+    let http;
+    try {
+      const result = await request('/responses', body, params);
+      response = result.data;
+      http = result.http;
+    } catch (error) {
+      const diagnostic = diagnosticFromError(error, { source: 'openai', kind: 'provider_error' });
+      emitEvent(emit, 'error.observed', diagnostic, meta);
+      emitEvent(emit, 'run.failed', { stage: 'model', provider: 'openai', model, error: diagnostic }, meta);
+      throw error;
+    }
+
+    const delta = usageParts(response);
+    const actualServiceTier = normalizeServiceTier(response.service_tier, serviceTier);
+    const cost = calculateModelCost(record, { ...delta, estimate_kind: 'provider' }, { serviceTier: actualServiceTier });
+    const usageSnapshot = createUsageSnapshot({
+      current_context: { input_tokens: delta.input_tokens, window_tokens: record.context_window },
+      cumulative: params.cumulativeUsage ? {
+        input_tokens: integer(params.cumulativeUsage.input_tokens) + delta.input_tokens,
+        output_tokens: integer(params.cumulativeUsage.output_tokens) + delta.output_tokens,
+        cached_input_tokens: integer(params.cumulativeUsage.cached_input_tokens) + delta.cached_input_tokens,
+        cache_write_tokens: integer(params.cumulativeUsage.cache_write_tokens) + delta.cache_write_tokens,
+        reasoning_tokens: integer(params.cumulativeUsage.reasoning_tokens) + delta.reasoning_tokens,
+      } : delta,
+      estimate_kind: 'provider',
+    });
+
+    emitEvent(emit, 'usage.snapshot', usageSnapshot, meta);
+    emitEvent(emit, 'cost.snapshot', cost, meta);
+    emitEvent(emit, 'model.completed', {
+      provider: 'openai', model, response_id: response.id, status: response.status,
+      request_id: http?.request_id || null, ray_id: http?.ray_id || null,
+      requested_service_tier: serviceTier, actual_service_tier: actualServiceTier,
+    }, meta);
+
+    return Object.freeze({
+      provider: 'openai',
+      model,
+      response_id: response.id,
+      status: response.status,
+      request_id: http?.request_id || null,
+      ray_id: http?.ray_id || null,
+      output_text: extractOpenAIOutputText(response),
+      tool_calls: Object.freeze(extractOpenAIFunctionCalls(response)),
+      usage_delta: Object.freeze(delta),
+      usage_snapshot: usageSnapshot,
+      cost,
+      requested_service_tier: serviceTier,
+      actual_service_tier: actualServiceTier,
+      raw: response,
+    });
+  }
+
+  async function continueWithToolOutputs(params = {}) {
+    const previousResponseId = clean(params.previousResponseId);
+    if (!previousResponseId) throw new TypeError('previousResponseId is required');
+    const outputs = (params.toolOutputs || []).map((row) => {
+      const callId = clean(row.call_id || row.callId);
+      if (!callId) throw new TypeError('tool output call_id is required');
+      const output = typeof row.output === 'string' ? row.output : JSON.stringify(row.output ?? null);
+      return { type: 'function_call_output', call_id: callId, output };
+    });
+    if (!outputs.length) throw new TypeError('at least one tool output is required');
+    return create({ ...params, previousResponseId, input: outputs });
+  }
+
+  async function compact(params = {}) {
+    const modelRecord = getModelRecord(params.model);
+    const model = modelRecord?.provider_model_id || clean(params.model);
+    if (!modelRecord || modelRecord.provider !== 'openai') throw new RangeError(`unsupported OpenAI model catalog entry: ${params.model}`);
+    const emit = params.emit || defaultEmit;
+    const meta = { runId: params.runId, sequence: params.sequence };
+    const body = {
+      model,
+      ...(clean(params.previousResponseId) ? { previous_response_id: clean(params.previousResponseId) } : {}),
+      ...(params.input != null ? { input: params.input } : {}),
+      ...(clean(params.instructions) ? { instructions: String(params.instructions) } : {}),
+      ...(clean(params.promptCacheKey) ? { prompt_cache_key: clean(params.promptCacheKey) } : {}),
+      ...(params.promptCacheOptions ? { prompt_cache_options: params.promptCacheOptions } : {}),
+    };
+    emitEvent(emit, 'context.compaction.started', { provider: 'openai', model, previous_response_id: body.previous_response_id || null }, meta);
+    let response;
+    let http;
+    try {
+      const result = await request('/responses/compact', body, params);
+      response = result.data;
+      http = result.http;
+    } catch (error) {
+      const diagnostic = diagnosticFromError(error, { source: 'openai', kind: 'provider_error' });
+      emitEvent(emit, 'error.observed', diagnostic, meta);
+      emitEvent(emit, 'run.failed', { stage: 'compaction', provider: 'openai', model, error: diagnostic }, meta);
+      throw error;
+    }
+    emitEvent(emit, 'context.compaction.completed', {
+      provider: 'openai', model, compaction_id: response.id, usage: response.usage || null,
+      request_id: http?.request_id || null, ray_id: http?.ray_id || null,
+    }, meta);
+    return Object.freeze({
+      provider: 'openai', model, compaction_id: response.id,
+      request_id: http?.request_id || null, ray_id: http?.ray_id || null,
+      output: Object.freeze(response.output || []), usage: response.usage || null, raw: response,
+    });
+  }
+
+  return Object.freeze({ provider: 'openai', create, continueWithToolOutputs, compact });
+}

package/src/security/process.js

@@ -1,31 +1,57 @@
 import { spawn } from 'node:child_process';
+import { createProcessDiagnosticError } from '../errors/index.js';
 
 export function runProcess(command, args, { cwd, timeoutMs = 300_000, signal, env = process.env, maxBytes = 8 * 1024 * 1024 } = {}) {
   return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(new Error('Command cancelled'));
-    const child = spawn(command, args, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    const safeArgs = Array.isArray(args) ? args : [];
+    const diagnostic = (code, message, extra = {}) => createProcessDiagnosticError({
+      code,
+      message,
+      command,
+      args: safeArgs,
+      cwd,
+      stdout,
+      stderr,
+      ...extra,
+    });
     let stdout = '', stderr = '', size = 0, failure, hardKill;
+    if (signal?.aborted) return reject(createProcessDiagnosticError({ code: 'process_cancelled', message: 'Command cancelled', command, args: safeArgs, cwd }));
+    const child = spawn(command, safeArgs, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
     function kill(sig) {
       try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, sig); } catch { /* already exited */ }
     }
-    function stop(reason) {
+    function stop(error) {
       if (failure) return;
-      failure = reason;
+      failure = error;
       kill('SIGTERM');
       hardKill = setTimeout(() => kill('SIGKILL'), 1000);
     }
-    const timer = setTimeout(() => stop('Command timed out'), timeoutMs);
-    const abort = () => stop('Command cancelled');
+    const timer = setTimeout(() => stop(diagnostic('process_timeout', 'Command timed out', { retriable: false })), timeoutMs);
+    const abort = () => stop(diagnostic('process_cancelled', 'Command cancelled'));
     signal?.addEventListener('abort', abort, { once: true });
     const receive = (key) => chunk => {
       size += chunk.length;
-      if (size > maxBytes) return stop('Command output exceeded 8 MiB');
+      if (size > maxBytes) return stop(diagnostic('process_output_limit', `Command output exceeded ${maxBytes} bytes`));
       if (key === 'stdout') stdout += chunk.toString(); else stderr += chunk.toString();
     };
     child.stdout.on('data', receive('stdout'));
     child.stderr.on('data', receive('stderr'));
     const cleanup = () => { clearTimeout(timer); clearTimeout(hardKill); signal?.removeEventListener('abort', abort); };
-    child.on('error', () => { cleanup(); reject(new Error('Cannot start requested command')); });
-    child.on('close', code => { cleanup(); failure ? reject(new Error(failure)) : resolve({ code: code ?? 1, stdout, stderr }); });
+    child.on('error', (cause) => {
+      cleanup();
+      reject(createProcessDiagnosticError({
+        code: cause?.code || 'process_spawn_failed',
+        message: cause?.message || 'Cannot start requested command',
+        command,
+        args: safeArgs,
+        cwd,
+        cause,
+      }));
+    });
+    child.on('close', (code, closeSignal) => {
+      cleanup();
+      if (failure) return reject(failure);
+      resolve({ code: code ?? 1, signal: closeSignal || null, stdout, stderr });
+    });
   });
 }

package/src/telemetry/contracts.js

@@ -0,0 +1,203 @@
+export const RUNTIME_RECEIPT_SCHEMA_VERSION = 1;
+
+const RUN_MODES = new Set(['ask', 'plan', 'agent', 'debug', 'multitask']);
+const RUN_STATUSES = new Set(['queued', 'running', 'completed', 'failed', 'partial', 'cancelled']);
+const APPROVAL_STATUSES = new Set(['pending', 'approved', 'denied', 'expired']);
+const TERMINAL_STATUSES = new Set(['queued', 'running', 'completed', 'failed', 'cancelled', 'unknown']);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function required(value, label) {
+  const text = clean(value);
+  if (!text) throw new TypeError(`${label} is required`);
+  return text;
+}
+
+function optional(value) {
+  const text = clean(value);
+  return text || null;
+}
+
+function nonNegativeInteger(value, fallback = 0) {
+  const number = Number(value ?? fallback);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError('expected a non-negative number');
+  return Math.floor(number);
+}
+
+function optionalNonNegativeInteger(value) {
+  if (value == null || value === '') return null;
+  return nonNegativeInteger(value);
+}
+
+function nonNegativeNumber(value, fallback = 0) {
+  const number = Number(value ?? fallback);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError('expected a non-negative number');
+  return number;
+}
+
+function canonicalMode(value) {
+  const mode = clean(value || 'agent').toLowerCase();
+  if (!RUN_MODES.has(mode)) throw new RangeError(`unsupported run mode: ${mode}`);
+  return mode;
+}
+
+function canonicalRunStatus(value) {
+  const status = clean(value || 'queued').toLowerCase();
+  if (!RUN_STATUSES.has(status)) throw new RangeError(`unsupported run status: ${status}`);
+  return status;
+}
+
+function jsonText(value, fallback) {
+  if (value == null || value === '') return JSON.stringify(fallback);
+  if (typeof value === 'string') {
+    JSON.parse(value);
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Provider-neutral execution receipt. The authenticated host supplies account_id;
+ * tenant/workspace/user aliases are deliberately not part of this contract.
+ */
+export function createRunReceipt(value = {}) {
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id ?? value.run_id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    conversation_id: optional(value.conversation_id ?? value.conversationId),
+    external_agent_id: optional(value.external_agent_id ?? value.externalAgentId),
+    parent_run_id: optional(value.parent_run_id ?? value.parentRunId),
+    source_client: optional(value.source_client ?? value.sourceClient),
+    surface: optional(value.surface),
+    mode: canonicalMode(value.mode),
+    model_key: optional(value.model_key ?? value.modelKey),
+    reasoning_effort: optional(value.reasoning_effort ?? value.reasoningEffort),
+    requested_service_tier: optional(value.requested_service_tier ?? value.requestedServiceTier),
+    actual_service_tier: optional(value.actual_service_tier ?? value.actualServiceTier),
+    selected_by: optional(value.selected_by ?? value.selectedBy),
+    routing_arm_id: optional(value.routing_arm_id ?? value.routingArmId),
+    status: canonicalRunStatus(value.status),
+    cancel_requested: value.cancel_requested === true || value.cancel_requested === 1 ? 1 : 0,
+    error_code: optional(value.error_code ?? value.errorCode),
+    error_message: optional(value.error_message ?? value.errorMessage),
+    model_call_count: nonNegativeInteger(value.model_call_count ?? value.modelCallCount),
+    tool_call_count: nonNegativeInteger(value.tool_call_count ?? value.toolCallCount),
+    input_tokens: nonNegativeInteger(value.input_tokens ?? value.inputTokens),
+    cached_input_tokens: nonNegativeInteger(value.cached_input_tokens ?? value.cachedInputTokens),
+    output_tokens: nonNegativeInteger(value.output_tokens ?? value.outputTokens),
+    reasoning_tokens: nonNegativeInteger(value.reasoning_tokens ?? value.reasoningTokens),
+    cost_usd: nonNegativeNumber(value.cost_usd ?? value.costUsd),
+    created_at_unix: optionalNonNegativeInteger(value.created_at_unix ?? value.createdAtUnix),
+    started_at_unix: optionalNonNegativeInteger(value.started_at_unix ?? value.startedAtUnix),
+    completed_at_unix: optionalNonNegativeInteger(value.completed_at_unix ?? value.completedAtUnix),
+    updated_at_unix: optionalNonNegativeInteger(value.updated_at_unix ?? value.updatedAtUnix),
+    latency_ms: optionalNonNegativeInteger(value.latency_ms ?? value.latencyMs),
+  });
+}
+
+/** One authoritative provider/model call receipt. */
+export function createUsageReceipt(value = {}) {
+  const inputTokens = nonNegativeInteger(value.input_tokens ?? value.inputTokens);
+  const cachedInputTokens = nonNegativeInteger(value.cached_input_tokens ?? value.cachedInputTokens);
+  const cacheWriteTokens = nonNegativeInteger(value.cache_write_tokens ?? value.cacheWriteTokens);
+  const outputTokens = nonNegativeInteger(value.output_tokens ?? value.outputTokens);
+  const reasoningTokens = nonNegativeInteger(value.reasoning_tokens ?? value.reasoningTokens);
+  const totalTokens = value.total_tokens == null && value.totalTokens == null
+    ? inputTokens + outputTokens
+    : nonNegativeInteger(value.total_tokens ?? value.totalTokens);
+
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    agent_run_id: optional(value.agent_run_id ?? value.agentRunId),
+    conversation_id: optional(value.conversation_id ?? value.conversationId),
+    repository_id: optional(value.repository_id ?? value.repositoryId),
+    source_client: optional(value.source_client ?? value.sourceClient),
+    usage_kind: optional(value.usage_kind ?? value.usageKind) || 'model',
+    provider: required(value.provider, 'provider'),
+    model_key: required(value.model_key ?? value.modelKey, 'model_key'),
+    model_call_index: optionalNonNegativeInteger(value.model_call_index ?? value.modelCallIndex),
+    provider_request_id: optional(value.provider_request_id ?? value.providerRequestId),
+    requested_service_tier: optional(value.requested_service_tier ?? value.requestedServiceTier),
+    actual_service_tier: optional(value.actual_service_tier ?? value.actualServiceTier),
+    input_tokens: inputTokens,
+    cached_input_tokens: cachedInputTokens,
+    cache_write_tokens: cacheWriteTokens,
+    output_tokens: outputTokens,
+    reasoning_tokens: reasoningTokens,
+    total_tokens: totalTokens,
+    cost_usd: nonNegativeNumber(value.cost_usd ?? value.costUsd),
+    cost_basis: optional(value.cost_basis ?? value.costBasis),
+    duration_ms: optionalNonNegativeInteger(value.duration_ms ?? value.durationMs),
+    status: optional(value.status) || 'ok',
+    error_code: optional(value.error_code ?? value.errorCode),
+    ref_table: optional(value.ref_table ?? value.refTable),
+    ref_id: optional(value.ref_id ?? value.refId),
+    created_at_unix: optionalNonNegativeInteger(value.created_at_unix ?? value.createdAtUnix),
+  });
+}
+
+/** Approval receipt linked to execution/tool/process lineage without ownership aliases. */
+export function createApprovalReceipt(value = {}) {
+  const status = clean(value.status || 'pending').toLowerCase();
+  if (!APPROVAL_STATUSES.has(status)) throw new RangeError(`unsupported approval status: ${status}`);
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    agent_run_id: optional(value.agent_run_id ?? value.agentRunId),
+    tool_call_id: optional(value.tool_call_id ?? value.toolCallId),
+    terminal_job_id: optional(value.terminal_job_id ?? value.terminalJobId),
+    conversation_id: optional(value.conversation_id ?? value.conversationId),
+    capability_key: optional(value.capability_key ?? value.capabilityKey),
+    tool_key: optional(value.tool_key ?? value.toolKey),
+    action_summary: required(value.action_summary ?? value.actionSummary, 'action_summary'),
+    sanitized_input_json: jsonText(value.sanitized_input_json ?? value.sanitizedInput, {}),
+    risk_level: optional(value.risk_level ?? value.riskLevel) || 'medium',
+    approval_type: optional(value.approval_type ?? value.approvalType) || 'tool',
+    status,
+    response_json: jsonText(value.response_json ?? value.response, {}),
+    approved_by: optional(value.approved_by ?? value.approvedBy),
+    created_at: optionalNonNegativeInteger(value.created_at ?? value.createdAt),
+    expires_at: optionalNonNegativeInteger(value.expires_at ?? value.expiresAt),
+    decided_at: optionalNonNegativeInteger(value.decided_at ?? value.decidedAt),
+    metadata_json: jsonText(value.metadata_json ?? value.metadata, {}),
+  });
+}
+
+/** Thin durable process-control receipt; full terminal transcripts stay elsewhere. */
+export function createTerminalJobReceipt(value = {}) {
+  const status = clean(value.status || 'queued').toLowerCase();
+  if (!TERMINAL_STATUSES.has(status)) throw new RangeError(`unsupported terminal job status: ${status}`);
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    instance_id: required(value.instance_id ?? value.instanceId, 'instance_id'),
+    connection_id: required(value.connection_id ?? value.connectionId, 'connection_id'),
+    session_id: optional(value.session_id ?? value.sessionId),
+    source_run_id: optional(value.source_run_id ?? value.sourceRunId),
+    tool_call_id: optional(value.tool_call_id ?? value.toolCallId),
+    execos_run_id: optional(value.execos_run_id ?? value.execosRunId),
+    status,
+    cwd: optional(value.cwd),
+    timeout_ms: optionalNonNegativeInteger(value.timeout_ms ?? value.timeoutMs),
+    exit_code: value.exit_code == null && value.exitCode == null ? null : Number(value.exit_code ?? value.exitCode),
+    failure_code: optional(value.failure_code ?? value.failureCode),
+    log_ref: optional(value.log_ref ?? value.logRef),
+    output_artifact_ref: optional(value.output_artifact_ref ?? value.outputArtifactRef),
+    artifact_refs_json: jsonText(value.artifact_refs_json ?? value.artifactRefs, []),
+    idempotency_key: optional(value.idempotency_key ?? value.idempotencyKey),
+    attempt: nonNegativeInteger(value.attempt),
+    max_attempts: Math.max(1, nonNegativeInteger(value.max_attempts ?? value.maxAttempts, 1)),
+    last_observed_at: optionalNonNegativeInteger(value.last_observed_at ?? value.lastObservedAt),
+    created_at: optionalNonNegativeInteger(value.created_at ?? value.createdAt),
+    started_at: optionalNonNegativeInteger(value.started_at ?? value.startedAt),
+    finished_at: optionalNonNegativeInteger(value.finished_at ?? value.finishedAt),
+    updated_at: optionalNonNegativeInteger(value.updated_at ?? value.updatedAt),
+  });
+}

package/src/telemetry/events.js

@@ -0,0 +1,48 @@
+export const AGENT_EVENT_TYPES = Object.freeze([
+  'run.started', 'run.status', 'run.completed', 'run.failed',
+  'error.observed',
+  'model.started', 'model.delta', 'model.completed',
+  'usage.snapshot', 'cost.snapshot',
+  'context.snapshot', 'context.compaction.started', 'context.compaction.completed',
+  'tool.search', 'tool.started', 'tool.completed', 'tool.failed',
+  'task.updated',
+]);
+
+function integer(value, label) {
+  const number = Number(value ?? 0);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError(`${label} must be a non-negative number`);
+  return Math.floor(number);
+}
+
+export function createAgentEvent(type, payload = {}, options = {}) {
+  if (!AGENT_EVENT_TYPES.includes(type)) throw new RangeError(`unsupported AgentEvent type: ${type}`);
+  const event = {
+    schema_version: 1,
+    type,
+    timestamp: options.timestamp || new Date().toISOString(),
+    ...(options.runId ? { run_id: String(options.runId) } : {}),
+    ...(Number.isInteger(options.sequence) && options.sequence >= 0 ? { sequence: options.sequence } : {}),
+    payload: payload && typeof payload === 'object' ? payload : { value: payload },
+  };
+  JSON.stringify(event);
+  return Object.freeze(event);
+}
+
+export function createUsageSnapshot(value = {}) {
+  const estimateKind = value.estimate_kind === 'provider' ? 'provider' : 'local';
+  return Object.freeze({
+    current_context: Object.freeze({
+      input_tokens: integer(value.current_context?.input_tokens ?? value.currentContextTokens, 'current_context.input_tokens'),
+      window_tokens: integer(value.current_context?.window_tokens ?? value.windowTokens, 'current_context.window_tokens'),
+    }),
+    cumulative: Object.freeze({
+      input_tokens: integer(value.cumulative?.input_tokens ?? value.inputTokens, 'cumulative.input_tokens'),
+      output_tokens: integer(value.cumulative?.output_tokens ?? value.outputTokens, 'cumulative.output_tokens'),
+      cached_input_tokens: integer(value.cumulative?.cached_input_tokens ?? value.cachedInputTokens, 'cumulative.cached_input_tokens'),
+      cache_write_tokens: integer(value.cumulative?.cache_write_tokens ?? value.cacheWriteTokens, 'cumulative.cache_write_tokens'),
+      reasoning_tokens: integer(value.cumulative?.reasoning_tokens ?? value.reasoningTokens, 'cumulative.reasoning_tokens'),
+    }),
+    estimate_kind: estimateKind,
+    provider_authoritative: estimateKind === 'provider',
+  });
+}

package/src/telemetry/index.js

@@ -0,0 +1,8 @@
+export { AGENT_EVENT_TYPES, createAgentEvent, createUsageSnapshot } from './events.js';
+export {
+  RUNTIME_RECEIPT_SCHEMA_VERSION,
+  createRunReceipt,
+  createUsageReceipt,
+  createApprovalReceipt,
+  createTerminalJobReceipt,
+} from './contracts.js';

package/src/tools/hydrate.js

@@ -0,0 +1,35 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function hydrateToolSchemas(catalog = [], selected = [], options = {}) {
+  if (!Array.isArray(catalog)) throw new TypeError('catalog must be an array');
+  if (!Array.isArray(selected)) throw new TypeError('selected must be an array');
+  const maxTools = Number.isInteger(options.maxTools) && options.maxTools > 0 ? options.maxTools : 8;
+  const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : 40_000;
+  const wanted = [...new Set(selected.map(clean).filter(Boolean))].slice(0, maxTools);
+  const byName = new Map(catalog.map((tool) => [clean(tool.tool || tool.name), tool]).filter(([name]) => name));
+  const tools = [];
+  const missing = [];
+  const deferred = [];
+  let schemaChars = 0;
+
+  for (const name of wanted) {
+    const tool = byName.get(name);
+    if (!tool) { missing.push(name); continue; }
+    const size = JSON.stringify(tool).length;
+    if (schemaChars + size > maxChars) { deferred.push(name); continue; }
+    tools.push(Object.freeze({ ...tool }));
+    schemaChars += size;
+  }
+
+  return Object.freeze({
+    tools: Object.freeze(tools),
+    receipt: Object.freeze({
+      catalog_items: catalog.length,
+      requested_tools: wanted.length,
+      hydrated_tools: tools.length,
+      schema_chars: schemaChars,
+      missing_tools: Object.freeze(missing),
+      deferred_tools: Object.freeze(deferred),
+    }),
+  });
+}

package/src/tools/index.js

@@ -1 +1,2 @@
 export { searchToolCards, toToolCard } from './search.js';
+export { hydrateToolSchemas } from './hydrate.js';