@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.11

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

@@ -0,0 +1,53 @@
+import type { AgentArtifact } from './artifacts';
+import type { AgentMessage, AgentRunStatus } from './agent';
+import type { AgentToolCall } from './tools';
+/**
+ * Workbench-facing event stream retained for UI/runtime compatibility.
+ */
+export type AgentEvent = {
+    type: 'message';
+    message: AgentMessage;
+} | {
+    type: 'message.delta';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'run.status';
+    runId: string;
+    status: AgentRunStatus;
+    error?: string;
+} | {
+    type: 'tool';
+    toolCall: AgentToolCall;
+} | {
+    type: 'artifact';
+    artifact: AgentArtifact;
+} | {
+    type: 'error';
+    runId?: string;
+    error: string;
+};
+export type AgentEventSourceKind = 'webhook' | 'tool' | 'workflow' | 'provider' | 'system' | 'user';
+export interface AgentEventSource {
+    kind: AgentEventSourceKind;
+    provider?: string;
+    ref?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Portable orchestration/domain event. Provider events can be retained while a host
+ * additionally emits normalized domain events (for example completeful.order.created
+ * followed by commerce.order.created).
+ */
+export interface AgentOrchestrationEvent<TPayload = unknown> {
+    id: string;
+    eventKey: string;
+    occurredAt: number;
+    source: AgentEventSource;
+    payload: TPayload;
+    accountId?: string;
+    subject?: string;
+    correlationId?: string;
+    causationId?: string;
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,38 @@
+import type { AgentSamErrorEnvelope } from './errors';
+export type AgentExecutionStatus = 'queued' | 'running' | 'retrying' | 'awaiting_input' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
+export interface AgentToolInvocation<TInput = unknown> {
+    id: string;
+    toolKey: string;
+    input: TInput;
+    requestedAt: number;
+    accountId?: string;
+    correlationId?: string;
+    causationId?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentToolExecutionResult<TOutput = unknown> {
+    output?: TOutput;
+    providerRequestId?: string;
+    usage?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentToolExecutionReceipt<TOutput = unknown> {
+    invocationId: string;
+    toolKey: string;
+    status: AgentExecutionStatus;
+    ok: boolean;
+    attempt: number;
+    queuedAt?: number;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number;
+    provider?: string;
+    input?: unknown;
+    output?: TOutput;
+    error?: AgentSamErrorEnvelope;
+    emittedEventIds?: string[];
+    providerRequestId?: string;
+    usage?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,31 @@
+export type AgentHookActionType = 'tool' | 'workflow' | 'event';
+export interface AgentHookAction {
+    actionId?: string;
+    type: AgentHookActionType;
+    target: string;
+    input?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentHookDefinition {
+    hookKey: string;
+    displayName?: string;
+    description?: string;
+    eventKeys: string[];
+    enabled: boolean;
+    filter?: Record<string, unknown>;
+    actions: AgentHookAction[];
+    metadata?: Record<string, unknown>;
+}
+export type AgentHookExecutionStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+export interface AgentHookExecutionReceipt {
+    executionId: string;
+    hookKey: string;
+    eventId: string;
+    status: AgentHookExecutionStatus;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number;
+    actionExecutionIds?: string[];
+    error?: unknown;
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Identity is established outside the workbench. These contracts only carry the
+ * authenticated principal into product authorization and runtime adapters.
+ */
+export interface AgentPrincipal {
+    accountId: string;
+    authUserId: string;
+    displayName?: string;
+    email?: string;
+    claims?: Record<string, unknown>;
+}
+export interface AgentIdentityProvider {
+    getPrincipal(): AgentPrincipal | null | Promise<AgentPrincipal | null>;
+    subscribe?(onChange: (principal: AgentPrincipal | null) => void): () => void;
+}

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

@@ -0,0 +1,16 @@
+export * from './agent';
+export * from './events';
+export * from './run';
+export * from './tools';
+export * from './authority';
+export * from './execution';
+export * from './providers';
+export * from './hooks';
+export * from './artifacts';
+export * from './context';
+export * from './adapter';
+export * from './models';
+export * from './identity';
+export * from './repository';
+export * from './errors';
+export * from './widgets';

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

@@ -0,0 +1,164 @@
+// src/agent.ts
+function isAgentRunTerminalStatus(status) {
+  return status === "completed" || status === "cancelled" || status === "failed" || status === "timed_out";
+}
+function isAgentRunWaitingStatus(status) {
+  return status === "waiting_external" || status === "waiting_child" || status === "awaiting_input" || status === "awaiting_approval" || status === "sleeping" || status === "retry_scheduled";
+}
+function isAgentRunModelActiveStatus(status) {
+  return status === "queued" || status === "running";
+}
+
+// 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
+  };
+}
+
+// src/repository.ts
+var REPOSITORY_STATUSES = ["active", "archived", "disabled"];
+var REPOSITORY_CONTRACT_TYPES = ["api", "schema", "runtime", "cli", "event", "receipt", "package"];
+var REPOSITORY_CONTRACT_STATUSES = ["active", "deprecated", "retired"];
+var REPOSITORY_DEPENDENCY_TYPES = ["runtime", "build", "contract", "package", "deploy", "tool", "data"];
+var REPOSITORY_DEPENDENCY_CRITICALITIES = ["informational", "compatible", "strict", "critical"];
+var REPOSITORY_FAILURE_POLICIES = ["warn", "block_certification", "block_deploy", "degrade"];
+
+// src/errors.ts
+var AGENTSAM_ERROR_SCHEMA_VERSION = 2;
+export {
+  AGENTSAM_ERROR_SCHEMA_VERSION,
+  REPOSITORY_CONTRACT_STATUSES,
+  REPOSITORY_CONTRACT_TYPES,
+  REPOSITORY_DEPENDENCY_CRITICALITIES,
+  REPOSITORY_DEPENDENCY_TYPES,
+  REPOSITORY_FAILURE_POLICIES,
+  REPOSITORY_STATUSES,
+  classifyAgentRunRetry,
+  evaluateAgentRunWake,
+  isAgentRunModelActiveStatus,
+  isAgentRunTerminalStatus,
+  isAgentRunWaitingStatus,
+  projectRunEventToActivity,
+  transitionAgentRunStatus,
+  wakeMatchesSuspension
+};

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

@@ -0,0 +1,9 @@
+export interface ModelOption {
+    id: string;
+    label: string;
+    short?: string;
+    description?: string;
+    provider?: string;
+    disabled?: boolean;
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,27 @@
+import type { AgentAuthorityRequirement, AgentResolvedAuthorityReference } from './authority';
+import type { AgentToolExecutionResult, AgentToolInvocation } from './execution';
+import type { AgentToolDefinition } from './tools';
+export interface AgentProviderDefinition {
+    providerKey: string;
+    displayName: string;
+    description?: string;
+    capabilityKeys?: string[];
+    toolKeys?: string[];
+    authority?: AgentAuthorityRequirement[];
+    metadata?: Record<string, unknown>;
+}
+export interface AgentProviderExecutionContext {
+    authority?: AgentResolvedAuthorityReference[];
+    accountId?: string;
+    deadlineAt?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Provider adapters implement provider-specific mechanics only.
+ * Generic retries, receipts, hooks, queueing and event dispatch remain execution-plane concerns.
+ */
+export interface AgentProviderAdapter<TContext extends AgentProviderExecutionContext = AgentProviderExecutionContext> {
+    readonly providerKey: string;
+    listTools?(): AgentToolDefinition[] | Promise<AgentToolDefinition[]>;
+    invoke<TInput = unknown, TOutput = unknown>(invocation: AgentToolInvocation<TInput>, context: TContext): Promise<AgentToolExecutionResult<TOutput>>;
+}

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

@@ -0,0 +1,56 @@
+export declare const REPOSITORY_STATUSES: readonly ["active", "archived", "disabled"];
+export type RepositoryStatus = (typeof REPOSITORY_STATUSES)[number];
+export declare const REPOSITORY_CONTRACT_TYPES: readonly ["api", "schema", "runtime", "cli", "event", "receipt", "package"];
+export type RepositoryContractType = (typeof REPOSITORY_CONTRACT_TYPES)[number];
+export declare const REPOSITORY_CONTRACT_STATUSES: readonly ["active", "deprecated", "retired"];
+export type RepositoryContractStatus = (typeof REPOSITORY_CONTRACT_STATUSES)[number];
+export declare const REPOSITORY_DEPENDENCY_TYPES: readonly ["runtime", "build", "contract", "package", "deploy", "tool", "data"];
+export type RepositoryDependencyType = (typeof REPOSITORY_DEPENDENCY_TYPES)[number];
+export declare const REPOSITORY_DEPENDENCY_CRITICALITIES: readonly ["informational", "compatible", "strict", "critical"];
+export type RepositoryDependencyCriticality = (typeof REPOSITORY_DEPENDENCY_CRITICALITIES)[number];
+export declare const REPOSITORY_FAILURE_POLICIES: readonly ["warn", "block_certification", "block_deploy", "degrade"];
+export type RepositoryFailurePolicy = (typeof REPOSITORY_FAILURE_POLICIES)[number];
+/** Portable repository identity. Account ownership belongs to the host registry, not this object. */
+export interface RepositoryIdentity {
+    schema_version: 1;
+    repository_id: string;
+    full_name: string;
+    role: string;
+    default_branch: string;
+    canonical_url: string | null;
+    status: RepositoryStatus;
+}
+/** Account-bound declaration of one contract provided by a repository. */
+export interface RepositoryContract {
+    schema_version: 1;
+    id: string;
+    account_id: string;
+    repository_id: string;
+    contract_key: string;
+    contract_version: string;
+    contract_type: RepositoryContractType;
+    name: string;
+    description: string | null;
+    manifest_path: string | null;
+    contract_hash: string;
+    status: RepositoryContractStatus;
+    created_at: number | null;
+    updated_at: number | null;
+}
+/** Account-bound cross-repository dependency edge. */
+export interface RepositoryDependency {
+    schema_version: 1;
+    id: string;
+    account_id: string;
+    source_repository_id: string;
+    target_repository_id: string;
+    dependency_type: RepositoryDependencyType;
+    contract_id: string | null;
+    criticality: RepositoryDependencyCriticality;
+    required_version: string | null;
+    required_contract_hash: string | null;
+    failure_policy: RepositoryFailurePolicy;
+    description: string | null;
+    created_at: number | null;
+    updated_at: number | null;
+}

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

@@ -0,0 +1,15 @@
+// src/repository.ts
+var REPOSITORY_STATUSES = ["active", "archived", "disabled"];
+var REPOSITORY_CONTRACT_TYPES = ["api", "schema", "runtime", "cli", "event", "receipt", "package"];
+var REPOSITORY_CONTRACT_STATUSES = ["active", "deprecated", "retired"];
+var REPOSITORY_DEPENDENCY_TYPES = ["runtime", "build", "contract", "package", "deploy", "tool", "data"];
+var REPOSITORY_DEPENDENCY_CRITICALITIES = ["informational", "compatible", "strict", "critical"];
+var REPOSITORY_FAILURE_POLICIES = ["warn", "block_certification", "block_deploy", "degrade"];
+export {
+  REPOSITORY_CONTRACT_STATUSES,
+  REPOSITORY_CONTRACT_TYPES,
+  REPOSITORY_DEPENDENCY_CRITICALITIES,
+  REPOSITORY_DEPENDENCY_TYPES,
+  REPOSITORY_FAILURE_POLICIES,
+  REPOSITORY_STATUSES
+};

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;