@agents24/node 0.2.0 → 0.3.0

package/dist/types/types.d.ts

@@ -1,11 +1,9 @@
 import type { Agents24SDKErrorKind } from "./errors.js";
-import type { ActiveThreadRun, Attachment, AttachmentUploadResult, ContextCompression, ContextWindow, ContextWindowConfidence, ContextWindowSource, ContextWindowStage, ContextWindowTracker, PublicResponseBlock, RunCancelResult, RunContext, RunResumeResult, RuntimeEvent, ThreadDeleteResult, ThreadDetail, ThreadSummary, ThreadSummaryEvent, ThreadTurn, ThreadsResponse, ToolInputOverrides } from "@agents24/client/protocol";
-export type { ActiveThreadRun, Attachment, AttachmentUploadResult, ContextCompression, ContextWindow, ContextWindowConfidence, ContextWindowSource, ContextWindowStage, ContextWindowTracker, PublicResponseBlock as ResponseBlock, RunCancelResult, RunContext, RunResumeResult, RuntimeEvent, ThreadDeleteResult, ThreadDetail, ThreadSummary, ThreadSummaryEvent, ThreadTurn, ThreadsResponse, ToolInputOverrides, };
+import type { ActiveThreadRun, Attachment, AttachmentContentAccess, AttachmentUploadResult, ContextCompression, ContextWindow, ContextWindowConfidence, ContextWindowSource, ContextWindowStage, ContextWindowTracker, PublicResponseBlock, RunCancelResult, RunContext, RunResumeResult, RuntimeEvent, ThreadDeleteResult, ThreadDetail, ThreadSummary, ThreadSummaryEvent, ThreadTurn, ThreadsResponse, ToolInputOverrides } from "@agents24/client/protocol";
+export type { ActiveThreadRun, Attachment, AttachmentContentAccess, AttachmentUploadResult, ContextCompression, ContextWindow, ContextWindowConfidence, ContextWindowSource, ContextWindowStage, ContextWindowTracker, PublicResponseBlock as ResponseBlock, RunCancelResult, RunContext, RunResumeResult, RuntimeEvent, ThreadDeleteResult, ThreadDetail, ThreadSummary, ThreadSummaryEvent, ThreadTurn, ThreadsResponse, ToolInputOverrides, };
 export type Agents24NodeOptions = {
     baseUrl: string;
     apiKey: string;
-    organizationId: string;
-    projectId: string;
     fetchImpl?: typeof fetch;
 };
 /** @deprecated Use Agents24NodeOptions. */
@@ -54,6 +52,7 @@ export type EmbedStreamRequest = {
     requested_model_id?: string;
     requested_model_node_id?: string;
     external_user_id: string;
+    external_user_issuer?: string;
     external_session_id?: string;
     metadata?: Record<string, unknown>;
     client?: Record<string, unknown>;
@@ -63,13 +62,40 @@ export type AttachRunRequest = {
     external_session_id?: string;
     metadata?: Record<string, unknown>;
     client?: Record<string, unknown>;
+    cursor?: number;
+};
+export type FeedbackRating = "like" | "dislike";
+export type FeedbackReason = "incorrect" | "irrelevant" | "incomplete" | "unsafe" | "citation_issue" | "other";
+export type ResponseFeedback = {
+    rating: FeedbackRating;
+    reason: FeedbackReason | null;
+    comment: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type ResponseFeedbackResult = {
+    run_id: string;
+    feedback: ResponseFeedback | null;
+};
+export type EmbeddedResponseFeedbackInput = {
+    external_user_id: string;
+    external_session_id?: string;
+    rating: FeedbackRating | null;
+    reason?: FeedbackReason | null;
+    comment?: string | null;
+};
+export type HitlAction = "approve" | "reject" | "connect" | "skip" | "respond";
+export type HitlAnswer = {
+    question_id: string;
+    selected_option_ids: string[];
+    custom_text?: string;
 };
-export type HitlAction = "approve" | "reject" | "connect" | "skip";
 export type ResumeRunRequest = AttachRunRequest & {
     schema_version: "agents24.hitl.resume.v2";
     interrupt_id: string;
     action: HitlAction;
     comment?: string;
+    answers?: HitlAnswer[];
 };
 export type McpAuthStartRequest = AttachRunRequest & {
     interrupt_id: string;
@@ -85,7 +111,7 @@ export type EmbedRuntimeBootstrap = {
     agent_name?: string;
     agent_version_id?: string;
     agent_version_number?: number;
-    model_selector?: Record<string, unknown> | null;
+    features: Record<string, unknown>;
     thread_events_path?: string | null;
     thread_events_url?: string | null;
 };
@@ -107,7 +133,6 @@ export type ThreadDetailOptions = {
     externalSessionId?: string;
     beforeTurnIndex?: number;
     limit?: number;
-    includeRunEvents?: boolean;
     includeSubthreads?: boolean;
     subthreadDepth?: number;
     subthreadTurnLimit?: number;
@@ -141,13 +166,46 @@ export type MultiAgentThreadSummaryEventOptions = ThreadSummaryEventOptions & {
 };
 export type ServerAttachmentUploadOptions = {
     threadId?: string;
+    agentVersionId?: string;
     files: File[];
     idempotencyKey?: string;
 };
+export type AttachmentContentAccessRequest = {
+    disposition: "inline" | "attachment";
+};
+export type EmbedAttachmentContentAccessRequest = AttachmentContentAccessRequest & {
+    external_user_id: string;
+    external_session_id?: string | null;
+};
 export type ServerEmbedAttachmentUploadOptions = ServerAttachmentUploadOptions & {
     externalUserId: string;
     externalSessionId?: string;
 };
+export type GraphValueRef = {
+    namespace: "workflow_input" | "state" | "node_output";
+    key: string;
+    node_id?: string;
+    expected_type?: "string" | "number" | "boolean" | "object" | "list" | "unknown";
+    label?: string;
+};
+export type WorkflowInputDefinition = {
+    key: string;
+    type: "string" | "number" | "boolean" | "object" | "list";
+    required?: boolean;
+    enabled?: boolean;
+    label?: string;
+    description?: string;
+    semantic_type?: string;
+    readonly?: boolean;
+    derived?: boolean;
+};
+export type StateVariableDefinition = {
+    key: string;
+    type: "string" | "number" | "boolean" | "object" | "list";
+    description?: string;
+    schema?: Record<string, unknown>;
+    default_value?: unknown;
+};
 export type GraphNode = {
     id: string;
     type: string;
@@ -158,71 +216,164 @@ export type GraphNode = {
     config: Record<string, unknown>;
     label?: string;
     data?: Record<string, unknown>;
-    input_mappings?: Record<string, unknown>;
+    input_mappings?: Record<string, string>;
 };
 export type GraphEdge = {
     id: string;
     source: string;
     target: string;
-    type?: string;
+    type?: "control" | "data";
     source_handle?: string;
     target_handle?: string;
     label?: string;
-    condition?: Record<string, unknown>;
+    condition?: string;
 };
 export type GraphDefinition = {
-    spec_version?: string;
-    graph_type?: "agent";
-    workflow_contract?: Record<string, unknown>;
-    state_contract?: Record<string, unknown>;
+    spec_version: "4.0";
+    graph_type: "agent";
+    workflow_contract: {
+        inputs: WorkflowInputDefinition[];
+    };
+    state_contract: {
+        variables: StateVariableDefinition[];
+    };
+    prompt_version_policies?: Record<string, unknown>;
     nodes: GraphNode[];
     edges: GraphEdge[];
+    metadata?: Record<string, unknown>;
+};
+export type NodeCatalogItem = {
+    type: string;
+    title: string;
+    description?: string | null;
+    category: string;
+    input_type: string;
+    output_type: string;
+    required_config_fields: string[];
+    icon?: string | null;
+    color?: string | null;
+    editor?: string | null;
+};
+export type BranchingHint = {
+    kind: string;
+    field?: string | null;
+    id_key?: string | null;
+    label_key?: string | null;
+    static_handles: string[];
+    default_handles: string[];
+};
+export type GraphHints = {
+    editor: string;
+    branching?: BranchingHint | null;
+};
+export type NodeAuthoringSpec = {
+    type: string;
+    title: string;
+    description?: string | null;
+    category: string;
+    input_type: string;
+    output_type: string;
+    config_schema: Record<string, unknown>;
+    input_schema?: Record<string, unknown> | null;
+    output_schema?: Record<string, unknown> | null;
+    field_contracts?: Record<string, unknown> | null;
+    graph_hints?: GraphHints | null;
+    node_template?: GraphNode | null;
+    normalization_defaults: Record<string, unknown>;
+};
+export type NodeCatalogResponse = {
+    nodes: NodeCatalogItem[];
+};
+export type NodeSchemaResponse = {
+    specs: Record<string, NodeAuthoringSpec>;
+    unknown: string[];
+    instance_contract: Record<string, unknown>;
+};
+export type AgentValidationIssue = {
+    code: string;
+    message: string;
+    severity: "error" | "warning";
+    node_id?: string | null;
+    edge_id?: string | null;
+    path?: string | null;
+    expected?: unknown;
+    actual?: unknown;
+    repair_hint?: string | null;
+};
+export type AgentValidationResult = {
+    valid: boolean;
+    errors: AgentValidationIssue[];
+    warnings: AgentValidationIssue[];
 };
 export type AgentCreateRequest = {
     name: string;
     description?: string | null;
+    tags?: string[];
     graph_definition: GraphDefinition;
     memory_config?: Record<string, unknown>;
     execution_constraints?: Record<string, unknown>;
 };
-export type AgentUpdateRequest = Partial<AgentCreateRequest> & {
-    status?: string;
-    is_active?: boolean;
-};
-export type AgentResponse = {
+export type AgentUpdateRequest = Partial<AgentCreateRequest>;
+export type AgentSummary = {
     id: string;
     organization_id: string;
-    project_id?: string | null;
     name: string;
     description?: string | null;
-    graph_definition: GraphDefinition;
-    memory_config: Record<string, unknown>;
-    execution_constraints: Record<string, unknown>;
-    status: string;
-    version: number;
-    is_active: boolean;
+    tags: string[];
+    lifecycle_status: "active" | "deprecated" | "archived" | "disabled";
+    publication_state: "never_published" | "published";
+    draft_revision_number: number;
     is_public: boolean;
     show_in_playground: boolean;
-    default_embed_policy_set_id?: string | null;
+    share_enabled: boolean;
+    share_handle?: string | null;
+    share_url?: string | null;
+    share_theme: "soft" | "sharp";
+    share_client_deployment_id?: string | null;
+    resource_policy_set_id?: string | null;
+    tool_binding_status?: string | null;
+    is_tool_enabled: boolean;
     created_at: string;
     updated_at: string;
     published_at?: string | null;
     latest_published_version_id?: string | null;
     has_unpublished_changes: boolean;
 };
+export type AgentResponse = AgentSummary & {
+    graph_definition: GraphDefinition;
+    memory_config: Record<string, unknown>;
+    execution_constraints: Record<string, unknown>;
+    attached_tools: Array<Record<string, unknown>>;
+};
 export type AgentListResponse = {
-    items: AgentResponse[];
+    items: Array<AgentSummary | AgentResponse>;
     total: number;
+    has_more: boolean;
+    skip: number;
+    limit: number;
+    view: "summary" | "full";
 };
 export type StartRunResult = {
     run_id: string;
     thread_id?: string | null;
 };
+export type FailureCategory = "validation" | "authentication" | "authorization" | "not_found" | "policy" | "conflict" | "billing" | "quota" | "rate_limit" | "capacity" | "dependency" | "protocol" | "timeout" | "internal";
+export type FailureView = {
+    schema_version: "agents24.failure.v1";
+    failure_id: string;
+    code: string;
+    category: FailureCategory;
+    message: string;
+    retryable: boolean;
+    request_id: string | null;
+    retry_after_ms: number | null;
+    details: Record<string, unknown>;
+};
 export type RunStatus = {
     id: string;
     status: string;
     result?: unknown;
-    error?: string | null;
+    failure?: FailureView | null;
     checkpoint?: Record<string, unknown> | null;
     run_usage?: Record<string, unknown>;
     context_window?: ContextWindow | null;
@@ -234,12 +385,51 @@ export type ControlPlaneRunEventsResponse = {
     events: RuntimeEvent[];
     [key: string]: unknown;
 };
-export type RunTrace = {
-    run: RunStatus;
-    tree: Record<string, unknown>;
-    events: ControlPlaneRunEventsResponse;
-    context: RunContext;
+export type TraceSpanKind = "run" | "workflow_node" | "agent" | "model" | "tool";
+export type TraceSpanStatus = "running" | "waiting" | "succeeded" | "failed" | "cancelled" | "skipped";
+export type TraceContent = {
+    type: "messages" | "message" | "text" | "json";
+    value: unknown;
+    redacted: boolean;
+    truncated: boolean;
 };
+export type TraceError = FailureView;
+export type TraceSpan = {
+    id: string;
+    span_id: string;
+    parent_id?: string | null;
+    run_id: string;
+    node_id?: string | null;
+    model_invocation_id?: string | null;
+    name: string;
+    kind: TraceSpanKind;
+    status: TraceSpanStatus;
+    sequence: number;
+    input?: TraceContent | null;
+    output?: TraceContent | null;
+    attributes: Record<string, unknown>;
+    diagnostics?: Record<string, unknown> | null;
+    failure?: TraceError | null;
+    started_at: string;
+    ended_at?: string | null;
+    duration_ms?: number | null;
+};
+export type TraceView = {
+    schema_version?: string | null;
+    trace_id: string;
+    root_run_id: string;
+    focus_run_id: string;
+    status: string;
+    legacy: boolean;
+    raw_events_available: boolean;
+    spans: TraceSpan[];
+    content_protection: {
+        redacted_fields: number;
+        truncated_fields: number;
+        diagnostics_included: boolean;
+    };
+};
+export type RunTrace = TraceView;
 export type AgentRef = string | {
     id: string;
 };
@@ -293,27 +483,16 @@ export type ClientRuntimeOidcConfig = {
 };
 export type ClientRuntimePolicyInput = {
     capabilities?: string[];
-    model?: {
-        allow_selection?: boolean;
-        allowed_model_ids?: string[];
-        default_model_id?: string | null;
-    };
-    tools?: {
-        allowed_tool_ids?: string[];
-        allow_input_overrides?: boolean;
-        allow_side_effecting_anonymous?: boolean;
-    };
+    model_selection?: "auto" | "enabled" | "disabled" | null;
     attachments?: {
         enabled?: boolean;
-        max_files_per_request?: number;
+        max_attachments_per_turn?: number;
         max_file_bytes?: number;
         max_total_bytes?: number;
         allowed_mime_types?: string[];
         max_image_pixels?: number;
         max_pdf_pages?: number;
         max_extracted_characters?: number;
-        retention_seconds?: number;
-        malware_scan_required?: boolean;
     };
     hitl?: {
         enabled?: boolean;
@@ -321,7 +500,7 @@ export type ClientRuntimePolicyInput = {
     };
     mcp?: {
         enabled?: boolean;
-        allowed_server_ids?: string[];
+        allow_anonymous?: boolean;
     };
     quotas?: {
         session_mints_per_minute?: number;
@@ -338,6 +517,7 @@ export type ClientRuntimePolicyInput = {
 };
 export type CreateClientDeploymentRequest = {
     agent_id: string;
+    resource_policy_set_id: string;
     version_policy?: {
         mode: "latest_published";
     } | {
@@ -352,12 +532,13 @@ export type CreateClientDeploymentRequest = {
     oidc?: ClientRuntimeOidcConfig | null;
     policy?: ClientRuntimePolicyInput;
 };
-export type UpdateClientDeploymentRequest = Partial<Omit<CreateClientDeploymentRequest, "agent_id">> & {
-    enabled?: boolean;
+export type UpdateClientDeploymentRequest = Partial<Omit<CreateClientDeploymentRequest, "agent_id" | "resource_policy_set_id">> & {
+    resource_policy_set_id?: string | null;
+    lifecycle_status?: "active" | "inactive";
 };
 export type ClientDeploymentListQuery = {
     agentId: string;
-    status?: "active" | "revoked";
+    lifecycleStatus?: "active" | "inactive";
     cursor?: string;
     limit?: number;
 };
@@ -379,8 +560,8 @@ export type ClientDeployment = {
     id: string;
     client_id: string;
     organization_id: string;
-    project_id: string;
     agent_id: string;
+    resource_policy_set_id: string | null;
     purpose: "client_integration" | "hosted_share";
     version_policy: {
         mode: "latest_published";
@@ -394,8 +575,7 @@ export type ClientDeployment = {
     };
     name: string;
     description: string | null;
-    enabled: boolean;
-    status: "active" | "revoked";
+    lifecycle_status: "active" | "inactive" | "deleted";
     policy_epoch: number;
     revocation_epoch: number;
     auth_modes: ClientAuthMode[];
@@ -407,7 +587,7 @@ export type ClientDeployment = {
     native_profiles: ClientNativeProfile[];
     created_at: string;
     updated_at: string;
-    revoked_at: string | null;
+    deleted_at: string | null;
 };
 export type ClientDeploymentListResponse = {
     items: ClientDeployment[];
@@ -431,7 +611,7 @@ export type ClientSessionCredentials = {
     refresh_expires_at: string | null;
     dpop_nonce: string | null;
 };
-export type PortableResourceKind = "agent" | "rag_pipeline" | "instruction";
+export type PortableResourceKind = "agent" | "rag_pipeline" | "instruction" | "knowledge_store";
 export type ResourceSelector = {
     kind: PortableResourceKind;
     id: string;
@@ -439,7 +619,7 @@ export type ResourceSelector = {
     version_id?: string;
 };
 export type ResourcePackageExportRequest = {
-    root: ResourceSelector;
+    selectors: ResourceSelector[];
 };
 export type ResourcePackageArchive = {
     data: Uint8Array;
@@ -460,19 +640,168 @@ export type ResourcePackageCompileResult = {
     format: "agents24.resource_package";
     schema_version: "1.0";
     package: Record<string, unknown>;
-    entrypoint: string;
     resources: Array<Record<string, unknown>>;
     requirements: string[];
     tool_exports: Array<Record<string, unknown>>;
     callable_bindings: Array<Record<string, unknown>>;
     diagnostics: ResourcePackageDiagnostic[];
-    bundle?: Record<string, unknown> | null;
+    bundle?: ResourceBundle | null;
 };
 export type ResourceBundleImportRequest = {
-    bundle: Record<string, unknown>;
+    bundle: ResourceBundle;
     selected_resource_keys?: string[];
     mappings?: Record<string, string>;
 };
+export type ResourceBundleOrigin = {
+    source_id: string;
+    target: "draft" | "version";
+    version_id?: string | null;
+    label: string;
+};
+export type ResourceBundleResource = {
+    resource_key: string;
+    kind: PortableResourceKind;
+    name: string;
+    document: Record<string, unknown>;
+    origin?: ResourceBundleOrigin;
+};
+export type ResourceBundleDependency = {
+    id: string;
+    from_resource_key: string;
+    to_resource_key?: string | null;
+    kind: string;
+    source_id: string;
+    source_name?: string | null;
+    document_path: string;
+    reference_type: string;
+    required: boolean;
+    bundled: boolean;
+    included?: boolean;
+    required_capability?: "chat" | "embedding";
+};
+export type ResourceBundle = {
+    format: "agents24.resource_bundle";
+    schema_version: "1.0";
+    exported_at?: string;
+    resources: ResourceBundleResource[];
+    dependencies: ResourceBundleDependency[];
+    warnings: string[];
+    tool_exports?: Array<Record<string, unknown>>;
+    callable_bindings?: Array<Record<string, unknown>>;
+};
+export type ResourceBundlePlan = Omit<ResourceBundle, "resources"> & {
+    resources: Array<Omit<ResourceBundleResource, "document">>;
+    blockers: Array<{
+        code: string;
+        message: string;
+    }>;
+    can_export: boolean;
+    external_references: ResourceBundleDependency[];
+};
+export type ResourceBundleExportRequest = {
+    selectors: ResourceSelector[];
+    included_resource_keys?: string[];
+};
+export type ResourceBundleCandidateList = {
+    items: Array<{
+        id: string;
+        name: string;
+    }>;
+    total: number;
+};
+export type ResourceBundleCandidateOptions = {
+    kind: string;
+    query?: string;
+    limit?: number;
+    offset?: number;
+    requiredCapability?: "chat" | "embedding";
+};
+export type ResourcePolicySummary = {
+    id: string;
+    name: string;
+    is_active: boolean;
+    [key: string]: unknown;
+};
+export type ResourcePolicyList = ResourcePolicySummary[];
+export type CustomerIdentityRequest = {
+    issuer: string;
+    subject: string;
+};
+export type SetCustomerResourcePolicyAssignmentRequest = CustomerIdentityRequest & {
+    policy_set_id: string;
+};
+export type EffectiveCustomerResourcePolicyRequest = CustomerIdentityRequest & {
+    deployment_id: string;
+};
+export type EmbedResourcePolicyRequest = {
+    external_user_id: string;
+    external_user_issuer?: string;
+    agent_version_id?: string;
+};
+export type ResourcePolicySubjectRef = {
+    kind: "agent" | "client_deployment" | "organization_user" | "customer_principal";
+    id: string;
+};
+export type ResourcePolicyQuotaSchedule = {
+    reset_anchor_at: string | null;
+    period_start: string;
+    next_reset_at: string;
+};
+export type CustomerResourcePolicyAssignment = {
+    customer_principal_ref: string;
+    subject_ref: ResourcePolicySubjectRef;
+    assignment: {
+        id: string;
+        policy_set: {
+            id: string;
+            name: string;
+        };
+    } | null;
+    quota_schedule: ResourcePolicyQuotaSchedule | null;
+};
+export type ClearCustomerResourcePolicyAssignmentResult = {
+    customer_principal_ref: string | null;
+    cleared: boolean;
+};
+export type EffectiveResourcePolicy = {
+    customer_principal_ref: string | null;
+    model_selection: {
+        selectable: boolean;
+        node_id: string | null;
+        default_id: string | null;
+        options: Array<{
+            id: string;
+            label: string;
+        }>;
+    };
+    quota_constraints: Array<{
+        model: {
+            id: string;
+            name: string;
+        };
+        boundary_kind: ResourcePolicySubjectRef["kind"];
+        boundary_ref: string;
+        used: number;
+        reserved: number;
+        limit: number;
+        remaining: number;
+        period_start: string;
+        reset_at: string;
+        blocked: boolean;
+    }>;
+    customer_assignment?: CustomerResourcePolicyAssignment;
+};
+export type SetResourcePolicyQuotaScheduleRequest = {
+    subject_ref: ResourcePolicySubjectRef;
+    reset_anchor_at: string | null;
+};
+export type ResetResourcePolicyQuotaRequest = {
+    subject_ref: ResourcePolicySubjectRef;
+};
+export type ResourcePolicyQuotaScheduleResult = {
+    subject_ref: ResourcePolicySubjectRef;
+    quota_schedule: ResourcePolicyQuotaSchedule;
+};
 export type ResourceBundleImportPreview = {
     resources: Array<Record<string, unknown>>;
     dependencies: Array<Record<string, unknown>>;