@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/packages/agentsam-contracts/dist/run.d.ts

@@ -0,0 +1,113 @@
+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;
+}
+export declare function classifyAgentRunRetry(input?: AgentRunRetryClassificationInput): AgentRunRetryClassification;
+export type AgentRunWakeDecisionReason = 'accepted' | 'duplicate' | 'run_mismatch' | 'expired' | 'condition_not_met';
+export interface AgentRunWakeDecision {
+    accepted: boolean;
+    reason: AgentRunWakeDecisionReason;
+    nextStatus?: 'queued';
+}
+export declare function evaluateAgentRunWake(suspension: AgentRunSuspension, wake: AgentRunWakeSignal, options?: {
+    consumedDedupeKeys?: Iterable<string>;
+    now?: number;
+}): AgentRunWakeDecision;
+export declare function wakeMatchesSuspension(suspension: AgentRunSuspension, wake: AgentRunWakeSignal, now?: number): boolean;
+export type AgentRunLifecycleAction = {
+    type: 'start';
+} | {
+    type: 'suspend';
+    status: AgentRunSuspension['state'];
+} | {
+    type: 'wake';
+} | {
+    type: 'complete';
+} | {
+    type: 'fail';
+} | {
+    type: 'cancel';
+} | {
+    type: 'timeout';
+};
+export declare function transitionAgentRunStatus(status: AgentRunStatus, action: AgentRunLifecycleAction): AgentRunStatus;
+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;
+}
+export declare function projectRunEventToActivity(event: AgentRunEvent): AgentActivityEventV1;

package/packages/agentsam-contracts/dist/run.js

@@ -0,0 +1,132 @@
+// src/run.ts
+var WAIT_CODES = /* @__PURE__ */ new Set([
+  "approval_required",
+  "input_required",
+  "external_pending",
+  "dependency_pending"
+]);
+var REPLAN_CODES = /* @__PURE__ */ new Set([
+  "precondition_failed",
+  "repository_changed",
+  "capability_unavailable"
+]);
+var TRANSIENT_CODES = /* @__PURE__ */ new Set([
+  "timeout",
+  "request_timeout",
+  "rate_limited",
+  "provider_unavailable",
+  "runtime_unavailable",
+  "econnreset",
+  "econnrefused",
+  "etimedout",
+  "eai_again"
+]);
+function classifyAgentRunRetry(input = {}) {
+  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" };
+}
+function evaluateAgentRunWake(suspension, wake, options = {}) {
+  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" };
+}
+function wakeMatchesSuspension(suspension, wake, now = wake.occurredAt) {
+  return evaluateAgentRunWake(suspension, wake, { now }).accepted;
+}
+function transitionAgentRunStatus(status, action) {
+  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;
+}
+function phaseForRunEvent(event) {
+  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) {
+  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";
+}
+function projectRunEventToActivity(event) {
+  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
+  };
+}
+export {
+  classifyAgentRunRetry,
+  evaluateAgentRunWake,
+  projectRunEventToActivity,
+  transitionAgentRunStatus,
+  wakeMatchesSuspension
+};

package/packages/agentsam-contracts/dist/tools.d.ts

@@ -0,0 +1,82 @@
+import type { AgentAuthorityRequirement } from './authority';
+export interface AgentCapability {
+    id: string;
+    label?: string;
+    description?: string;
+    enabled?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export type AgentJsonSchema = Record<string, unknown>;
+export type AgentToolSideEffectLevel = 'none' | 'local_write' | 'external_write' | 'billable_external_write' | 'destructive_possible';
+export type AgentToolRiskLevel = 'low' | 'moderate' | 'high' | 'critical';
+export type AgentToolReceiptMode = 'full' | 'redacted' | 'metadata_only';
+export type AgentToolIdempotencyMode = 'not_applicable' | 'intrinsic' | 'supported' | 'required';
+export type AgentToolHandlerType = 'local' | 'http' | 'worker_rpc' | 'execos' | 'mcp' | 'custom';
+export interface AgentToolHandlerReference {
+    type: AgentToolHandlerType;
+    ref: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentToolRetryPolicy {
+    maxAttempts: number;
+    backoff?: 'none' | 'fixed' | 'exponential';
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    retryableReasons?: string[];
+}
+export interface AgentToolDefinition {
+    toolKey: string;
+    displayName: string;
+    description?: string;
+    provider?: string;
+    pluginId?: string;
+    capabilityKey: string;
+    handler?: AgentToolHandlerReference;
+    inputSchema: AgentJsonSchema;
+    outputSchema: AgentJsonSchema;
+    authority?: AgentAuthorityRequirement[];
+    riskLevel: AgentToolRiskLevel;
+    sideEffectLevel: AgentToolSideEffectLevel;
+    idempotencyMode: AgentToolIdempotencyMode;
+    timeoutMs?: number;
+    retryPolicy?: AgentToolRetryPolicy;
+    receiptMode?: AgentToolReceiptMode;
+    sensitiveInputPaths?: string[];
+    sensitiveOutputPaths?: string[];
+    emitsEvents?: string[];
+    active?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export type AgentToolCallStatus = 'queued' | 'running' | 'retrying' | 'awaiting_input' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
+export interface AgentToolCall {
+    id: string;
+    runId?: string;
+    name: string;
+    toolKey?: string;
+    status: AgentToolCallStatus;
+    startedAt?: number;
+    completedAt?: number;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+export type AgentToolPermissionDecision = 'allow_once' | 'allow_session' | 'deny';
+export interface AgentToolPermissionDatum {
+    label: string;
+    value: string;
+}
+export interface AgentToolPermissionRequest {
+    id: string;
+    toolKey: string;
+    displayName: string;
+    provider?: string;
+    summary?: string;
+    scope?: string;
+    sharedData?: AgentToolPermissionDatum[];
+    riskLevel?: AgentToolRiskLevel;
+    sideEffectLevel?: AgentToolSideEffectLevel;
+    destructive?: boolean;
+    openWorld?: boolean;
+    metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/dist/widgets.d.ts

@@ -0,0 +1,38 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-contracts",
-  "version": "2.6.9",
+  "version": "2.6.11",
   "description": "Framework-neutral AgentSam contracts for workbench, tools, providers, events, hooks, execution, identity and repository context.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,10 @@
       "types": "./dist/events.d.ts",
       "import": "./dist/events.js"
     },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "import": "./dist/run.js"
+    },
     "./tools": {
       "types": "./dist/tools.d.ts",
       "import": "./dist/tools.js"
@@ -64,6 +68,10 @@
     "./errors": {
       "types": "./dist/errors.d.ts",
       "import": "./dist/errors.js"
+    },
+    "./widgets": {
+      "types": "./dist/widgets.d.ts",
+      "import": "./dist/widgets.js"
     }
   },
   "scripts": {

package/packages/agentsam-contracts/scripts/build.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
 
 const cwd = fileURLToPath(new URL('../', import.meta.url));
-const modules = ['index','agent','events','tools','authority','execution','providers','hooks','artifacts','context','adapter','models','identity','repository','errors'];
+const modules = ['index','agent','events','run','tools','authority','execution','providers','hooks','artifacts','context','adapter','models','identity','repository','errors','widgets'];
 rmSync(`${cwd}/dist`, { recursive: true, force: true });
 await build({
   absWorkingDir: cwd,

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

@@ -22,14 +22,89 @@ export interface AgentInput {
   capabilityIds?: string[];
 }
 
-export type AgentRunStatus = 'queued' | 'running' | 'completed' | 'cancelled' | 'failed';
+export type AgentRunMode = 'ask' | 'plan' | 'agent' | 'debug' | 'multitask';
+
+export type AgentRunSelectedBy = 'manual' | 'automatic' | 'fallback';
+
+export type AgentRunStatus =
+  | 'queued'
+  | 'running'
+  | 'paused'
+  | 'waiting_external'
+  | 'waiting_child'
+  | 'awaiting_input'
+  | 'awaiting_approval'
+  | 'sleeping'
+  | 'retry_scheduled'
+  | 'partial'
+  | 'completed'
+  | 'cancelled'
+  | 'failed'
+  | 'timed_out';
+
+export type AgentRunTerminalStatus = 'completed' | 'cancelled' | 'failed' | 'timed_out';
+
+export type AgentRunWaitingStatus =
+  | 'waiting_external'
+  | 'waiting_child'
+  | 'awaiting_input'
+  | 'awaiting_approval'
+  | 'sleeping'
+  | 'retry_scheduled';
 
 export interface AgentRun {
   id: string;
-  conversationId: string;
+  conversationId?: string;
   status: AgentRunStatus;
-  startedAt: number;
+  startedAt?: number;
   completedAt?: number;
+
+  accountId?: string;
+  kind?: string;
+  externalAgentId?: string;
+  externalRunId?: string;
+  parentRunId?: string;
+  sourceClient?: string;
+  surface?: string;
+  mode?: AgentRunMode;
   modelId?: string;
+  modelKey?: string;
+  reasoningEffort?: string;
+  requestedServiceTier?: string;
+  actualServiceTier?: string;
+  selectedBy?: AgentRunSelectedBy;
+  cancelRequested?: boolean;
+  errorCode?: string;
+  errorMessage?: string;
   error?: string;
+  modelCallCount?: number;
+  toolCallCount?: number;
+  inputTokens?: number;
+  cachedInputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  costUsd?: number;
+  createdAt?: number;
+  updatedAt?: number;
+  latencyMs?: number;
+  planId?: string;
+  todoId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export function isAgentRunTerminalStatus(status: AgentRunStatus): status is AgentRunTerminalStatus {
+  return status === 'completed' || status === 'cancelled' || status === 'failed' || status === 'timed_out';
+}
+
+export function isAgentRunWaitingStatus(status: AgentRunStatus): status is AgentRunWaitingStatus {
+  return status === 'waiting_external'
+    || status === 'waiting_child'
+    || status === 'awaiting_input'
+    || status === 'awaiting_approval'
+    || status === 'sleeping'
+    || status === 'retry_scheduled';
+}
+
+export function isAgentRunModelActiveStatus(status: AgentRunStatus): boolean {
+  return status === 'queued' || status === 'running';
 }

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

@@ -1,14 +1,17 @@
 // GENERATED by scripts/generate-error-contracts.mjs. Do not edit by hand.
 
-export const AGENTSAM_ERROR_SCHEMA_VERSION = 1 as const;
+export const AGENTSAM_ERROR_SCHEMA_VERSION = 2 as const;
 
 export type AgentSamErrorCode = "OK" | "CANCELLED" | "UNKNOWN" | "INVALID_ARGUMENT" | "DEADLINE_EXCEEDED" | "NOT_FOUND" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "RESOURCE_EXHAUSTED" | "FAILED_PRECONDITION" | "ABORTED" | "OUT_OF_RANGE" | "UNIMPLEMENTED" | "INTERNAL" | "UNAVAILABLE" | "DATA_LOSS" | "UNAUTHENTICATED";
-export type AgentSamErrorReason = "unknown" | "input_invalid" | "input_out_of_range" | "precondition_failed" | "unsupported_operation" | "auth_missing" | "auth_invalid" | "permission_denied" | "user_permission_denied" | "provider_not_connected" | "provider_credential_missing" | "provider_credential_invalid" | "provider_credential_expired" | "provider_scope_insufficient" | "provider_budget_exhausted" | "provider_quota_exhausted" | "provider_rate_limited" | "provider_capacity_exhausted" | "provider_unavailable" | "provider_overloaded" | "provider_request_invalid" | "provider_model_not_found" | "provider_region_unsupported" | "provider_content_blocked" | "context_window_exceeded" | "service_tier_unsupported" | "continuation_invalid" | "target_not_found" | "already_exists" | "conflict" | "stale_version" | "rate_limited" | "quota_exhausted" | "capacity_exhausted" | "transport_unreachable" | "transport_refused" | "transport_timeout" | "upstream_invalid_response" | "dns_unresolved" | "tls_handshake_failed" | "tls_certificate_invalid" | "tunnel_connector_unavailable" | "cancelled" | "deadline_exceeded" | "execution_timeout" | "execution_failed" | "process_spawn_failed" | "process_crashed" | "process_output_limit" | "device_not_enrolled" | "device_credential_missing" | "device_credential_invalid" | "device_credential_expired" | "device_registration_missing" | "device_registration_stale" | "connection_revoked" | "connection_disabled" | "identity_resolution_failed" | "identity_mismatch" | "repository_scope_violation" | "repository_changed" | "index_stale" | "index_failed" | "embedding_failed" | "vector_store_failed" | "github_installation_missing" | "github_repository_not_found" | "github_rate_limited" | "github_secondary_rate_limited" | "github_scope_insufficient" | "cloudflare_workers_cpu_exhausted" | "cloudflare_service_binding_unavailable" | "cloudflare_durable_object_unavailable" | "cloudflare_d1_unavailable" | "cloudflare_r2_unavailable" | "docker_daemon_unavailable" | "docker_image_not_found" | "docker_build_failed" | "docker_container_failed" | "docker_registry_auth_failed" | "docker_pull_rate_limited" | "gcp_project_missing" | "gcp_api_disabled" | "gcp_quota_exhausted" | "gcp_vm_not_found" | "gcp_vm_unavailable" | "cad_tool_not_installed" | "cad_tool_not_executable" | "cad_tool_version_incompatible" | "cad_component_missing" | "cad_dependency_missing" | "cad_dependency_version_incompatible" | "cad_source_parse_failed" | "cad_input_format_unsupported" | "cad_import_failed" | "cad_model_recompute_failed" | "cad_constraint_unsatisfied" | "cad_geometry_invalid" | "cad_null_shape" | "cad_boolean_failed" | "cad_kernel_failed" | "cad_script_failed" | "cad_export_format_unsupported" | "cad_export_failed" | "cad_output_missing" | "cad_output_invalid" | "cad_render_engine_unavailable" | "cad_gpu_unavailable" | "cad_render_failed" | "cad_memory_exhausted" | "cad_process_crashed" | "cad_warning_escalated" | "policy_blocked" | "copyright_blocked" | "persistence_failed" | "data_corrupt" | "data_loss" | "internal" | "internal_invariant_violation" | "internal_configuration_invalid" | "internal_contract_violation" | "internal_adapter_failed" | "internal_dependency_failed";
+export type AgentSamErrorReason = "unknown" | "input_invalid" | "input_out_of_range" | "precondition_failed" | "unsupported_operation" | "auth_missing" | "auth_invalid" | "permission_denied" | "user_permission_denied" | "provider_not_connected" | "provider_credential_missing" | "provider_credential_invalid" | "provider_credential_expired" | "provider_scope_insufficient" | "provider_budget_exhausted" | "provider_quota_exhausted" | "provider_rate_limited" | "provider_capacity_exhausted" | "provider_unavailable" | "provider_overloaded" | "provider_request_invalid" | "provider_model_not_found" | "provider_region_unsupported" | "provider_content_blocked" | "context_window_exceeded" | "service_tier_unsupported" | "continuation_invalid" | "target_not_found" | "already_exists" | "conflict" | "stale_version" | "rate_limited" | "quota_exhausted" | "capacity_exhausted" | "transport_unreachable" | "transport_refused" | "transport_timeout" | "upstream_invalid_response" | "dns_unresolved" | "tls_handshake_failed" | "tls_certificate_invalid" | "tunnel_connector_unavailable" | "cancelled" | "deadline_exceeded" | "execution_timeout" | "execution_failed" | "process_spawn_failed" | "process_crashed" | "process_output_limit" | "device_not_enrolled" | "device_credential_missing" | "device_credential_invalid" | "device_credential_expired" | "device_registration_missing" | "device_registration_stale" | "connection_revoked" | "connection_disabled" | "identity_resolution_failed" | "identity_mismatch" | "repository_scope_violation" | "repository_changed" | "index_stale" | "index_failed" | "embedding_failed" | "vector_store_failed" | "github_installation_missing" | "github_repository_not_found" | "github_rate_limited" | "github_secondary_rate_limited" | "github_scope_insufficient" | "cloudflare_workers_cpu_exhausted" | "cloudflare_service_binding_unavailable" | "cloudflare_durable_object_unavailable" | "cloudflare_d1_unavailable" | "cloudflare_r2_unavailable" | "docker_daemon_unavailable" | "docker_image_not_found" | "docker_build_failed" | "docker_container_failed" | "docker_registry_auth_failed" | "docker_pull_rate_limited" | "gcp_project_missing" | "gcp_api_disabled" | "gcp_quota_exhausted" | "gcp_vm_not_found" | "gcp_vm_unavailable" | "cad_tool_not_installed" | "cad_tool_not_executable" | "cad_tool_version_incompatible" | "cad_component_missing" | "cad_dependency_missing" | "cad_dependency_version_incompatible" | "cad_source_parse_failed" | "cad_input_format_unsupported" | "cad_import_failed" | "cad_model_recompute_failed" | "cad_constraint_unsatisfied" | "cad_geometry_invalid" | "cad_null_shape" | "cad_boolean_failed" | "cad_kernel_failed" | "cad_script_failed" | "cad_export_format_unsupported" | "cad_export_failed" | "cad_output_missing" | "cad_output_invalid" | "cad_render_engine_unavailable" | "cad_gpu_unavailable" | "cad_render_failed" | "cad_memory_exhausted" | "cad_process_crashed" | "cad_warning_escalated" | "policy_blocked" | "copyright_blocked" | "persistence_failed" | "data_corrupt" | "data_loss" | "internal" | "internal_invariant_violation" | "internal_configuration_invalid" | "internal_contract_violation" | "internal_adapter_failed" | "internal_dependency_failed" | "hook_definition_invalid" | "hook_duplicate_id" | "hook_not_found" | "hook_disabled" | "hook_event_unsupported" | "hook_configuration_invalid" | "hook_adapter_unknown" | "hook_adapter_unavailable" | "hook_handler_unavailable" | "hook_handler_timeout" | "hook_handler_failed" | "hook_output_invalid" | "hook_output_limit_exceeded" | "hook_output_field_unsupported" | "hook_http_timeout" | "hook_http_request_failed" | "hook_http_response_invalid" | "hook_http_response_limit_exceeded" | "hook_http_protocol_unsupported" | "hook_http_credentials_forbidden" | "hook_mcp_timeout" | "hook_mcp_server_unavailable" | "hook_mcp_capability_missing" | "hook_mcp_capability_duplicate" | "hook_mcp_response_invalid" | "hook_mcp_transport_failed" | "hook_lsp_timeout" | "hook_lsp_server_unavailable" | "hook_lsp_language_required" | "hook_lsp_capability_unsupported" | "hook_lsp_initialize_failed" | "hook_lsp_response_invalid" | "hook_command_required" | "hook_command_timeout" | "hook_command_spawn_failed" | "hook_command_exit_nonzero" | "hook_command_output_limit_exceeded" | "hook_command_output_invalid" | "hook_permission_denied" | "hook_capability_unavailable" | "hook_capability_duplicate" | "hook_error_handling_invalid" | "hook_error_handling_unsupported" | "hook_retry_limit_exceeded" | "hook_stop_decision_invalid" | "package_manifest_invalid" | "package_export_missing" | "package_file_missing" | "package_unwanted_file_included" | "package_dependency_missing" | "package_dependency_version_mismatch" | "lockfile_missing" | "lockfile_stale" | "lockfile_incompatible" | "workspace_not_installed" | "workspace_resolution_failed" | "workspace_boundary_invalid" | "build_dependency_missing" | "build_failed" | "build_output_missing" | "build_output_stale" | "pack_failed" | "pack_contents_invalid" | "pack_provenance_violation" | "distribution_artifact_missing" | "distribution_identity_mismatch" | "distribution_version_mismatch" | "distribution_install_failed" | "distribution_smoke_failed" | "release_train_misaligned" | "published_artifact_stale" | "published_artifact_missing" | "schema_invalid" | "schema_version_unsupported" | "schema_contract_mismatch" | "schema_pack_missing" | "schema_pack_dependency_missing" | "schema_pack_dependency_cycle" | "schema_pack_ownership_conflict" | "migration_missing" | "migration_failed" | "migration_checksum_mismatch" | "migration_order_invalid" | "migration_already_applied_conflict" | "migration_requires_manual_repair" | "database_unreachable" | "database_driver_unsupported" | "database_authority_unresolved" | "database_authorization_failed" | "database_schema_drift" | "model_discovery_failed" | "model_catalog_stale" | "model_snapshot_missing" | "model_snapshot_stale" | "model_capability_unknown" | "model_capability_unsupported" | "model_provider_mismatch" | "model_identity_conflict" | "model_probe_failed" | "model_probe_partial" | "runtime_not_installed" | "runtime_not_running" | "runtime_version_incompatible" | "runtime_capability_missing" | "runtime_protocol_mismatch" | "runtime_connection_unresolved" | "runtime_connection_revoked" | "pty_create_failed" | "pty_attach_failed" | "pty_session_not_found" | "pty_session_expired" | "pty_replay_cursor_invalid" | "transport_not_configured" | "transport_auth_failed" | "transport_attach_failed" | "sidecar_missing" | "sidecar_start_failed" | "sidecar_health_failed" | "tool_not_found" | "tool_disabled" | "tool_handler_unavailable" | "tool_execution_failed" | "tool_timeout" | "tool_output_invalid" | "tool_permission_denied" | "mcp_timeout" | "mcp_server_unavailable" | "mcp_capability_unsupported" | "mcp_response_invalid" | "mcp_transport_failed" | "lsp_timeout" | "lsp_server_unavailable" | "lsp_capability_unsupported" | "lsp_response_invalid" | "lsp_transport_failed" | "mcp_call_failed" | "lsp_request_failed";
 export type AgentSamErrorSeverity = "transient" | "blocking_user_fixable" | "blocking_internal" | "policy_blocking";
 export type AgentSamErrorSourceKind = "user" | "agentsam" | "provider" | "dependency" | "runtime" | "policy";
 export type AgentSamErrorResolutionOwner = "user" | "agentsam" | "provider" | "organization_admin" | "policy" | "unknown";
-export type AgentSamErrorDomain = "runtime" | "provider" | "auth" | "device" | "terminal" | "transport" | "repository" | "indexing" | "knowledge" | "cad" | "deployment" | "persistence" | "policy" | "tool";
-export type AgentSamRemediationAction = "none" | "retry" | "retry_later" | "reauthenticate" | "connect_provider" | "configure_provider_credential" | "refresh_provider_credential" | "request_permission" | "reenroll_device" | "reconnect_service" | "install_dependency" | "upgrade_dependency" | "configure_dependency" | "change_configuration" | "change_input" | "reduce_scope" | "increase_quota" | "add_budget" | "select_model" | "change_region" | "restart_runtime" | "inspect_platform" | "contact_provider" | "contact_agentsam" | "contact_organization_admin";
+export type AgentSamErrorDomain = "runtime" | "provider" | "auth" | "identity" | "device" | "terminal" | "transport" | "repository" | "indexing" | "knowledge" | "cad" | "hook" | "model" | "configuration" | "schema" | "migration" | "database" | "package" | "build" | "distribution" | "deployment" | "workflow" | "persistence" | "policy" | "tool";
+export type AgentSamErrorFailureClass = "input" | "validation" | "authentication" | "authorization" | "policy" | "discovery" | "resolution" | "availability" | "transport" | "protocol" | "timeout" | "rate_limit" | "capacity" | "resource" | "configuration" | "dependency" | "filesystem" | "persistence" | "consistency" | "conflict" | "process" | "ipc" | "data_integrity" | "cancellation" | "cancelled" | "build" | "distribution" | "migration" | "schema" | "identity" | "execution" | "internal" | "unknown";
+export type AgentSamErrorStage = "discover" | "resolve" | "load" | "configure" | "validate" | "authorize" | "connect" | "prepare" | "install" | "build" | "start" | "execute" | "transform" | "persist" | "migrate" | "verify" | "publish" | "attach" | "detach" | "cleanup" | "shutdown";
+export type AgentSamErrorFailureBehavior = "fail_closed" | "fail_open" | "observe_only" | "retry_bounded" | "skip" | "abort" | "no_replay";
+export type AgentSamRemediationAction = "none" | "retry" | "retry_later" | "reauthenticate" | "connect_provider" | "configure_provider_credential" | "refresh_provider_credential" | "request_permission" | "reenroll_device" | "reconnect_service" | "install_dependency" | "upgrade_dependency" | "configure_dependency" | "change_configuration" | "change_input" | "reduce_scope" | "increase_quota" | "add_budget" | "select_model" | "change_region" | "restart_runtime" | "inspect_platform" | "contact_provider" | "contact_agentsam" | "contact_organization_admin" | "restart_service" | "repair_schema" | "run_migration" | "regenerate_artifact" | "update_lockfile" | "reinstall_workspace" | "republish_artifact";
 export type AgentSamErrorSideEffectState = "none" | "not_started" | "confirmed_not_applied" | "confirmed_applied" | "partially_applied" | "unknown";
 export type AgentSamErrorOutcomeStatus = "success" | "partial" | "failure";
 
@@ -28,14 +31,22 @@ export interface AgentSamErrorEnvelope {
   schema_version: typeof AGENTSAM_ERROR_SCHEMA_VERSION;
   code: AgentSamErrorCode;
   reason: AgentSamErrorReason | (string & {});
+  domain: AgentSamErrorDomain;
+  failure_class: AgentSamErrorFailureClass;
+  stage: AgentSamErrorStage;
+  native_stage: string | null;
+  feature: string | null;
+  failure_behavior: AgentSamErrorFailureBehavior | null;
   severity: AgentSamErrorSeverity;
-  source: AgentSamErrorSource;
+  retryable: boolean;
+  side_effect_state: AgentSamErrorSideEffectState;
   resolution_owner: AgentSamErrorResolutionOwner;
-  domain: AgentSamErrorDomain;
+  source: AgentSamErrorSource;
+  adapter: string | null;
+  protocol: string | null;
+  transport: string | null;
   tool: string | null;
-  stage: string | null;
   message: string;
-  retryable: boolean;
   retry_after_ms: number | null;
   remediation: AgentSamErrorRemediation;
   resource: AgentSamErrorResource | null;
@@ -43,7 +54,6 @@ export interface AgentSamErrorEnvelope {
   environment: AgentSamEnvironmentEvidence | null;
   http_status: number | null;
   grpc_status: number | null;
-  transport: string | null;
   provider: string | null;
   provider_code: string | null;
   request_id: string | null;
@@ -51,7 +61,6 @@ export interface AgentSamErrorEnvelope {
   fingerprint: string;
   occurrence_count: number;
   details: unknown;
-  failure_class?: string;
   operation?: AgentSamErrorOperation;
   retry?: AgentSamErrorRetry;
   fallback?: AgentSamErrorFallback;

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

@@ -1,5 +1,6 @@
 export * from './agent';
 export * from './events';
+export * from './run';
 export * from './tools';
 export * from './authority';
 export * from './execution';
@@ -12,3 +13,4 @@ export * from './models';
 export * from './identity';
 export * from './repository';
 export * from './errors';
+export * from './widgets';