@kweaver-ai/kweaver-sdk 0.4.0

package/dist/auth/oauth.js

@@ -0,0 +1,417 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { URL } from "node:url";
+import { openBrowser } from "../utils/browser.js";
+import { fetchTextOrThrow, HttpError, NetworkRequestError } from "../utils/http.js";
+import { getCurrentPlatform, loadCallbackSession, loadClientConfig, loadTokenConfig, saveCallbackSession, saveClientConfig, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
+export function normalizeBaseUrl(value) {
+    return value.replace(/\/+$/, "");
+}
+function randomValue(size = 24) {
+    return randomBytes(size).toString("hex");
+}
+export function getAuthorizationSuccessMessage() {
+    return "Authorization succeeded. You can close this page and return to the terminal.";
+}
+function toBasicAuth(clientId, clientSecret) {
+    const user = encodeURIComponent(clientId);
+    const password = encodeURIComponent(clientSecret);
+    return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+}
+function buildTokenConfig(baseUrl, token) {
+    const obtainedAt = new Date().toISOString();
+    const expiresAt = token.expires_in === undefined
+        ? undefined
+        : new Date(Date.now() + token.expires_in * 1000).toISOString();
+    return {
+        baseUrl,
+        accessToken: token.access_token,
+        tokenType: token.token_type,
+        scope: token.scope,
+        expiresIn: token.expires_in,
+        expiresAt,
+        refreshToken: token.refresh_token,
+        idToken: token.id_token,
+        obtainedAt,
+    };
+}
+export async function registerClient(options) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    const payload = {
+        client_name: options.clientName,
+        grant_types: ["authorization_code", "implicit", "refresh_token"],
+        response_types: ["token id_token", "code", "token"],
+        scope: "openid offline all",
+        redirect_uris: [options.redirectUri],
+        post_logout_redirect_uris: [options.logoutRedirectUri],
+        metadata: {
+            device: {
+                name: options.clientName,
+                client_type: "web",
+                description: "kweaver CLI",
+            },
+        },
+    };
+    const { body } = await fetchTextOrThrow(`${baseUrl}/oauth2/clients`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    const data = JSON.parse(body);
+    const clientConfig = {
+        baseUrl,
+        clientId: data.client_id,
+        clientSecret: data.client_secret,
+        redirectUri: options.redirectUri,
+        logoutRedirectUri: options.logoutRedirectUri,
+        scope: payload.scope,
+        lang: options.lang,
+        product: options.product,
+        xForwardedPrefix: options.xForwardedPrefix,
+    };
+    saveClientConfig(clientConfig);
+    return clientConfig;
+}
+function toSuccessfulLogoutPath(pathname) {
+    if (pathname.endsWith("/callback")) {
+        return `${pathname.slice(0, -"/callback".length)}/successful-logout`;
+    }
+    return `${pathname.replace(/\/$/, "")}/successful-logout`;
+}
+function normalizeListenHost(host) {
+    return host?.trim() || "127.0.0.1";
+}
+export function buildAuthRedirectConfig(options) {
+    const listenHost = normalizeListenHost(options.host);
+    const listenPort = options.port;
+    if (options.redirectUriOverride) {
+        const redirect = new URL(options.redirectUriOverride);
+        const logout = new URL(options.redirectUriOverride);
+        logout.pathname = toSuccessfulLogoutPath(redirect.pathname);
+        logout.search = "";
+        logout.hash = "";
+        return {
+            redirectUri: redirect.toString(),
+            logoutRedirectUri: logout.toString(),
+            listenHost,
+            listenPort,
+            callbackPath: redirect.pathname,
+        };
+    }
+    return {
+        redirectUri: `http://${listenHost}:${listenPort}/callback`,
+        logoutRedirectUri: `http://${listenHost}:${listenPort}/successful-logout`,
+        listenHost,
+        listenPort,
+        callbackPath: "/callback",
+    };
+}
+export async function ensureClientConfig(options) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    const redirect = buildAuthRedirectConfig({
+        port: options.port,
+        host: options.host,
+        redirectUriOverride: options.redirectUriOverride,
+    });
+    const { redirectUri, logoutRedirectUri } = redirect;
+    const client = loadClientConfig(baseUrl);
+    if (client &&
+        !options.forceRegister &&
+        client.baseUrl === baseUrl &&
+        client.redirectUri === redirectUri &&
+        client.clientId &&
+        client.clientSecret) {
+        return { client, created: false };
+    }
+    const createdClient = await registerClient({
+        baseUrl,
+        clientName: options.clientName,
+        redirectUri,
+        logoutRedirectUri,
+        lang: options.lang,
+        product: options.product,
+        xForwardedPrefix: options.xForwardedPrefix,
+    });
+    return {
+        client: createdClient,
+        created: true,
+    };
+}
+export function buildAuthorizationUrl(client, state = randomValue(12)) {
+    const authorizationUrl = new URL(`${client.baseUrl}/oauth2/auth`);
+    authorizationUrl.searchParams.set("redirect_uri", client.redirectUri);
+    authorizationUrl.searchParams.set("x-forwarded-prefix", client.xForwardedPrefix ?? "");
+    authorizationUrl.searchParams.set("client_id", client.clientId);
+    authorizationUrl.searchParams.set("scope", client.scope);
+    authorizationUrl.searchParams.set("response_type", "code");
+    authorizationUrl.searchParams.set("state", state);
+    authorizationUrl.searchParams.set("lang", client.lang ?? "zh-cn");
+    if (client.product) {
+        authorizationUrl.searchParams.set("product", client.product);
+    }
+    return authorizationUrl.toString();
+}
+function waitForAuthorizationCode(options, expectedState) {
+    const { listenHost, listenPort, callbackPath } = options;
+    return new Promise((resolve, reject) => {
+        const server = createServer((request, response) => {
+            if (!request.url) {
+                response.statusCode = 400;
+                response.end("Missing request URL");
+                return;
+            }
+            const callbackUrl = new URL(request.url, `http://${request.headers.host ?? `${listenHost}:${listenPort}`}`);
+            if (callbackUrl.pathname !== callbackPath) {
+                response.statusCode = 404;
+                response.end("Not Found");
+                return;
+            }
+            const error = callbackUrl.searchParams.get("error");
+            if (error) {
+                response.statusCode = 400;
+                response.end(`Authorization failed: ${error}`);
+                server.close();
+                reject(new Error(`Authorization failed: ${error}`));
+                return;
+            }
+            const state = callbackUrl.searchParams.get("state");
+            if (state !== expectedState) {
+                response.statusCode = 400;
+                response.end("State mismatch");
+                server.close();
+                reject(new Error("State mismatch in OAuth callback"));
+                return;
+            }
+            const code = callbackUrl.searchParams.get("code");
+            if (!code) {
+                response.statusCode = 400;
+                response.end("Missing authorization code");
+                server.close();
+                reject(new Error("Missing authorization code"));
+                return;
+            }
+            response.statusCode = 200;
+            response.setHeader("content-type", "text/plain; charset=utf-8");
+            response.end(getAuthorizationSuccessMessage());
+            server.close();
+            resolve({
+                code,
+                state,
+                scope: callbackUrl.searchParams.get("scope") ?? undefined,
+            });
+        });
+        server.on("error", (error) => reject(error));
+        server.listen(listenPort, listenHost);
+    });
+}
+async function exchangeAuthorizationCode(client, code) {
+    const payload = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: client.redirectUri,
+    });
+    const { body } = await fetchTextOrThrow(`${client.baseUrl}/oauth2/token`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            accept: "application/json",
+            authorization: toBasicAuth(client.clientId, client.clientSecret),
+        },
+        body: payload.toString(),
+    });
+    const tokenConfig = buildTokenConfig(client.baseUrl, JSON.parse(body));
+    saveTokenConfig(tokenConfig);
+    return tokenConfig;
+}
+/**
+ * Call the platform's end-session endpoint so the server invalidates the session.
+ * Best-effort: failures are ignored so local logout still proceeds.
+ */
+export async function callLogoutEndpoint(client, token) {
+    const url = new URL(`${client.baseUrl}/oauth2/signout`);
+    if (token?.idToken) {
+        url.searchParams.set("id_token_hint", token.idToken);
+    }
+    url.searchParams.set("post_logout_redirect_uri", client.logoutRedirectUri);
+    url.searchParams.set("client_id", client.clientId);
+    try {
+        const response = await fetch(url.toString(), { method: "GET", redirect: "manual" });
+        if (!response.ok && response.status !== 302) {
+            const body = await response.text();
+            console.error(`Logout endpoint returned ${response.status}: ${body.slice(0, 200)}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Logout endpoint request failed: ${msg}`);
+    }
+}
+export async function refreshAccessToken(client, refreshToken) {
+    const payload = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+    });
+    const { body } = await fetchTextOrThrow(`${client.baseUrl}/oauth2/token`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            accept: "application/json",
+            authorization: toBasicAuth(client.clientId, client.clientSecret),
+        },
+        body: payload.toString(),
+    });
+    const parsed = JSON.parse(body);
+    const tokenConfig = buildTokenConfig(client.baseUrl, {
+        ...parsed,
+        refresh_token: parsed.refresh_token ?? refreshToken,
+    });
+    saveTokenConfig(tokenConfig);
+    return tokenConfig;
+}
+export async function ensureValidToken() {
+    const envToken = process.env.KWEAVER_TOKEN;
+    const envBaseUrl = process.env.KWEAVER_BASE_URL;
+    if (envToken && envBaseUrl) {
+        return {
+            baseUrl: normalizeBaseUrl(envBaseUrl),
+            accessToken: envToken,
+            tokenType: "bearer",
+            scope: "openid",
+            obtainedAt: new Date().toISOString(),
+        };
+    }
+    const currentPlatform = getCurrentPlatform();
+    if (!currentPlatform) {
+        throw new Error("No active platform selected. Run `kweaver auth <platform-url>` first.");
+    }
+    const client = loadClientConfig(currentPlatform);
+    const token = loadTokenConfig(currentPlatform);
+    if (!client || !token) {
+        throw new Error(`Missing saved credentials for ${currentPlatform}. Run \`kweaver auth ${currentPlatform}\` first.`);
+    }
+    if (!token.expiresAt) {
+        return token;
+    }
+    const expiresAtMs = Date.parse(token.expiresAt);
+    if (Number.isNaN(expiresAtMs) || expiresAtMs - 60_000 > Date.now()) {
+        return token;
+    }
+    if (!token.refreshToken) {
+        throw new Error("Access token expired and no refresh token is available. Run auth login again.");
+    }
+    return refreshAccessToken(client, token.refreshToken);
+}
+export async function login(options) {
+    const redirect = buildAuthRedirectConfig({
+        port: options.port,
+        host: options.host,
+        redirectUriOverride: options.redirectUriOverride,
+    });
+    const { client, created } = await ensureClientConfig({
+        baseUrl: options.baseUrl,
+        port: options.port,
+        clientName: options.clientName,
+        forceRegister: options.forceRegister,
+        host: options.host,
+        redirectUriOverride: options.redirectUriOverride,
+        lang: options.lang,
+        product: options.product,
+        xForwardedPrefix: options.xForwardedPrefix,
+    });
+    const state = randomValue(12);
+    const authorizationUrl = buildAuthorizationUrl(client, state);
+    const waitForCode = waitForAuthorizationCode({
+        listenHost: redirect.listenHost,
+        listenPort: redirect.listenPort,
+        callbackPath: redirect.callbackPath,
+    }, state);
+    if (options.open) {
+        console.log(`Opening browser for authorization: ${authorizationUrl}`);
+        const opened = await openBrowser(authorizationUrl);
+        if (!opened) {
+            console.error("Failed to open a browser automatically. Open this URL manually:");
+            console.error(authorizationUrl);
+        }
+    }
+    else {
+        console.log("Authorization URL:");
+        console.log(authorizationUrl);
+        console.log("");
+        console.log(`Redirect URI: ${client.redirectUri}`);
+        console.log(`Waiting for OAuth callback on http://${redirect.listenHost}:${redirect.listenPort}${redirect.callbackPath}`);
+        if (redirect.listenHost === "127.0.0.1" || redirect.listenHost === "localhost") {
+            console.log("");
+            console.log("If your browser is on another machine, use SSH port forwarding first:");
+            console.log(`ssh -L ${redirect.listenPort}:127.0.0.1:${redirect.listenPort} user@server`);
+        }
+    }
+    const callbackResult = await waitForCode;
+    const callback = {
+        baseUrl: client.baseUrl,
+        redirectUri: client.redirectUri,
+        code: callbackResult.code,
+        state: callbackResult.state,
+        scope: callbackResult.scope,
+        receivedAt: new Date().toISOString(),
+    };
+    saveCallbackSession(callback);
+    const token = await exchangeAuthorizationCode(client, callbackResult.code);
+    setCurrentPlatform(client.baseUrl);
+    return { client, token, authorizationUrl, callback, created };
+}
+export function getStoredAuthSummary(baseUrl) {
+    const targetBaseUrl = baseUrl ?? getCurrentPlatform() ?? undefined;
+    return {
+        client: loadClientConfig(targetBaseUrl),
+        token: loadTokenConfig(targetBaseUrl),
+        callback: loadCallbackSession(targetBaseUrl),
+    };
+}
+function formatOAuthErrorBody(body) {
+    let data;
+    try {
+        data = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (!data || typeof data.error !== "string") {
+        return null;
+    }
+    const code = data.error;
+    const description = typeof data.error_description === "string" ? data.error_description : "";
+    const lines = [`OAuth error: ${code}`];
+    if (description) {
+        lines.push(description);
+    }
+    if (code === "invalid_grant") {
+        lines.push("");
+        lines.push("The refresh token or authorization code is invalid or expired. Run `kweaver auth <platform-url>` again to log in.");
+    }
+    return lines.join("\n");
+}
+export function formatHttpError(error) {
+    if (error instanceof HttpError) {
+        const oauthMessage = formatOAuthErrorBody(error.body);
+        if (oauthMessage) {
+            return `HTTP ${error.status} ${error.statusText}\n\n${oauthMessage}`;
+        }
+        return `${error.message}\n${error.body}`.trim();
+    }
+    if (error instanceof NetworkRequestError) {
+        return [
+            error.message,
+            `Method: ${error.method}`,
+            `URL: ${error.url}`,
+            `Cause: ${error.causeMessage}`,
+            `Hint: ${error.hint}`,
+        ].join("\n").trim();
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,79 @@
+import { runAgentCommand } from "./commands/agent.js";
+import { runAuthCommand } from "./commands/auth.js";
+import { runKnCommand } from "./commands/bkn.js";
+import { runCallCommand } from "./commands/call.js";
+import { runContextLoaderCommand } from "./commands/context-loader.js";
+import { runTokenCommand } from "./commands/token.js";
+function printHelp() {
+    console.log(`kweaver
+
+Usage:
+  kweaver auth <platform-url>
+  kweaver auth login <platform-url>
+  kweaver auth <platform-url> [--alias name] [--no-open] [--host host] [--redirect-uri uri]
+  kweaver auth status [platform-url]
+  kweaver auth list
+  kweaver auth use <platform-url>
+  kweaver auth logout [platform-url]
+  kweaver auth delete <platform-url>
+  kweaver token
+  kweaver call <url> [-X METHOD] [-H "Name: value"] [-d BODY] [--pretty] [--verbose] [-bd value]
+  kweaver agent chat <agent_id> [-m "message"] [--version value] [--conversation-id id] [--stream] [--no-stream] [--verbose] [-bd value]
+  kweaver agent list [options]
+  kweaver bkn list [options]
+  kweaver bkn get <kn-id> [options]
+  kweaver bkn search <kn-id> <query> [options]
+  kweaver bkn create [options]
+  kweaver bkn update <kn-id> [options]
+  kweaver bkn delete <kn-id>
+  kweaver context-loader [config|kn-search|...]
+  kweaver --help
+
+Commands:
+  auth           Login, list, inspect, and switch saved platform auth profiles
+  token          Print the current access token, refreshing it first if needed
+  call           Call an API with curl-style flags and auto-injected token headers
+  agent          Chat with a KWeaver agent (agent chat <id>), list published agents (agent list)
+  bkn           Business knowledge network (list/get/create/update/delete/export/stats; object-type, subgraph, action-type, action-log)
+  context-loader Call context-loader MCP (tools, resources, prompts; kn-search, query-*, etc.)
+  help           Show this message`);
+}
+export async function run(argv) {
+    const [command, ...rest] = argv;
+    if (argv.length === 0 || !command || command === "--help" || command === "-h" || command === "help") {
+        printHelp();
+        return 0;
+    }
+    if (command === "auth") {
+        return runAuthCommand(rest);
+    }
+    if (command === "call" || command === "curl") {
+        return runCallCommand(rest);
+    }
+    if (command === "token") {
+        return runTokenCommand(rest);
+    }
+    if (command === "agent") {
+        return runAgentCommand(rest);
+    }
+    if (command === "bkn") {
+        return runKnCommand(rest);
+    }
+    if (command === "context-loader" || command === "context") {
+        return runContextLoaderCommand(rest);
+    }
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    return 1;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    run(process.argv.slice(2))
+        .then((code) => {
+        process.exit(code);
+    })
+        .catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        process.exit(1);
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+import { AgentsResource } from "./resources/agents.js";
+import { ConversationsResource } from "./resources/conversations.js";
+import { ContextLoaderResource } from "./resources/context-loader.js";
+import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
+import { BknResource } from "./resources/bkn.js";
+/**
+ * Shared credentials passed to every resource method.
+ * Internal — use KWeaverClient.
+ */
+export interface ClientContext {
+    /** Returns the base options that every API function requires. */
+    base(): {
+        baseUrl: string;
+        accessToken: string;
+        businessDomain: string;
+    };
+}
+export interface KWeaverClientOptions {
+    /**
+     * KWeaver platform base URL (e.g. "https://your-kweaver.com").
+     * When omitted, reads the active platform saved by `kweaver auth login`.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer access token.
+     * When omitted, reads the token saved for the active platform.
+     */
+    accessToken?: string;
+    /**
+     * x-business-domain header value.  Defaults to "bd_public".
+     * Override with KWEAVER_BUSINESS_DOMAIN env var or pass explicitly.
+     */
+    businessDomain?: string;
+}
+/**
+ * Main entry point for the KWeaver TypeScript SDK.
+ *
+ * @example Using explicit credentials:
+ * ```typescript
+ * import { KWeaverClient } from "kweaver-sdk";
+ *
+ * const client = new KWeaverClient({
+ *   baseUrl: "https://your-kweaver.com",
+ *   accessToken: "your-token",
+ * });
+ *
+ * const kns = await client.knowledgeNetworks.list();
+ * const reply = await client.agents.chat("agent-id", "你好");
+ * console.log(reply.text);
+ * ```
+ *
+ * @example Using credentials saved by `kweaver auth login` (zero config):
+ * ```typescript
+ * const client = new KWeaverClient();   // reads ~/.kweaver/
+ * ```
+ *
+ * @example Using environment variables:
+ * ```typescript
+ * // Set KWEAVER_BASE_URL and KWEAVER_TOKEN
+ * const client = new KWeaverClient();
+ * ```
+ */
+export declare class KWeaverClient implements ClientContext {
+    private readonly _baseUrl;
+    private readonly _accessToken;
+    private readonly _businessDomain;
+    /** Knowledge network CRUD and schema (object/relation/action types). */
+    readonly knowledgeNetworks: KnowledgeNetworksResource;
+    /** Agent listing and chat (single-shot and streaming). */
+    readonly agents: AgentsResource;
+    /** BKN engine: instance queries, subgraph, action execute/poll, action logs. */
+    readonly bkn: BknResource;
+    /** Conversation and message history. */
+    readonly conversations: ConversationsResource;
+    constructor(opts?: KWeaverClientOptions);
+    /** @internal — used by resource classes to build API call options. */
+    base(): {
+        baseUrl: string;
+        accessToken: string;
+        businessDomain: string;
+    };
+    /**
+     * Create a ContextLoaderResource bound to a specific knowledge network.
+     *
+     * @param mcpUrl  Full MCP endpoint URL (e.g. from `kweaver context-loader config show`).
+     * @param knId    Knowledge network ID to search against.
+     *
+     * @example
+     * ```typescript
+     * const cl = client.contextLoader(mcpUrl, "d5iv6c9818p72mpje8pg");
+     * const results = await cl.search({ query: "高血压 治疗" });
+     * ```
+     */
+    contextLoader(mcpUrl: string, knId: string): ContextLoaderResource;
+}

package/dist/client.js

@@ -0,0 +1,104 @@
+import { getCurrentPlatform, loadTokenConfig, } from "./config/store.js";
+import { AgentsResource } from "./resources/agents.js";
+import { ConversationsResource } from "./resources/conversations.js";
+import { ContextLoaderResource } from "./resources/context-loader.js";
+import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
+import { BknResource } from "./resources/bkn.js";
+// ── KWeaverClient ─────────────────────────────────────────────────────────────
+/**
+ * Main entry point for the KWeaver TypeScript SDK.
+ *
+ * @example Using explicit credentials:
+ * ```typescript
+ * import { KWeaverClient } from "kweaver-sdk";
+ *
+ * const client = new KWeaverClient({
+ *   baseUrl: "https://your-kweaver.com",
+ *   accessToken: "your-token",
+ * });
+ *
+ * const kns = await client.knowledgeNetworks.list();
+ * const reply = await client.agents.chat("agent-id", "你好");
+ * console.log(reply.text);
+ * ```
+ *
+ * @example Using credentials saved by `kweaver auth login` (zero config):
+ * ```typescript
+ * const client = new KWeaverClient();   // reads ~/.kweaver/
+ * ```
+ *
+ * @example Using environment variables:
+ * ```typescript
+ * // Set KWEAVER_BASE_URL and KWEAVER_TOKEN
+ * const client = new KWeaverClient();
+ * ```
+ */
+export class KWeaverClient {
+    _baseUrl;
+    _accessToken;
+    _businessDomain;
+    /** Knowledge network CRUD and schema (object/relation/action types). */
+    knowledgeNetworks;
+    /** Agent listing and chat (single-shot and streaming). */
+    agents;
+    /** BKN engine: instance queries, subgraph, action execute/poll, action logs. */
+    bkn;
+    /** Conversation and message history. */
+    conversations;
+    constructor(opts = {}) {
+        const envUrl = process.env.KWEAVER_BASE_URL;
+        const envToken = process.env.KWEAVER_TOKEN;
+        const envDomain = process.env.KWEAVER_BUSINESS_DOMAIN;
+        // Resolve baseUrl: explicit > env > saved config
+        let baseUrl = opts.baseUrl ?? envUrl;
+        let accessToken = opts.accessToken ?? envToken;
+        if (!baseUrl || !accessToken) {
+            const platform = getCurrentPlatform();
+            if (platform) {
+                const stored = loadTokenConfig(platform);
+                if (!baseUrl)
+                    baseUrl = platform;
+                if (!accessToken && stored)
+                    accessToken = stored.accessToken;
+            }
+        }
+        if (!baseUrl) {
+            throw new Error("KWeaverClient: baseUrl is required. " +
+                "Pass it explicitly, set KWEAVER_BASE_URL, or run `kweaver auth login`.");
+        }
+        if (!accessToken) {
+            throw new Error("KWeaverClient: accessToken is required. " +
+                "Pass it explicitly, set KWEAVER_TOKEN, or run `kweaver auth login`.");
+        }
+        this._baseUrl = baseUrl.replace(/\/+$/, "");
+        this._accessToken = accessToken;
+        this._businessDomain = opts.businessDomain ?? envDomain ?? "bd_public";
+        this.knowledgeNetworks = new KnowledgeNetworksResource(this);
+        this.agents = new AgentsResource(this);
+        this.bkn = new BknResource(this);
+        this.conversations = new ConversationsResource(this);
+    }
+    /** @internal — used by resource classes to build API call options. */
+    base() {
+        return {
+            baseUrl: this._baseUrl,
+            accessToken: this._accessToken,
+            businessDomain: this._businessDomain,
+        };
+    }
+    /**
+     * Create a ContextLoaderResource bound to a specific knowledge network.
+     *
+     * @param mcpUrl  Full MCP endpoint URL (e.g. from `kweaver context-loader config show`).
+     * @param knId    Knowledge network ID to search against.
+     *
+     * @example
+     * ```typescript
+     * const cl = client.contextLoader(mcpUrl, "d5iv6c9818p72mpje8pg");
+     * const results = await cl.search({ query: "高血压 治疗" });
+     * ```
+     */
+    contextLoader(mcpUrl, knId) {
+        return new ContextLoaderResource(this, mcpUrl, knId);
+    }
+}