@kweaver-ai/kweaver-sdk 0.6.10 → 0.7.2

package/dist/commands/context-loader.js

@@ -1,22 +1,85 @@
 import { ensureValidToken, formatHttpError, resolveActivePlatform, with401RefreshRetry } from "../auth/oauth.js";
-import { knSearch, knSchemaSearch, queryObjectInstance, queryInstanceSubgraph, getLogicPropertiesValues, getActionInfo, listTools, listResources, readResource, listResourceTemplates, listPrompts, getPrompt, } from "../api/context-loader.js";
-import { addContextLoaderEntry, getCurrentContextLoaderKn, loadContextLoaderConfig, removeContextLoaderEntry, setCurrentContextLoader, } from "../config/store.js";
+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);
     }
     return {
+        baseUrl: active.url,
         mcpUrl: kn.mcpUrl,
         knId: kn.knId,
         accessToken: "", // filled by caller after ensureValidToken
+        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;
@@ -26,29 +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
-  kn-search <query> [--only-schema]    Layer 1: Search schema (object_types, relation_types, action_types)
-  kn-schema-search <query> [--max N]   Layer 1: Discover candidate concepts
-  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)
+  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 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") {
@@ -60,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);
@@ -76,6 +151,10 @@ Examples:
             return runListPrompts(options, rest, pretty);
         if (subcommand === "prompt")
             return runGetPrompt(options, rest, pretty);
+        if (subcommand === "search-schema")
+            return runSearchSchema(options, rest, pretty);
+        if (subcommand === "tool-call")
+            return runToolCall(options, rest, pretty);
         if (subcommand === "kn-search")
             return runKnSearch(options, rest, pretty);
         if (subcommand === "kn-schema-search")
@@ -88,6 +167,8 @@ Examples:
             return runGetLogicProperties(options, rest, pretty);
         if (subcommand === "get-action-info")
             return runGetActionInfo(options, rest, pretty);
+        if (subcommand === "find-skills")
+            return runFindSkills(options, rest, pretty);
         return -1;
     };
     try {
@@ -108,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>");
@@ -279,29 +374,170 @@ async function runGetPrompt(options, args, pretty) {
     console.log(formatOutput(result, pretty));
     return 0;
 }
+function parseResponseText(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function parseSearchSchemaScope(raw) {
+    const scope = {
+        include_object_types: false,
+        include_relation_types: false,
+        include_action_types: false,
+        include_metric_types: false,
+    };
+    const aliases = {
+        object: "include_object_types",
+        objects: "include_object_types",
+        object_type: "include_object_types",
+        object_types: "include_object_types",
+        relation: "include_relation_types",
+        relations: "include_relation_types",
+        relation_type: "include_relation_types",
+        relation_types: "include_relation_types",
+        action: "include_action_types",
+        actions: "include_action_types",
+        action_type: "include_action_types",
+        action_types: "include_action_types",
+        metric: "include_metric_types",
+        metrics: "include_metric_types",
+        metric_type: "include_metric_types",
+        metric_types: "include_metric_types",
+    };
+    for (const item of raw.split(",")) {
+        const key = item.trim().toLowerCase();
+        if (!key)
+            continue;
+        const field = aliases[key];
+        if (!field) {
+            throw new Error(`Invalid --scope value: ${item}`);
+        }
+        scope[field] = true;
+    }
+    return scope;
+}
+async function runSearchSchema(options, args, pretty) {
+    let query;
+    let responseFormat;
+    let searchScope;
+    let maxConcepts;
+    let schemaBrief;
+    let enableRerank;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if ((arg === "--format" || arg === "-f") && args[i + 1]) {
+            const value = args[i + 1];
+            if (value !== "json" && value !== "toon") {
+                console.error("Usage: kweaver context-loader search-schema <query> [--format json|toon] [--scope object,relation,action,metric] [--max N] [--brief] [--no-rerank]");
+                return 1;
+            }
+            responseFormat = value;
+            i += 1;
+        }
+        else if ((arg === "--scope" || arg === "-s") && args[i + 1]) {
+            try {
+                searchScope = parseSearchSchemaScope(args[i + 1]);
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+            i += 1;
+        }
+        else if ((arg === "--max" || arg === "-n") && args[i + 1]) {
+            maxConcepts = parseInt(args[i + 1], 10);
+            if (!Number.isFinite(maxConcepts)) {
+                console.error("Usage: kweaver context-loader search-schema <query> [--max N]");
+                return 1;
+            }
+            i += 1;
+        }
+        else if (arg === "--brief") {
+            schemaBrief = true;
+        }
+        else if (arg === "--no-rerank") {
+            enableRerank = false;
+        }
+        else if (!arg.startsWith("-") && !query) {
+            query = arg;
+        }
+    }
+    if (!query) {
+        console.error("Usage: kweaver context-loader search-schema <query> [--format json|toon] [--scope object,relation,action,metric] [--max N] [--brief] [--no-rerank]");
+        return 1;
+    }
+    const result = await searchSchema(options, {
+        query,
+        response_format: responseFormat,
+        search_scope: searchScope,
+        max_concepts: maxConcepts,
+        schema_brief: schemaBrief,
+        enable_rerank: enableRerank,
+    });
+    console.log(formatOutput(result, pretty));
+    return 0;
+}
+async function runToolCall(options, args, pretty) {
+    let toolName;
+    let rawArgs;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if ((arg === "--args" || arg === "-a") && args[i + 1]) {
+            rawArgs = args[i + 1];
+            i += 1;
+        }
+        else if (!arg.startsWith("-") && !toolName) {
+            toolName = arg;
+        }
+    }
+    if (!toolName || rawArgs === undefined) {
+        console.error("Usage: kweaver context-loader tool-call <name> --args '<json>'");
+        return 1;
+    }
+    let parsedArgs;
+    try {
+        parsedArgs = JSON.parse(rawArgs);
+    }
+    catch {
+        console.error("Invalid --args JSON");
+        return 1;
+    }
+    if (parsedArgs === null || typeof parsedArgs !== "object" || Array.isArray(parsedArgs)) {
+        console.error("--args must be a JSON object");
+        return 1;
+    }
+    const result = await callTool(options, toolName, parsedArgs);
+    console.log(formatOutput(result, pretty));
+    return 0;
+}
 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 effectiveOptions = knIdOverride ? { ...options, knId: knIdOverride } : options;
-    const result = await knSearch(effectiveOptions, { query, only_schema: onlySchema });
+    const raw = await knSearchHttp({
+        baseUrl: options.baseUrl,
+        accessToken: options.accessToken,
+        businessDomain: options.businessDomain,
+        knId: options.knId,
+        query,
+        onlySchema,
+    });
+    const result = parseResponseText(raw);
     console.log(formatOutput(result, pretty));
     return 0;
 }
@@ -322,10 +558,15 @@ async function runKnSchemaSearch(options, args, pretty) {
         console.error("Usage: kweaver context-loader kn-schema-search <query> [--max N]");
         return 1;
     }
-    const result = await knSchemaSearch(options, {
+    const raw = await semanticSearch({
+        baseUrl: options.baseUrl,
+        accessToken: options.accessToken,
+        businessDomain: options.businessDomain,
+        knId: options.knId,
         query,
-        max_concepts: maxConcepts,
+        maxConcepts,
     });
+    const result = parseResponseText(raw);
     console.log(formatOutput(result, pretty));
     return 0;
 }
@@ -385,3 +626,66 @@ async function runGetActionInfo(options, args, pretty) {
     console.log(formatOutput(result, pretty));
     return 0;
 }
+async function runFindSkills(options, args, pretty) {
+    const usage = "Usage: kweaver context-loader find-skills <object_type_id> " +
+        "[--query <text>] [--top-k N] [--instance-identities <json>] [--format json|toon]";
+    let objectTypeId;
+    let skillQuery;
+    let topK;
+    let instanceIdentities;
+    let responseFormat;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if ((arg === "--query" || arg === "-q") && args[i + 1]) {
+            skillQuery = args[i + 1];
+            i += 1;
+        }
+        else if ((arg === "--top-k" || arg === "-n") && args[i + 1]) {
+            topK = parseInt(args[i + 1], 10);
+            if (!Number.isFinite(topK)) {
+                console.error(usage);
+                return 1;
+            }
+            i += 1;
+        }
+        else if ((arg === "--instance-identities" || arg === "-i") && args[i + 1]) {
+            try {
+                const parsed = JSON.parse(args[i + 1]);
+                if (!Array.isArray(parsed)) {
+                    throw new Error("--instance-identities must be a JSON array");
+                }
+                instanceIdentities = parsed;
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+            i += 1;
+        }
+        else if ((arg === "--format" || arg === "-f") && args[i + 1]) {
+            const value = args[i + 1];
+            if (value !== "json" && value !== "toon") {
+                console.error(usage);
+                return 1;
+            }
+            responseFormat = value;
+            i += 1;
+        }
+        else if (!arg.startsWith("-") && !objectTypeId) {
+            objectTypeId = arg;
+        }
+    }
+    if (!objectTypeId) {
+        console.error(usage);
+        return 1;
+    }
+    const result = await findSkills(options, {
+        object_type_id: objectTypeId,
+        skill_query: skillQuery,
+        top_k: topK,
+        instance_identities: instanceIdentities,
+        response_format: responseFormat,
+    });
+    console.log(formatOutput(result, pretty));
+    return 0;
+}

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;