@openbkn/bkn-sdk 0.1.1 → 0.1.2

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,6 @@ 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).
- */
-
 interface SearchSchemaOptions {
     searchScope?: string[];
     maxConcepts?: number;
@@ -426,6 +455,8 @@ interface TemplateArg {
 
 interface ListRunsOptions {
     since?: string;
+    page?: number;
+    limit?: number;
 }
 interface LogsOptions {
     page?: number;
@@ -547,7 +578,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 +605,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 +748,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. */
@@ -791,6 +823,11 @@ interface ListToolboxesOptions {
     limit?: number;
     offset?: number;
 }
+interface ListToolsOptions {
+    page?: number;
+    pageSize?: number;
+    all?: boolean;
+}
 interface CreateToolboxOptions {
     name: string;
     serviceUrl: string;
@@ -807,7 +844,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 +863,275 @@ 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[];
+}
+
+/**
+ * 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 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;
+    executed: number;
+    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;
+    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 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;
+    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[];
+    };
+}
+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
  * trace tree, runs deterministic symbolic predicates, and (in hybrid mode) adds
@@ -913,9 +1219,261 @@ 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): {
     /** 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;
@@ -946,6 +1504,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
@@ -1069,23 +1629,41 @@ 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;
@@ -1126,12 +1704,12 @@ declare function vega(ctx: RequestContext): {
     deleteCatalog: (id: string) => Promise<unknown>;
     testCatalogConnection: (id: string) => Promise<unknown>;
     discoverCatalog: (id: string, wait?: boolean) => Promise<unknown>;
-    catalogResources: (id: string, category?: string) => Promise<unknown>;
+    catalogResources: (id: string, category?: string, limit?: number, offset?: number) => Promise<unknown>;
     catalogHealth: (ids: string[]) => Promise<unknown>;
     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;
@@ -1369,17 +1947,13 @@ 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;
 }
 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 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 };