@openbkn/bkn-sdk 0.1.1-alpha.8 → 0.1.1

package/dist/index.d.ts

@@ -59,12 +59,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 +236,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 +260,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 +280,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>;
@@ -245,9 +315,66 @@ declare function agents(ctx: RequestContext): {
     }) => Promise<ChatResult>;
 };
 
+/**
+ * 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>;
+};
+
 /**
  * Context-loader client over the agent-retrieval MCP endpoint (JSON-RPC).
- * Reimplemented slim from kweaver-sdk: initialize → session id →
+ * 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).
  */
@@ -256,6 +383,8 @@ 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 +392,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,7 +420,7 @@ 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.
  */
 
@@ -318,7 +452,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 +499,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;
@@ -492,6 +626,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,21 +638,86 @@ 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. */
@@ -534,6 +735,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>;
 };
@@ -667,8 +870,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";
@@ -756,7 +959,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 +969,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 +989,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 +1013,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 +1037,71 @@ 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;
+}
+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;
+}
 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 +1111,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>;
     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>;
     /** Build a resource's index. With `wait`, polls until terminal. */
     build: (req: CreateBuildTaskRequest, opts?: {
         wait?: boolean;
@@ -865,11 +1147,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 +1176,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 +1187,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 +1200,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 +1229,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 +1269,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 +1283,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 +1307,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 +1344,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 +1359,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,7 +1367,7 @@ 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>;
     /** Per-request timeout; defaults to 30s. */
     timeoutMs?: number;