@openbkn/bkn-sdk 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -408,6 +408,258 @@ declare function appKeys(ctx: RequestContext): {
     adminRevoke: (id: string) => Promise<void>;
 };
 
+type LifecycleErrorCode = "conversation_required" | "conversation_not_found" | "conversation_closed" | "conversation_expired" | "conversation_owner_mismatch" | "interaction_required" | "interaction_in_progress" | "interaction_terminal" | "operation_required" | "idempotency_conflict" | "event_payload_conflict" | "receipt_pending" | "terminal_conflict" | "closure_manifest_invalid" | "feature_not_installed" | "capability_not_licensed" | "permission_denied" | "resource_not_disclosed";
+interface LifecycleError {
+    code: LifecycleErrorCode;
+    message: string;
+    retryable: boolean;
+    retry_after_ms: number;
+    current_status?: string;
+    required_action?: string;
+    request_id?: string;
+}
+interface LifecycleErrorEnvelope {
+    error: LifecycleError;
+}
+interface LifecycleOwner {
+    tenant_id: string;
+    business_domain_id: string;
+    application_principal_id: string;
+    effective_subject_type: "user" | "service";
+    effective_subject_id: string;
+    delegation_id?: string;
+}
+interface ManagedConversation {
+    conversation_id: string;
+    agent_name?: string;
+    owner: LifecycleOwner;
+    external_conversation_key: string;
+    generation: number;
+    status: "active" | "closed" | "expired";
+    one_shot: boolean;
+    row_version: number;
+    created_at: string;
+    updated_at: string;
+    closed_at?: string;
+}
+interface ConversationPage {
+    entries: ManagedConversation[];
+}
+interface ListConversationsQuery {
+    limit?: number;
+}
+interface ExpectedOperation {
+    operation_id: string;
+    required: boolean;
+}
+interface ExpectedReceipt {
+    receipt_id: string;
+    required: boolean;
+}
+interface EvidenceReference {
+    evidence_ref: string;
+    ref_type: "event" | "artifact" | "artifact_fragment" | "operation_output" | "claim";
+    source_interaction_id: string;
+    source_revision_id: string;
+    source_operation_id?: string;
+    artifact_ref?: string;
+    fragment_selector?: string;
+    version: string;
+    content_hash: string;
+    as_of?: string;
+}
+interface ClaimSupport {
+    target_ref: string;
+    target_type: "evidence" | "claim" | "artifact_fragment" | "operation_output";
+    source_interaction_id: string;
+    source_revision_id: string;
+    source_operation_id?: string;
+    version: string;
+    content_hash: string;
+    fragment_selector?: string;
+    role: string;
+    status: "adopted" | "rejected";
+    reason?: string;
+}
+interface ManagedClaim {
+    claim_id: string;
+    claim_type: string;
+    materiality: "material" | "supporting";
+    claim_status: "asserted" | "withdrawn";
+    content_artifact_ref: string;
+    required_support_roles: string[];
+    supports: ClaimSupport[];
+}
+interface InteractionCompletionInput {
+    terminal_idempotency_key: string;
+    lease_token: string;
+    lease_epoch: number;
+    completion_manifest_version: string;
+    completion_reason: string;
+    answer_artifact_ref?: string;
+    claims?: ManagedClaim[];
+    expected_operations?: ExpectedOperation[];
+    expected_receipts?: ExpectedReceipt[];
+    assembler_deadline?: string;
+}
+interface InteractionClosureManifest {
+    completion_manifest_version: string;
+    completion_reason: string;
+    answer_artifact_ref?: string;
+    claims?: ManagedClaim[];
+    expected_operations?: ExpectedOperation[];
+    expected_receipts?: ExpectedReceipt[];
+    assembler_deadline?: string;
+    system_partial_reasons?: string[];
+}
+interface ManagedInteraction {
+    interaction_id: string;
+    conversation_id: string;
+    ordinal: number;
+    execution_status: "active" | "completed" | "failed" | "canceled" | "handed_off" | "abandoned";
+    evidence_status: "not_applicable" | "assembling" | "complete" | "partial" | "failed";
+    closure_manifest?: InteractionClosureManifest;
+    lease_token: string;
+    lease_epoch: number;
+    lease_version: number;
+    lease_expires_at: string;
+    row_version: number;
+    created_at: string;
+    updated_at: string;
+    terminal_at?: string;
+}
+interface ManagedOperation {
+    operation_id: string;
+    conversation_id: string;
+    interaction_id: string;
+    operation_key: string;
+    tool_name: string;
+    normalized_input_hash: string;
+    parent_operation_id?: string;
+    causation_event_ids?: string[];
+    attempt: number;
+    attempt_status: "pending" | "completed" | "failed";
+    retryable: boolean;
+    row_version: number;
+    created_at: string;
+    updated_at: string;
+}
+interface LifecycleBusinessRef {
+    ref_type: string;
+    ref_id: string;
+    business_domain_id: string;
+    version: string;
+    as_of?: string;
+    display_hint?: string;
+}
+type EvidenceDurability = "pending" | "durable" | "failed";
+interface OperationReceipt {
+    receipt_id: string;
+    schema_version: string;
+    owner: LifecycleOwner;
+    conversation_id: string;
+    interaction_id: string;
+    operation_id: string;
+    attempt: number;
+    operation_key: string;
+    tool_name: string;
+    normalized_input_hash: string;
+    receipt_status: "pending" | "completed" | "failed";
+    evidence_durability: EvidenceDurability;
+    required: boolean;
+    request_id: string;
+    trace_id: string;
+    causation_event_ids: string[];
+    observed_evidence_refs: EvidenceReference[];
+    business_refs: LifecycleBusinessRef[];
+    artifact_refs: string[];
+    partial_reasons: string[];
+    row_version: number;
+    issued_at: string;
+    terminal_at?: string;
+    payload_hash: string;
+}
+interface OperationResult {
+    operation: ManagedOperation;
+    receipt: OperationReceipt;
+    created: boolean;
+}
+interface EnsureConversationInput {
+    external_conversation_key: string;
+    idempotency_key?: string;
+    one_shot?: boolean;
+}
+interface CreateNewConversationGenerationInput extends EnsureConversationInput {
+    idempotency_key: string;
+}
+interface ResumeConversationInput {
+    conversation_id: string;
+}
+interface CloseConversationInput {
+    idempotency_key?: string;
+}
+interface StartInteractionInput {
+    idempotency_key: string;
+    agent_name?: string;
+    lease_seconds?: number;
+}
+interface EnsureOperationInput {
+    operation_key: string;
+    tool_name: string;
+    normalized_input_hash: string;
+    parent_operation_id?: string;
+    causation_event_ids?: string[];
+    required?: boolean;
+    lease_token: string;
+    lease_epoch: number;
+}
+interface RetryOperationAttemptInput {
+    lease_token: string;
+    lease_epoch: number;
+}
+interface FinishOperationAttemptInput {
+    receipt_id: string;
+    payload_hash: string;
+    evidence_durability: EvidenceDurability;
+    retryable?: boolean;
+    request_id: string;
+    trace_id: string;
+    observed_evidence_refs?: EvidenceReference[];
+    business_refs?: LifecycleBusinessRef[];
+    artifact_refs?: string[];
+    partial_reasons?: string[];
+}
+interface TraceLifecycleApi {
+    listConversations(query?: ListConversationsQuery): Promise<ConversationPage>;
+    ensureConversation(input: EnsureConversationInput): Promise<ManagedConversation>;
+    createNewConversationGeneration(input: CreateNewConversationGenerationInput): Promise<ManagedConversation>;
+    resumeConversation(input: ResumeConversationInput): Promise<ManagedConversation>;
+    getConversation(conversationId: string): Promise<ManagedConversation>;
+    closeConversation(conversationId: string, input: CloseConversationInput): Promise<ManagedConversation>;
+    startInteraction(conversationId: string, input: StartInteractionInput): Promise<ManagedInteraction>;
+    getInteraction(interactionId: string): Promise<ManagedInteraction>;
+    completeInteraction(interactionId: string, input: InteractionCompletionInput): Promise<ManagedInteraction>;
+    failInteraction(interactionId: string, input: InteractionCompletionInput): Promise<ManagedInteraction>;
+    cancelInteraction(interactionId: string, input: InteractionCompletionInput): Promise<ManagedInteraction>;
+    handoffInteraction(interactionId: string, input: InteractionCompletionInput): Promise<ManagedInteraction>;
+    ensureOperation(conversationId: string, interactionId: string, input: EnsureOperationInput): Promise<OperationResult>;
+    getOperation(operationId: string): Promise<ManagedOperation>;
+    retryOperationAttempt(operationId: string, input: RetryOperationAttemptInput): Promise<OperationResult>;
+    completeOperationAttempt(operationId: string, attempt: number, input: FinishOperationAttemptInput): Promise<OperationResult>;
+    failOperationAttempt(operationId: string, attempt: number, input: FinishOperationAttemptInput): Promise<OperationResult>;
+    getReceipt(receiptId: string): Promise<OperationReceipt>;
+}
+declare function traceLifecycleApi(ctx: RequestContext): TraceLifecycleApi;
+
+interface ManagedToolResult<T = unknown> {
+    value: T;
+    receipt: OperationReceipt;
+}
+/** Adapter-owned MCP metadata for lifecycle-safe host retries. */
+interface ToolCallOptions {
+    hostConversationKey?: string;
+    clientInvocationId?: string;
+}
 interface SearchSchemaOptions {
     searchScope?: string[];
     maxConcepts?: number;
@@ -415,8 +667,6 @@ interface SearchSchemaOptions {
 /** Progressive KN-detail disclosure level: `summary` (skeleton + property names) | `full`. */
 type DetailLevel = "summary" | "full";
 
-/** Context-loader resource surface (MCP over agent-retrieval). */
-
 declare function context(ctx: RequestContext): {
     searchSchema: (knId: string, query: string, opts?: SearchSchemaOptions) => Promise<unknown>;
     queryObjectInstance: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
@@ -426,7 +676,8 @@ declare function context(ctx: RequestContext): {
     relationTypes: (knId: string, ids: string[]) => Promise<unknown>;
     info: () => Promise<unknown>;
     tools: (knId: string) => Promise<unknown>;
-    toolCall: (knId: string, name: string, args: Record<string, unknown>) => Promise<unknown>;
+    toolCall: (knId: string, name: string, args: Record<string, unknown>, options?: ToolCallOptions) => Promise<unknown>;
+    managedToolCall: <T = unknown>(knId: string, name: string, args: Record<string, unknown>, options?: ToolCallOptions) => Promise<ManagedToolResult<T>>;
     callMethod: (knId: string, method: string, params?: Record<string, unknown>) => Promise<unknown>;
     queryInstanceSubgraph: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
     logicProperties: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
@@ -481,6 +732,33 @@ declare function dataflows(ctx: RequestContext): {
     createBkn: (template: string, args: Record<string, unknown>) => Promise<unknown>;
 };
 
+/** The body field the lifecycle middleware reads. Snake_case: it goes on the wire. */
+interface BknContext {
+    conversation_id: string;
+    interaction_id: string;
+    /** v1 only. v2 rejects the field outright, so it must stay absent there. */
+    operation_key?: string;
+}
+/**
+ * Release the interactions this process opened.
+ *
+ * Only v2 is released. Its finish takes an id and an outcome, where v1's
+ * cancel demands a closure manifest — and the two kinds of v1 session are
+ * skipped for different reasons: one we opened ourselves carries `one_shot`
+ * and is swept when idle, while one opened inside a caller's conversation has
+ * no `one_shot` to rely on and no manifest we can supply (see `openSession`),
+ * so it waits out its five-minute lease. The outcome is `cancelled` because a
+ * CLI invocation has no answer artifact to close over, and `completed` without
+ * one is rejected.
+ *
+ * Best-effort by construction: this runs while a process is shutting down,
+ * where a throw would turn a successful command into a failed one. The whole
+ * release is bounded, not just its final call — the handshake being awaited
+ * here has no deadline of its own, so a server that accepted the connection
+ * and went quiet would hold the process open after its output was printed.
+ */
+declare function releaseLifecycleSessions(): Promise<void>;
+
 /**
  * Knowledge-network backend client (ontology-manager + agent-retrieval).
  * Responses are passed through as parsed JSON
@@ -522,6 +800,15 @@ interface SemanticSearchOptions {
     mode?: string;
     maxConcepts?: number;
     returnQueryUnderstanding?: boolean;
+    /**
+     * A `bkn_context` the caller built itself, sent as-is.
+     *
+     * The same escape hatch `context.toolCall` has: supplying one skips the
+     * managed session entirely, so an `operation_key` pre-registered through
+     * `ManagedTrace` survives instead of being replaced, and
+     * `parent_operation_id` / `causation_event_ids` travel with it.
+     */
+    bknContext?: BknContext;
 }
 
 interface CreateFromCatalogOptions {
@@ -773,6 +1060,33 @@ declare function resources(ctx: RequestContext): {
     query: (id: string, opts?: QueryResourceOptions) => Promise<unknown>;
 };
 
+/**
+ * Which side of the skill API to read.
+ *
+ * The consumer surface serves the **published** release; the management surface
+ * serves the **draft** (current) version and takes `view`/`modify` permissions
+ * rather than `execute`/`public_access`/`view`. The two disagree whenever a
+ * skill has been edited but not republished, so they are never interchangeable.
+ */
+type SkillView = "published" | "draft";
+interface ExecuteSkillOptions {
+    /** Shell command run inside the sandbox, relative to the skill's work dir. */
+    entryShell: string;
+    /** Sandbox wall-clock limit in seconds. */
+    timeout?: number;
+}
+interface SkillExecutionResult {
+    skill_id?: string;
+    session_id?: string;
+    work_dir?: string;
+    command?: string;
+    exit_code?: number;
+    stdout?: string;
+    stderr?: string;
+    execution_time?: number;
+    /** True when the sandbox stubbed the run instead of executing it. */
+    mocked?: boolean;
+}
 interface ListSkillsOptions {
     page?: number;
     pageSize?: number;
@@ -781,16 +1095,69 @@ interface ListSkillsOptions {
     status?: string;
     createUser?: string;
 }
+/**
+ * `url` hands back a pre-signed object-store link; `content` inlines the file
+ * body. Only the management surface honours `content` today — the consumer
+ * surface ignores it and answers with a URL either way.
+ */
+type SkillResponseMode = "url" | "content";
+interface SkillContentResponse {
+    skill_id?: string;
+    version?: string;
+    url?: string;
+    /** Present only when the backend honoured `response_mode=content`. */
+    content?: string;
+    files?: SkillFileEntry[];
+}
+interface SkillFileEntry {
+    rel_path: string;
+    file_type?: string;
+    size?: number;
+    mime_type?: string;
+}
+interface SkillReadFileResponse {
+    skill_id?: string;
+    rel_path?: string;
+    url?: string;
+    content?: string;
+    mime_type?: string;
+    file_type?: string;
+}
 type SkillStatus = "unpublish" | "published" | "offline";
 
+/** Which version a read targets: the published release, or the editable draft. */
+interface SkillViewOptions {
+    draft?: boolean;
+}
 declare function skills(ctx: RequestContext): {
     list: (opts?: ListSkillsOptions) => Promise<unknown>;
     get: (skillId: string) => Promise<unknown>;
     market: (opts?: ListSkillsOptions) => Promise<unknown>;
     marketGet: (skillId: string) => Promise<unknown>;
     delete: (skillId: string) => Promise<unknown>;
-    content: (skillId: string) => Promise<unknown>;
-    readFile: (skillId: string, relPath: string) => Promise<unknown>;
+    content: (skillId: string, opts?: SkillViewOptions) => Promise<SkillContentResponse>;
+    readFile: (skillId: string, relPath: string, opts?: SkillViewOptions) => Promise<SkillReadFileResponse>;
+    /** SKILL.md's own text, for callers that want the document rather than a link. */
+    contentRaw: (skillId: string, opts?: SkillViewOptions) => Promise<string>;
+    /** A bundled file's text. */
+    readFileRaw: (skillId: string, relPath: string, opts?: SkillViewOptions) => Promise<string>;
+    /** Run the skill in the platform sandbox. */
+    execute: (skillId: string, opts: ExecuteSkillOptions) => Promise<SkillExecutionResult>;
+    /** Resolve skill ids to names; unknown ids are simply absent from the result. */
+    names: (ids: string[]) => Promise<unknown>;
+    /**
+     * One level of the skill's file tree. Directories are inferred from the
+     * manifest's paths — see utils/skill-tree.
+     */
+    files: (skillId: string, path?: string, opts?: SkillViewOptions) => Promise<{
+        skillId: string;
+        path: string;
+        entries: SkillChild[];
+        totalFiles: number;
+        totalSize: number;
+    }>;
+    /** The manifest itself, for callers that want to render the whole tree. */
+    fileManifest: (skillId: string, opts?: SkillViewOptions) => Promise<SkillFileEntry[]>;
     history: (skillId: string) => Promise<unknown>;
     setStatus: (skillId: string, status: SkillStatus) => Promise<unknown>;
     updateMetadata: (skillId: string, body: unknown) => Promise<unknown>;
@@ -804,13 +1171,13 @@ declare function skills(ctx: RequestContext): {
     /** Replace a skill's package from a local directory. */
     updatePackage: (skillId: string, dir: string) => Promise<unknown>;
     /** Download a skill archive to a local .zip file. */
-    download: (skillId: string, outPath?: string) => Promise<{
+    download: (skillId: string, outPath?: string, opts?: SkillViewOptions) => Promise<{
         skillId: string;
         path: string;
         bytes: number;
     }>;
     /** Download a skill archive and extract it into a directory. */
-    install: (skillId: string, dir?: string) => Promise<{
+    install: (skillId: string, dir?: string, opts?: SkillViewOptions) => Promise<{
         skillId: string;
         dir: string;
         files: number;
@@ -882,6 +1249,85 @@ interface FixturePathValidationResult {
     results: FixtureValidationResult[];
 }
 
+type ConversationStrategy = {
+    mode: "resume_by_id";
+    conversationId: string;
+} | {
+    mode: "ensure_current";
+    externalConversationKey: string;
+} | {
+    mode: "one_shot";
+    externalConversationKey?: string;
+} | {
+    mode: "create_new_generation";
+    externalConversationKey: string;
+};
+type ManagedCompletionInput = Omit<InteractionCompletionInput, "terminal_idempotency_key" | "lease_token" | "lease_epoch">;
+interface BknBusinessContext {
+    bkn_context: {
+        conversation_id: string;
+        interaction_id: string;
+        operation_key: string;
+        parent_operation_id?: string;
+        causation_event_ids?: string[];
+    };
+}
+interface SupportCandidate {
+    ref: EvidenceReference;
+    state: "observed";
+    adopted: false;
+}
+interface ManagedInteractionScope {
+    conversation: ManagedConversation;
+    interaction: ManagedInteraction;
+    bknContext(operationKey: string, parentOperationId?: string, causationEventIds?: string[]): BknBusinessContext;
+    recordReceipt(receipt: OperationReceipt): void;
+    supportCandidates(): SupportCandidate[];
+    runOperation<T>(input: ManagedOperationInput, execute: (call: ManagedOperationCall) => Promise<ManagedOperationExecution<T>>): Promise<ManagedOperationResult<T>>;
+    cancel(reason: string): Promise<ManagedInteraction>;
+    handoff(reason: string): Promise<ManagedInteraction>;
+}
+interface ManagedOperationInput {
+    operationKey?: string;
+    toolName: string;
+    normalizedInputHash: string;
+    parentOperationId?: string;
+    causationEventIds?: string[];
+    required?: boolean;
+    /** Maximum authoritative attempt ordinal, including the current attempt. */
+    maxAttempts?: number;
+}
+interface ManagedOperationCall {
+    context: BknBusinessContext;
+    operation: ManagedOperation;
+    receipt: OperationReceipt;
+}
+interface ManagedOperationExecution<T> {
+    value: T;
+    receipt: OperationReceipt;
+}
+type ManagedOperationResult<T> = (ManagedOperationExecution<T> & {
+    recovered: false;
+}) | {
+    value: undefined;
+    receipt: OperationReceipt;
+    recovered: true;
+};
+interface ManagedTraceOptions {
+    idFactory?: () => string;
+}
+declare class ManagedTrace {
+    private readonly api;
+    private readonly idFactory;
+    private readonly pendingConversations;
+    private readonly activeConversationIds;
+    constructor(api: TraceLifecycleApi, options?: ManagedTraceOptions);
+    withInteraction(strategy: ConversationStrategy, callback: (scope: ManagedInteractionScope) => Promise<ManagedCompletionInput>): Promise<ManagedInteraction>;
+    private resolveConversation;
+    private ensureCurrent;
+    private runOperation;
+}
+
 /**
  * BKN Trace client (agent-observability). Implements raw trace search and a
  * two-hop "spans by conversation" fetch. The full
@@ -889,74 +1335,6 @@ interface FixturePathValidationResult {
  * is NOT included here — see docs/exec-plans/tech-debt-tracker.md.
  */
 
-interface EvidenceTraceContext {
-    trace_id: string;
-    traceparent: string;
-    "bkn.request.id": string;
-    "bkn.conversation.id"?: string;
-    "bkn.tenant.id"?: string;
-    business_domain?: string;
-    "bkn.account.id": string;
-    "bkn.account.type": string;
-}
-type BusinessEvidenceEventType = "agent.interaction.started" | "retrieval.completed" | "knowledge.read.observed" | "data.query.observed" | "logic.execution.observed" | "model.call.observed" | "tool.called" | "tool.result.observed" | "claim.created" | "evidence.refs.created" | "business.refs.resolved" | "action.recommended" | "action.approval_requested" | "action.approved" | "action.rejected" | "action.executed" | "action.result_recorded";
-interface EvidenceEvent {
-    event_id: string;
-    event_type: BusinessEvidenceEventType | (string & {});
-    "bkn.trace.schema.version": string;
-    observed_at: string;
-    emitted_at: string;
-    producer_module: string;
-    trace_id: string;
-    span_id: string;
-    "bkn.request.id": string;
-    "bkn.operation.name": string;
-    interaction_id?: string;
-    operation_id?: string;
-    causation_event_id?: string;
-    claim_id?: string;
-    attempt?: number;
-    payload: Record<string, unknown>;
-}
-interface EvidenceIngestRequest {
-    "bkn.trace.schema.version": "2.0.0" | "2.1.0" | "2.2.0";
-    trace: EvidenceTraceContext;
-    events: EvidenceEvent[];
-}
-type EvidenceArtifactType = "action_input" | "action_result" | "data_result" | "logic_execution" | "query" | "question" | "result";
-interface EvidenceArtifact {
-    artifact_id: string;
-    artifact_type: EvidenceArtifactType;
-    "bkn.request.id": string;
-    trace_id?: string;
-    interaction_id?: string;
-    operation_id?: string;
-    claim_id?: string;
-    source_ref?: string;
-    business_refs?: string[];
-    content_type: string;
-    schema_version: "2.2.0";
-    observed_at: string;
-    as_of?: string;
-    source_version?: string;
-    content_hash: string;
-    content?: unknown;
-    snapshot_ref?: string;
-    "bkn.tenant.id"?: string;
-    business_domain?: string;
-    "bkn.account.id": string;
-    "bkn.account.type": string;
-    initiator?: string;
-    agent_or_app?: string;
-}
-interface EvidenceArtifactIngestResponse {
-    artifact_id: string;
-    artifact_type: EvidenceArtifactType;
-    "bkn.request.id": string;
-    trace_id?: string;
-    content_hash: string;
-    created: boolean;
-}
 interface ActionSummary {
     recommended: number;
     approved: number;
@@ -964,27 +1342,6 @@ interface ActionSummary {
     completed: number;
     last_status?: string;
 }
-interface RequestSummary {
-    request_id: string;
-    conversation_id?: string;
-    interaction_id?: string;
-    started_at?: string;
-    completed_at?: string;
-    initiator?: string;
-    agent_or_app?: string;
-    business_domain?: string;
-    knowledge_networks?: string[];
-    question_preview?: string;
-    result_preview?: string;
-    status: string;
-    evidence_completeness: string;
-    partial_reasons?: string[];
-    business_refs?: string[];
-    action_summary: Partial<ActionSummary>;
-    trace_count: number;
-    duration_ms?: number;
-    error_summary?: string;
-}
 interface TraceExecutionSummary {
     trace_id: string;
     request_id: string;
@@ -1000,47 +1357,6 @@ interface TraceExecutionSummary {
     duration_ms?: number;
     error_summary?: string;
 }
-interface SummaryPage<T> {
-    entries: T[];
-    total: number;
-    next_cursor?: string | null;
-    truncated: boolean;
-    partial: boolean;
-    partial_reasons?: string[];
-}
-interface RequestSummaryQuery {
-    limit?: number;
-    cursor?: string;
-    from?: string;
-    to?: string;
-    status?: string;
-    agentOrApp?: string;
-    businessDomain?: string;
-    conversationId?: string;
-    interactionId?: string;
-    knowledgeNetwork?: string;
-    evidenceCompleteness?: string;
-    keyword?: string;
-}
-interface InteractionSummary {
-    interaction_id: string;
-    conversation_id?: string;
-    started_at?: string;
-    completed_at?: string;
-    status: string;
-    duration_ms?: number;
-    requests: RequestSummary[];
-    traces: TraceExecutionSummary[];
-}
-interface EvidenceIngestResponse {
-    trace_id: string;
-    "bkn.request.id": string;
-    "bkn.trace.schema.version": string;
-    accepted_event_count: number;
-    claim_count: number;
-    evidence_ref_count: number;
-    business_ref_count: number;
-}
 interface VisibilitySummary {
     authorized_ref_count: number;
     redacted_ref_count: number;
@@ -1085,52 +1401,6 @@ interface TraceGraphResponse {
         edges: TraceGraphEdge[];
     };
 }
-interface EvidenceChainResponse {
-    trace_id: string;
-    "bkn.request.id": string;
-    partial: boolean;
-    partial_reason: string[];
-    visibility_summary: VisibilitySummary;
-    page: GraphPage;
-    data: {
-        claims: Array<Record<string, unknown>>;
-        evidence_refs: Array<Record<string, unknown>>;
-        business_refs: Array<Record<string, unknown>>;
-    };
-}
-interface BusinessGraphResponse {
-    trace_id: string;
-    "bkn.request.id": string;
-    partial: boolean;
-    partial_reason: string[];
-    visibility_summary: VisibilitySummary;
-    page: GraphPage;
-    data: {
-        nodes: Array<Record<string, unknown>>;
-        edges: Array<Record<string, unknown>>;
-    };
-}
-interface SnapshotPreviewResponse {
-    trace_id: string;
-    "bkn.request.id": string;
-    partial: boolean;
-    partial_reason: string[];
-    visibility_summary: VisibilitySummary;
-    snapshot_ref: {
-        snapshot_id: string;
-        mode: "preview" | string;
-        uri?: string;
-    };
-    manifest: Record<string, unknown>;
-}
-type TraceScope = string | {
-    traceId: string;
-} | {
-    requestId: string;
-};
-interface TraceQueryOptions {
-    limit?: number;
-}
 
 /**
  * Trace diagnose engine. Fetches a conversation's spans, shapes them into a
@@ -1219,261 +1489,15 @@ interface EvalSetResult {
     cases: CaseResult[];
 }
 
-type EvidenceEmitter = (body: EvidenceIngestRequest) => Promise<EvidenceIngestResponse>;
-type IDFactory = () => string;
-interface TraceSessionOptions {
-    trace: EvidenceTraceContext;
-    producerModule: string;
-    spanId: string;
-    interactionId?: string;
-    conversationId?: string;
-    contractVersion?: "2.1.0" | "2.2.0";
-    emit: EvidenceEmitter;
-    idFactory?: IDFactory;
-    now?: () => string;
-}
-interface InteractionBase {
-    operationName: string;
-    intentHash: string;
-    mode: "chat" | "task" | "background";
-    questionArtifactRef?: string;
-}
-type InteractionInput = InteractionBase & ({
-    agentId: string;
-    appRef?: string;
-} | {
-    agentId?: string;
-    appRef: string;
-});
-interface OperationEventPayloadMap {
-    "retrieval.completed": {
-        query_hash: string;
-        candidate_count: number;
-        truncated: boolean;
-        version_status?: string;
-        source_refs?: string[];
-    };
-    "knowledge.read.observed": {
-        kn_id: string;
-        read_kind: string;
-        version_status: string;
-        schema_version?: string;
-        business_refs?: string[];
-    };
-    "data.query.observed": {
-        query_hash: string;
-        query_type: string;
-        row_count: number;
-        truncated?: boolean;
-        as_of?: string;
-        version_status?: string;
-        resource_refs?: string[];
-        field_refs?: string[];
-        query_artifact_ref?: string;
-        result_artifact_ref?: string;
-    };
-    "logic.execution.observed": {
-        logic_ref: string;
-        input_artifact_ref: string;
-        result_artifact_ref: string;
-        status: "ok" | "success" | "error";
-    };
-    "model.call.observed": {
-        model_name: string;
-        model_provider: string;
-        status: "ok" | "error";
-        input_token_count: number;
-        output_token_count: number;
-        prompt_hash: string;
-        output_hash: string;
-        error_category?: string;
-        error_hash?: string;
-    };
-    "tool.called": {
-        tool_id: string;
-        tool_name: string;
-        args_hash: string;
-        visibility: string;
-        version_status: string;
-    };
-    "tool.result.observed": {
-        tool_id: string;
-        tool_name: string;
-        status: "success" | "error";
-        result_hash?: string;
-        error_hash?: string;
-        visibility: string;
-        version_status: string;
-    };
-}
-type OperationEventType = keyof OperationEventPayloadMap;
-interface OperationInput<T extends OperationEventType = OperationEventType> {
-    operationName: string;
-    causationEventId: string;
-    operationId?: string;
-    attempt?: number;
-    claimId?: string;
-    payload: OperationEventPayloadMap[T];
-}
-interface ClaimInput {
-    operationName: string;
-    causationEventId: string;
-    claimId: string;
-    claimType: "answer" | "recommendation" | "structured_output" | "finding";
-    claimHash: string;
-    sourceEventIds: string[];
-    operationIds: string[];
-    resultArtifactRef?: string;
-    visibility?: string;
-    versionStatus?: string;
-}
-interface EvidenceRefInput {
-    refId: string;
-    refType: string;
-    sourceSystem: string;
-    validity: "observed" | "available" | "unavailable" | "expired" | "partial";
-    versionStatus: "versioned" | "unversioned" | "not_auditable";
-    visibility: "visible" | "redacted" | "hidden" | "omitted" | "unresolved" | "unauthorized";
-    summaryHash?: string;
-}
-interface EvidenceRefsInput {
-    operationName: string;
-    claimId: string;
-    causationEventId?: string;
-    refs: EvidenceRefInput[];
-}
-interface BusinessRefInput {
-    refId: string;
-    refType: "knowledge_network" | "object" | "property" | "relation" | "metric" | "logic" | "action";
-    sourceSystem: string;
-    validity: "observed" | "available" | "unavailable" | "expired" | "partial";
-    versionStatus: "versioned" | "unversioned" | "not_auditable";
-    visibility: "visible" | "redacted" | "hidden" | "omitted" | "unresolved" | "unauthorized";
-}
-interface BusinessRefsInput {
-    operationName: string;
-    claimId: string;
-    causationEventId?: string;
-    resolverStatus: "resolved" | "partial" | "unresolved";
-    refs: BusinessRefInput[];
-}
-interface ActionHandle {
-    readonly actionInstanceId: string;
-    readonly claimId: string;
-    readonly operationId: string;
-    readonly lastEventId: string;
-    readonly state: "recommended" | "approval_requested" | "approved" | "rejected" | "executed" | "result_recorded";
-}
-interface RecommendActionInput {
-    operationName: string;
-    claimId: string;
-    actionType: string;
-    targetRefs: string[];
-    reasonHash: string;
-    reasonArtifactRef?: string;
-    inputArtifactRef?: string;
-    causationEventId?: string;
-}
-type ExecuteActionInput = {
-    status: "ok";
-    invocationRef: string;
-} | {
-    status: "error";
-    invocationRef: string;
-    errorCategory: string;
-    errorHash: string;
-};
-type ActionResultInput = {
-    status: string;
-    resultHash: string;
-} & ({
-    resultArtifactRef: string;
-    taskRef?: string;
-    artifactRef?: never;
-} | {
-    taskRef: string;
-    artifactRef?: string;
-    resultArtifactRef?: string;
-} | {
-    taskRef?: string;
-    artifactRef: string;
-    resultArtifactRef?: string;
-});
-declare class TraceSession {
-    readonly interactionId: string;
-    private readonly trace;
-    private readonly producerModule;
-    private readonly spanId;
-    private readonly emit;
-    private readonly contractVersion;
-    private readonly idFactory;
-    private readonly now;
-    private readonly events;
-    private readonly eventIDs;
-    private readonly operationIDs;
-    private readonly claimEventIDs;
-    private readonly actions;
-    private flushTail;
-    constructor(options: TraceSessionOptions);
-    startInteraction(input: InteractionInput): EvidenceEvent;
-    observeOperation<T extends OperationEventType>(eventType: T, input: OperationInput<T>): EvidenceEvent;
-    createClaim(input: ClaimInput): EvidenceEvent;
-    createEvidenceRefs(input: EvidenceRefsInput): EvidenceEvent;
-    resolveBusinessRefs(input: BusinessRefsInput): EvidenceEvent;
-    recommendAction(input: RecommendActionInput): ActionHandle;
-    requestActionApproval(action: ActionHandle, input: {
-        policyRef: string;
-    }): EvidenceEvent;
-    approveAction(action: ActionHandle, input: {
-        actorRef: string;
-        policyDecisionRef: string;
-    }): EvidenceEvent;
-    rejectAction(action: ActionHandle, input: {
-        actorRef: string;
-        policyDecisionRef: string;
-    }): EvidenceEvent;
-    executeAction(action: ActionHandle, input: ExecuteActionInput): EvidenceEvent;
-    recordActionResult(action: ActionHandle, input: ActionResultInput): EvidenceEvent;
-    pendingEvents(): EvidenceEvent[];
-    flush(): Promise<EvidenceIngestResponse | undefined>;
-    private appendAction;
-    private append;
-    private flushEvents;
-    private assertContractPayload;
-    private assertKnownRefs;
-    private requireClaim;
-    private expectActionState;
-}
-
 declare function trace(ctx: RequestContext): {
+    /** Low-level BKN Trace 3.0 lifecycle and durable receipt API. */
+    lifecycle: TraceLifecycleApi;
+    /** Own one complete interaction lifecycle around an application callback. */
+    withInteraction: (strategy: ConversationStrategy, callback: (scope: ManagedInteractionScope) => Promise<ManagedCompletionInput>) => Promise<ManagedInteraction>;
     /** Raw trace search (OpenSearch-style body). */
     search: (body: unknown) => Promise<unknown>;
-    /** Submit BKN Trace phase-two claim/evidence/business events. */
-    emitEvidenceEvents: (body: EvidenceIngestRequest) => Promise<EvidenceIngestResponse>;
-    /** Store one authorized BKN Trace 2.2 business-content artifact. */
-    emitArtifact: (body: EvidenceArtifact) => Promise<EvidenceArtifactIngestResponse>;
-    /** Read one authorized BKN Trace 2.2 business-content artifact. */
-    artifact: (artifactId: string) => Promise<EvidenceArtifact>;
-    /** Product-facing business request list and request-to-trace drilldown. */
-    requests: {
-        get: (requestId: string) => Promise<RequestSummary>;
-        list: (query?: RequestSummaryQuery) => Promise<SummaryPage<RequestSummary>>;
-        traces: (requestId: string, query?: Pick<RequestSummaryQuery, "cursor" | "limit">) => Promise<SummaryPage<TraceExecutionSummary>>;
-    };
-    /** Aggregate all OpenBKN requests and traces for one caller-owned interaction. */
-    interactions: {
-        get: (interactionId: string) => Promise<InteractionSummary>;
-    };
-    /** Create a typed BKN Trace 2.1 session for an Agent or AI application. */
-    createSession: (options: Omit<TraceSessionOptions, "emit">) => TraceSession;
     /** Normalized trace tree/status graph by trace id. */
     graph: (traceId: string) => Promise<TraceGraphResponse>;
-    /** Claim -> evidence/business refs graph by trace id or BKN request id. */
-    evidenceChain: (scope: TraceScope, opts?: TraceQueryOptions) => Promise<EvidenceChainResponse>;
-    /** Business semantic graph by trace id or BKN request id. */
-    businessGraph: (scope: TraceScope, opts?: TraceQueryOptions) => Promise<BusinessGraphResponse>;
-    /** Metadata-only evidence snapshot preview by trace id or BKN request id. */
-    snapshotPreview: (scope: TraceScope, opts?: TraceQueryOptions) => Promise<SnapshotPreviewResponse>;
     /** All span source docs for a conversation. */
     spans: (conversationId: string, opts?: {
         maxTraceIds?: number;
@@ -1525,32 +1549,113 @@ declare function trace(ctx: RequestContext): {
 
 declare const BuildMode: z.ZodEnum<["batch", "streaming"]>;
 type BuildMode = z.infer<typeof BuildMode>;
+declare const BuildTaskStatus: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+type BuildTaskStatus = z.infer<typeof BuildTaskStatus>;
+declare const CatalogHealthCheckScheduleMode: z.ZodEnum<["inherit", "enabled", "disabled"]>;
+type CatalogHealthCheckScheduleMode = z.infer<typeof CatalogHealthCheckScheduleMode>;
+declare const CatalogHealthCheckStatus: z.ZodEnum<["healthy", "degraded", "unhealthy", "offline", "unchecked"]>;
+type CatalogHealthCheckStatus = z.infer<typeof CatalogHealthCheckStatus>;
+declare const CatalogHealthStatus: z.ZodObject<{
+    id: z.ZodString;
+    health_check_status: z.ZodEnum<["healthy", "degraded", "unhealthy", "offline", "unchecked"]>;
+    last_check_time: z.ZodOptional<z.ZodNumber>;
+    health_check_result: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    health_check_status: z.ZodEnum<["healthy", "degraded", "unhealthy", "offline", "unchecked"]>;
+    last_check_time: z.ZodOptional<z.ZodNumber>;
+    health_check_result: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    health_check_status: z.ZodEnum<["healthy", "degraded", "unhealthy", "offline", "unchecked"]>;
+    last_check_time: z.ZodOptional<z.ZodNumber>;
+    health_check_result: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+type CatalogHealthStatus = z.infer<typeof CatalogHealthStatus>;
+type CatalogHealthCheckScheduleRequest = {
+    mode: "enabled";
+    cronExpr: string;
+} | {
+    mode: "inherit" | "disabled";
+    cronExpr?: never;
+};
+declare const CatalogHealthCheckSchedule: z.ZodObject<{
+    catalog_id: z.ZodString;
+    mode: z.ZodEnum<["inherit", "enabled", "disabled"]>;
+    cron_expr: z.ZodOptional<z.ZodString>;
+    last_run: z.ZodNumber;
+    next_run: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    catalog_id: z.ZodString;
+    mode: z.ZodEnum<["inherit", "enabled", "disabled"]>;
+    cron_expr: z.ZodOptional<z.ZodString>;
+    last_run: z.ZodNumber;
+    next_run: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    catalog_id: z.ZodString;
+    mode: z.ZodEnum<["inherit", "enabled", "disabled"]>;
+    cron_expr: z.ZodOptional<z.ZodString>;
+    last_run: z.ZodNumber;
+    next_run: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+type CatalogHealthCheckSchedule = z.infer<typeof CatalogHealthCheckSchedule>;
+interface CatalogConnectionTestRequest {
+    connectorType: string;
+    connectorConfig: Record<string, unknown>;
+}
+declare const CatalogConnectionTestResult: z.ZodObject<{
+    success: z.ZodBoolean;
+    message: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    success: z.ZodBoolean;
+    message: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    success: z.ZodBoolean;
+    message: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+type CatalogConnectionTestResult = z.infer<typeof CatalogConnectionTestResult>;
+interface CatalogWriteOptions {
+    allowUnhealthy?: boolean;
+}
 /** POST /build-tasks body. */
-declare const CreateBuildTaskRequest: z.ZodObject<{
+declare const CreateBuildTaskRequest: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
     resource_id: z.ZodString;
-    mode: z.ZodEnum<["batch", "streaming"]>;
+    mode: z.ZodLiteral<"batch">;
     execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
 }, "strip", z.ZodTypeAny, {
-    mode: "batch" | "streaming";
+    mode: "batch";
     resource_id: string;
     execute_type?: "full" | "incremental" | undefined;
 }, {
-    mode: "batch" | "streaming";
+    mode: "batch";
     resource_id: string;
     execute_type?: "full" | "incremental" | undefined;
-}>;
+}>, z.ZodObject<{
+    resource_id: z.ZodString;
+    mode: z.ZodLiteral<"streaming">;
+    execute_type: z.ZodOptional<z.ZodNever>;
+}, "strip", z.ZodTypeAny, {
+    mode: "streaming";
+    resource_id: string;
+    execute_type?: undefined;
+}, {
+    mode: "streaming";
+    resource_id: string;
+    execute_type?: undefined;
+}>]>;
 type CreateBuildTaskRequest = z.infer<typeof CreateBuildTaskRequest>;
 declare const BuildTask: z.ZodObject<{
     id: z.ZodString;
     resource_id: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<["batch", "streaming"]>>;
-    status: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>>;
     state: z.ZodOptional<z.ZodString>;
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
     index_config: z.ZodOptional<z.ZodUnknown>;
     catalog_id: z.ZodOptional<z.ZodString>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
     index_health: z.ZodOptional<z.ZodObject<{
         embedding: z.ZodString;
         fulltext: z.ZodString;
@@ -1568,13 +1673,14 @@ declare const BuildTask: z.ZodObject<{
     id: z.ZodString;
     resource_id: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<["batch", "streaming"]>>;
-    status: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>>;
     state: z.ZodOptional<z.ZodString>;
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
     index_config: z.ZodOptional<z.ZodUnknown>;
     catalog_id: z.ZodOptional<z.ZodString>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
     index_health: z.ZodOptional<z.ZodObject<{
         embedding: z.ZodString;
         fulltext: z.ZodString;
@@ -1592,13 +1698,14 @@ declare const BuildTask: z.ZodObject<{
     id: z.ZodString;
     resource_id: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<["batch", "streaming"]>>;
-    status: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>>;
     state: z.ZodOptional<z.ZodString>;
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
     index_config: z.ZodOptional<z.ZodUnknown>;
     catalog_id: z.ZodOptional<z.ZodString>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
     index_health: z.ZodOptional<z.ZodObject<{
         embedding: z.ZodString;
         fulltext: z.ZodString;
@@ -1614,15 +1721,533 @@ declare const BuildTask: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>>;
 }, z.ZodTypeAny, "passthrough">>;
 type BuildTask = z.infer<typeof BuildTask>;
+/** Lightweight BuildTask representation returned by list APIs. */
+declare const BuildTaskSummary: z.ZodObject<{
+    id: z.ZodString;
+    resource_id: z.ZodString;
+    resource_name: z.ZodOptional<z.ZodString>;
+    catalog_id: z.ZodString;
+    catalog_name: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+    mode: z.ZodEnum<["batch", "streaming"]>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+    total_count: z.ZodNumber;
+    synced_count: z.ZodNumber;
+    vectorized_count: z.ZodNumber;
+    synced_mark: z.ZodString;
+    error_msg: z.ZodOptional<z.ZodString>;
+    creator: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        type: string;
+        name?: string | undefined;
+    }, {
+        id: string;
+        type: string;
+        name?: string | undefined;
+    }>;
+    create_time: z.ZodNumber;
+    update_time: z.ZodNumber;
+    index_health: z.ZodOptional<z.ZodObject<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    resource_id: z.ZodString;
+    resource_name: z.ZodOptional<z.ZodString>;
+    catalog_id: z.ZodString;
+    catalog_name: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+    mode: z.ZodEnum<["batch", "streaming"]>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+    total_count: z.ZodNumber;
+    synced_count: z.ZodNumber;
+    vectorized_count: z.ZodNumber;
+    synced_mark: z.ZodString;
+    error_msg: z.ZodOptional<z.ZodString>;
+    creator: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        type: string;
+        name?: string | undefined;
+    }, {
+        id: string;
+        type: string;
+        name?: string | undefined;
+    }>;
+    create_time: z.ZodNumber;
+    update_time: z.ZodNumber;
+    index_health: z.ZodOptional<z.ZodObject<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    resource_id: z.ZodString;
+    resource_name: z.ZodOptional<z.ZodString>;
+    catalog_id: z.ZodString;
+    catalog_name: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+    mode: z.ZodEnum<["batch", "streaming"]>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+    total_count: z.ZodNumber;
+    synced_count: z.ZodNumber;
+    vectorized_count: z.ZodNumber;
+    synced_mark: z.ZodString;
+    error_msg: z.ZodOptional<z.ZodString>;
+    creator: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        type: string;
+        name?: string | undefined;
+    }, {
+        id: string;
+        type: string;
+        name?: string | undefined;
+    }>;
+    create_time: z.ZodNumber;
+    update_time: z.ZodNumber;
+    index_health: z.ZodOptional<z.ZodObject<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">>;
+type BuildTaskSummary = z.infer<typeof BuildTaskSummary>;
+declare const ListBuildTasksResponse: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+    total_count: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+    total_count: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        resource_id: z.ZodString;
+        resource_name: z.ZodOptional<z.ZodString>;
+        catalog_id: z.ZodString;
+        catalog_name: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+        mode: z.ZodEnum<["batch", "streaming"]>;
+        execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
+        total_count: z.ZodNumber;
+        synced_count: z.ZodNumber;
+        vectorized_count: z.ZodNumber;
+        synced_mark: z.ZodString;
+        error_msg: z.ZodOptional<z.ZodString>;
+        creator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }, {
+            id: string;
+            type: string;
+            name?: string | undefined;
+        }>;
+        create_time: z.ZodNumber;
+        update_time: z.ZodNumber;
+        index_health: z.ZodOptional<z.ZodObject<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            embedding: z.ZodString;
+            fulltext: z.ZodString;
+            usable: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+    total_count: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+type ListBuildTasksResponse = z.infer<typeof ListBuildTasksResponse>;
 interface ListBuildTasksOptions {
     limit?: number;
     offset?: number;
     resourceId?: string;
     catalogId?: string;
-    status?: string | string[];
+    status?: BuildTaskStatus | BuildTaskStatus[];
     active?: boolean;
     mode?: BuildMode;
-    orderBy?: "default" | "created_at" | "updated_at" | "status" | "mode";
+    orderBy?: "created_at" | "updated_at";
     order?: "asc" | "desc";
 }
 interface DeleteBuildTasksOptions {
@@ -1671,7 +2296,7 @@ interface ListCatalogsOptions {
     tag?: string;
     type?: "physical" | "logical" | string;
     enabled?: boolean;
-    healthCheckStatus?: string;
+    healthCheckStatus?: CatalogHealthCheckStatus;
     includeExtensions?: boolean;
     includeExtensionKeys?: string;
     extensionPairs?: Array<{
@@ -1685,27 +2310,64 @@ interface ListCatalogsOptions {
 interface CreateCatalogRequest {
     name: string;
     connectorType: string;
-    connectorConfig: unknown;
+    connectorConfig: Record<string, unknown>;
     tags?: string[];
     description?: string;
     enabled?: boolean;
     id?: string;
     internal?: boolean;
     extensions?: Record<string, string>;
+    healthCheckSchedule?: CatalogHealthCheckScheduleRequest | null;
+}
+/** Full PUT /catalogs/{id} body; the path id is injected by the API client. */
+interface UpdateCatalogRequest {
+    name: string;
+    connectorType: string;
+    enabled: boolean;
+    connectorConfig?: Record<string, unknown>;
+    tags?: string[];
+    description?: string;
+    extensions?: Record<string, string>;
 }
 
 declare function vega(ctx: RequestContext): {
     catalogs: (opts?: ListCatalogsOptions) => Promise<unknown>;
     getCatalog: (id: string) => Promise<unknown>;
-    createCatalog: (req: CreateCatalogRequest) => Promise<unknown>;
-    updateCatalog: (id: string, req: Partial<CreateCatalogRequest>) => Promise<unknown>;
+    createCatalog: (req: CreateCatalogRequest, opts?: CatalogWriteOptions) => Promise<unknown>;
+    updateCatalog: (id: string, req: UpdateCatalogRequest, opts?: CatalogWriteOptions) => Promise<unknown>;
     enableCatalog: (id: string) => Promise<unknown>;
     disableCatalog: (id: string) => Promise<unknown>;
     deleteCatalog: (id: string) => Promise<unknown>;
-    testCatalogConnection: (id: string) => Promise<unknown>;
+    testCatalogConnectionConfig: (req: CatalogConnectionTestRequest) => Promise<zod.objectOutputType<{
+        success: zod.ZodBoolean;
+        message: zod.ZodOptional<zod.ZodString>;
+    }, zod.ZodTypeAny, "passthrough">>;
+    testCatalogConnection: (id: string) => Promise<zod.objectOutputType<{
+        success: zod.ZodBoolean;
+        message: zod.ZodOptional<zod.ZodString>;
+    }, zod.ZodTypeAny, "passthrough">>;
+    catalogHealthCheckSchedule: (id: string) => Promise<zod.objectOutputType<{
+        catalog_id: zod.ZodString;
+        mode: zod.ZodEnum<["inherit", "enabled", "disabled"]>;
+        cron_expr: zod.ZodOptional<zod.ZodString>;
+        last_run: zod.ZodNumber;
+        next_run: zod.ZodNumber;
+    }, zod.ZodTypeAny, "passthrough">>;
+    updateCatalogHealthCheckSchedule: (id: string, req: CatalogHealthCheckScheduleRequest) => Promise<zod.objectOutputType<{
+        catalog_id: zod.ZodString;
+        mode: zod.ZodEnum<["inherit", "enabled", "disabled"]>;
+        cron_expr: zod.ZodOptional<zod.ZodString>;
+        last_run: zod.ZodNumber;
+        next_run: zod.ZodNumber;
+    }, zod.ZodTypeAny, "passthrough">>;
     discoverCatalog: (id: string, wait?: boolean) => Promise<unknown>;
     catalogResources: (id: string, category?: string, limit?: number, offset?: number) => Promise<unknown>;
-    catalogHealth: (ids: string[]) => Promise<unknown>;
+    catalogHealth: (id: string) => Promise<zod.objectOutputType<{
+        id: zod.ZodString;
+        health_check_status: zod.ZodEnum<["healthy", "degraded", "unhealthy", "offline", "unchecked"]>;
+        last_check_time: zod.ZodOptional<zod.ZodNumber>;
+        health_check_result: zod.ZodOptional<zod.ZodString>;
+    }, zod.ZodTypeAny, "passthrough">>;
     connectorTypes: () => Promise<unknown>;
     connectorType: (type: string) => Promise<unknown>;
     /** Run SQL / OpenSearch DSL directly against a data source. */
@@ -1720,13 +2382,14 @@ declare function vega(ctx: RequestContext): {
         id: zod.ZodString;
         resource_id: zod.ZodOptional<zod.ZodString>;
         mode: zod.ZodOptional<zod.ZodEnum<["batch", "streaming"]>>;
-        status: zod.ZodOptional<zod.ZodString>;
+        status: zod.ZodOptional<zod.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>>;
         state: zod.ZodOptional<zod.ZodString>;
         total_count: zod.ZodOptional<zod.ZodNumber>;
         synced_count: zod.ZodOptional<zod.ZodNumber>;
         vectorized_count: zod.ZodOptional<zod.ZodNumber>;
         index_config: zod.ZodOptional<zod.ZodUnknown>;
         catalog_id: zod.ZodOptional<zod.ZodString>;
+        execute_type: zod.ZodOptional<zod.ZodEnum<["incremental", "full"]>>;
         index_health: zod.ZodOptional<zod.ZodObject<{
             embedding: zod.ZodString;
             fulltext: zod.ZodString;
@@ -1741,7 +2404,136 @@ declare function vega(ctx: RequestContext): {
             usable: zod.ZodBoolean;
         }, zod.ZodTypeAny, "passthrough">>>;
     }, zod.ZodTypeAny, "passthrough">>;
-    buildTasks: (opts?: ListBuildTasksOptions) => Promise<unknown>;
+    buildTasks: (opts?: ListBuildTasksOptions) => Promise<zod.objectOutputType<{
+        entries: zod.ZodArray<zod.ZodObject<{
+            id: zod.ZodString;
+            resource_id: zod.ZodString;
+            resource_name: zod.ZodOptional<zod.ZodString>;
+            catalog_id: zod.ZodString;
+            catalog_name: zod.ZodOptional<zod.ZodString>;
+            status: zod.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+            mode: zod.ZodEnum<["batch", "streaming"]>;
+            execute_type: zod.ZodOptional<zod.ZodEnum<["incremental", "full"]>>;
+            total_count: zod.ZodNumber;
+            synced_count: zod.ZodNumber;
+            vectorized_count: zod.ZodNumber;
+            synced_mark: zod.ZodString;
+            error_msg: zod.ZodOptional<zod.ZodString>;
+            creator: zod.ZodObject<{
+                id: zod.ZodString;
+                name: zod.ZodOptional<zod.ZodString>;
+                type: zod.ZodString;
+            }, "strip", zod.ZodTypeAny, {
+                id: string;
+                type: string;
+                name?: string | undefined;
+            }, {
+                id: string;
+                type: string;
+                name?: string | undefined;
+            }>;
+            create_time: zod.ZodNumber;
+            update_time: zod.ZodNumber;
+            index_health: zod.ZodOptional<zod.ZodObject<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, "passthrough", zod.ZodTypeAny, zod.objectOutputType<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, zod.ZodTypeAny, "passthrough">, zod.objectInputType<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, zod.ZodTypeAny, "passthrough">>>;
+        }, "passthrough", zod.ZodTypeAny, zod.objectOutputType<{
+            id: zod.ZodString;
+            resource_id: zod.ZodString;
+            resource_name: zod.ZodOptional<zod.ZodString>;
+            catalog_id: zod.ZodString;
+            catalog_name: zod.ZodOptional<zod.ZodString>;
+            status: zod.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+            mode: zod.ZodEnum<["batch", "streaming"]>;
+            execute_type: zod.ZodOptional<zod.ZodEnum<["incremental", "full"]>>;
+            total_count: zod.ZodNumber;
+            synced_count: zod.ZodNumber;
+            vectorized_count: zod.ZodNumber;
+            synced_mark: zod.ZodString;
+            error_msg: zod.ZodOptional<zod.ZodString>;
+            creator: zod.ZodObject<{
+                id: zod.ZodString;
+                name: zod.ZodOptional<zod.ZodString>;
+                type: zod.ZodString;
+            }, "strip", zod.ZodTypeAny, {
+                id: string;
+                type: string;
+                name?: string | undefined;
+            }, {
+                id: string;
+                type: string;
+                name?: string | undefined;
+            }>;
+            create_time: zod.ZodNumber;
+            update_time: zod.ZodNumber;
+            index_health: zod.ZodOptional<zod.ZodObject<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, "passthrough", zod.ZodTypeAny, zod.objectOutputType<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, zod.ZodTypeAny, "passthrough">, zod.objectInputType<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, zod.ZodTypeAny, "passthrough">>>;
+        }, zod.ZodTypeAny, "passthrough">, zod.objectInputType<{
+            id: zod.ZodString;
+            resource_id: zod.ZodString;
+            resource_name: zod.ZodOptional<zod.ZodString>;
+            catalog_id: zod.ZodString;
+            catalog_name: zod.ZodOptional<zod.ZodString>;
+            status: zod.ZodEnum<["init", "running", "stopping", "stopped", "completed", "failed"]>;
+            mode: zod.ZodEnum<["batch", "streaming"]>;
+            execute_type: zod.ZodOptional<zod.ZodEnum<["incremental", "full"]>>;
+            total_count: zod.ZodNumber;
+            synced_count: zod.ZodNumber;
+            vectorized_count: zod.ZodNumber;
+            synced_mark: zod.ZodString;
+            error_msg: zod.ZodOptional<zod.ZodString>;
+            creator: zod.ZodObject<{
+                id: zod.ZodString;
+                name: zod.ZodOptional<zod.ZodString>;
+                type: zod.ZodString;
+            }, "strip", zod.ZodTypeAny, {
+                id: string;
+                type: string;
+                name?: string | undefined;
+            }, {
+                id: string;
+                type: string;
+                name?: string | undefined;
+            }>;
+            create_time: zod.ZodNumber;
+            update_time: zod.ZodNumber;
+            index_health: zod.ZodOptional<zod.ZodObject<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, "passthrough", zod.ZodTypeAny, zod.objectOutputType<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, zod.ZodTypeAny, "passthrough">, zod.objectInputType<{
+                embedding: zod.ZodString;
+                fulltext: zod.ZodString;
+                usable: zod.ZodBoolean;
+            }, zod.ZodTypeAny, "passthrough">>>;
+        }, zod.ZodTypeAny, "passthrough">>, "many">;
+        total_count: zod.ZodNumber;
+    }, zod.ZodTypeAny, "passthrough">>;
     deleteBuildTasks: (ids: string[], opts?: DeleteBuildTasksOptions) => Promise<unknown>;
     startBuildTask: (taskId: string, opts?: {
         reset?: boolean;
@@ -1782,6 +2574,15 @@ declare class HttpError extends Error {
     readonly hint?: string;
     constructor(status: number, statusText: string, body: string, hint?: string);
 }
+/**
+ * Raised when an MCP tool answers with `isError`. The transport call succeeded,
+ * so this is not an {@link HttpError} — but the server's error `code` is what
+ * decides whether a caller can recover, so it travels with the error.
+ */
+declare class ToolError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
 /** Raised for bad CLI/SDK input before any request is made. */
 declare class InputError extends Error {
     constructor(message: string);
@@ -1940,6 +2741,33 @@ declare namespace auth {
   export { type auth_AuthStatus as AuthStatus, type auth_PlatformListItem as PlatformListItem, type auth_WhoamiResult as WhoamiResult, auth_attachToken as attachToken, auth_currentToken as currentToken, auth_currentTokenFresh as currentTokenFresh, auth_deletePlatform as deletePlatform, auth_exportCreds as exportCreds, auth_hostOf as hostOf, auth_listPlatforms as listPlatforms, auth_logout as logout, auth_status as status, auth_switchUser as switchUser, auth_use as use, auth_userIdFromToken as userIdFromToken, auth_usersOf as usersOf, auth_whoami as whoami };
 }
 
+/**
+ * Directory views over a skill's file manifest.
+ *
+ * The backend manifest is a flat list of archive-relative paths — registration
+ * drops zip directory entries — so the folder structure here is inferred from
+ * the paths themselves. One consequence is inherent: a directory that holds no
+ * files cannot appear, because nothing in the manifest mentions it.
+ */
+
+interface SkillDirChild {
+    name: string;
+    type: "dir";
+    /** Files anywhere beneath this directory. */
+    files: number;
+    /** Total bytes beneath this directory. */
+    size: number;
+}
+interface SkillFileChild {
+    name: string;
+    type: "file";
+    relPath: string;
+    fileType?: string;
+    size?: number;
+    mime?: string;
+}
+type SkillChild = SkillDirChild | SkillFileChild;
+
 interface RequestInitEx {
     method?: string;
     /** JSON body — serialized and Content-Type set automatically. */
@@ -1951,9 +2779,16 @@ interface RequestInitEx {
     redirect?: "follow" | "error" | "manual";
     /** Per-request timeout; defaults to 30s. */
     timeoutMs?: number;
+    /**
+     * Raise undici's 300s response-header deadline for this request.
+     *
+     * Needed by any endpoint that blocks until its work finishes — it sends no
+     * headers until then, so `timeoutMs` alone cannot buy more than 300s.
+     */
+    headersTimeoutMs?: number;
 }
 declare function request<T = unknown>(ctx: RequestContext, path: string, init?: RequestInitEx): Promise<T>;
 
 declare function resolveContext(opts?: ClientOptions): RequestContext;
 
-export { type ActionHandle, type ActionResultInput, type ActionSummary, type BknClient, BuildMode, BuildTask, type BusinessEvidenceEventType, type BusinessGraphResponse, type BusinessRefInput, type BusinessRefsInput, type ClaimInput, type ClientOptions, CreateBuildTaskRequest, DEFAULT_BUSINESS_DOMAIN, DEFAULT_LIST_LIMIT, DEFAULT_QUERY_LIMIT, type DslRawQueryRequest, type EvidenceArtifact, type EvidenceArtifactIngestResponse, type EvidenceArtifactType, type EvidenceChainResponse, type EvidenceEvent, type EvidenceIngestRequest, type EvidenceIngestResponse, type EvidenceRefInput, type EvidenceRefsInput, type EvidenceTraceContext, type ExecuteActionInput, type GraphPage, HttpError, InputError, type InteractionInput, type InteractionSummary, type OperationEventPayloadMap, type OperationEventType, type OperationInput, type QueryPagingMode, type RawQueryContinuationRequest, type RawQueryPaging, type RawQueryRequest, type RecommendActionInput, type RequestContext, type RequestSummary, type RequestSummaryQuery, type SnapshotPreviewResponse, type SqlRawQueryRequest, type SummaryPage, type TraceExecutionSummary, type TraceGraphEdge, type TraceGraphNode, type TraceGraphResponse, type TraceQueryOptions, type TraceScope, TraceSession, type TraceSessionOptions, type VisibilitySummary, admin, agents, auth, context, createClient, dataflows, kn, models, request, resolveContext, resources, skills, toolboxes, trace, vega };
+export { type ActionSummary, type BknBusinessContext, type BknClient, type BknContext, BuildMode, BuildTask, BuildTaskSummary, type CatalogConnectionTestRequest, CatalogConnectionTestResult, CatalogHealthCheckSchedule, CatalogHealthCheckScheduleMode, type CatalogHealthCheckScheduleRequest, CatalogHealthCheckStatus, CatalogHealthStatus, type CatalogWriteOptions, type ClaimSupport, type ClientOptions, type CloseConversationInput, type ConversationPage, type ConversationStrategy, CreateBuildTaskRequest, type CreateCatalogRequest, type CreateNewConversationGenerationInput, DEFAULT_BUSINESS_DOMAIN, DEFAULT_LIST_LIMIT, DEFAULT_QUERY_LIMIT, type DslRawQueryRequest, type EnsureConversationInput, type EnsureOperationInput, type EvidenceDurability, type EvidenceReference, type ExecuteSkillOptions, type ExpectedOperation, type ExpectedReceipt, type FinishOperationAttemptInput, type GraphPage, HttpError, InputError, type InteractionCompletionInput, type LifecycleBusinessRef, type LifecycleError, type LifecycleErrorCode, type LifecycleErrorEnvelope, type LifecycleOwner, type ListBuildTasksOptions, ListBuildTasksResponse, type ListConversationsQuery, type ManagedClaim, type ManagedCompletionInput, type ManagedConversation, type ManagedInteraction, type ManagedInteractionScope, type ManagedOperation, type ManagedOperationCall, type ManagedOperationExecution, type ManagedOperationInput, type ManagedOperationResult, type ManagedToolResult, ManagedTrace, type ManagedTraceOptions, type OperationReceipt, type OperationResult, type QueryPagingMode, type RawQueryContinuationRequest, type RawQueryPaging, type RawQueryRequest, type RequestContext, type ResumeConversationInput, type RetryOperationAttemptInput, type SkillChild, type SkillContentResponse, type SkillDirChild, type SkillExecutionResult, type SkillFileChild, type SkillFileEntry, type SkillReadFileResponse, type SkillResponseMode, type SkillView, type SkillViewOptions, type SqlRawQueryRequest, type StartInteractionInput, type SupportCandidate, type ToolCallOptions, ToolError, type TraceExecutionSummary, type TraceGraphEdge, type TraceGraphNode, type TraceGraphResponse, type TraceLifecycleApi, type UpdateCatalogRequest, type VisibilitySummary, admin, agents, auth, context, createClient, dataflows, kn, models, releaseLifecycleSessions, request, resolveContext, resources, skills, toolboxes, trace, traceLifecycleApi, vega };