@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/packages/agentsam-contracts/src/run.ts

@@ -0,0 +1,320 @@
+import type { AgentRunStatus } from './agent';
+
+export type AgentRunSuspensionReason =
+  | 'external'
+  | 'child_run'
+  | 'approval'
+  | 'input'
+  | 'retry'
+  | 'scheduled'
+  | 'rate_limit';
+
+export interface AgentRunSuspension {
+  runId: string;
+  state:
+    | 'waiting_external'
+    | 'waiting_child'
+    | 'awaiting_input'
+    | 'awaiting_approval'
+    | 'sleeping'
+    | 'retry_scheduled';
+  reason: AgentRunSuspensionReason;
+  wakeAt?: number;
+  wakeEvent?: string;
+  dependencyRunIds?: string[];
+  attempt?: number;
+  resumeStepId?: string;
+  checkpointRef?: string;
+  expiresAt?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export type AgentRunWakeKind = 'event' | 'dependency' | 'scheduled' | 'manual';
+
+export interface AgentRunWakeSignal {
+  id: string;
+  runId: string;
+  kind: AgentRunWakeKind;
+  occurredAt: number;
+  dedupeKey: string;
+  eventKey?: string;
+  dependencyRunId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type AgentRunRetryClass = 'transient' | 'wait' | 'replan' | 'terminal';
+
+export interface AgentRunRetryClassificationInput {
+  code?: string | null;
+  statusCode?: number | null;
+  retryable?: boolean | null;
+}
+
+export interface AgentRunRetryClassification {
+  class: AgentRunRetryClass;
+  automaticRetry: boolean;
+  reason: string;
+}
+
+const WAIT_CODES = new Set([
+  'approval_required',
+  'input_required',
+  'external_pending',
+  'dependency_pending',
+]);
+
+const REPLAN_CODES = new Set([
+  'precondition_failed',
+  'repository_changed',
+  'capability_unavailable',
+]);
+
+const TRANSIENT_CODES = new Set([
+  'timeout',
+  'request_timeout',
+  'rate_limited',
+  'provider_unavailable',
+  'runtime_unavailable',
+  'econnreset',
+  'econnrefused',
+  'etimedout',
+  'eai_again',
+]);
+
+export function classifyAgentRunRetry(input: AgentRunRetryClassificationInput = {}): AgentRunRetryClassification {
+  const code = String(input.code || '').trim().toLowerCase();
+  const statusCode = Number(input.statusCode);
+
+  if (input.retryable === true) {
+    return { class: 'transient', automaticRetry: true, reason: code || 'explicit_retryable' };
+  }
+  if (input.retryable === false) {
+    return { class: 'terminal', automaticRetry: false, reason: code || 'explicit_non_retryable' };
+  }
+  if (WAIT_CODES.has(code)) {
+    return { class: 'wait', automaticRetry: false, reason: code };
+  }
+  if (REPLAN_CODES.has(code)) {
+    return { class: 'replan', automaticRetry: false, reason: code };
+  }
+  if (TRANSIENT_CODES.has(code) || [408, 425, 429, 500, 502, 503, 504].includes(statusCode)) {
+    return { class: 'transient', automaticRetry: true, reason: code || `http_${statusCode}` };
+  }
+  return { class: 'terminal', automaticRetry: false, reason: code || 'unclassified_failure' };
+}
+
+export type AgentRunWakeDecisionReason =
+  | 'accepted'
+  | 'duplicate'
+  | 'run_mismatch'
+  | 'expired'
+  | 'condition_not_met';
+
+export interface AgentRunWakeDecision {
+  accepted: boolean;
+  reason: AgentRunWakeDecisionReason;
+  nextStatus?: 'queued';
+}
+
+export function evaluateAgentRunWake(
+  suspension: AgentRunSuspension,
+  wake: AgentRunWakeSignal,
+  options: { consumedDedupeKeys?: Iterable<string>; now?: number } = {},
+): AgentRunWakeDecision {
+  const consumed = new Set(options.consumedDedupeKeys || []);
+  if (consumed.has(wake.dedupeKey)) return { accepted: false, reason: 'duplicate' };
+  if (suspension.runId !== wake.runId) return { accepted: false, reason: 'run_mismatch' };
+
+  const now = options.now ?? wake.occurredAt;
+  if (suspension.expiresAt != null && now > suspension.expiresAt) {
+    return { accepted: false, reason: 'expired' };
+  }
+
+  const matched = wake.kind === 'manual'
+    || Boolean(suspension.wakeEvent && wake.eventKey === suspension.wakeEvent)
+    || Boolean(
+      wake.kind === 'dependency'
+      && wake.dependencyRunId
+      && (suspension.dependencyRunIds || []).includes(wake.dependencyRunId),
+    )
+    || Boolean(wake.kind === 'scheduled' && suspension.wakeAt != null && now >= suspension.wakeAt);
+
+  return matched
+    ? { accepted: true, reason: 'accepted', nextStatus: 'queued' }
+    : { accepted: false, reason: 'condition_not_met' };
+}
+
+export function wakeMatchesSuspension(
+  suspension: AgentRunSuspension,
+  wake: AgentRunWakeSignal,
+  now = wake.occurredAt,
+): boolean {
+  return evaluateAgentRunWake(suspension, wake, { now }).accepted;
+}
+
+export type AgentRunLifecycleAction =
+  | { type: 'start' }
+  | { type: 'suspend'; status: AgentRunSuspension['state'] }
+  | { type: 'wake' }
+  | { type: 'complete' }
+  | { type: 'fail' }
+  | { type: 'cancel' }
+  | { type: 'timeout' };
+
+export function transitionAgentRunStatus(status: AgentRunStatus, action: AgentRunLifecycleAction): AgentRunStatus {
+  if (status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'timed_out') {
+    return status;
+  }
+  if (action.type === 'cancel') return 'cancelled';
+  if (action.type === 'timeout') return 'timed_out';
+  if (action.type === 'complete') return 'completed';
+  if (action.type === 'fail') return 'failed';
+  if (action.type === 'suspend') return action.status;
+  if (action.type === 'wake') return 'queued';
+  if (action.type === 'start') return 'running';
+  return status;
+}
+
+export type AgentRunEventType =
+  | 'run.created'
+  | 'run.queued'
+  | 'run.started'
+  | 'run.status'
+  | 'run.suspended'
+  | 'run.woken'
+  | 'run.cancel_requested'
+  | 'run.cancelled'
+  | 'run.timed_out'
+  | 'run.failed'
+  | 'run.completed'
+  | 'step.started'
+  | 'step.progress'
+  | 'step.completed'
+  | 'decision.made'
+  | 'tool.started'
+  | 'tool.completed'
+  | 'artifact.created'
+  | 'file.changed'
+  | 'approval.required'
+  | 'input.required'
+  | 'verification.completed'
+  | (string & {});
+
+export type AgentActivityPhase =
+  | 'boot'
+  | 'observe'
+  | 'context'
+  | 'plan'
+  | 'execute'
+  | 'verify'
+  | 'compact'
+  | 'waiting'
+  | 'recover'
+  | 'complete';
+
+export type AgentActivityEventType =
+  | 'run.started'
+  | 'phase.changed'
+  | 'step.started'
+  | 'step.progress'
+  | 'step.completed'
+  | 'decision.made'
+  | 'tool.started'
+  | 'tool.completed'
+  | 'artifact.created'
+  | 'file.changed'
+  | 'approval.required'
+  | 'input.required'
+  | 'verification.completed'
+  | 'run.failed'
+  | 'run.completed';
+
+export interface AgentRunEvent {
+  id: string;
+  runId: string;
+  parentRunId?: string;
+  seq: number;
+  eventType: AgentRunEventType;
+  status?: AgentRunStatus;
+  phase?: AgentActivityPhase;
+  stepId?: string;
+  label?: string;
+  detail?: string | null;
+  progress?: { current: number; total: number } | null;
+  source?: { kind?: string; name?: string | null } | null;
+  evidence?: Record<string, unknown> | null;
+  createdAt: number;
+}
+
+export interface AgentActivityEventV1 {
+  schema: 'agentsam.activity.v1';
+  run_id: string;
+  seq: number;
+  timestamp: string;
+  phase: AgentActivityPhase;
+  event: AgentActivityEventType;
+  step_id: string | null;
+  parent_id: string | null;
+  label: string;
+  detail: string | null;
+  progress: { current: number; total: number } | null;
+  source: { kind: string; name: string | null };
+  evidence: Record<string, unknown> | null;
+}
+
+function phaseForRunEvent(event: AgentRunEvent): AgentActivityPhase {
+  if (event.phase) return event.phase;
+  if (event.eventType === 'run.created' || event.eventType === 'run.queued' || event.eventType === 'run.started') return 'boot';
+  if (event.eventType === 'run.suspended') return 'waiting';
+  if (event.eventType === 'run.woken' || event.eventType === 'run.cancel_requested') return 'recover';
+  if (event.eventType === 'verification.completed') return 'verify';
+  if (event.eventType === 'run.completed' || event.eventType === 'run.cancelled' || event.eventType === 'run.timed_out') return 'complete';
+  if (event.eventType === 'run.failed') return 'complete';
+  return 'execute';
+}
+
+function activityTypeForRunEvent(event: AgentRunEvent): AgentActivityEventType {
+  if (event.eventType === 'run.started') return 'run.started';
+  if (event.eventType === 'run.completed') return 'run.completed';
+  if (event.eventType === 'run.failed' || event.eventType === 'run.timed_out') return 'run.failed';
+  if (event.eventType === 'run.cancelled' || event.eventType === 'run.suspended' || event.eventType === 'run.woken' || event.eventType === 'run.status' || event.eventType === 'run.cancel_requested' || event.eventType === 'run.created' || event.eventType === 'run.queued') return 'phase.changed';
+  if (event.eventType === 'step.started') return 'step.started';
+  if (event.eventType === 'step.completed') return 'step.completed';
+  if (event.eventType === 'decision.made') return 'decision.made';
+  if (event.eventType === 'tool.started') return 'tool.started';
+  if (event.eventType === 'tool.completed') return 'tool.completed';
+  if (event.eventType === 'artifact.created') return 'artifact.created';
+  if (event.eventType === 'file.changed') return 'file.changed';
+  if (event.eventType === 'approval.required') return 'approval.required';
+  if (event.eventType === 'input.required') return 'input.required';
+  if (event.eventType === 'verification.completed') return 'verification.completed';
+  return 'step.progress';
+}
+
+export function projectRunEventToActivity(event: AgentRunEvent): AgentActivityEventV1 {
+  const evidence = {
+    ...(event.evidence || {}),
+    run_event_id: event.id,
+    run_event_type: event.eventType,
+    ...(event.status ? { run_status: event.status } : {}),
+  };
+
+  return {
+    schema: 'agentsam.activity.v1',
+    run_id: event.runId,
+    seq: event.seq,
+    timestamp: new Date(event.createdAt).toISOString(),
+    phase: phaseForRunEvent(event),
+    event: activityTypeForRunEvent(event),
+    step_id: event.stepId ?? null,
+    parent_id: event.parentRunId ?? null,
+    label: event.label || '',
+    detail: event.detail ?? null,
+    progress: event.progress ?? null,
+    source: {
+      kind: event.source?.kind || 'sam',
+      name: event.source?.name ?? null,
+    },
+    evidence,
+  };
+}

package/packages/agentsam-contracts/src/widgets.ts

@@ -0,0 +1,58 @@
+import type { AgentSamErrorEnvelope } from './errors';
+
+export type AgentSamWidgetSize = 'small' | 'medium' | 'large';
+
+export type AgentSamWidgetKind =
+  | 'countdown'
+  | 'clock'
+  | 'metric'
+  | 'list'
+  | 'launcher'
+  | 'brand'
+  | (string & {});
+
+export interface AgentSamWidgetDataSource {
+  /** Existing route key, tool operation id, or host-owned projection id. */
+  source: string;
+  /** Host-defined refresh class, such as realtime, short, medium, or manual. */
+  refresh?: string;
+}
+
+export interface AgentSamWidgetDefinition {
+  id: string;
+  kind: AgentSamWidgetKind;
+  title: string;
+  description?: string;
+  icon?: string;
+  sizes: readonly AgentSamWidgetSize[];
+  data?: AgentSamWidgetDataSource;
+  /** Route key or host-resolved deep link. Do not put credentials or raw provider secrets here. */
+  deeplink?: string;
+}
+
+export interface AgentSamWidgetReadyState {
+  status: 'ready';
+  updated_at?: string;
+}
+
+export interface AgentSamWidgetStaleState {
+  status: 'stale';
+  updated_at: string;
+  error: AgentSamErrorEnvelope;
+}
+
+export interface AgentSamWidgetEmptyState {
+  status: 'empty';
+  updated_at?: string;
+}
+
+export interface AgentSamWidgetErrorState {
+  status: 'error';
+  error: AgentSamErrorEnvelope;
+}
+
+export type AgentSamWidgetState =
+  | AgentSamWidgetReadyState
+  | AgentSamWidgetStaleState
+  | AgentSamWidgetEmptyState
+  | AgentSamWidgetErrorState;

package/packages/agentsam-contracts/test/contracts.test.mjs

@@ -10,7 +10,7 @@ test('contracts package stays framework neutral', async () => {
 
 test('execution-plane contracts are exported as first-class package surfaces', async () => {
   const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
-  for (const key of ['./tools', './authority', './execution', './providers', './events', './hooks']) {
+  for (const key of ['./tools', './authority', './execution', './providers', './events', './run', './hooks', './widgets']) {
     const entry = pkg.exports[key];
     assert.equal(typeof entry, 'object', `missing typed contract export: ${key}`);
     assert.match(entry.types, /^\.\/dist\/.+\.d\.ts$/);

package/packages/agentsam-contracts/test/run-contract.test.mjs

@@ -0,0 +1,94 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  classifyAgentRunRetry,
+  evaluateAgentRunWake,
+  isAgentRunModelActiveStatus,
+  isAgentRunTerminalStatus,
+  isAgentRunWaitingStatus,
+  projectRunEventToActivity,
+  transitionAgentRunStatus,
+} from '../dist/index.js';
+
+test('run lifecycle distinguishes model-active, waiting, and terminal states', () => {
+  assert.equal(isAgentRunModelActiveStatus('running'), true);
+  assert.equal(isAgentRunModelActiveStatus('waiting_external'), false);
+  assert.equal(isAgentRunWaitingStatus('waiting_child'), true);
+  assert.equal(isAgentRunTerminalStatus('timed_out'), true);
+  assert.equal(isAgentRunTerminalStatus('partial'), false);
+
+  assert.equal(transitionAgentRunStatus('queued', { type: 'start' }), 'running');
+  assert.equal(transitionAgentRunStatus('running', { type: 'suspend', status: 'waiting_external' }), 'waiting_external');
+  assert.equal(transitionAgentRunStatus('waiting_external', { type: 'wake' }), 'queued');
+  assert.equal(transitionAgentRunStatus('running', { type: 'cancel' }), 'cancelled');
+  assert.equal(transitionAgentRunStatus('running', { type: 'timeout' }), 'timed_out');
+  assert.equal(transitionAgentRunStatus('completed', { type: 'wake' }), 'completed');
+});
+
+test('wake evaluation is deterministic and rejects duplicate wake signals', () => {
+  const suspension = {
+    runId: 'run_parent',
+    state: 'waiting_child',
+    reason: 'child_run',
+    dependencyRunIds: ['run_child'],
+    expiresAt: 2_000,
+  };
+  const wake = {
+    id: 'wake_1',
+    runId: 'run_parent',
+    kind: 'dependency',
+    dependencyRunId: 'run_child',
+    occurredAt: 1_000,
+    dedupeKey: 'child:run_child:complete',
+  };
+
+  assert.deepEqual(evaluateAgentRunWake(suspension, wake), {
+    accepted: true,
+    reason: 'accepted',
+    nextStatus: 'queued',
+  });
+  assert.deepEqual(evaluateAgentRunWake(suspension, wake, {
+    consumedDedupeKeys: [wake.dedupeKey],
+  }), {
+    accepted: false,
+    reason: 'duplicate',
+  });
+  assert.equal(evaluateAgentRunWake(suspension, { ...wake, dependencyRunId: 'other' }).accepted, false);
+  assert.equal(evaluateAgentRunWake(suspension, { ...wake, occurredAt: 2_001 }, { now: 2_001 }).reason, 'expired');
+});
+
+test('retry classification only auto-retries transient failures', () => {
+  assert.deepEqual(classifyAgentRunRetry({ statusCode: 429 }), {
+    class: 'transient',
+    automaticRetry: true,
+    reason: 'http_429',
+  });
+  assert.equal(classifyAgentRunRetry({ code: 'approval_required' }).class, 'wait');
+  assert.equal(classifyAgentRunRetry({ code: 'repository_changed' }).class, 'replan');
+  assert.equal(classifyAgentRunRetry({ code: 'permission_denied' }).automaticRetry, false);
+});
+
+test('append-only run events project to agentsam.activity.v1 without losing provenance', () => {
+  const projected = projectRunEventToActivity({
+    id: 'evt_42',
+    runId: 'run_parent',
+    parentRunId: 'run_root',
+    seq: 42,
+    eventType: 'run.suspended',
+    status: 'waiting_external',
+    label: 'Waiting for deployment',
+    detail: 'Provider job is still pending',
+    createdAt: Date.parse('2026-10-03T07:00:00.000Z'),
+    source: { kind: 'queue', name: 'deployments' },
+    evidence: { provider_job_id: 'dep_123' },
+  });
+
+  assert.equal(projected.schema, 'agentsam.activity.v1');
+  assert.equal(projected.phase, 'waiting');
+  assert.equal(projected.event, 'phase.changed');
+  assert.equal(projected.parent_id, 'run_root');
+  assert.equal(projected.evidence.run_event_id, 'evt_42');
+  assert.equal(projected.evidence.run_event_type, 'run.suspended');
+  assert.equal(projected.evidence.run_status, 'waiting_external');
+});

package/packages/agentsam-errors/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@inneranimalmedia/agentsam-errors",
-  "version": "2.6.9",
+  "version": "2.6.11",
   "description": "Canonical AgentSam runtime error normalization, classification, transport, remediation and rendering.",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./catalog": "./protocol/error-catalog.json",
+    "./schema": "./protocol/agentsam.error.v2.schema.json"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"
@@ -22,7 +28,9 @@
     "directory": "packages/agentsam-errors"
   },
   "files": [
-    "src"
+    "src",
+    "types",
+    "protocol"
   ],
   "license": "MIT"
 }