@kweaver-ai/kweaver-sdk 0.4.8 → 0.4.10

package/README.md

@@ -98,7 +98,7 @@ const results = await cl.search({ query: "hypertension treatment" });
 ## CLI Reference
 
 ```
-kweaver auth login/status/list/use/delete/logout
+kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] — also: status, list, use, delete, logout
 kweaver token
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties

package/README.zh.md

@@ -98,7 +98,7 @@ const results = await cl.search({ query: "高血压 治疗" });
 ## 命令速查
 
 ```
-kweaver auth login/status/list/use/delete/logout
+kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] — 另有 status、list、use、delete、logout
 kweaver token
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties

package/dist/auth/oauth.js

@@ -74,10 +74,9 @@ export async function oauth2Login(baseUrl, options) {
             }
         });
         server.listen(port, "127.0.0.1", () => {
-            // Step 5: Open browser
-            import("node:child_process").then(({ exec }) => {
-                const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-                exec(`${cmd} "${authUrl}"`);
+            // Step 5: Open browser (uses spawn with proper Windows quoting)
+            import("../utils/browser.js").then(({ openBrowser }) => {
+                openBrowser(authUrl);
             });
         });
     });

package/dist/cli.js

@@ -33,7 +33,7 @@ Usage:
   kweaver agent get <agent_id> [-bd value] [--pretty]
   kweaver agent get-by-key <key> [-bd value] [--pretty]
   kweaver agent sessions <agent_id> [-bd value] [--limit N] [--pretty]
-  kweaver agent history <agent_id> <session_id> [-bd value] [--limit N] [--pretty]
+  kweaver agent history <conversation_id> [-bd value] [--limit N] [--pretty]
   kweaver agent create [options]
   kweaver agent update <agent_id> [options]
   kweaver agent delete <agent_id> [-bd value]
@@ -54,10 +54,10 @@ Usage:
   kweaver bkn update <kn-id> [options]
   kweaver bkn delete <kn-id> [-y]
   kweaver bkn build <kn-id> [--wait] [--no-wait] [--timeout N]
-  kweaver bkn validate <kn-id>
+  kweaver bkn validate <directory> [--detect-encoding|--no-detect-encoding] [--source-encoding name]
   kweaver bkn export <kn-id>
   kweaver bkn stats <kn-id>
-  kweaver bkn push <directory> [--branch main] [-bd value]
+  kweaver bkn push <directory> [--branch main] [-bd value] [--detect-encoding|--no-detect-encoding] [--source-encoding name]
   kweaver bkn pull <kn-id> [directory] [--branch main] [-bd value]
   kweaver bkn object-type list|get|create|update|delete|query|properties <kn-id> ...
   kweaver bkn relation-type list|get|create|update|delete <kn-id> ...
@@ -154,7 +154,9 @@ function safeExit(code) {
         process.exit(code);
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+if (fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
     run(process.argv.slice(2))
         .then((code) => {
         safeExit(code);

package/dist/commands/auth.js

@@ -4,19 +4,29 @@ export async function runAuthCommand(args) {
     const target = args[0];
     const rest = args.slice(1);
     if (!target || target === "--help" || target === "-h") {
-        console.log(`kweaver auth login <url>     Login to a platform (browser login)
-kweaver auth <url>           Login (shorthand)
-kweaver auth status [url]    Show current auth status
+        console.log(`kweaver auth login <url> [--alias <name>] [-u user] [-p pass] [--playwright]
+kweaver auth <url>           Login (shorthand; same options as login)
+kweaver auth status [url|alias]
 kweaver auth list            List saved platforms
-kweaver auth use <url>       Switch active platform
-kweaver auth logout [url]    Logout (clear local token)
-kweaver auth delete <url>    Delete saved credentials`);
+kweaver auth use <url|alias> Switch active platform
+kweaver auth logout [url|alias]   Logout (clear local token)
+kweaver auth delete <url|alias>   Delete saved credentials
+
+Login options (browser OAuth2 by default; use -u/-p for headless Playwright):
+  --alias <name>   Short name for this platform (use with auth use / status / logout)
+  -u, --username   Username (with -p triggers Playwright login)
+  -p, --password   Password
+  --playwright     Force browser (Playwright) login even without -u/-p`);
         return 0;
     }
     if (target === "login") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            console.log(`kweaver auth login <platform-url> [--alias <name>] [-u user] [-p pass] [--playwright]`);
+            return 0;
+        }
         const url = rest[0];
-        if (!url) {
-            console.error("Usage: kweaver auth login <platform-url>");
+        if (!url || url.startsWith("-")) {
+            console.error("Usage: kweaver auth login <platform-url> [--alias <name>] [-u user] [-p pass] [--playwright]");
             return 1;
         }
         return runAuthCommand([url, ...rest.slice(1)]);
@@ -182,8 +192,8 @@ kweaver auth delete <url>    Delete saved credentials`);
         console.log(`Run \`kweaver auth login ${logoutTarget}\` to sign in again.`);
         return 0;
     }
-    console.error("Usage: kweaver auth login <platform-url>");
-    console.error("       kweaver auth <platform-url> [--alias <name>]");
+    console.error("Usage: kweaver auth login <platform-url> [--alias <name>] [-u user] [-p pass] [--playwright]");
+    console.error("       kweaver auth <platform-url> [--alias <name>] [-u user] [-p pass] [--playwright]");
     console.error("       kweaver auth status [platform-url|alias]");
     console.error("       kweaver auth list");
     console.error("       kweaver auth use <platform-url|alias>");

package/dist/commands/bkn.d.ts

@@ -1,3 +1,4 @@
+import { type BknEncodingImportOptions } from "../utils/bkn-encoding.js";
 export interface KnListOptions {
     offset: number;
     limit: number;
@@ -46,6 +47,7 @@ export interface KnPushOptions {
     branch: string;
     businessDomain: string;
     pretty: boolean;
+    encodingOptions: BknEncodingImportOptions;
 }
 export declare function parseKnPushArgs(args: string[]): KnPushOptions;
 export interface KnPullOptions {
@@ -64,6 +66,14 @@ export interface KnObjectTypeQueryOptions {
 }
 export declare function parseKnObjectTypeQueryArgs(args: string[]): KnObjectTypeQueryOptions;
 export declare function runKnCommand(args: string[]): Promise<number>;
+/** Parse object-type create args: --name --dataview-id --primary-key --display-key [--property '<json>' ...] */
+export declare function parseObjectTypeCreateArgs(args: string[]): {
+    knId: string;
+    body: string;
+    businessDomain: string;
+    branch: string;
+    pretty: boolean;
+};
 /** Fields merged via GET → modify → PUT (not raw body mode). */
 export interface ObjectTypeMergeFields {
     name?: string;
@@ -110,6 +120,14 @@ export interface KnActionTypeExecuteOptions {
     timeout: number;
 }
 export declare function parseKnActionTypeExecuteArgs(args: string[]): KnActionTypeExecuteOptions;
+/** Parse relation-type create args: --name --source --target [--mapping src:tgt ...] */
+export declare function parseRelationTypeCreateArgs(args: string[]): {
+    knId: string;
+    body: string;
+    businessDomain: string;
+    branch: string;
+    pretty: boolean;
+};
 export declare function parseKnBuildArgs(args: string[]): {
     knId: string;
     wait: boolean;

package/dist/commands/bkn.js

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, validateNetwork } from "@kweaver-ai/bkn";
+import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, getObjectType, createObjectTypes, updateObjectType, deleteObjectTypes, getRelationType, createRelationTypes, updateRelationType, deleteRelationTypes, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
 import { objectTypeQuery, objectTypeProperties, subgraph, actionTypeQuery, actionTypeExecute, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "../api/ontology-query.js";
@@ -354,12 +355,13 @@ export function parseKnDeleteArgs(args) {
     return { knId, businessDomain, yes };
 }
 export function parseKnPushArgs(args) {
+    const { rest, options: encodingOptions } = stripBknEncodingCliArgs(args);
     let directory = "";
     let branch = "main";
     let businessDomain = "";
     let pretty = true;
-    for (let i = 0; i < args.length; i += 1) {
-        const arg = args[i];
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
         if (arg === "--help" || arg === "-h") {
             throw new Error("help");
         }
@@ -394,7 +396,7 @@ export function parseKnPushArgs(args) {
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { directory, branch, businessDomain, pretty };
+    return { directory, branch, businessDomain, pretty, encodingOptions };
 }
 export function parseKnPullArgs(args) {
     let knId = "";
@@ -601,8 +603,8 @@ Subcommands:
   update <kn-id> [options]  Update a knowledge network
   delete <kn-id>       Delete a knowledge network
   build <kn-id> [--wait|--no-wait] [--timeout n]   Trigger full build
-  validate <directory>   Validate a local BKN directory (no upload)
-  push <directory> [--branch main]   Upload BKN directory as tar
+  validate <directory> [--detect-encoding|--no-detect-encoding] [--source-encoding n]   Validate local BKN (no upload)
+  push <directory> [--branch main] [--detect-encoding|--no-detect-encoding] [--source-encoding n]   Upload BKN as tar
   pull <kn-id> [<directory>] [--branch main]   Download BKN tar and extract
   export <kn-id>       Export knowledge network (alias for get --export)
   stats <kn-id>        Get statistics (alias for get --stats)
@@ -692,7 +694,7 @@ export async function runKnCommand(args) {
     }
 }
 /** Parse object-type create args: --name --dataview-id --primary-key --display-key [--property '<json>' ...] */
-function parseObjectTypeCreateArgs(args) {
+export function parseObjectTypeCreateArgs(args) {
     let name = "";
     let dataviewId = "";
     let primaryKey = "";
@@ -746,6 +748,7 @@ function parseObjectTypeCreateArgs(args) {
         throw new Error("Usage: kweaver bkn object-type create <kn-id> --name X --dataview-id Y --primary-key Z --display-key W");
     }
     const entry = {
+        branch,
         name,
         data_source: { type: "data_view", id: dataviewId },
         primary_keys: [primaryKey],
@@ -762,7 +765,7 @@ function parseObjectTypeCreateArgs(args) {
             type: "string",
         }));
     }
-    const body = JSON.stringify({ entries: [entry], branch });
+    const body = JSON.stringify({ entries: [entry] });
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
     return { knId, body, businessDomain, branch, pretty };
@@ -1285,7 +1288,7 @@ kweaver bkn object-type delete <kn-id> <ot-ids> [-y]`);
     }
 }
 /** Parse relation-type create args: --name --source --target [--mapping src:tgt ...] */
-function parseRelationTypeCreateArgs(args) {
+export function parseRelationTypeCreateArgs(args) {
     let name = "";
     let source = "";
     let target = "";
@@ -1339,6 +1342,7 @@ function parseRelationTypeCreateArgs(args) {
         throw new Error("Usage: kweaver bkn relation-type create <kn-id> --name X --source <ot-id> --target <ot-id> [--mapping src:tgt ...]");
     }
     const entry = {
+        branch,
         name,
         source_object_type_id: source,
         target_object_type_id: target,
@@ -1348,7 +1352,7 @@ function parseRelationTypeCreateArgs(args) {
             target_property: { name: t },
         })),
     };
-    const body = JSON.stringify({ entries: [entry], branch });
+    const body = JSON.stringify({ entries: [entry] });
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
     return { knId, body, businessDomain, branch, pretty };
@@ -2194,6 +2198,7 @@ async function runKnCreateFromDsCommand(args) {
             const pk = detectPrimaryKey(t);
             const dk = detectDisplayKey(t, pk);
             const entry = {
+                branch: "main",
                 name: t.name,
                 data_source: { type: "data_view", id: viewMap[t.name] },
                 primary_keys: [pk],
@@ -2204,7 +2209,7 @@ async function runKnCreateFromDsCommand(args) {
                     type: "string",
                 })),
             };
-            const otBody = JSON.stringify({ entries: [entry], branch: "main" });
+            const otBody = JSON.stringify({ entries: [entry] });
             const otResponse = await createObjectTypes({
                 ...base,
                 knId,
@@ -2443,8 +2448,13 @@ export function packDirectoryToTar(dirPath) {
         encoding: "buffer",
         env: { ...process.env, COPYFILE_DISABLE: "1" },
     });
-    if (result.error)
+    if (result.error) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            throw new Error("tar executable not found. On Windows, ensure tar.exe is in PATH " +
+                "(ships with Windows 10 1803+) or install GNU tar via Git for Windows / scoop.");
+        }
         throw result.error;
+    }
     if (result.status !== 0) {
         throw new Error(`tar pack failed: ${result.stderr?.toString() ?? result.status}`);
     }
@@ -2457,6 +2467,10 @@ export function extractTarToDirectory(tarBuffer, dirPath) {
         input: tarBuffer,
     });
     if (result.error) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            throw new Error("tar executable not found. On Windows, ensure tar.exe is in PATH " +
+                "(ships with Windows 10 1803+) or install GNU tar via Git for Windows / scoop.");
+        }
         throw result.error;
     }
     if (result.status !== 0) {
@@ -2470,7 +2484,10 @@ Pack a BKN directory into a tar and upload to import as a knowledge network.
 Options:
   --branch <s>       Branch name (default: main)
   -bd, --biz-domain  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON output`;
+  --pretty           Pretty-print JSON output
+  --detect-encoding  Detect .bkn encoding and normalize to UTF-8 (default: on)
+  --no-detect-encoding  Do not detect; require UTF-8 .bkn files
+  --source-encoding <name>  Decode all .bkn files with this encoding (e.g. gb18030); overrides detection`;
 const KN_PULL_HELP = `kweaver bkn pull <kn-id> [<directory>] [options]
 
 Download a BKN tar from a knowledge network and extract to a local directory.
@@ -2481,12 +2498,28 @@ Options:
   -bd, --biz-domain  Business domain (default: bd_public)`;
 async function runKnValidateCommand(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("Usage: kweaver bkn validate <directory>\n\nValidate a local BKN directory without uploading.");
+        console.log("Usage: kweaver bkn validate <directory> [options]\n\n" +
+            "Validate a local BKN directory without uploading.\n\n" +
+            "Options:\n" +
+            "  --detect-encoding       Detect .bkn encoding and normalize to UTF-8 (default: on)\n" +
+            "  --no-detect-encoding    Require UTF-8 .bkn files\n" +
+            "  --source-encoding <n>   Decode all .bkn with this encoding (e.g. gb18030)");
         return 0;
     }
-    const directory = args.find((a) => !a.startsWith("-"));
+    let encodingOptions;
+    let restArgs;
+    try {
+        const stripped = stripBknEncodingCliArgs(args);
+        encodingOptions = stripped.options;
+        restArgs = stripped.rest;
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const directory = restArgs.find((a) => !a.startsWith("-"));
     if (!directory) {
-        console.error("Missing directory. Usage: kweaver bkn validate <directory>");
+        console.error("Missing directory. Usage: kweaver bkn validate <directory> [options]");
         return 1;
     }
     const absDir = resolve(directory);
@@ -2504,8 +2537,9 @@ async function runKnValidateCommand(args) {
         }
         throw err;
     }
+    const prepared = prepareBknDirectoryForImport(absDir, encodingOptions);
     try {
-        const network = await loadNetwork(absDir);
+        const network = await loadNetwork(prepared.dir);
         const result = validateNetwork(network);
         if (!result.ok) {
             for (const e of result.errors)
@@ -2523,6 +2557,9 @@ async function runKnValidateCommand(args) {
         console.error(`BKN validation failed: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }
+    finally {
+        prepared.cleanup();
+    }
 }
 async function runKnPushCommand(args) {
     let options;
@@ -2552,41 +2589,48 @@ async function runKnPushCommand(args) {
         }
         throw err;
     }
+    const prepared = prepareBknDirectoryForImport(absDir, options.encodingOptions);
+    const workDir = prepared.dir;
     try {
-        const network = await loadNetwork(absDir);
-        const objs = allObjects(network);
-        const rels = allRelations(network);
-        const acts = allActions(network);
-        console.error(`Validated: ${objs.length} object types, ${rels.length} relation types, ${acts.length} action types`);
-    }
-    catch (error) {
-        console.error(`BKN validation failed: ${error instanceof Error ? error.message : String(error)}`);
-        return 1;
-    }
-    try {
-        await generateChecksum(absDir);
-        console.error("Checksum generated");
-    }
-    catch (error) {
-        console.error(`Checksum generation failed: ${error instanceof Error ? error.message : String(error)}`);
-        return 1;
-    }
-    try {
-        const tarBuffer = packDirectoryToTar(absDir);
-        const token = await ensureValidToken();
-        const body = await uploadBkn({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            tarBuffer,
-            businessDomain: options.businessDomain,
-            branch: options.branch,
-        });
-        console.log(formatCallOutput(body, options.pretty));
-        return 0;
+        try {
+            const network = await loadNetwork(workDir);
+            const objs = allObjects(network);
+            const rels = allRelations(network);
+            const acts = allActions(network);
+            console.error(`Validated: ${objs.length} object types, ${rels.length} relation types, ${acts.length} action types`);
+        }
+        catch (error) {
+            console.error(`BKN validation failed: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+        try {
+            await generateChecksum(workDir);
+            console.error("Checksum generated");
+        }
+        catch (error) {
+            console.error(`Checksum generation failed: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+        try {
+            const tarBuffer = packDirectoryToTar(workDir);
+            const token = await ensureValidToken();
+            const body = await uploadBkn({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                tarBuffer,
+                businessDomain: options.businessDomain,
+                branch: options.branch,
+            });
+            console.log(formatCallOutput(body, options.pretty));
+            return 0;
+        }
+        catch (error) {
+            console.error(formatHttpError(error));
+            return 1;
+        }
     }
-    catch (error) {
-        console.error(formatHttpError(error));
-        return 1;
+    finally {
+        prepared.cleanup();
     }
 }
 async function runKnPullCommand(args) {

package/dist/config/store.js

@@ -24,9 +24,10 @@ function getLegacyTokenFilePath() {
 function getLegacyCallbackFilePath() {
     return join(getConfigDirPath(), "callback.json");
 }
+const IS_WIN32 = process.platform === "win32";
 function ensureDir(path) {
     if (!existsSync(path)) {
-        mkdirSync(path, { recursive: true, mode: 0o700 });
+        mkdirSync(path, { recursive: true, ...(IS_WIN32 ? {} : { mode: 0o700 }) });
     }
 }
 function ensureConfigDir() {
@@ -41,8 +42,9 @@ function readJsonFile(filePath) {
 }
 function writeJsonFile(filePath, value) {
     ensureConfigDir();
-    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    chmodSync(filePath, 0o600);
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, IS_WIN32 ? {} : { mode: 0o600 });
+    if (!IS_WIN32)
+        chmodSync(filePath, 0o600);
 }
 function encodePlatformKey(baseUrl) {
     return Buffer.from(baseUrl, "utf8")

package/dist/utils/bkn-encoding.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Normalize .bkn file bytes to UTF-8 for BKN import (validate / push).
+ * Used when --detect-encoding (default) or --source-encoding is active.
+ */
+/** Minimum confidence (0–1) for charset detection before failing. */
+export declare const BKN_DETECT_MIN_CONFIDENCE = 0.65;
+export interface BknEncodingImportOptions {
+    /** When true (default), detect encoding for non-UTF-8 .bkn files. */
+    detectEncoding: boolean;
+    /** When set, decode all .bkn files with this encoding (overrides detection). */
+    sourceEncoding: string | null;
+}
+/**
+ * Parse --no-detect-encoding, --detect-encoding, --source-encoding <name> from argv.
+ * Remaining args are returned for positional parsing (directory, etc.).
+ */
+export declare function stripBknEncodingCliArgs(args: string[]): {
+    rest: string[];
+    options: BknEncodingImportOptions;
+};
+/**
+ * Decode raw .bkn bytes to a UTF-8 Buffer (no BOM).
+ */
+export declare function normalizeBknFileBytes(raw: Buffer, options: BknEncodingImportOptions, fileLabel: string): Buffer;
+/**
+ * When normalization is needed, copy the tree to a temp dir with .bkn files normalized to UTF-8.
+ * Returns the directory to pass to loadNetwork and a cleanup function.
+ */
+export declare function prepareBknDirectoryForImport(absDir: string, options: BknEncodingImportOptions): {
+    dir: string;
+    cleanup: () => void;
+};

package/dist/utils/bkn-encoding.js

@@ -0,0 +1,152 @@
+/**
+ * Normalize .bkn file bytes to UTF-8 for BKN import (validate / push).
+ * Used when --detect-encoding (default) or --source-encoding is active.
+ */
+import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import chardet from "chardet";
+import iconv from "iconv-lite";
+/** Minimum confidence (0–1) for charset detection before failing. */
+export const BKN_DETECT_MIN_CONFIDENCE = 0.65;
+/**
+ * Parse --no-detect-encoding, --detect-encoding, --source-encoding <name> from argv.
+ * Remaining args are returned for positional parsing (directory, etc.).
+ */
+export function stripBknEncodingCliArgs(args) {
+    let detectEncoding = true;
+    let sourceEncoding = null;
+    const rest = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--no-detect-encoding") {
+            detectEncoding = false;
+            continue;
+        }
+        if (arg === "--detect-encoding") {
+            detectEncoding = true;
+            continue;
+        }
+        if (arg === "--source-encoding") {
+            const v = args[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("Missing value for --source-encoding (e.g. gb18030)");
+            }
+            sourceEncoding = v;
+            i += 1;
+            continue;
+        }
+        rest.push(arg);
+    }
+    return {
+        rest,
+        options: { detectEncoding, sourceEncoding },
+    };
+}
+function isValidUtf8(buf) {
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(buf);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function stripUtf8Bom(buf) {
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+        return buf.subarray(3);
+    }
+    return buf;
+}
+/**
+ * Decode raw .bkn bytes to a UTF-8 Buffer (no BOM).
+ */
+export function normalizeBknFileBytes(raw, options, fileLabel) {
+    if (options.sourceEncoding) {
+        const enc = options.sourceEncoding.trim().toLowerCase();
+        if (enc === "utf-8" || enc === "utf8") {
+            const body = stripUtf8Bom(raw);
+            if (!isValidUtf8(body)) {
+                throw new Error(`Invalid UTF-8 in ${fileLabel} despite --source-encoding utf-8`);
+            }
+            return Buffer.from(body.toString("utf8"), "utf8");
+        }
+        if (!iconv.encodingExists(enc)) {
+            throw new Error(`Unsupported --source-encoding: ${options.sourceEncoding}`);
+        }
+        const text = iconv.decode(raw, enc);
+        return Buffer.from(text, "utf8");
+    }
+    if (!options.detectEncoding) {
+        const body = stripUtf8Bom(raw);
+        if (!isValidUtf8(body)) {
+            throw new Error(`Invalid UTF-8 in ${fileLabel}. Use --detect-encoding (default) or --source-encoding (e.g. gb18030).`);
+        }
+        return Buffer.from(body.toString("utf8"), "utf8");
+    }
+    let work = stripUtf8Bom(raw);
+    if (isValidUtf8(work)) {
+        return Buffer.from(work.toString("utf8"), "utf8");
+    }
+    const matches = chardet.analyse(work);
+    const best = matches[0];
+    if (!best || best.confidence < BKN_DETECT_MIN_CONFIDENCE) {
+        throw new Error(`Could not detect encoding confidently for ${fileLabel} (best confidence ${best?.confidence ?? 0}). ` +
+            `Try --source-encoding gb18030 or save files as UTF-8.`);
+    }
+    const name = best.name ?? "utf-8";
+    if (!iconv.encodingExists(name)) {
+        throw new Error(`Detected encoding "${name}" is not supported for ${fileLabel}. Try --source-encoding.`);
+    }
+    const text = iconv.decode(work, name);
+    return Buffer.from(text, "utf8");
+}
+/**
+ * When normalization is needed, copy the tree to a temp dir with .bkn files normalized to UTF-8.
+ * Returns the directory to pass to loadNetwork and a cleanup function.
+ */
+export function prepareBknDirectoryForImport(absDir, options) {
+    const needWork = options.sourceEncoding != null || options.detectEncoding;
+    if (!needWork) {
+        return { dir: absDir, cleanup: () => { } };
+    }
+    const root = resolve(absDir);
+    const tmpRoot = mkdtempSync(join(tmpdir(), "kweaver-bkn-"));
+    function walk(srcDir, destDir) {
+        mkdirSync(destDir, { recursive: true });
+        const entries = readdirSync(srcDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === "." || entry.name === "..")
+                continue;
+            const srcPath = join(srcDir, entry.name);
+            const destPath = join(destDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(srcPath, destPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (entry.name.endsWith(".bkn")) {
+                const raw = readFileSync(srcPath);
+                const rel = relative(root, srcPath) || entry.name;
+                const out = normalizeBknFileBytes(raw, options, rel);
+                writeFileSync(destPath, out);
+            }
+            else {
+                copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+    walk(root, tmpRoot);
+    return {
+        dir: tmpRoot,
+        cleanup: () => {
+            try {
+                rmSync(tmpRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+}

package/dist/utils/browser.js

@@ -1,20 +1,23 @@
 import { spawn } from "node:child_process";
 export function openBrowser(url) {
-    const command = process.platform === "darwin"
-        ? "open"
-        : process.platform === "win32"
-            ? "cmd"
-            : "xdg-open";
-    const args = process.platform === "win32"
-        ? ["/c", "start", "", url]
+    const isWindows = process.platform === "win32";
+    const command = process.platform === "darwin" ? "open" : isWindows ? "rundll32.exe" : "xdg-open";
+    const args = isWindows
+        ? [
+            "url.dll,FileProtocolHandler",
+            url,
+        ]
         : [url];
     return new Promise((resolve) => {
         const child = spawn(command, args, {
-            detached: true,
             stdio: "ignore",
+            detached: !isWindows,
+            windowsHide: true,
         });
-        child.on("error", () => resolve(false));
-        child.unref();
-        resolve(true);
+        child.once("error", () => resolve(false));
+        child.once("spawn", () => resolve(true));
+        if (!isWindows) {
+            child.unref();
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,6 +29,7 @@
     "lint": "tsc --noEmit -p tsconfig.json",
     "test": "node --import tsx --test test/*.test.ts",
     "test:e2e": "node --import tsx test/e2e/ensure-token.ts && node --import tsx --test --test-concurrency=1 test/e2e/**/*.test.ts",
+    "test:e2e:strict": "node test/e2e/run-e2e-strict.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -50,6 +51,7 @@
   "devDependencies": {
     "@types/node": "^24.6.0",
     "@types/react": "^19.2.14",
+    "playwright": "^1.58.2",
     "tsx": "^4.20.5",
     "typescript": "^5.9.3"
   },
@@ -63,6 +65,9 @@
   },
   "dependencies": {
     "@kweaver-ai/bkn": "^0.1.0",
+    "@playwright/test": "^1.58.2",
+    "chardet": "^2.1.1",
+    "iconv-lite": "^0.7.2",
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",