@openbkn/bkn-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,955 @@
+import { z } from 'zod';
+
+/** Shared types for the SDK surface. No runtime, no side effects. */
+/** Options a caller supplies; any field may be resolved from env/config store. */
+interface ClientOptions {
+    baseUrl?: string;
+    token?: string;
+    /** Specific user credentials (transient); maps to legacy `--user`. */
+    user?: string;
+    /** Business domain header; defaults to `bd_public`. */
+    businessDomain?: string;
+    /** Skip TLS verification (dev / self-signed only). */
+    insecure?: boolean;
+}
+/** Fully resolved request context — every field is known. */
+interface RequestContext {
+    baseUrl: string;
+    token: string;
+    businessDomain: string;
+    insecure: boolean;
+}
+declare const DEFAULT_BUSINESS_DOMAIN = "bd_public";
+/** Default list/query limits — see AGENTS.md conventions. */
+declare const DEFAULT_LIST_LIMIT = 30;
+declare const DEFAULT_QUERY_LIMIT = 50;
+
+interface RawCallOptions {
+    method?: string;
+    /** Extra headers as raw "Name: value" strings. */
+    header?: string[];
+    /** Raw request body (string). Mutually exclusive with `form`. */
+    data?: string;
+    /** Multipart fields: "key=value" or "key=@/path/to/file". */
+    form?: string[];
+    /** Override business domain for this call. */
+    businessDomain?: string;
+    verbose?: boolean;
+    timeoutMs?: number;
+}
+interface RawCallResult {
+    status: number;
+    statusText: string;
+    body: string;
+}
+
+/**
+ * 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.
+ */
+
+interface AdminListOptions {
+    role?: string;
+    offset?: number;
+    limit?: number;
+    name?: string;
+    orgId?: string;
+}
+interface ListRolesOptions {
+    offset?: number;
+    limit?: number;
+    keyword?: string;
+}
+interface CreateOrgInput {
+    name: string;
+    parentId?: string;
+    managerID?: string | null;
+    code?: string;
+    remark?: string;
+    status?: number;
+    email?: string;
+}
+interface UpdateOrgInput {
+    name?: string;
+    managerID?: string | null;
+    code?: string;
+    remark?: string;
+    status?: number;
+    email?: string;
+}
+interface CreateUserInput {
+    loginName: string;
+    displayName?: string;
+    email?: string;
+    departmentIds?: string[];
+    code?: string;
+    position?: string;
+    remark?: string;
+    telNumber?: string;
+    priority?: number;
+    csfLevel?: number;
+}
+interface UpdateUserInput {
+    displayName?: string;
+    code?: string;
+    position?: string;
+    remark?: string;
+    email?: string;
+    telNumber?: string;
+    managerID?: string;
+    priority?: number;
+    csfLevel?: number;
+}
+interface AuditListOptions {
+    page?: number;
+    size?: number;
+    user?: string;
+    start?: string;
+    end?: string;
+}
+type MemberType = "user" | "department" | "group" | "app";
+
+/** Build / render a department hierarchy from flat ISF search entries. */
+
+interface OrgNode {
+    id: string;
+    name: string;
+    children: OrgNode[];
+}
+
+declare function admin(ctx: RequestContext): {
+    orgList: (opts?: AdminListOptions) => Promise<unknown>;
+    orgGet: (deptId: string) => Promise<unknown>;
+    orgMembers: (deptId: string, opts?: {
+        role?: string;
+        offset?: number;
+        limit?: number;
+    }) => Promise<unknown>;
+    orgTree: (role?: string) => Promise<OrgNode[]>;
+    orgCreate: (input: CreateOrgInput) => Promise<unknown>;
+    orgUpdate: (deptId: string, input: UpdateOrgInput) => Promise<unknown>;
+    orgDelete: (deptId: string) => Promise<unknown>;
+    userList: (opts?: AdminListOptions) => Promise<unknown>;
+    userGet: (userId: string) => Promise<unknown>;
+    userRoles: (userId: string) => Promise<unknown>;
+    userCreate: (input: CreateUserInput) => Promise<unknown>;
+    userUpdate: (userId: string, input: UpdateUserInput) => Promise<unknown>;
+    userDelete: (userId: string) => Promise<unknown>;
+    userResetPassword: (userId: string, newPassword: string) => Promise<unknown>;
+    roleList: (opts?: ListRolesOptions) => Promise<unknown>;
+    roleGet: (roleId: string) => Promise<unknown>;
+    roleMembers: (roleId: string, opts?: {
+        keyword?: string;
+        limit?: number;
+    }) => Promise<unknown>;
+    addRoleMember: (roleId: string, id: string, type?: MemberType) => Promise<unknown>;
+    removeRoleMember: (roleId: string, id: string, type?: MemberType) => Promise<unknown>;
+    auditList: (opts?: AuditListOptions) => Promise<unknown>;
+};
+
+interface ChatResult {
+    text: string;
+    conversationId?: string;
+}
+interface SendChatOptions {
+    conversationId?: string;
+    stream?: boolean;
+    onDelta?: (text: string) => void;
+}
+
+/**
+ * Agent client (agent-factory v3). Read side + published listing, mirroring
+ * kweaver-sdk api/agent-list.ts. Responses passed through as parsed JSON.
+ */
+
+interface ListAgentsOptions {
+    name?: string;
+    offset?: number;
+    limit?: number;
+    categoryId?: string;
+    customSpaceId?: string;
+    isToSquare?: number;
+}
+interface PagingOptions {
+    offset?: number;
+    limit?: number;
+    name?: string;
+}
+
+declare function agents(ctx: RequestContext): {
+    list: (opts?: ListAgentsOptions) => Promise<unknown>;
+    get: (agentId: string) => Promise<unknown>;
+    getByKey: (key: string) => Promise<unknown>;
+    personalList: (opts?: PagingOptions) => Promise<unknown>;
+    templateList: (opts?: PagingOptions) => Promise<unknown>;
+    templateGet: (templateId: string) => Promise<unknown>;
+    categoryList: () => Promise<unknown>;
+    create: (body: unknown) => Promise<unknown>;
+    update: (agentId: string, body: unknown) => Promise<unknown>;
+    delete: (agentId: string) => Promise<unknown>;
+    publish: (agentId: string) => Promise<unknown>;
+    unpublish: (agentId: string) => Promise<unknown>;
+    sessions: (agentKey: string, opts?: {
+        page?: number;
+        size?: number;
+    }) => Promise<unknown>;
+    history: (agentKey: string, conversationId: string) => Promise<unknown>;
+    /** List skill ids attached to an agent (config.skills.skills). */
+    skillList: (agentId: string) => Promise<string[]>;
+    /** Attach skill(s) to an agent (dedup), then persist. */
+    skillAdd: (agentId: string, skillIds: string[]) => Promise<unknown>;
+    /** Detach skill(s) from an agent, then persist. */
+    skillRemove: (agentId: string, skillIds: string[]) => Promise<unknown>;
+    /** Send a chat turn to an agent (resolves agent id/key/version first). */
+    chat: (agentId: string, query: string, opts?: SendChatOptions & {
+        version?: string;
+    }) => Promise<ChatResult>;
+};
+
+/**
+ * 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).
+ */
+
+interface SearchSchemaOptions {
+    searchScope?: string[];
+    maxConcepts?: number;
+}
+
+/** Context-loader resource surface (MCP over agent-retrieval). */
+
+declare function context(ctx: RequestContext): {
+    searchSchema: (knId: string, query: string, opts?: SearchSchemaOptions) => Promise<unknown>;
+    queryObjectInstance: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
+    findSkills: (knId: string, objectTypeId: string, topK?: number) => Promise<unknown>;
+    tools: (knId: string) => Promise<unknown>;
+    toolCall: (knId: string, name: string, args: 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>;
+    resources: (knId: string) => Promise<unknown>;
+    resource: (knId: string, uri: string) => Promise<unknown>;
+    templates: (knId: string) => Promise<unknown>;
+    prompts: (knId: string) => Promise<unknown>;
+    prompt: (knId: string, name: string, args?: Record<string, unknown>) => Promise<unknown>;
+};
+
+type TemplateType = "dataset" | "bkn" | "dataflow";
+interface TemplateArg {
+    name: string;
+    required?: boolean;
+    description?: string;
+    type?: string;
+    default?: unknown;
+}
+
+/**
+ * Dataflow backend client (automation v2). Read endpoints (list/runs/logs) are
+ * implemented from kweaver-sdk; trigger/create bodies are deferred until the
+ * contract is verified on a live env. Responses passed through as parsed JSON.
+ */
+
+interface ListRunsOptions {
+    since?: string;
+}
+interface LogsOptions {
+    page?: number;
+    limit?: number;
+}
+
+declare function dataflows(ctx: RequestContext): {
+    list: () => Promise<unknown>;
+    runs: (dagId: string, opts?: ListRunsOptions) => Promise<unknown>;
+    logs: (dagId: string, instanceId: string, opts?: LogsOptions) => Promise<unknown>;
+    run: (dagId: string, url: string, name: string) => Promise<unknown>;
+    create: (body: unknown) => Promise<unknown>;
+    templates: () => {
+        type: TemplateType;
+        name: string;
+        description?: string;
+        arguments: TemplateArg[];
+    }[];
+    /** Instantiate a dataset template → create a vega resource. */
+    createDataset: (template: string, args: Record<string, unknown>) => Promise<unknown>;
+    /** Instantiate a bkn template → create a knowledge network. */
+    createBkn: (template: string, args: Record<string, unknown>) => Promise<unknown>;
+};
+
+/**
+ * Knowledge-network backend client (ontology-manager + agent-retrieval).
+ * Endpoints mirror kweaver-sdk; responses are passed through as parsed JSON
+ * (shapes vary by backend version — validate at higher layers as needed).
+ */
+
+interface ListKnOptions {
+    offset?: number;
+    limit?: number;
+    sort?: string;
+    direction?: "asc" | "desc";
+    namePattern?: string;
+    tag?: string;
+}
+interface GetKnOptions {
+    /** Return the full export payload. */
+    exportMode?: boolean;
+    /** Include statistics in the response. */
+    stats?: boolean;
+}
+interface CreateKnOptions {
+    name: string;
+    branch?: string;
+    baseBranch?: string;
+}
+interface ActionLogListOptions {
+    actionTypeId?: string;
+    status?: string;
+    triggerType?: string;
+    limit?: number;
+    needTotal?: boolean;
+}
+interface ListSchemaOptions {
+    branch?: string;
+    /** -1 = all (backend default). */
+    limit?: number;
+}
+interface SemanticSearchOptions {
+    mode?: string;
+    maxConcepts?: number;
+    returnQueryUnderstanding?: boolean;
+}
+
+interface CreateFromCatalogOptions {
+    catalogId: string;
+    name: string;
+    tables?: string[];
+    pkMap?: Record<string, string>;
+    build?: boolean;
+    noRollback?: boolean;
+    /** Pre-fetched row samples per table (e.g. from a CSV import) for PK detection. */
+    sampleRows?: Record<string, Array<Record<string, string | null>>>;
+    onProgress?: (msg: string) => void;
+}
+interface CreateFromCsvOptions {
+    catalogId: string;
+    name: string;
+    files: string;
+    tablePrefix?: string;
+    batchSize?: number;
+    tables?: string[];
+    pkMap?: Record<string, string>;
+    build?: boolean;
+    noRollback?: boolean;
+    onProgress?: (msg: string) => void;
+}
+
+/** Knowledge-network resource surface (the exported SDK API). */
+
+declare function kn(ctx: RequestContext): {
+    list: (opts?: ListKnOptions) => Promise<unknown>;
+    get: (knId: string, opts?: GetKnOptions) => Promise<unknown>;
+    search: (knId: string, query: string, opts?: SemanticSearchOptions) => Promise<unknown>;
+    create: (opts: CreateKnOptions) => Promise<unknown>;
+    update: (knId: string, body: unknown) => Promise<unknown>;
+    delete: (knId: string) => Promise<unknown>;
+    subgraph: (knId: string, body: unknown) => Promise<unknown>;
+    actionLogs: (knId: string, opts?: ActionLogListOptions) => Promise<unknown>;
+    actionLog: (knId: string, logId: string) => Promise<unknown>;
+    cancelActionLog: (knId: string, logId: string) => Promise<unknown>;
+    actionExecution: (knId: string, executionId: string) => Promise<unknown>;
+    metricQuery: (knId: string, metricId: string, body: unknown) => Promise<unknown>;
+    metricDryRun: (knId: string, body: unknown) => Promise<unknown>;
+    metricList: (knId: string, opts?: ListSchemaOptions) => Promise<unknown>;
+    metricGet: (knId: string, metricId: string) => Promise<unknown>;
+    metricCreate: (knId: string, body: unknown) => Promise<unknown>;
+    metricUpdate: (knId: string, metricId: string, body: unknown) => Promise<unknown>;
+    metricDelete: (knId: string, metricId: string) => Promise<unknown>;
+    metricSearch: (knId: string, body: unknown) => Promise<unknown>;
+    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>;
+    objectTypeDelete: (knId: string, id: string) => Promise<unknown>;
+    relationTypes: (knId: string, opts?: ListSchemaOptions) => Promise<unknown>;
+    relationTypeGet: (knId: string, id: string) => Promise<unknown>;
+    relationTypeCreate: (knId: string, body: unknown) => Promise<unknown>;
+    relationTypeUpdate: (knId: string, id: string, body: unknown) => Promise<unknown>;
+    relationTypeDelete: (knId: string, id: string) => Promise<unknown>;
+    actionTypes: (knId: string, opts?: ListSchemaOptions) => Promise<unknown>;
+    actionTypeQuery: (knId: string, atId: string, body: unknown) => Promise<unknown>;
+    actionTypeExecute: (knId: string, atId: string, body: unknown) => Promise<unknown>;
+    actionTypeInputs: (knId: string, atId: string) => Promise<unknown>;
+    actionTypeGet: (knId: string, id: string) => Promise<unknown>;
+    conceptGroups: (knId: string) => Promise<unknown>;
+    conceptGroup: (knId: string, cgId: string) => Promise<unknown>;
+    conceptGroupCreate: (knId: string, body: unknown) => Promise<unknown>;
+    conceptGroupUpdate: (knId: string, cgId: string, body: unknown) => Promise<unknown>;
+    conceptGroupDelete: (knId: string, cgId: string) => Promise<unknown>;
+    conceptGroupAddMembers: (knId: string, cgId: string, body: unknown) => Promise<unknown>;
+    conceptGroupRemoveMembers: (knId: string, cgId: string, otIds: string) => Promise<unknown>;
+    actionSchedules: (knId: string) => Promise<unknown>;
+    actionSchedule: (knId: string, scheduleId: string) => Promise<unknown>;
+    actionScheduleCreate: (knId: string, body: unknown) => Promise<unknown>;
+    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>;
+    createFromCsv: (opts: CreateFromCsvOptions) => Promise<unknown>;
+    /** Pack a local BKN directory and upload it as a knowledge network. */
+    push: (dir: string, opts?: {
+        branch?: string;
+    }) => Promise<unknown>;
+    /** Download a knowledge network and extract it into a local directory. */
+    pull: (knId: string, dir: string, opts?: {
+        branch?: string;
+    }) => Promise<{
+        knId: string;
+        dir: string;
+        bytes: number;
+    }>;
+};
+
+interface ListModelsOptions {
+    page?: number;
+    limit?: number;
+    name?: string;
+    modelType?: string;
+}
+interface ChatMessage {
+    role: string;
+    content: string;
+}
+
+/** Model-factory resource surface: management reads + runtime invocation. */
+
+declare function models(ctx: RequestContext): {
+    llm: {
+        list: (opts?: ListModelsOptions) => Promise<unknown>;
+        get: (modelId: string) => Promise<unknown>;
+        chat: (modelId: string, messages: ChatMessage[]) => Promise<unknown>;
+        chatStream: (modelId: string, messages: ChatMessage[], onDelta: (t: string) => void) => Promise<string>;
+        add: (body: unknown) => Promise<unknown>;
+        edit: (body: unknown) => Promise<unknown>;
+        delete: (modelIds: string[]) => Promise<unknown>;
+        test: (body: unknown) => Promise<unknown>;
+    };
+    small: {
+        list: (opts?: ListModelsOptions) => Promise<unknown>;
+        get: (modelId: string) => Promise<unknown>;
+        embeddings: (modelId: string, input: string[]) => Promise<unknown>;
+        rerank: (modelId: string, query: string, documents: string[]) => Promise<unknown>;
+        add: (body: unknown) => Promise<unknown>;
+        edit: (body: unknown) => Promise<unknown>;
+        delete: (modelIds: string[]) => Promise<unknown>;
+        test: (body: unknown) => Promise<unknown>;
+    };
+};
+
+/**
+ * Vega-backend resource client (list/find/get/query/delete). Endpoints mirror
+ * kweaver-sdk `api/resources.ts`. Responses passed through as parsed JSON.
+ */
+
+interface ListResourcesOptions {
+    datasourceId?: string;
+    name?: string;
+    /** Resource category, e.g. table | logicview. */
+    category?: string;
+    limit?: number;
+}
+interface FindResourceOptions {
+    datasourceId?: string;
+    /** Exact name match instead of fuzzy. */
+    exact?: boolean;
+}
+interface QueryResourceOptions {
+    limit?: number;
+    offset?: number;
+    needTotal?: boolean;
+}
+
+/** Resource surface (the exported SDK API) over vega-backend resources. */
+
+declare function resources(ctx: RequestContext): {
+    list: (opts?: ListResourcesOptions) => Promise<unknown>;
+    get: (id: string) => Promise<unknown>;
+    delete: (id: string) => Promise<unknown>;
+    find: (name: string, opts?: FindResourceOptions) => Promise<unknown>;
+    query: (id: string, opts?: QueryResourceOptions) => Promise<unknown>;
+};
+
+interface ListSkillsOptions {
+    page?: number;
+    pageSize?: number;
+    name?: string;
+    source?: string;
+    status?: string;
+    createUser?: string;
+}
+type SkillStatus = "unpublish" | "published" | "offline";
+
+declare function skills(ctx: RequestContext): {
+    list: (opts?: ListSkillsOptions) => Promise<unknown>;
+    get: (skillId: string) => Promise<unknown>;
+    market: (opts?: ListSkillsOptions) => Promise<unknown>;
+    marketGet: (skillId: string) => Promise<unknown>;
+    delete: (skillId: string) => Promise<unknown>;
+    content: (skillId: string) => Promise<unknown>;
+    readFile: (skillId: string, relPath: string) => Promise<unknown>;
+    history: (skillId: string) => Promise<unknown>;
+    setStatus: (skillId: string, status: SkillStatus) => Promise<unknown>;
+    updateMetadata: (skillId: string, body: unknown) => Promise<unknown>;
+    republish: (skillId: string, version: string) => Promise<unknown>;
+    publishHistory: (skillId: string, version: string) => Promise<unknown>;
+    /** Zip a local skill directory and register it. */
+    register: (dir: string, opts?: {
+        source?: string;
+        extendInfo?: unknown;
+    }) => Promise<unknown>;
+    /** Replace a skill's package from a local directory. */
+    updatePackage: (skillId: string, dir: string) => Promise<unknown>;
+    /** Download a skill archive to a local .zip file. */
+    download: (skillId: string, outPath?: string) => Promise<{
+        skillId: string;
+        path: string;
+        bytes: number;
+    }>;
+    /** Download a skill archive and extract it into a directory. */
+    install: (skillId: string, dir?: string) => Promise<{
+        skillId: string;
+        dir: string;
+        files: number;
+    }>;
+};
+
+type ImpexType = "toolbox" | "mcp" | "operator";
+interface ListToolboxesOptions {
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+}
+interface CreateToolboxOptions {
+    name: string;
+    serviceUrl: string;
+    description?: string;
+    source?: string;
+}
+interface ToolInvokeEnvelope {
+    header?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    path?: Record<string, unknown>;
+    body?: unknown;
+    timeout?: number;
+}
+
+declare function toolboxes(ctx: RequestContext): {
+    list: (opts?: ListToolboxesOptions) => Promise<unknown>;
+    tools: (boxId: string) => Promise<unknown>;
+    create: (opts: CreateToolboxOptions) => Promise<unknown>;
+    delete: (boxId: string) => Promise<unknown>;
+    publish: (boxId: string) => Promise<unknown>;
+    unpublish: (boxId: string) => Promise<unknown>;
+    setToolStatus: (boxId: string, toolIds: string[], status: "enabled" | "disabled") => Promise<unknown>;
+    upload: (boxId: string, filePath: string, metadataType?: string) => Promise<unknown>;
+    /** Export a toolbox config to a local `.adp` file. */
+    export: (id: string, outPath: string, type?: ImpexType) => Promise<{
+        id: string;
+        path: string;
+        bytes: number;
+    }>;
+    /** Import a toolbox config from a local `.adp` file. */
+    import: (filePath: string, type?: ImpexType) => Promise<unknown>;
+    execute: (boxId: string, toolId: string, e?: ToolInvokeEnvelope) => Promise<unknown>;
+    debug: (boxId: string, toolId: string, e?: ToolInvokeEnvelope) => Promise<unknown>;
+};
+
+/**
+ * Trace diagnose engine. Fetches a conversation's spans, shapes them into a
+ * trace tree, runs deterministic symbolic predicates, and (in hybrid mode) adds
+ * gated LLM-judged rubric findings + an LLM synthesized summary. Cross-trace
+ * `scan` is the remaining piece (see docs/exec-plans/tech-debt-tracker.md).
+ */
+
+interface Finding {
+    ruleId: string;
+    judgmentKind: "symbolic" | "rubric";
+    severity: "low" | "medium" | "high";
+    symptom: string;
+    evidence: {
+        spans: string[];
+        excerpt: string;
+    };
+    suggestedFix: {
+        target: string;
+        change: string;
+    };
+    confidence?: "low" | "medium" | "high";
+}
+interface Summary {
+    headline: string;
+    primaryRootCause: string | null;
+    targetForFix: string | null;
+}
+interface DiagnoseReport {
+    traceId: string;
+    conversationId: string;
+    diagnosedAt: string | null;
+    mode: "symbolic-only" | "hybrid";
+    rulesApplied: string[];
+    findingCount: number;
+    summary?: Summary;
+    findings: Finding[];
+}
+
+/**
+ * Trace eval-set — build a set of evaluation cases and run them against a live
+ * agent. Each case is {query, assertions[]}; `test` runs the query through the
+ * 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.
+ */
+
+type AssertionType = "contains" | "not_contains" | "regex" | "tool_call_count" | "tool_call_order" | "latency_ms" | "semantic_match";
+interface EvalAssertion {
+    type: AssertionType;
+    [key: string]: unknown;
+}
+interface EvalCase {
+    query_id: string;
+    input: {
+        user_message: string;
+    };
+    reference?: {
+        answer: string;
+    };
+    assertions?: EvalAssertion[];
+    tags?: string[];
+}
+interface AssertionResult {
+    type: AssertionType;
+    verdict: "pass" | "fail" | "skip";
+    actual?: unknown;
+    reason?: string;
+}
+interface CaseResult {
+    queryId: string;
+    query: string;
+    answer: string;
+    conversationId: string | null;
+    assertions: AssertionResult[];
+    errorCode?: string;
+}
+interface EvalSetResult {
+    agentId: string;
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    cases: CaseResult[];
+}
+
+declare function trace(ctx: RequestContext): {
+    /** Raw trace search (OpenSearch-style body). */
+    search: (body: unknown) => Promise<unknown>;
+    /** All span source docs for a conversation. */
+    spans: (conversationId: string, opts?: {
+        maxTraceIds?: number;
+        maxSpans?: number;
+    }) => Promise<Record<string, unknown>[]>;
+    diagnose: (conversationId: string, opts?: {
+        llm?: boolean;
+        judgeTimeoutMs?: number;
+    }) => Promise<DiagnoseReport>;
+    /**
+     * Scan (batch-diagnose) several conversations and aggregate the findings:
+     * per-trace reports + a recurring-rule tally across the batch.
+     */
+    scan: (conversationIds: string[], opts?: {
+        llm?: boolean;
+        judgeTimeoutMs?: number;
+    }) => Promise<{
+        scanned: number;
+        totalFindings: number;
+        recurringRules: {
+            ruleId: string;
+            count: number;
+        }[];
+        reports: (DiagnoseReport | {
+            conversationId: string;
+            error: string;
+        })[];
+    }>;
+    /** Build eval cases from a loosely-shaped queries object/array. */
+    evalSetBuild: (raw: unknown) => EvalCase[];
+    /**
+     * 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
+     * `semantic_match` assertions via the local claude judge.
+     */
+    evalSetTest: (agentId: string, cases: EvalCase[], opts?: {
+        version?: string;
+        llm?: boolean;
+    }) => Promise<EvalSetResult>;
+};
+
+/**
+ * Vega backend client — catalog/resource reads + BuildTask (index build).
+ * Build config lives on the task (CreateBuildTaskRequest), per the platform model.
+ */
+
+declare const BuildMode: z.ZodEnum<["batch", "streaming"]>;
+type BuildMode = z.infer<typeof BuildMode>;
+/** POST /build-tasks body. */
+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>;
+}, "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;
+}, {
+    mode: "batch" | "streaming";
+    resource_id: string;
+    embedding_fields?: string[] | undefined;
+    build_key_fields?: string[] | undefined;
+    embedding_model?: string | undefined;
+    model_dimensions?: number | undefined;
+}>;
+type CreateBuildTaskRequest = z.infer<typeof CreateBuildTaskRequest>;
+declare const BuildTask: z.ZodObject<{
+    id: z.ZodString;
+    resource_id: z.ZodString;
+    mode: z.ZodEnum<["batch", "streaming"]>;
+    state: z.ZodOptional<z.ZodString>;
+    synced_count: z.ZodOptional<z.ZodNumber>;
+    vectorized_count: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    mode: "batch" | "streaming";
+    id: string;
+    resource_id: string;
+    state?: string | undefined;
+    synced_count?: number | undefined;
+    vectorized_count?: number | undefined;
+}, {
+    mode: "batch" | "streaming";
+    id: string;
+    resource_id: string;
+    state?: string | undefined;
+    synced_count?: number | undefined;
+    vectorized_count?: number | undefined;
+}>;
+type BuildTask = z.infer<typeof BuildTask>;
+interface ListCatalogsOptions {
+    limit?: number;
+    offset?: number;
+}
+
+declare function vega(ctx: RequestContext): {
+    catalogs: (opts?: ListCatalogsOptions) => Promise<unknown>;
+    getCatalog: (id: string) => Promise<unknown>;
+    catalogResources: (id: string, category?: string) => Promise<unknown>;
+    catalogHealth: (ids: string[]) => Promise<unknown>;
+    connectorTypes: () => Promise<unknown>;
+    connectorType: (type: string) => Promise<unknown>;
+    /** Build a resource's index. With `wait`, polls until terminal. */
+    build: (req: CreateBuildTaskRequest, opts?: {
+        wait?: boolean;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }) => Promise<BuildTask>;
+    buildStatus: (taskId: string) => Promise<{
+        mode: "batch" | "streaming";
+        id: string;
+        resource_id: string;
+        state?: string | undefined;
+        synced_count?: number | undefined;
+        vectorized_count?: number | undefined;
+    }>;
+};
+
+interface BknClient {
+    readonly ctx: RequestContext;
+    readonly kn: ReturnType<typeof kn>;
+    readonly resource: ReturnType<typeof resources>;
+    readonly dataflows: ReturnType<typeof dataflows>;
+    readonly agents: ReturnType<typeof agents>;
+    readonly context: ReturnType<typeof context>;
+    readonly models: ReturnType<typeof models>;
+    readonly skills: ReturnType<typeof skills>;
+    readonly toolboxes: ReturnType<typeof toolboxes>;
+    readonly trace: ReturnType<typeof trace>;
+    readonly admin: ReturnType<typeof admin>;
+    readonly vega: ReturnType<typeof vega>;
+    /** Raw API passthrough (the `call` escape hatch). */
+    call(path: string, opts?: RawCallOptions): Promise<RawCallResult>;
+}
+declare function createClient(opts?: ClientOptions): BknClient;
+
+/** Typed errors and their mapping to user-facing messages + exit codes. */
+/** Raised when an HTTP request returns a non-2xx status. */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+/** Raised for bad CLI/SDK input before any request is made. */
+declare class InputError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Minimal JWT payload decoder — base64url decode only, NO signature check.
+ * Used to surface identity (sub / username / email) from a stored token.
+ * Never trust this for authorization decisions; it is display-only.
+ */
+interface JwtClaims {
+    sub?: string;
+    name?: string;
+    preferred_username?: string;
+    email?: string;
+    exp?: number;
+    [key: string]: unknown;
+}
+
+interface TokenConfig {
+    baseUrl: string;
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresAt?: string;
+    /** Skip TLS verification for this platform (saved by `auth login -k`). */
+    tlsInsecure?: boolean;
+    /** Login name persisted at login time (fallback when JWT lacks claims). */
+    username?: string;
+    /** Human-readable name from userinfo. */
+    displayName?: string;
+}
+/** userId from the token's JWT `sub` (id_token first), else "default". */
+declare function userIdFromToken(token: TokenConfig): string;
+interface PlatformUser {
+    userId: string;
+    username?: string;
+    displayName?: string;
+}
+
+/**
+ * Auth resource — credential store + identity (multi-user, store-backed).
+ * Interactive browser/password OAuth lives in `auth/oauth.ts` and is persisted
+ * here via `attachToken`.
+ */
+
+declare function hostOf(baseUrl: string): string;
+/** Save a token (under its derived user) and make it the active platform/user. */
+declare function attachToken(baseUrl: string, accessToken: string, opts?: {
+    refreshToken?: string;
+    idToken?: string;
+    insecure?: boolean;
+}): {
+    baseUrl: string;
+    userId: string;
+    username?: string;
+};
+interface AuthStatus {
+    baseUrl?: string;
+    userId?: string;
+    hasToken: boolean;
+    username?: string;
+    expired?: boolean;
+}
+declare function status(): AuthStatus;
+declare function currentToken(): string;
+declare function whoami(): JwtClaims;
+interface PlatformListItem {
+    baseUrl: string;
+    userId: string;
+    username?: string;
+    active: boolean;
+}
+/** Flat list of platform/user pairs with a saved session. */
+declare function listPlatforms(): PlatformListItem[];
+/** Switch the active platform (must already have a saved token). */
+declare function use(baseUrl: string): void;
+declare function logout(): boolean;
+declare function deletePlatform(baseUrl: string, userId?: string): boolean;
+/** Switch the active user for a platform (token must already be saved). */
+declare function switchUser(baseUrl: string, userId: string): {
+    baseUrl: string;
+    userId: string;
+};
+/** List saved user profiles for one platform. */
+declare function usersOf(baseUrl: string): PlatformUser[];
+/** Export the active session's tokens (for seeding a headless host). */
+declare function exportCreds(): {
+    baseUrl: string;
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+};
+
+type auth_AuthStatus = AuthStatus;
+type auth_PlatformListItem = PlatformListItem;
+declare const auth_attachToken: typeof attachToken;
+declare const auth_currentToken: typeof currentToken;
+declare const auth_deletePlatform: typeof deletePlatform;
+declare const auth_exportCreds: typeof exportCreds;
+declare const auth_hostOf: typeof hostOf;
+declare const auth_listPlatforms: typeof listPlatforms;
+declare const auth_logout: typeof logout;
+declare const auth_status: typeof status;
+declare const auth_switchUser: typeof switchUser;
+declare const auth_use: typeof use;
+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, auth_attachToken as attachToken, auth_currentToken as currentToken, 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 };
+}
+
+/**
+ * Thin fetch wrapper: explicit timeout, auth headers, JSON in/out, typed errors.
+ * The single choke point for every backend call — resources build on this.
+ */
+
+interface RequestInitEx {
+    method?: string;
+    /** JSON body — serialized and Content-Type set automatically. */
+    body?: unknown;
+    /** Query params appended to the path. */
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    /** 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 };