@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.2

package/dist/commands/bkn-ops.js

@@ -4,14 +4,36 @@ 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 } from "../auth/oauth.js";
-import { createKnowledgeNetwork, createObjectTypes, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
+import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
 import { listTablesWithColumns, scanMetadata, getDatasource } from "../api/datasources.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
+import { resolveFiles } from "./ds.js";
+import { buildTableName } from "./import-csv.js";
 import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createActionSchedule, updateActionSchedule, setActionScheduleStatus, deleteActionSchedules, listJobs, getJob, getJobTasks, deleteJobs, } from "../api/bkn-backend.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
 import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, confirmYes, } from "./bkn-utils.js";
+// ── BKN object name validation ──────────────────────────────────────────────
+// Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
+// validateObjectName (driveradapters/validate.go:85). 40 utf-8 codepoints,
+// non-empty. Backend rejects the whole batch on first violation, so we surface
+// every offender locally before any side-effecting call.
+export const BKN_OBJECT_NAME_MAX_LENGTH = 40;
+export function assertValidBknObjectNames(names, context) {
+    const offenders = [];
+    for (const name of names) {
+        const len = [...name].length;
+        if (len === 0 || len > BKN_OBJECT_NAME_MAX_LENGTH) {
+            offenders.push({ name, length: len });
+        }
+    }
+    if (offenders.length === 0)
+        return;
+    const lines = offenders.map((o) => `  - ${o.name} (${o.length} chars)`);
+    throw new Error(`${context}: ${offenders.length} name(s) violate BKN object-name limit ` +
+        `(1..${BKN_OBJECT_NAME_MAX_LENGTH} utf-8 chars):\n${lines.join("\n")}`);
+}
 // ── Build ───────────────────────────────────────────────────────────────────
 const KN_BUILD_HELP = `kweaver bkn build <kn-id> [options]
 
@@ -461,6 +483,7 @@ Options:
   --build (default)  Build after creation
   --no-build       Skip build after creation
   --timeout <n>    Build timeout in seconds (default: 300)
+  --no-rollback    Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain  Business domain (default: bd_public)
   --pretty         Pretty-print output (default)`;
 export function parseKnCreateFromDsArgs(args) {
@@ -471,6 +494,7 @@ export function parseKnCreateFromDsArgs(args) {
     let timeout = 300;
     let businessDomain = "";
     let pretty = true;
+    let noRollback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -491,6 +515,10 @@ export function parseKnCreateFromDsArgs(args) {
             build = false;
             continue;
         }
+        if (arg === "--no-rollback") {
+            noRollback = true;
+            continue;
+        }
         if (arg === "--timeout" && args[i + 1]) {
             timeout = parseInt(args[++i], 10);
             if (Number.isNaN(timeout) || timeout < 1)
@@ -515,7 +543,7 @@ export function parseKnCreateFromDsArgs(args) {
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, name, tables, build, timeout, businessDomain, pretty };
+    return { dsId, name, tables, build, timeout, businessDomain, pretty, noRollback };
 }
 /** Sanitize a table name into a BKN-safe ID (alphanumeric + underscore). */
 function sanitizeBknId(name) {
@@ -576,7 +604,12 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             console.error("No tables available");
             return 1;
         }
-        // Phase 1: Create DataViews for each table
+        // Pre-flight: catch every offending OT name before any side effect.
+        // Backend rejects the whole batch on first violation (validate.go:90),
+        // so retroactive rollback is wasted work if we can fail fast here.
+        assertValidBknObjectNames(targetTables.map((t) => t.name), "Object type names derived from table names");
+        // Phase 1: Create DataViews for each table. findDataView is idempotent;
+        // not tracked for rollback so a retry can reuse what's already there.
         console.error(`Creating data views for ${targetTables.length} table(s) ...`);
         const viewMap = {};
         for (const t of targetTables) {
@@ -597,7 +630,8 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
                 }));
             viewMap[t.name] = dvId;
         }
-        // Phase 2: Create the KN record
+        // Phase 2: Create the KN. If any subsequent step fails we DELETE this
+        // KN — backend cascades to OTs (knowledge_network_service.go:917-969).
         const knBody = JSON.stringify({
             name: options.name,
             branch: "main",
@@ -611,72 +645,91 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         const knItem = Array.isArray(knParsed) ? knParsed[0] : knParsed;
         const knId = String(knItem?.id ?? "");
         console.error(`Knowledge network created: ${knId}`);
-        // Phase 3: Create object types via REST API
-        console.error(`Creating ${targetTables.length} object type(s) ...`);
+        let createdKnId = knId;
         const otResults = [];
-        for (const t of targetTables) {
-            const pk = detectPrimaryKey(t, sampleRows?.[t.name]);
-            const dk = detectDisplayKey(t, pk);
-            const uniqueProps = [pk, dk].filter((x, i, a) => a.indexOf(x) === i);
-            const entry = {
-                branch: "main",
-                name: t.name,
-                data_source: { type: "data_view", id: viewMap[t.name] },
-                primary_keys: [pk],
-                display_key: dk,
-                data_properties: t.columns.map((c) => ({
-                    name: c.name,
-                    display_name: c.name,
-                    type: "string",
-                    mapped_field: { name: c.name, type: c.type || "varchar" },
-                })),
-            };
-            const otBody = JSON.stringify({ entries: [entry] });
+        let statusStr = "skipped";
+        try {
+            // Phase 3: Single batched POST. Backend wraps all entries in one tx
+            // (object_type_service.go:213-355) — all-or-nothing.
+            console.error(`Creating ${targetTables.length} object type(s) ...`);
+            const entries = targetTables.map((t) => {
+                const pk = detectPrimaryKey(t, sampleRows?.[t.name]);
+                const dk = detectDisplayKey(t, pk);
+                return {
+                    branch: "main",
+                    name: t.name,
+                    data_source: { type: "data_view", id: viewMap[t.name] },
+                    primary_keys: [pk],
+                    display_key: dk,
+                    data_properties: t.columns.map((c) => ({
+                        name: c.name,
+                        display_name: c.name,
+                        type: "string",
+                        mapped_field: { name: c.name, type: c.type || "varchar" },
+                    })),
+                    _meta: { pk, dk },
+                };
+            });
+            const wireEntries = entries.map(({ _meta: _, ...rest }) => rest);
+            const otBody = JSON.stringify({ entries: wireEntries });
             const otResponse = await createObjectTypes({
                 ...base,
                 knId,
                 body: otBody,
             });
             const otParsed = JSON.parse(otResponse);
-            const otItem = otParsed.entries?.[0];
-            otResults.push({
-                name: t.name,
-                id: otItem?.id ?? "",
-                field_count: t.columns.length,
-            });
-            console.error(`  Created: ${t.name} (${t.columns.length} fields, pk=${pk}, dk=${dk})`);
-        }
-        if (otResults.length === 0) {
-            const errorOutput = {
-                kn_id: knId,
-                kn_name: options.name,
-                error: "No object types were created",
-            };
-            console.log(JSON.stringify(errorOutput, null, options.pretty ? 2 : 0));
-            return 1;
-        }
-        let statusStr = "skipped";
-        if (options.build) {
-            console.error("Building ...");
-            await buildKnowledgeNetwork({ ...base, knId });
-            const TERMINAL = ["completed", "failed", "success"];
-            try {
-                statusStr = await pollWithBackoff({
-                    fn: async () => {
-                        const statusBody = await getBuildStatus({ ...base, knId });
-                        const statusParsed = JSON.parse(statusBody);
-                        const jobs = Array.isArray(statusParsed) ? statusParsed : (statusParsed.entries ?? []);
-                        const state = (jobs[0]?.state ?? "running").toLowerCase();
-                        if (TERMINAL.includes(state))
-                            return { done: true, value: state };
-                        return { done: false, value: "running" };
-                    },
-                    interval: 2000,
-                    timeout: options.timeout * 1000,
+            const otItems = Array.isArray(otParsed) ? otParsed : (otParsed.entries ?? []);
+            for (let i = 0; i < entries.length; i += 1) {
+                const t = targetTables[i];
+                const meta = entries[i]._meta;
+                otResults.push({
+                    name: t.name,
+                    id: otItems[i]?.id ?? "",
+                    field_count: t.columns.length,
                 });
+                console.error(`  Created: ${t.name} (${t.columns.length} fields, pk=${meta.pk}, dk=${meta.dk})`);
             }
-            catch {
-                // timeout — statusStr remains "skipped"
+            if (options.build) {
+                console.error("Building ...");
+                await buildKnowledgeNetwork({ ...base, knId });
+                const TERMINAL = ["completed", "failed", "success"];
+                try {
+                    statusStr = await pollWithBackoff({
+                        fn: async () => {
+                            const statusBody = await getBuildStatus({ ...base, knId });
+                            const statusParsed = JSON.parse(statusBody);
+                            const jobs = Array.isArray(statusParsed) ? statusParsed : (statusParsed.entries ?? []);
+                            const state = (jobs[0]?.state ?? "running").toLowerCase();
+                            if (TERMINAL.includes(state))
+                                return { done: true, value: state };
+                            return { done: false, value: "running" };
+                        },
+                        interval: 2000,
+                        timeout: options.timeout * 1000,
+                    });
+                }
+                catch {
+                    // build timeout — KN itself is fine, just mark skipped
+                }
+            }
+            // Reached the end without throwing — clear the rollback handle.
+            createdKnId = undefined;
+        }
+        finally {
+            if (createdKnId !== undefined) {
+                if (options.noRollback) {
+                    console.error(`Leaving partial KN ${createdKnId} in place (--no-rollback)`);
+                }
+                else {
+                    console.error(`Rolling back KN ${createdKnId} ...`);
+                    try {
+                        await deleteKnowledgeNetwork({ ...base, knId: createdKnId });
+                        console.error(`Rolled back KN ${createdKnId}`);
+                    }
+                    catch (rollbackErr) {
+                        console.error(`Rollback failed for KN ${createdKnId}: ${formatHttpError(rollbackErr)}`);
+                    }
+                }
             }
         }
         const output = {
@@ -708,6 +761,7 @@ Options:
   --no-build           Skip build
   --recreate           Use "insert" mode on first batch (only effective for new tables)
   --timeout <n>        Build timeout in seconds (default: 300)
+  --no-rollback        Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain    Business domain (default: bd_public)`;
 export function parseKnCreateFromCsvArgs(args) {
     let dsId = "";
@@ -720,6 +774,7 @@ export function parseKnCreateFromCsvArgs(args) {
     let recreate = false;
     let timeout = 300;
     let businessDomain = "";
+    let noRollback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -758,6 +813,10 @@ export function parseKnCreateFromCsvArgs(args) {
             recreate = true;
             continue;
         }
+        if (arg === "--no-rollback") {
+            noRollback = true;
+            continue;
+        }
         if (arg === "--timeout" && args[i + 1]) {
             timeout = parseInt(args[++i], 10);
             if (Number.isNaN(timeout) || timeout < 1)
@@ -778,7 +837,7 @@ export function parseKnCreateFromCsvArgs(args) {
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain };
+    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain, noRollback };
 }
 export async function runKnCreateFromCsvCommand(args) {
     let options;
@@ -793,6 +852,20 @@ export async function runKnCreateFromCsvCommand(args) {
         console.error(formatHttpError(error));
         return 1;
     }
+    // Pre-flight: predict OT names from (table-prefix + csv basename) and
+    // reject before any CSV is imported. CSV import is expensive; failing
+    // here saves the user a multi-minute round trip.
+    try {
+        const filePaths = await resolveFiles(options.files);
+        const predictedNames = options.tables.length > 0
+            ? options.tables
+            : filePaths.map((p) => buildTableName(p, options.tablePrefix));
+        assertValidBknObjectNames(predictedNames, "Object type names derived from CSV file names");
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
     // Phase 1: Import CSVs
     console.error("Phase 1: Importing CSVs ...");
     const importArgs = [
@@ -844,6 +917,7 @@ export async function runKnCreateFromCsvCommand(args) {
         options.build ? "--build" : "--no-build",
         "--timeout", String(options.timeout),
         "-bd", options.businessDomain,
+        ...(options.noRollback ? ["--no-rollback"] : []),
     ];
     return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);
 }

package/dist/commands/config.js

@@ -2,6 +2,7 @@ import { listBusinessDomains } from "../api/business-domains.js";
 import { fetchEacpUserInfo, resolveActivePlatform, withTokenRetry } from "../auth/oauth.js";
 import { HttpError } from "../utils/http.js";
 import { loadPlatformBusinessDomain, resolveBusinessDomain, savePlatformBusinessDomain, } from "../config/store.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
 const HELP = `kweaver config
 
 Subcommands:
@@ -50,6 +51,13 @@ export async function runConfigCommand(args) {
             return 1;
         }
         const platform = active.url;
+        try {
+            assertNotStatelessForWrite("config set-bd");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         savePlatformBusinessDomain(platform, value);
         const provenance = active.source === "env" ? `${platform} via KWEAVER_BASE_URL` : platform;
         console.log(`Business domain set to: ${value} (${provenance})`);

package/dist/commands/context-loader.js

@@ -2,12 +2,28 @@ import { ensureValidToken, formatHttpError, resolveActivePlatform, with401Refres
 import { callTool, searchSchema, queryObjectInstance, queryInstanceSubgraph, getLogicPropertiesValues, getActionInfo, findSkills, listTools, listResources, readResource, listResourceTemplates, listPrompts, getPrompt, } from "../api/context-loader.js";
 import { knSearchHttp, semanticSearch } from "../api/semantic-search.js";
 import { addContextLoaderEntry, getCurrentContextLoaderKn, loadContextLoaderConfig, removeContextLoaderEntry, resolveBusinessDomain, setCurrentContextLoader, } from "../config/store.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
+const CONTEXT_LOADER_CONFIG_DEPRECATION = "[deprecated] `kweaver context-loader config ...` will be removed in a future release. " +
+    "Pass <kn-id> as the first positional to runtime subcommands instead, e.g. " +
+    "`kweaver context-loader tools <kn-id>` (or use the `--kn-id <id>` flag).";
 const MCP_NOT_CONFIGURED = "Context-loader MCP is not configured. Run: kweaver context-loader config set --kn-id <kn-id>";
-function ensureContextLoaderConfig() {
+const MCP_PATH = "/api/agent-retrieval/v1/mcp";
+function ensureContextLoaderConfig(knIdOverride) {
     const active = resolveActivePlatform();
     if (!active) {
         throw new Error("No platform selected. Set KWEAVER_BASE_URL or run: kweaver auth <platform-url>");
     }
+    // Override path (positional <kn-id> or --kn-id flag): derive MCP URL from
+    // the active platform; do not touch the deprecated saved config.
+    if (knIdOverride) {
+        return {
+            baseUrl: active.url,
+            mcpUrl: active.url.replace(/\/+$/, "") + MCP_PATH,
+            knId: knIdOverride,
+            accessToken: "",
+            businessDomain: resolveBusinessDomain(active.url),
+        };
+    }
     const kn = getCurrentContextLoaderKn();
     if (!kn) {
         throw new Error(MCP_NOT_CONFIGURED);
@@ -20,6 +36,50 @@ function ensureContextLoaderConfig() {
         businessDomain: resolveBusinessDomain(active.url),
     };
 }
+// Subcommands that consult `ensureContextLoaderConfig`. The number is the
+// minimum non-flag positional count expected by the handler itself (after
+// kn-id is extracted). When the leading non-flag positional count exceeds
+// this minimum, the first one is treated as <kn-id>.
+const RUNTIME_MIN_POSITIONALS = {
+    tools: 0,
+    resources: 0,
+    templates: 0,
+    prompts: 0,
+    prompt: 1,
+    resource: 1,
+    "search-schema": 1,
+    "tool-call": 1,
+    "kn-search": 1,
+    "kn-schema-search": 1,
+    "query-object-instance": 1,
+    "query-instance-subgraph": 1,
+    "get-logic-properties": 1,
+    "get-action-info": 1,
+    "find-skills": 1,
+};
+function extractKnIdOverride(subcommand, rest) {
+    // 1) Explicit flag wins. `--kn-id <id>` / `-k <id>` is allowed for every
+    //    runtime subcommand and is consumed before the handler sees `rest`.
+    for (let i = 0; i < rest.length; i += 1) {
+        if ((rest[i] === "--kn-id" || rest[i] === "-k") && rest[i + 1]) {
+            const id = rest[i + 1];
+            rest.splice(i, 2);
+            return id;
+        }
+    }
+    // 2) Positional <kn-id> as the first non-flag arg, when leading non-flag
+    //    positional count exceeds what the handler itself requires.
+    const min = RUNTIME_MIN_POSITIONALS[subcommand];
+    if (min === undefined)
+        return undefined;
+    let cut = 0;
+    while (cut < rest.length && !rest[cut].startsWith("-"))
+        cut += 1;
+    if (cut > min) {
+        return rest.shift();
+    }
+    return undefined;
+}
 function formatOutput(value, pretty) {
     const json = JSON.stringify(value, null, pretty ? 2 : 0);
     return json;
@@ -29,34 +89,38 @@ export async function runContextLoaderCommand(args) {
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
         console.log(`kweaver context-loader
 
+KN selection (for runtime subcommands below):
+  Pass <kn-id> as the FIRST positional, e.g. \`kweaver context-loader tools <kn-id>\`,
+  or use the global \`--kn-id <id>\` / \`-k <id>\` flag. When omitted, falls back to
+  the deprecated saved config managed by \`kweaver context-loader config\`.
+
 Subcommands:
-  config set --kn-id <id> [--name n]   Add or update kn config (MCP URL derived from platform)
-  config use <name>                    Switch current config
-  config list                         List all configs and current
-  config remove <name>                 Remove a config
-  config show                         Show current config (knId + mcpUrl)
-  tools                               tools/list - list available tools
-  resources                           resources/list - list resources
-  resource <uri>                      resources/read - read resource by URI
-  templates                           resources/templates/list - list resource templates
-  prompts                             prompts/list - list prompts
-  prompt <name> [--args json]          prompts/get - get prompt by name
-  search-schema <query> [options]      MCP search_schema (object/relation/action/metric types)
-  tool-call <name> --args '<json>'     MCP tools/call for any server tool
-  kn-search <query> [--only-schema]    Compatibility: HTTP kn_search
-  kn-schema-search <query> [--max N]   Compatibility: HTTP semantic-search
-  query-object-instance <json>         Layer 2: Query instances (args as JSON)
-  query-instance-subgraph <json>       Layer 2: Query subgraph (args as JSON)
-  get-logic-properties <json>          Layer 3: Get logic property values (args as JSON)
-  get-action-info <json>               Layer 3: Get action info (args as JSON)
-  find-skills <ot_id> [options]        Layer 3: Recall skills for an object type
+  config set --kn-id <id> [--name n]   [deprecated] Add or update kn config
+  config use <name>                    [deprecated] Switch current config
+  config list                          [deprecated] List all configs and current
+  config remove <name>                 [deprecated] Remove a config
+  config show                          [deprecated] Show current config (knId + mcpUrl)
+  tools <kn-id>                        tools/list - list available tools
+  resources <kn-id>                    resources/list - list resources
+  resource <kn-id> <uri>               resources/read - read resource by URI
+  templates <kn-id>                    resources/templates/list - list resource templates
+  prompts <kn-id>                      prompts/list - list prompts
+  prompt <kn-id> <name> [--args json]  prompts/get - get prompt by name
+  search-schema <kn-id> <query> [opts] MCP search_schema (object/relation/action/metric)
+  tool-call <kn-id> <name> --args '<json>'  MCP tools/call for any server tool
+  kn-search <kn-id> <query> [--only-schema]  Compatibility: HTTP kn_search
+  kn-schema-search <kn-id> <query> [--max N] Compatibility: HTTP semantic-search
+  query-object-instance <kn-id> <json>       Layer 2: Query instances
+  query-instance-subgraph <kn-id> <json>     Layer 2: Query subgraph
+  get-logic-properties <kn-id> <json>        Layer 3: Get logic property values
+  get-action-info <kn-id> <json>             Layer 3: Get action info
+  find-skills <kn-id> <ot_id> [options]      Layer 3: Recall skills for an object type
 
 Examples:
-  kweaver context-loader config set --kn-id d5iv6c9818p72mpje8pg
-  kweaver context-loader config set --kn-id xyz123 --name project-a
-  kweaver context-loader search-schema "利润率" --scope object,metric --max 5
-  kweaver context-loader tool-call search_schema --args '{"query":"利润率"}'
-  kweaver context-loader kn-search "高血压 治疗 药品" --only-schema --pretty`);
+  kweaver context-loader tools d5iv6c9818p72mpje8pg
+  kweaver context-loader search-schema d5iv6c9818p72mpje8pg "利润率" --scope object,metric --max 5
+  kweaver context-loader tool-call d5iv6c9818p72mpje8pg search_schema --args '{"query":"利润率"}'
+  kweaver context-loader kn-search d5iv6c9818p72mpje8pg "高血压 治疗 药品" --only-schema --pretty`);
         return 0;
     }
     if (subcommand === "config") {
@@ -68,9 +132,12 @@ Examples:
         pretty = true;
         rest.splice(prettyIdx, 1);
     }
+    // Extract `<kn-id>` (positional or --kn-id/-k flag) before per-subcommand
+    // arg parsing. When provided it bypasses the deprecated saved config.
+    const knIdOverride = extractKnIdOverride(subcommand, rest);
     const dispatch = async () => {
         const token = await ensureValidToken();
-        const base = ensureContextLoaderConfig();
+        const base = ensureContextLoaderConfig(knIdOverride);
         const options = { ...base, accessToken: token.accessToken };
         if (subcommand === "tools")
             return runListTools(options, rest, pretty);
@@ -122,16 +189,30 @@ Examples:
 async function runConfigCommand(args) {
     const [action, ...rest] = args;
     if (!action || action === "--help" || action === "-h") {
-        console.log(`kweaver context-loader config
+        console.log(`kweaver context-loader config  [deprecated]
 
 Subcommands:
   set --kn-id <id> [--name <name>]   Add or update kn config (default name: default)
   use <name>                         Switch current config
   list                               List all configs and current
   remove <name>                      Remove a config
-  show                               Show current config (knId + mcpUrl)`);
+  show                               Show current config (knId + mcpUrl)
+
+Note: this command group is deprecated and will be removed in a future release.
+      It is disabled entirely in stateless mode (\`--token\`).`);
         return 0;
     }
+    // Stateless mode (`--token`) does not support any context-loader config
+    // operations; the saved config lives under `~/.kweaver/` and is foreign
+    // to the stateless paradigm.
+    try {
+        assertNotStatelessForWrite(`context-loader config ${action}`);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    console.warn(CONTEXT_LOADER_CONFIG_DEPRECATION);
     const active = resolveActivePlatform();
     if (!active) {
         console.error("No platform selected. Set KWEAVER_BASE_URL or run: kweaver auth <platform-url>");
@@ -435,29 +516,24 @@ async function runToolCall(options, args, pretty) {
 async function runKnSearch(options, args, pretty) {
     let query;
     let onlySchema = false;
-    let knIdOverride;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--only-schema") {
             onlySchema = true;
         }
-        else if ((arg === "--kn-id" || arg === "-k") && args[i + 1]) {
-            knIdOverride = args[i + 1];
-            i += 1;
-        }
         else if (!arg.startsWith("-") && !query) {
             query = arg;
         }
     }
     if (!query) {
-        console.error("Usage: kweaver context-loader kn-search <query> [--kn-id <id>] [--only-schema]");
+        console.error("Usage: kweaver context-loader kn-search <kn-id> <query> [--only-schema]");
         return 1;
     }
     const raw = await knSearchHttp({
         baseUrl: options.baseUrl,
         accessToken: options.accessToken,
         businessDomain: options.businessDomain,
-        knId: knIdOverride ?? options.knId,
+        knId: options.knId,
         query,
         onlySchema,
     });

package/dist/commands/ds.d.ts

@@ -5,6 +5,29 @@ export declare function parseDsListArgs(args: string[]): {
     businessDomain: string;
     pretty: boolean;
 };
+/**
+ * Match candidate signature against a list response (the kind returned by
+ * `listDatasources`). Connection metadata lives under `bin_data` — host,
+ * port, account, plus type-specific fields (`database_name` for MySQL etc.).
+ *
+ * Exported for unit testing.
+ */
+export interface DsMatchSignature {
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    account: string;
+    name?: string;
+}
+export interface DsMatchHit {
+    id: string;
+    name: string;
+    matchedByName: boolean;
+    matchedByTuple: boolean;
+}
+export declare function findExistingDatasource(listBody: string, sig: DsMatchSignature): DsMatchHit | undefined;
+export declare function findDatasourceIdByName(listBody: string, name: string): string | undefined;
 export declare function parseImportCsvArgs(args: string[]): {
     datasourceId: string;
     files: string;