@openbkn/bkn-sdk 0.1.1 → 0.1.3-rc.1

package/dist/index.d.ts

@@ -12,6 +12,10 @@ interface ClientOptions {
     businessDomain?: string;
     /** Skip TLS verification (dev / self-signed only). */
     insecure?: boolean;
+    /** Dedicated producer credential, sent only to BKN Trace evidence write endpoints. */
+    evidenceIngestToken?: string;
+    /** Optional BKN Trace phase-one context for request correlation. */
+    trace?: TraceContextOptions;
 }
 /** Fully resolved request context — every field is known. */
 interface RefreshableTokens {
@@ -24,6 +28,10 @@ interface RequestContext {
     token: string;
     businessDomain: string;
     insecure: boolean;
+    /** Dedicated producer credential; never sent to read or non-Trace endpoints. */
+    evidenceIngestToken?: string;
+    /** Stable per-client BKN Trace context propagated on outbound requests. */
+    trace?: TraceContext;
     /**
      * Stored-credential refresh: on a 401, swap the refresh token for a fresh
      * access token, persist it, and retry once. Absent for explicit `--token`/env.
@@ -34,6 +42,34 @@ interface RequestContext {
         persist: (tokens: RefreshableTokens) => void;
     };
 }
+interface TraceContextOptions {
+    /** OpenBKN request id. Generated as `req_<uuid>` when omitted or invalid. */
+    requestId?: string;
+    /** W3C Trace Context header. Generated when omitted or invalid. */
+    traceparent?: string;
+    /** Caller-owned business conversation id. The SDK never generates one. */
+    conversationId?: string;
+    /** Caller-owned id for one user question and its operations. The SDK never generates one. */
+    interactionId?: string;
+    /** Replay-stable operation id. Transports generate one per logical operation when omitted. */
+    operationId?: string;
+    /** Retry ordinal for the operation. Defaults to 1. */
+    attempt?: number;
+    /** Producer observation time in RFC3339 format. Generated per logical operation when omitted. */
+    observedAt?: string;
+    /** Baggage values are allowlisted before propagation. */
+    baggage?: Record<string, string>;
+}
+interface TraceContext {
+    requestId: string;
+    traceparent: string;
+    conversationId?: string;
+    interactionId?: string;
+    operationId?: string;
+    attempt?: number;
+    observedAt?: string;
+    baggage?: Record<string, string>;
+}
 declare const DEFAULT_BUSINESS_DOMAIN = "bd_public";
 /** Default list/query limits — see AGENTS.md conventions. */
 declare const DEFAULT_LIST_LIMIT = 30;
@@ -372,13 +408,258 @@ declare function appKeys(ctx: RequestContext): {
     adminRevoke: (id: string) => Promise<void>;
 };
 
-/**
- * Context-loader client over the agent-retrieval MCP endpoint (JSON-RPC).
- * Slim implementation: initialize → session id →
- * notifications/initialized, then tools/call. Handles plain-JSON and
- * SSE (`data:`) response bodies. Per-process session cache (5 min TTL).
- */
+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;
@@ -386,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>;
@@ -397,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>;
@@ -426,6 +706,8 @@ interface TemplateArg {
 
 interface ListRunsOptions {
     since?: string;
+    page?: number;
+    limit?: number;
 }
 interface LogsOptions {
     page?: number;
@@ -450,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
@@ -491,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 {
@@ -547,7 +865,6 @@ declare function kn(ctx: RequestContext): {
     metricValidate: (knId: string, body: unknown) => Promise<unknown>;
     objectTypes: (knId: string, opts?: ListSchemaOptions) => Promise<unknown>;
     objectTypeQuery: (knId: string, otId: string, body: unknown) => Promise<unknown>;
-    objectTypeProperties: (knId: string, otId: string) => Promise<unknown>;
     objectTypeGet: (knId: string, id: string) => Promise<unknown>;
     objectTypeCreate: (knId: string, body: unknown) => Promise<unknown>;
     objectTypeUpdate: (knId: string, id: string, body: unknown) => Promise<unknown>;
@@ -575,10 +892,6 @@ declare function kn(ctx: RequestContext): {
     actionScheduleUpdate: (knId: string, scheduleId: string, body: unknown) => Promise<unknown>;
     actionScheduleSetStatus: (knId: string, scheduleId: string, body: unknown) => Promise<unknown>;
     actionScheduleDelete: (knId: string, ids: string) => Promise<unknown>;
-    jobs: (knId: string) => Promise<unknown>;
-    job: (knId: string, jobId: string) => Promise<unknown>;
-    jobTasks: (knId: string, jobId: string) => Promise<unknown>;
-    jobDelete: (knId: string, ids: string) => Promise<unknown>;
     relationTypePaths: (knId: string, body: unknown) => Promise<unknown>;
     bknResources: () => Promise<unknown>;
     createFromCatalog: (opts: CreateFromCatalogOptions) => Promise<unknown>;
@@ -722,11 +1035,17 @@ interface FindResourceOptions {
     datasourceId?: string;
     /** Exact name match instead of fuzzy. */
     exact?: boolean;
+    /** Rows to fetch before filtering; `-1` = all. Defaults to the list default. */
+    limit?: number;
 }
 interface QueryResourceOptions {
     limit?: number;
     offset?: number;
     needTotal?: boolean;
+    pagingMode?: "single" | "cursor";
+    keepAliveSec?: number;
+    /** Opaque cursor returned by the preceding resource data page. */
+    cursor?: string;
 }
 
 /** Resource surface (the exported SDK API) over vega-backend resources. */
@@ -741,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;
@@ -749,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>;
@@ -772,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;
@@ -791,6 +1190,11 @@ interface ListToolboxesOptions {
     limit?: number;
     offset?: number;
 }
+interface ListToolsOptions {
+    page?: number;
+    pageSize?: number;
+    all?: boolean;
+}
 interface CreateToolboxOptions {
     name: string;
     serviceUrl: string;
@@ -807,7 +1211,7 @@ interface ToolInvokeEnvelope {
 
 declare function toolboxes(ctx: RequestContext): {
     list: (opts?: ListToolboxesOptions) => Promise<unknown>;
-    tools: (boxId: string) => Promise<unknown>;
+    tools: (boxId: string, opts?: ListToolsOptions) => Promise<unknown>;
     create: (opts: CreateToolboxOptions) => Promise<unknown>;
     delete: (boxId: string) => Promise<unknown>;
     publish: (boxId: string) => Promise<unknown>;
@@ -826,6 +1230,178 @@ declare function toolboxes(ctx: RequestContext): {
     debug: (boxId: string, toolId: string, e?: ToolInvokeEnvelope) => Promise<unknown>;
 };
 
+interface FixtureValidationError {
+    code: string;
+    path: string;
+    message: string;
+}
+interface FixtureValidationResult {
+    fixtureId: string;
+    result: "pass" | "fail";
+    contractVersion: string | null;
+    errors: FixtureValidationError[];
+    warnings: string[];
+    expectedResult: "pass" | "fail" | null;
+    expectationMatched: boolean;
+}
+interface FixturePathValidationResult {
+    ok: boolean;
+    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
+ * diagnose/eval-set rule engine (LLM-as-judge) is a separate large feature and
+ * is NOT included here — see docs/exec-plans/tech-debt-tracker.md.
+ */
+
+interface ActionSummary {
+    recommended: number;
+    approved: number;
+    executed: number;
+    completed: number;
+    last_status?: string;
+}
+interface TraceExecutionSummary {
+    trace_id: string;
+    request_id: string;
+    conversation_id?: string;
+    interaction_id?: string;
+    started_at?: string;
+    completed_at?: string;
+    agent_or_app?: string;
+    business_domain?: string;
+    root_operation?: string;
+    status: string;
+    span_count: number;
+    duration_ms?: number;
+    error_summary?: string;
+}
+interface VisibilitySummary {
+    authorized_ref_count: number;
+    redacted_ref_count: number;
+    hidden_ref_count: number;
+    omitted_ref_count: number;
+    unresolved_ref_count: number;
+    unauthorized_ref_count?: number;
+}
+interface GraphPage {
+    node_count: number;
+    edge_count: number;
+    truncated?: boolean;
+    next_cursor?: string | null;
+}
+interface TraceGraphNode {
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    kind: string;
+    service_name?: string;
+    status: string;
+    error_message?: string;
+    start_nano: number;
+    end_nano: number;
+    duration_nano: number;
+}
+interface TraceGraphEdge {
+    id: string;
+    parent_span_id: string;
+    child_span_id: string;
+    edge_type: string;
+}
+interface TraceGraphResponse {
+    trace_id: string;
+    status: string;
+    duration_nano: number;
+    partial: boolean;
+    partial_reason: string[];
+    page: GraphPage;
+    data: {
+        nodes: TraceGraphNode[];
+        edges: TraceGraphEdge[];
+    };
+}
+
 /**
  * Trace diagnose engine. Fetches a conversation's spans, shapes them into a
  * trace tree, runs deterministic symbolic predicates, and (in hybrid mode) adds
@@ -914,8 +1490,14 @@ interface EvalSetResult {
 }
 
 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>;
+    /** Normalized trace tree/status graph by trace id. */
+    graph: (traceId: string) => Promise<TraceGraphResponse>;
     /** All span source docs for a conversation. */
     spans: (conversationId: string, opts?: {
         maxTraceIds?: number;
@@ -946,6 +1528,8 @@ declare function trace(ctx: RequestContext): {
     }>;
     /** Build eval cases from a loosely-shaped queries object/array. */
     evalSetBuild: (raw: unknown) => EvalCase[];
+    /** Validate BKN Trace phase-one fixture files or directories. */
+    validateFixture: (path: string) => FixturePathValidationResult;
     /**
      * Run an eval set against an agent: each case's query is sent to the agent,
      * the resulting trace is fetched, and assertions are checked. `llm` enables
@@ -965,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;
@@ -1008,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;
@@ -1032,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;
@@ -1054,38 +1721,574 @@ 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 {
     ignoreMissing?: boolean;
     deleteActiveIndex?: boolean;
 }
-interface SqlQueryRequest {
-    /** SQL string (MySQL/MariaDB/PostgreSQL) or an OpenSearch DSL object. */
-    query: string | Record<string, unknown>;
-    /** Query mode. `stream` uses cursor-style paging through `query_id`. */
-    query_type?: "standard" | "stream";
-    /**
-     * Source type (mysql | mariadb | postgresql | opensearch …). Required by the
-     * current vega-backend raw query handler.
-     */
-    resource_type: string;
-    /** Streaming batch size (100–10000, default server-side). */
-    stream_size?: number;
-    /** Query timeout in seconds (1–3600). */
-    query_timeout?: number;
-    /** Cursor session id for paged streaming. */
-    query_id?: string;
+type QueryPagingMode = "single" | "cursor";
+/** Paging options for an initial Vega raw query. */
+interface RawQueryPaging {
+    mode?: QueryPagingMode;
+    offset?: number;
+    limit?: number;
+    keep_alive_sec?: number;
+}
+/** Opaque cursor continuation. No initial-query fields may accompany it. */
+interface RawQueryContinuationRequest {
+    paging: {
+        cursor: string;
+    };
+    /** Accepted by the API but cannot override the value frozen on the first page. */
+    need_total?: boolean;
+}
+interface RawQueryInitialBase {
+    paging?: RawQueryPaging;
+    /** Per-page timeout in seconds (1–3600); defaults to 60 server-side. */
+    query_timeout_sec?: number;
+    need_total?: boolean;
+}
+interface SqlRawQueryRequest extends RawQueryInitialBase {
+    query: string;
+    query_format: "sql";
+    /** SQL input dialect; defaults to postgres server-side. */
+    input_dialect?: "postgres" | "mysql" | "trino" | "duckdb";
 }
+interface DslRawQueryRequest extends RawQueryInitialBase {
+    query: Record<string, unknown>;
+    query_format: "dsl";
+    input_dialect: "opensearch";
+}
+/** Request contract for POST /resources/query. */
+type RawQueryRequest = SqlRawQueryRequest | DslRawQueryRequest | RawQueryContinuationRequest;
 interface ListCatalogsOptions {
     limit?: number;
     offset?: number;
@@ -1093,7 +2296,7 @@ interface ListCatalogsOptions {
     tag?: string;
     type?: "physical" | "logical" | string;
     enabled?: boolean;
-    healthCheckStatus?: string;
+    healthCheckStatus?: CatalogHealthCheckStatus;
     includeExtensions?: boolean;
     includeExtensionKeys?: string;
     extensionPairs?: Array<{
@@ -1107,31 +2310,68 @@ 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) => Promise<unknown>;
-    catalogHealth: (ids: string[]) => Promise<unknown>;
+    catalogResources: (id: string, category?: string, limit?: number, offset?: number) => 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. */
-    sql: (body: SqlQueryRequest) => Promise<unknown>;
+    sql: (body: RawQueryRequest) => Promise<unknown>;
     /** Build a resource's index. With `wait`, polls until terminal. */
     build: (req: CreateBuildTaskRequest, opts?: {
         wait?: boolean;
@@ -1142,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;
@@ -1163,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;
@@ -1204,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);
@@ -1362,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. */
@@ -1369,17 +2775,20 @@ interface RequestInitEx {
     /** Query params appended to the path. */
     query?: Record<string, string | number | boolean | Array<string | number | boolean> | undefined>;
     headers?: Record<string, string>;
+    /** Redirect policy; credential-bearing writes should use `manual`. */
+    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>;
 
-/**
- * Resolve a full RequestContext from explicit options → env → store.
- * Order: caller options win, then env vars, then the active platform/user
- * in `~/.bkn/`.
- */
-
 declare function resolveContext(opts?: ClientOptions): RequestContext;
 
-export { type BknClient, BuildMode, BuildTask, type ClientOptions, CreateBuildTaskRequest, DEFAULT_BUSINESS_DOMAIN, DEFAULT_LIST_LIMIT, DEFAULT_QUERY_LIMIT, HttpError, InputError, type RequestContext, 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 };