@openbkn/bkn-sdk 0.1.1-alpha.9 → 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;
@@ -59,12 +95,64 @@ interface RawCallResult {
 }
 
 /**
- * Admin (operator) client — user-management + authorization. Mirrors
- * kweaver-admin. Reads and writes (org/user create/update/delete +
- * reset-password) implemented; org/user detail and writes go through ISFWeb
- * thrift where the REST routes are RegisterPrivate. Passed through as JSON.
+ * bkn-safe admin API (`/api/safe/v1/admin/*`, token-gated; the gateway-exposed
+ * replacement for the retired ISF UserManagement / Authorization / EACP). The
+ * logged-in user must be an admin: 401 = no/invalid token, 403 = not an admin.
+ * Only `audit list` has no endpoint (login-log retired by design). Response
+ * shapes: `{users|roles|departments, total}`; department `parent_id` (not the
+ * ISF `parent_deps[]`). See docs/exec-plans/admin-bkn-safe-migration.md.
+ * Also carries the cluster license hub (`/admin/license/*`, issue #224).
  */
 
+/** licverify judgement states. `invalid` also covers "no license installed". */
+type LicenseState = "valid" | "grace" | "fallback_community" | "invalid";
+/** GET /admin/license response (admin detail view). */
+interface LicenseDetail {
+    state: LicenseState;
+    /** Whether the installed license is fingerprint-bound to this instance. */
+    activated: boolean;
+    /** This cluster's machine code (present even with no license installed). */
+    instance_fp: string;
+    error?: string;
+    /** Background auto-renew failure — license itself may still be valid. */
+    renew_error?: string;
+    edition?: string;
+    lic_id?: string;
+    customer?: {
+        name?: string;
+        [k: string]: unknown;
+    };
+    /** Unix seconds; expires_at 0 = never expires (community). */
+    issued_at?: number;
+    expires_at?: number;
+    contract_expires_at?: number;
+    /** Only present in `grace` state. */
+    grace_remaining_days?: number;
+    features?: string[];
+    limits?: Record<string, number>;
+}
+/**
+ * Import outcome. Plain success = the stored license's detail. `stored: true`
+ * = the .lic was verified and stored, but issuer activation failed (HTTP
+ * 409/502) — both facts matter, the import is not lost.
+ */
+type LicenseImportResult = LicenseDetail | {
+    stored: true;
+    error: string;
+    license: LicenseDetail;
+};
+
+/**
+ * Admin (operator) input shapes — the CLI-facing contract for the `admin`
+ * command group. `src/resources/admin.ts` maps each of these onto the bkn-safe
+ * client in `./safe.ts`, which is where the requests live.
+ *
+ * The ISF clients that used to back these types (`/api/user-management/v1`,
+ * `/api/authorization/v1`, `/isfweb/api/ShareMgnt`, `/api/eacp/v1`) were removed
+ * once ISF was retired — see docs/exec-plans/admin-bkn-safe-migration.md. Some
+ * fields here are wider than bkn-safe accepts and are dropped in the mapping;
+ * that lossiness is documented in the migration plan.
+ */
 interface AdminListOptions {
     role?: string;
     offset?: number;
@@ -184,6 +272,17 @@ declare function admin(ctx: RequestContext): {
         ok: true;
     }>;
     auditList: (_opts?: AuditListOptions) => never;
+    licenseGet: () => Promise<LicenseDetail>;
+    licenseImport: (licenseText: string, opts?: {
+        receipt?: boolean;
+    }) => Promise<LicenseImportResult>;
+    licenseActivate: () => Promise<LicenseDetail>;
+    licenseRemove: () => Promise<{
+        ok: true;
+    }>;
+    licenseFingerprint: () => Promise<{
+        instance_fp: string;
+    }>;
 };
 
 interface ChatResult {
@@ -197,8 +296,10 @@ interface SendChatOptions {
 }
 
 /**
- * Agent client (agent-factory v3). Read side + published listing, mirroring
- * kweaver-sdk api/agent-list.ts. Responses passed through as parsed JSON.
+ * Agent client (agent-factory v3). Read side + published listing.
+ * Responses passed through as parsed JSON.
+ * @deprecated The Decision Agent (agent-factory) surface is being phased out and
+ * may be removed in a future release. Avoid building new integrations on it.
  */
 
 interface ListAgentsOptions {
@@ -215,6 +316,11 @@ interface PagingOptions {
     name?: string;
 }
 
+/**
+ * Decision Agent resource surface.
+ * @deprecated The Decision Agent (agent-factory) surface is being phased out and
+ * may be removed in a future release. Avoid building new integrations on it.
+ */
 declare function agents(ctx: RequestContext): {
     list: (opts?: ListAgentsOptions) => Promise<unknown>;
     get: (agentId: string) => Promise<unknown>;
@@ -246,16 +352,68 @@ declare function agents(ctx: RequestContext): {
 };
 
 /**
- * Context-loader client over the agent-retrieval MCP endpoint (JSON-RPC).
- * Reimplemented slim from kweaver-sdk: initialize → session id →
- * notifications/initialized, then tools/call. Handles plain-JSON and
- * SSE (`data:`) response bodies. Per-process session cache (5 min TTL).
+ * AppKey API (`/api/safe/v1/{me,admin}/api-keys`, OAuth-token-gated). AppKeys
+ * are user-issued long-lived credentials (prefix `bak_`) that authenticate AS
+ * their owner — downstream authorization is identical to that owner's OAuth
+ * token. Issuing/managing them needs a real OAuth session (an AppKey itself
+ * cannot mint AppKeys). The plaintext `key` is returned ONCE, on create.
+ * Usage of an AppKey is drop-in: pass it as the bearer `--token` against the
+ * Context Loader (agent-retrieval) MCP/REST surface. See issue #75.
  */
 
+/** A key's public metadata — never carries the secret. */
+interface ApiKey {
+    id: string;
+    key_id: string;
+    name: string;
+    /** Masked preview for display, e.g. `bak_b3ff****b234` — safe to show in lists. */
+    masked: string;
+    enabled: boolean;
+    /** `null` = never expires. */
+    expires_at: string | null;
+    /** `null` = never used (zombie-key signal). */
+    last_used_at: string | null;
+    created_at: string;
+    /** Present only on the admin list. */
+    owner_user_id?: string;
+}
+/** Create response — `key` is the full plaintext, shown only this once. */
+interface CreatedApiKey extends ApiKey {
+    key: string;
+}
+interface CreateApiKeyInput {
+    name: string;
+    /** RFC3339; omit = backend default (1 year). Must be in the future. */
+    expiresAt?: string;
+    /** `true` = never expire (wins over `expiresAt`). */
+    neverExpire?: boolean;
+}
+
+declare function appKeys(ctx: RequestContext): {
+    /** List the caller's own keys (no secrets). */
+    list: () => Promise<{
+        keys: ApiKey[];
+    }>;
+    /** Issue a key — the result's `key` is the plaintext, shown only once. */
+    create: (input: CreateApiKeyInput) => Promise<CreatedApiKey>;
+    /** Revoke one of the caller's keys (immediate). */
+    revoke: (id: string) => Promise<void>;
+    /** Rotate a key in place — new plaintext (shown once); old secret dies now. */
+    regenerate: (id: string) => Promise<CreatedApiKey>;
+    /** Admin: list all keys, or one owner's (adds `owner_user_id`). */
+    adminList: (ownerId?: string) => Promise<{
+        keys: ApiKey[];
+    }>;
+    /** Admin: revoke any key. */
+    adminRevoke: (id: string) => Promise<void>;
+};
+
 interface SearchSchemaOptions {
     searchScope?: string[];
     maxConcepts?: number;
 }
+/** Progressive KN-detail disclosure level: `summary` (skeleton + property names) | `full`. */
+type DetailLevel = "summary" | "full";
 
 /** Context-loader resource surface (MCP over agent-retrieval). */
 
@@ -263,8 +421,13 @@ declare function context(ctx: RequestContext): {
     searchSchema: (knId: string, query: string, opts?: SearchSchemaOptions) => Promise<unknown>;
     queryObjectInstance: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
     findSkills: (knId: string, objectTypeId: string, topK?: number) => Promise<unknown>;
+    knDetail: (knId: string, detailLevel?: DetailLevel) => Promise<unknown>;
+    objectTypes: (knId: string, ids: string[]) => Promise<unknown>;
+    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>;
+    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>;
     actionInfo: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
@@ -286,12 +449,14 @@ interface TemplateArg {
 
 /**
  * Dataflow backend client (automation v2). Read endpoints (list/runs/logs) are
- * implemented from kweaver-sdk; trigger/create bodies are deferred until the
+ * implemented; trigger/create bodies are deferred until the
  * contract is verified on a live env. Responses passed through as parsed JSON.
  */
 
 interface ListRunsOptions {
     since?: string;
+    page?: number;
+    limit?: number;
 }
 interface LogsOptions {
     page?: number;
@@ -318,7 +483,7 @@ declare function dataflows(ctx: RequestContext): {
 
 /**
  * Knowledge-network backend client (ontology-manager + agent-retrieval).
- * Endpoints mirror kweaver-sdk; responses are passed through as parsed JSON
+ * Responses are passed through as parsed JSON
  * (shapes vary by backend version — validate at higher layers as needed).
  */
 
@@ -365,7 +530,7 @@ interface CreateFromCatalogOptions {
     tables?: string[];
     pkMap?: Record<string, string>;
     build?: boolean;
-    /** Per-table resource columns to vectorize (sets the build task's embedding_fields). */
+    /** Per-table resource columns to vectorize (sets resource schema index features). */
     embeddingFields?: Record<string, string[]>;
     embeddingModel?: string;
     noRollback?: boolean;
@@ -413,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>;
@@ -441,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>;
@@ -492,6 +652,8 @@ declare function models(ctx: RequestContext): {
         edit: (body: unknown) => Promise<unknown>;
         delete: (modelIds: string[]) => Promise<unknown>;
         test: (body: unknown) => Promise<unknown>;
+        /** Set (or clear) the system default LLM. */
+        setDefault: (modelId: string, isDefault?: boolean) => Promise<unknown>;
     };
     small: {
         list: (opts?: ListModelsOptions) => Promise<unknown>;
@@ -502,30 +664,101 @@ declare function models(ctx: RequestContext): {
         edit: (body: unknown) => Promise<unknown>;
         delete: (modelIds: string[]) => Promise<unknown>;
         test: (body: unknown) => Promise<unknown>;
+        /** Set (or clear) the system default small model (type inferred from the model). */
+        setDefault: (modelId: string, isDefault?: boolean) => Promise<unknown>;
+        /** Get the system default small model for a type (default "embedding"). */
+        getDefault: (modelType?: string) => Promise<unknown>;
     };
 };
 
 /**
- * Vega-backend resource client (list/find/get/query/delete). Endpoints mirror
- * kweaver-sdk `api/resources.ts`. Responses passed through as parsed JSON.
+ * Vega-backend resource client (list/find/get/query/delete).
+ * Responses passed through as parsed JSON.
  */
 
+interface PropertyFeature {
+    name?: string;
+    display_name?: string;
+    feature_type: "keyword" | "fulltext" | "vector" | string;
+    description?: string;
+    ref_property?: string;
+    is_default?: boolean;
+    is_native?: boolean;
+    config?: Record<string, unknown>;
+}
+interface ResourceProperty {
+    name: string;
+    display_name?: string;
+    type?: string;
+    description?: string;
+    original_name?: string;
+    original_type?: string;
+    original_description?: string;
+    features?: PropertyFeature[];
+    attributes?: Record<string, unknown>;
+    extensions?: Record<string, string>;
+}
+interface ResourceIndexConfig {
+    build_key_fields?: string[];
+    default_fulltext_analyzer?: string;
+    default_embedding_model?: string;
+}
 interface ListResourcesOptions {
     datasourceId?: string;
     name?: string;
     /** Resource category, e.g. table | logicview. */
     category?: string;
+    status?: string;
+    database?: string;
     limit?: number;
+    offset?: number;
+    sort?: "name" | "create_time" | "update_time" | string;
+    direction?: "asc" | "desc";
+    includeExtensions?: boolean;
+    includeExtensionKeys?: string;
+    extensionPairs?: Array<{
+        key: string;
+        value: string;
+    }>;
 }
+interface UpdateResourceOptions {
+    name?: string;
+    catalogId?: string;
+    tags?: string[];
+    description?: string;
+    category?: string;
+    status?: string;
+    database?: string;
+    sourceIdentifier?: string;
+    sourceMetadata?: Record<string, unknown>;
+    schemaDefinition?: ResourceProperty[];
+    indexConfig?: ResourceIndexConfig | null;
+    logicDefinition?: unknown;
+    extensions?: Record<string, string>;
+}
+interface ConfigureResourceIndexOptions {
+    buildKeyFields?: string[];
+    embeddingFields?: string[];
+    embeddingModel?: string;
+    fulltextFields?: string[];
+    fulltextAnalyzer?: string;
+}
+declare function configureResourceIndex(ctx: RequestContext, id: string, opts: ConfigureResourceIndexOptions): Promise<unknown>;
 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. */
@@ -534,6 +767,8 @@ declare function resources(ctx: RequestContext): {
     list: (opts?: ListResourcesOptions) => Promise<unknown>;
     get: (id: string) => Promise<unknown>;
     delete: (id: string) => Promise<unknown>;
+    update: (id: string, patch: UpdateResourceOptions) => Promise<unknown>;
+    configureIndex: (id: string, opts: Parameters<typeof configureResourceIndex>[2]) => Promise<unknown>;
     find: (name: string, opts?: FindResourceOptions) => Promise<unknown>;
     query: (id: string, opts?: QueryResourceOptions) => Promise<unknown>;
 };
@@ -588,6 +823,11 @@ interface ListToolboxesOptions {
     limit?: number;
     offset?: number;
 }
+interface ListToolsOptions {
+    page?: number;
+    pageSize?: number;
+    all?: boolean;
+}
 interface CreateToolboxOptions {
     name: string;
     serviceUrl: string;
@@ -604,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>;
@@ -623,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
@@ -667,8 +1176,8 @@ interface DiagnoseReport {
  * agent, fetches the resulting trace, and checks each assertion. Deterministic
  * assertion kinds (contains, regex, tool-call count/order, latency) need no LLM;
  * `semantic_match` reuses the local-claude judge. Builder lifts cases from a
- * queries file (JSON). The diagnosis-report lift + YAML shards + redaction from
- * kweaver-sdk are deferred — see tech-debt.
+ * queries file (JSON). The diagnosis-report lift + YAML shards + redaction
+ * are deferred — see tech-debt.
  */
 
 type AssertionType = "contains" | "not_contains" | "regex" | "tool_call_count" | "tool_call_order" | "latency_ms" | "semantic_match";
@@ -710,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;
@@ -743,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
@@ -756,7 +1519,8 @@ declare function trace(ctx: RequestContext): {
 
 /**
  * Vega backend client — catalog/resource reads + BuildTask (index build).
- * Build config lives on the task (CreateBuildTaskRequest), per the platform model.
+ * Build config is snapshotted from the Resource's schema_definition/features and
+ * index_config when the BuildTask is created.
  */
 
 declare const BuildMode: z.ZodEnum<["batch", "streaming"]>;
@@ -765,24 +1529,15 @@ type BuildMode = z.infer<typeof BuildMode>;
 declare const CreateBuildTaskRequest: z.ZodObject<{
     resource_id: z.ZodString;
     mode: z.ZodEnum<["batch", "streaming"]>;
-    embedding_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    build_key_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
 }, "strip", z.ZodTypeAny, {
     mode: "batch" | "streaming";
     resource_id: string;
-    embedding_fields?: string[] | undefined;
-    build_key_fields?: string[] | undefined;
-    embedding_model?: string | undefined;
-    model_dimensions?: number | undefined;
+    execute_type?: "full" | "incremental" | undefined;
 }, {
     mode: "batch" | "streaming";
     resource_id: string;
-    embedding_fields?: string[] | undefined;
-    build_key_fields?: string[] | undefined;
-    embedding_model?: string | undefined;
-    model_dimensions?: number | undefined;
+    execute_type?: "full" | "incremental" | undefined;
 }>;
 type CreateBuildTaskRequest = z.infer<typeof CreateBuildTaskRequest>;
 declare const BuildTask: z.ZodObject<{
@@ -794,10 +1549,21 @@ declare const BuildTask: z.ZodObject<{
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
-    embedding_fields: z.ZodOptional<z.ZodString>;
-    build_key_fields: z.ZodOptional<z.ZodString>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    index_config: z.ZodOptional<z.ZodUnknown>;
+    catalog_id: z.ZodOptional<z.ZodString>;
+    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.ZodOptional<z.ZodString>;
@@ -807,10 +1573,21 @@ declare const BuildTask: z.ZodObject<{
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
-    embedding_fields: z.ZodOptional<z.ZodString>;
-    build_key_fields: z.ZodOptional<z.ZodString>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    index_config: z.ZodOptional<z.ZodUnknown>;
+    catalog_id: z.ZodOptional<z.ZodString>;
+    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.ZodOptional<z.ZodString>;
@@ -820,15 +1597,89 @@ declare const BuildTask: z.ZodObject<{
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
-    embedding_fields: z.ZodOptional<z.ZodString>;
-    build_key_fields: z.ZodOptional<z.ZodString>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    index_config: z.ZodOptional<z.ZodUnknown>;
+    catalog_id: z.ZodOptional<z.ZodString>;
+    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 BuildTask = z.infer<typeof BuildTask>;
+interface ListBuildTasksOptions {
+    limit?: number;
+    offset?: number;
+    resourceId?: string;
+    catalogId?: string;
+    status?: string | string[];
+    active?: boolean;
+    mode?: BuildMode;
+    orderBy?: "default" | "created_at" | "updated_at" | "status" | "mode";
+    order?: "asc" | "desc";
+}
+interface DeleteBuildTasksOptions {
+    ignoreMissing?: boolean;
+    deleteActiveIndex?: boolean;
+}
+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;
+    name?: string;
+    tag?: string;
+    type?: "physical" | "logical" | string;
+    enabled?: boolean;
+    healthCheckStatus?: string;
+    includeExtensions?: boolean;
+    includeExtensionKeys?: string;
+    extensionPairs?: Array<{
+        key: string;
+        value: string;
+    }>;
+    sort?: "name" | "create_time" | "update_time" | string;
+    direction?: "asc" | "desc";
 }
 /** POST /catalogs body. `connector_config` shape varies by connector (raw passthrough). */
 interface CreateCatalogRequest {
@@ -838,18 +1689,27 @@ interface CreateCatalogRequest {
     tags?: string[];
     description?: string;
     enabled?: boolean;
+    id?: string;
+    internal?: boolean;
+    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>;
     enableCatalog: (id: string) => Promise<unknown>;
+    disableCatalog: (id: string) => Promise<unknown>;
+    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: RawQueryRequest) => Promise<unknown>;
     /** Build a resource's index. With `wait`, polls until terminal. */
     build: (req: CreateBuildTaskRequest, opts?: {
         wait?: boolean;
@@ -865,11 +1725,28 @@ declare function vega(ctx: RequestContext): {
         total_count: zod.ZodOptional<zod.ZodNumber>;
         synced_count: zod.ZodOptional<zod.ZodNumber>;
         vectorized_count: zod.ZodOptional<zod.ZodNumber>;
-        embedding_fields: zod.ZodOptional<zod.ZodString>;
-        build_key_fields: zod.ZodOptional<zod.ZodString>;
-        embedding_model: zod.ZodOptional<zod.ZodString>;
-        model_dimensions: zod.ZodOptional<zod.ZodNumber>;
+        index_config: zod.ZodOptional<zod.ZodUnknown>;
+        catalog_id: zod.ZodOptional<zod.ZodString>;
+        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">>;
+    buildTasks: (opts?: ListBuildTasksOptions) => Promise<unknown>;
+    deleteBuildTasks: (ids: string[], opts?: DeleteBuildTasksOptions) => Promise<unknown>;
+    startBuildTask: (taskId: string, opts?: {
+        reset?: boolean;
+    }) => Promise<unknown>;
+    stopBuildTask: (taskId: string) => Promise<unknown>;
 };
 
 interface BknClient {
@@ -877,6 +1754,10 @@ interface BknClient {
     readonly kn: ReturnType<typeof kn>;
     readonly resource: ReturnType<typeof resources>;
     readonly dataflows: ReturnType<typeof dataflows>;
+    /**
+     * @deprecated Decision Agent (agent-factory) is being phased out and may be
+     * removed in a future release. Avoid building new integrations on it.
+     */
     readonly agents: ReturnType<typeof agents>;
     readonly context: ReturnType<typeof context>;
     readonly models: ReturnType<typeof models>;
@@ -884,6 +1765,7 @@ interface BknClient {
     readonly toolboxes: ReturnType<typeof toolboxes>;
     readonly trace: ReturnType<typeof trace>;
     readonly admin: ReturnType<typeof admin>;
+    readonly appKeys: ReturnType<typeof appKeys>;
     readonly vega: ReturnType<typeof vega>;
     /** Raw API passthrough (the `call` escape hatch). */
     call(path: string, opts?: RawCallOptions): Promise<RawCallResult>;
@@ -896,7 +1778,9 @@ declare class HttpError extends Error {
     readonly status: number;
     readonly statusText: string;
     readonly body: string;
-    constructor(status: number, statusText: string, body: string);
+    /** Optional next-step guidance, overriding the status default (e.g. AppKey re-issue). */
+    readonly hint?: string;
+    constructor(status: number, statusText: string, body: string, hint?: string);
 }
 /** Raised for bad CLI/SDK input before any request is made. */
 declare class InputError extends Error {
@@ -923,16 +1807,28 @@ interface TokenConfig {
     refreshToken?: string;
     idToken?: string;
     expiresAt?: string;
-    /** Skip TLS verification for this platform (saved by `auth login -k`). */
-    tlsInsecure?: boolean;
-    /** Platform has no auth stack (no bkn-safe) — requests carry no token. */
-    noAuth?: boolean;
     /** Login name persisted at login time (fallback when JWT lacks claims). */
     username?: string;
     /** Human-readable name from userinfo. */
     displayName?: string;
+    /**
+     * Skip TLS verification for this platform (saved by `auth login -k`), so a
+     * self-signed platform needn't repeat `-k` on every command. The opt-out is
+     * applied per request via an undici dispatcher (see api/tls.ts) and is scoped
+     * to this platform's requests — it never touches the global TLS setting or a
+     * library consumer's unrelated traffic.
+     */
+    tlsInsecure?: boolean;
 }
-/** userId from the token's JWT `sub` (id_token first), else "default". */
+/**
+ * userId from the token's JWT `sub` (id_token first), else "default".
+ *
+ * The `sub` is attacker-supplied — the JWT is never signature-checked — and it
+ * becomes a path segment under `userDir`. An unconstrained one escapes the
+ * store: `sub: "../../<other-platform>/users/default"` overwrites another
+ * platform's saved token, so the victim's later commands there authenticate as
+ * whoever issued this token. Constrain it the way BKN_PROFILE is constrained.
+ */
 declare function userIdFromToken(token: TokenConfig): string;
 interface PlatformUser {
     userId: string;
@@ -951,20 +1847,13 @@ declare function hostOf(baseUrl: string): string;
 declare function attachToken(baseUrl: string, accessToken: string, opts?: {
     refreshToken?: string;
     idToken?: string;
-    insecure?: boolean;
     username?: string;
+    insecure?: boolean;
 }): {
     baseUrl: string;
     userId: string;
     username?: string;
 };
-/** Register a no-auth platform session (no token; the platform has no bkn-safe). */
-declare function attachNoAuth(baseUrl: string, opts?: {
-    insecure?: boolean;
-}): {
-    baseUrl: string;
-    noAuth: true;
-};
 interface AuthStatus {
     baseUrl?: string;
     userId?: string;
@@ -972,15 +1861,22 @@ interface AuthStatus {
     username?: string;
     expired?: boolean;
 }
-declare function status(): AuthStatus;
-declare function currentToken(): string;
+declare function status(opts?: {
+    user?: string;
+}): AuthStatus;
+declare function currentToken(opts?: {
+    user?: string;
+}): string;
 /**
  * Like {@link currentToken} but proactively refreshes an expired access token
  * when a refresh token is stored, persisting the result. API requests already
  * refresh on a 401 (see api/http.ts); this covers the `auth token` getter,
  * whose output is copied out and used elsewhere where no 401 retry can help.
  */
-declare function currentTokenFresh(): Promise<string>;
+declare function currentTokenFresh(opts?: {
+    insecure?: boolean;
+    user?: string;
+}): Promise<string>;
 interface WhoamiResult extends JwtClaims {
     /** Platform the active session belongs to. */
     baseUrl?: string;
@@ -989,7 +1885,9 @@ interface WhoamiResult extends JwtClaims {
     /** Resolved account/login name — what `auth login` looked up and stored. */
     username?: string;
 }
-declare function whoami(): WhoamiResult;
+declare function whoami(opts?: {
+    user?: string;
+}): WhoamiResult;
 interface PlatformListItem {
     baseUrl: string;
     userId: string;
@@ -1024,7 +1922,6 @@ declare function exportCreds(): {
 type auth_AuthStatus = AuthStatus;
 type auth_PlatformListItem = PlatformListItem;
 type auth_WhoamiResult = WhoamiResult;
-declare const auth_attachNoAuth: typeof attachNoAuth;
 declare const auth_attachToken: typeof attachToken;
 declare const auth_currentToken: typeof currentToken;
 declare const auth_currentTokenFresh: typeof currentTokenFresh;
@@ -1040,7 +1937,7 @@ declare const auth_userIdFromToken: typeof userIdFromToken;
 declare const auth_usersOf: typeof usersOf;
 declare const auth_whoami: typeof whoami;
 declare namespace auth {
-  export { type auth_AuthStatus as AuthStatus, type auth_PlatformListItem as PlatformListItem, type auth_WhoamiResult as WhoamiResult, auth_attachNoAuth as attachNoAuth, 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 };
+  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 };
 }
 
 interface RequestInitEx {
@@ -1048,19 +1945,15 @@ interface RequestInitEx {
     /** JSON body — serialized and Content-Type set automatically. */
     body?: unknown;
     /** Query params appended to the path. */
-    query?: Record<string, string | number | boolean | undefined>;
+    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 };