@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.12

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

@@ -0,0 +1,66 @@
+import type { AgentAttachment } from './artifacts';
+import type { AgentContext } from './context';
+export type AgentRole = 'user' | 'assistant' | 'system' | 'tool';
+export interface AgentMessage {
+    id: string;
+    role: AgentRole;
+    content: string;
+    createdAt: number;
+    name?: string;
+    modelId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentInput {
+    conversationId: string;
+    text: string;
+    attachments?: AgentAttachment[];
+    context?: AgentContext;
+    modelId?: string;
+    capabilityIds?: string[];
+}
+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;
+    status: AgentRunStatus;
+    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 declare function isAgentRunTerminalStatus(status: AgentRunStatus): status is AgentRunTerminalStatus;
+export declare function isAgentRunWaitingStatus(status: AgentRunStatus): status is AgentRunWaitingStatus;
+export declare function isAgentRunModelActiveStatus(status: AgentRunStatus): boolean;

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

@@ -0,0 +1,15 @@
+// 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";
+}
+export {
+  isAgentRunModelActiveStatus,
+  isAgentRunTerminalStatus,
+  isAgentRunWaitingStatus
+};

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

@@ -0,0 +1,70 @@
+export type AgentArtifactKind = 'code' | 'file' | 'preview' | 'browser' | 'terminal' | 'deploy' | 'render' | 'model' | 'receipt' | string;
+export interface AgentAttachment {
+    id: string;
+    /** @deprecated prefer kind — kept for backward compatibility */
+    name: string;
+    mimeType?: string;
+    size?: number;
+    /** @deprecated text-file shortcut — do not use for images */
+    text?: string;
+    url?: string;
+    metadata?: Record<string, unknown>;
+    /** Structured multimodal fields (v1+) */
+    kind?: 'image' | 'document' | 'text' | 'archive' | 'audio' | 'video' | 'model' | 'binary';
+    source?: {
+        type: 'local_path';
+        path: string;
+    } | {
+        type: 'blob';
+        blobId: string;
+    } | {
+        type: 'url';
+        url: string;
+    } | {
+        type: 'r2';
+        bucket: string;
+        key: string;
+    } | {
+        type: 'artifact';
+        artifactId: string;
+    };
+    sha256?: string;
+    image?: {
+        width: number;
+        height: number;
+        alpha?: boolean;
+        orientation?: number;
+    };
+    preview?: {
+        url?: string;
+        localPath?: string;
+    };
+    inference?: {
+        mimeType: string;
+        source: {
+            type: 'local_path';
+            path: string;
+        } | {
+            type: 'blob';
+            blobId: string;
+        } | {
+            type: 'url';
+            url: string;
+        };
+        width?: number;
+        height?: number;
+        bytes?: number;
+    };
+    lifetime?: 'ephemeral' | 'conversation' | 'project' | 'artifact' | 'brand';
+}
+export interface AgentArtifact {
+    id: string;
+    kind: AgentArtifactKind;
+    title?: string;
+    mimeType?: string;
+    content?: string;
+    url?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,21 @@
+export type AgentAuthorityType = 'none' | 'host' | 'binding' | 'secret' | 'oauth' | 'connection';
+export interface AgentAuthorityRequirement {
+    type: AgentAuthorityType;
+    ref?: string;
+    provider?: string;
+    scopes?: string[];
+    optional?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Opaque, non-secret reference to authority resolved by the host runtime.
+ * Raw credentials/tokens must not be serialized into portable AgentSam contracts.
+ */
+export interface AgentResolvedAuthorityReference {
+    type: Exclude<AgentAuthorityType, 'none'>;
+    ref: string;
+    provider?: string;
+    accountRef?: string;
+    scopes?: string[];
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,14 @@
+export type AgentSurface = 'chat' | 'work' | 'cad' | 'cms' | string;
+export interface AgentContext {
+    surface: AgentSurface;
+    accountId?: string;
+    authUserId?: string;
+    repository?: string;
+    files?: string[];
+    selection?: unknown;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentContextProvider {
+    getContext(): AgentContext | Promise<AgentContext>;
+}

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

@@ -0,0 +1,121 @@
+export declare const AGENTSAM_ERROR_SCHEMA_VERSION: 2;
+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" | "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" | "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";
+export interface AgentSamErrorSource {
+    kind: AgentSamErrorSourceKind;
+    name: string;
+    service: string | null;
+}
+export interface AgentSamErrorRemediation {
+    action: AgentSamRemediationAction;
+    message: string | null;
+    automatic: boolean;
+    command: string | null;
+    url: string | null;
+}
+export interface AgentSamErrorResource {
+    type: string;
+    id: string | null;
+    name: string | null;
+}
+export interface AgentSamNativeErrorEvidence {
+    code: string | null;
+    exception_type: string | null;
+    exit_code: number | null;
+    signal: string | null;
+    stderr: string | null;
+    stdout: string | null;
+    stack: string | null;
+}
+export interface AgentSamEnvironmentEvidence {
+    detected_version: string | null;
+    required_version: string | null;
+    component: string | null;
+    runtime: string | null;
+    platform: string | null;
+}
+export interface AgentSamErrorOperation {
+    kind?: string | null;
+    action?: string | null;
+    resource_type?: string | null;
+    resource_id?: string | null;
+    read_only?: boolean;
+    idempotent?: boolean;
+    side_effect_state?: AgentSamErrorSideEffectState;
+}
+export interface AgentSamErrorRetry {
+    allowed?: boolean;
+    strategy?: string;
+    retry_after_ms?: number | null;
+    max_attempts?: number | null;
+    requires_idempotency_key?: boolean;
+}
+export interface AgentSamErrorFallback {
+    allowed?: boolean;
+    strategy?: string | null;
+    preserve_semantics?: boolean;
+    target?: string | null;
+}
+export interface AgentSamErrorNotification {
+    user?: string;
+    operator?: string;
+    agent?: string;
+}
+export interface AgentSamErrorPartialResult {
+    completed?: number;
+    failed?: number;
+    failures?: unknown[];
+}
+export interface AgentSamErrorEnvelope {
+    ok: false;
+    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;
+    retryable: boolean;
+    side_effect_state: AgentSamErrorSideEffectState;
+    resolution_owner: AgentSamErrorResolutionOwner;
+    source: AgentSamErrorSource;
+    adapter: string | null;
+    protocol: string | null;
+    transport: string | null;
+    tool: string | null;
+    message: string;
+    retry_after_ms: number | null;
+    remediation: AgentSamErrorRemediation;
+    resource: AgentSamErrorResource | null;
+    native: AgentSamNativeErrorEvidence | null;
+    environment: AgentSamEnvironmentEvidence | null;
+    http_status: number | null;
+    grpc_status: number | null;
+    provider: string | null;
+    provider_code: string | null;
+    request_id: string | null;
+    trace_id: string | null;
+    fingerprint: string;
+    occurrence_count: number;
+    details: unknown;
+    operation?: AgentSamErrorOperation;
+    retry?: AgentSamErrorRetry;
+    fallback?: AgentSamErrorFallback;
+    notify?: AgentSamErrorNotification;
+    cause?: unknown;
+    status?: AgentSamErrorOutcomeStatus;
+    partial?: AgentSamErrorPartialResult;
+}

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

@@ -0,0 +1,5 @@
+// src/errors.ts
+var AGENTSAM_ERROR_SCHEMA_VERSION = 2;
+export {
+  AGENTSAM_ERROR_SCHEMA_VERSION
+};

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';