@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/cli.js

@@ -9,14 +9,93 @@ import { runContextLoaderCommand } from "./commands/context-loader.js";
 import { runDataflowCommand } from "./commands/dataflow.js";
 import { runDsCommand } from "./commands/ds.js";
 import { runExploreCommand } from "./commands/explore.js";
-import { runDataviewCommand } from "./commands/dataview.js";
+import { runResourceCommand } from "./commands/resource.js";
 import { runModelCommand } from "./commands/model.js";
 import { runSkillCommand } from "./commands/skill.js";
 import { runTokenCommand } from "./commands/token.js";
 import { runToolboxCommand } from "./commands/toolbox.js";
 import { runToolCommand } from "./commands/tool.js";
 import { runVegaCommand } from "./commands/vega.js";
+import { renderHelp } from "./help/format.js";
 function printHelp() {
+    console.log(renderHelp({
+        tagline: "KWeaver SDK — operate KWeaver platform from CLI",
+        usage: [
+            "kweaver [global flags] <command> <subcommand> [flags]",
+            "kweaver --version | -V",
+            "kweaver --help | -h",
+        ],
+        sections: [
+            {
+                title: "AUTHENTICATION & CONFIG",
+                items: [
+                    { name: "auth", desc: "Login / switch / list saved platform credentials" },
+                    { name: "token", desc: "Print current access token (auto-refresh)" },
+                    { name: "config", desc: "Per-platform business-domain config" },
+                ],
+            },
+            {
+                title: "DECISION AGENT",
+                items: [
+                    { name: "agent", desc: "Agent CRUD, chat, sessions, publish" },
+                    { name: "toolbox", desc: "Agent toolbox lifecycle" },
+                    { name: "tool", desc: "Tools inside toolbox" },
+                ],
+            },
+            {
+                title: "AI DATA PLATFORM",
+                items: [
+                    { name: "bkn", desc: "Knowledge network — build, query, action, metric" },
+                    { name: "ds", desc: "Datasource (list, get, connect, tables)" },
+                    { name: "resource (res)", desc: "Resources — list, find, get, query, delete" },
+                    { name: "dataflow", desc: "Dataflow document workflows (run, runs, logs)" },
+                    { name: "vega", desc: "Vega observability — catalog, resource, query" },
+                    { name: "context-loader (context)", desc: "MCP/HTTP context loader (reads BKN schema/instances)" },
+                ],
+            },
+            {
+                title: "TRACE AI",
+                items: [
+                    { name: "trace", desc: "Diagnose conversations / build eval-sets / schema validate" },
+                ],
+            },
+            {
+                title: "FOUNDATION",
+                items: [
+                    { name: "call (curl)", desc: "curl-style API call with auto-injected auth headers" },
+                    { name: "explore", desc: "Interactive web UI" },
+                    { name: "model", desc: "Model factory — LLM / small-model CRUD + chat" },
+                    { name: "skill", desc: "Skill registry / market" },
+                    { name: "help", desc: "Show help — use `help all` for full signatures" },
+                ],
+            },
+        ],
+        flags: [
+            { name: "--base-url <url>", desc: "Override platform URL  (env: KWEAVER_BASE_URL)" },
+            { name: "--token <value>", desc: "Override access token  (env: KWEAVER_TOKEN; disables write commands)" },
+            { name: "--user <id|name>", desc: "Use specific user credentials (env: KWEAVER_USER)" },
+            { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+            { name: "--compact", desc: "Compact JSON output (pipeline-friendly)" },
+            { name: "--help, -h", desc: "Show help" },
+            { name: "--version, -V", desc: "Show version" },
+        ],
+        environment: [
+            { name: "KWEAVER_PROFILE", desc: "Isolate active-platform/user state per shell" },
+            { name: "KWEAVERC_CONFIG_DIR", desc: "Override config root (~/.kweaver)" },
+        ],
+        examples: [
+            "kweaver auth https://platform.example.com",
+            "kweaver agent chat <agent_id> -m \"hello\"",
+            "kweaver bkn build <kn-id> --wait",
+        ],
+        learnMore: [
+            "Use `kweaver <command> --help` for command-specific help",
+            "Use `kweaver help all` for full command signatures (migration fallback)",
+            "For agents/multi-terminal: prefer `--user <id>` over `auth switch`",
+        ],
+    }));
+}
+function printHelpFull() {
     console.log(`kweaver
 
 Usage:
@@ -76,11 +155,11 @@ Usage:
   kweaver model small list|get|add|edit|delete|test|embeddings|rerank|--template ...
   kweaver model --help
 
-  kweaver dataview list [--datasource-id id] [--type atomic|custom] [--limit n] [-bd value]
-  kweaver dataview find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
-  kweaver dataview get <id> [-bd value]
-  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [--raw-sql] [-bd value]
-  kweaver dataview delete <id> [-y] [-bd value]
+  kweaver resource list [--datasource-id id] [--type table|logicview] [--limit n] [-bd value]
+  kweaver resource find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
+  kweaver resource get <id> [-bd value]
+  kweaver resource query <id> [--limit n] [--offset n] [--need-total] [-bd value]
+  kweaver resource delete <id> [-y] [-bd value]
 
   kweaver bkn list [options]
   kweaver bkn get <kn-id> [options]
@@ -108,8 +187,9 @@ Usage:
   kweaver config list-bd
   kweaver config show
 
-  kweaver skill list|get|register|status|delete [options]
+  kweaver skill list|get|market-get|register|status|delete [options]
   kweaver skill market [options]
+  kweaver skill update-metadata|update-package|history|republish|publish-history [options]
   kweaver skill content <skill-id> [--raw] [--output file]
   kweaver skill read-file <skill-id> <rel-path> [--raw] [--output file]
   kweaver skill download|install <skill-id> [path] [options]
@@ -134,14 +214,15 @@ Usage:
   kweaver vega query execute|sql [options]
   kweaver vega connector-type list|get [options]
 
+  kweaver context-loader help <subcommand>
   kweaver context-loader config set|use|list|remove|show [options]                (deprecated; not supported with --token)
   kweaver context-loader tools|resources|templates|prompts <kn-id> [--cursor]
   kweaver context-loader resource <kn-id> <uri>
   kweaver context-loader prompt <kn-id> <name> [--args json]
-  kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--max N]
+  kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--concept-groups ids] [--max N]
   kweaver context-loader tool-call <kn-id> <name> --args '<json>'
-  kweaver context-loader kn-search <kn-id> <query> [--only-schema]                 (compat HTTP)
-  kweaver context-loader kn-schema-search <kn-id> <query> [--max N]                (compat HTTP)
+  kweaver context-loader kn-search <kn-id> <query> [--only-schema]                 (deprecated; use search-schema)
+  kweaver context-loader kn-schema-search <kn-id> <query> [--max N]                (deprecated; use search-schema)
   kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
                                                           (omit <kn-id> to fall back to deprecated saved config)
   (alias: kweaver context ...)
@@ -174,11 +255,11 @@ Commands:
   ds             Manage datasources (list, get, delete, tables, connect)
   dataflow       Dataflow document workflows (list, run, runs, logs)
   model          Model factory: LLM/small-model CRUD (manager) and llm chat (OpenAI-compatible API)
-  dataview|dv    List, find, get, query (SQL), delete data views (atomic / custom)
+  resource|res   List, find, get, query, delete vega-backend resources (table / logicview)
   bkn            Knowledge network (CRUD, build, validate, export, stats, push/pull,
                  object-type, relation-type, subgraph, action-type, action-execution, action-log)
   config         Per-platform configuration (business domain)
-  skill          Skill registry and market (register, search, progressive read, download/install)
+  skill          Skill registry and market (register, edit, history, progressive read, download/install)
   toolbox        Agent toolbox lifecycle (create, list, publish, delete, export, import)
   tool           Tools inside a toolbox (upload OpenAPI spec, list, enable/disable)
   vega           Vega observability (catalog, resource, query/sql, connector-type, health/stats/inspect)
@@ -236,10 +317,23 @@ export async function run(argv) {
         console.log(pkg.version);
         return 0;
     }
-    if (argv.length === 0 || !command || command === "--help" || command === "-h" || command === "help") {
+    if (argv.length === 0 || !command || command === "--help" || command === "-h") {
         printHelp();
         return 0;
     }
+    if (command === "help") {
+        const topic = rest[0];
+        if (!topic) {
+            printHelp();
+            return 0;
+        }
+        if (topic === "all") {
+            printHelpFull();
+            return 0;
+        }
+        // `help <command>` → forward to `<command> --help`
+        return run([...rest, "--help"]);
+    }
     if (command === "auth") {
         return runAuthCommand(rest);
     }
@@ -255,8 +349,8 @@ export async function run(argv) {
     if (command === "model") {
         return runModelCommand(rest);
     }
-    if (command === "dataview" || command === "dv") {
-        return runDataviewCommand(rest);
+    if (command === "resource" || command === "res") {
+        return runResourceCommand(rest);
     }
     if (command === "token") {
         return runTokenCommand(rest);

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import { ConversationsResource } from "./resources/conversations.js";
 import { ContextLoaderResource } from "./resources/context-loader.js";
 import { DataflowsResource } from "./resources/dataflows.js";
 import { DataSourcesResource } from "./resources/datasources.js";
-import { DataViewsResource } from "./resources/dataviews.js";
+import { ResourcesResource } from "./resources/resources.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
@@ -98,8 +98,8 @@ export declare class KWeaverClient implements ClientContext {
     readonly dataflows: DataflowsResource;
     /** Data source management (connect, test, list tables). */
     readonly datasources: DataSourcesResource;
-    /** Data view creation and retrieval. */
-    readonly dataviews: DataViewsResource;
+    /** Vega-backend resource management (table/logicview resources under a catalog). */
+    readonly resources: ResourcesResource;
     /** Vega observability platform (catalogs, resources, connector types). */
     readonly vega: VegaResource;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */

package/dist/client.js

@@ -8,7 +8,7 @@ import { ConversationsResource } from "./resources/conversations.js";
 import { ContextLoaderResource } from "./resources/context-loader.js";
 import { DataflowsResource } from "./resources/dataflows.js";
 import { DataSourcesResource } from "./resources/datasources.js";
-import { DataViewsResource } from "./resources/dataviews.js";
+import { ResourcesResource } from "./resources/resources.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
@@ -60,8 +60,8 @@ export class KWeaverClient {
     dataflows;
     /** Data source management (connect, test, list tables). */
     datasources;
-    /** Data view creation and retrieval. */
-    dataviews;
+    /** Vega-backend resource management (table/logicview resources under a catalog). */
+    resources;
     /** Vega observability platform (catalogs, resources, connector types). */
     vega;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */
@@ -100,7 +100,7 @@ export class KWeaverClient {
             this.conversations = new ConversationsResource(this);
             this.dataflows = new DataflowsResource(this);
             this.datasources = new DataSourcesResource(this);
-            this.dataviews = new DataViewsResource(this);
+            this.resources = new ResourcesResource(this);
             this.vega = new VegaResource(this);
             this.skills = new SkillsResource(this);
             this.toolboxes = new ToolboxesResource(this);
@@ -156,7 +156,7 @@ export class KWeaverClient {
         this.conversations = new ConversationsResource(this);
         this.dataflows = new DataflowsResource(this);
         this.datasources = new DataSourcesResource(this);
-        this.dataviews = new DataViewsResource(this);
+        this.resources = new ResourcesResource(this);
         this.vega = new VegaResource(this);
         this.skills = new SkillsResource(this);
         this.toolboxes = new ToolboxesResource(this);

package/dist/commands/agent/mode.d.ts

@@ -0,0 +1,6 @@
+export declare const AGENT_MODES: readonly ["default", "dolphin", "react"];
+export type AgentMode = typeof AGENT_MODES[number];
+export declare const AGENT_MODE_HELP = "  --mode <mode>          Agent mode: default, dolphin, react (default: default)\n\nAgent mode config:\n  config.mode accepts \"default\", \"dolphin\", or \"react\".\n  If --mode is provided, it overrides config.mode.\n  If neither --mode nor config.mode is provided, the CLI sends config.mode=\"default\".\n\nReAct config:\n  react_config is only valid when mode is \"react\".\n  Provide it through --config or --config-path, for example:\n    {\n      \"mode\": \"react\",\n      \"react_config\": {\n        \"disable_history_in_a_conversation\": false,\n        \"disable_llm_cache\": false\n      }\n    }";
+export declare function parseAgentMode(value: string, flagName?: string): AgentMode;
+export declare function normalizeAgentConfigInput(value: unknown): Record<string, unknown>;
+export declare function applyAgentModeToConfig(config: Record<string, unknown>, explicitMode?: AgentMode): void;

package/dist/commands/agent/mode.js

@@ -0,0 +1,75 @@
+export const AGENT_MODES = ["default", "dolphin", "react"];
+const AGENT_MODE_SET = new Set(AGENT_MODES);
+export const AGENT_MODE_HELP = `  --mode <mode>          Agent mode: default, dolphin, react (default: default)
+
+Agent mode config:
+  config.mode accepts "default", "dolphin", or "react".
+  If --mode is provided, it overrides config.mode.
+  If neither --mode nor config.mode is provided, the CLI sends config.mode="default".
+
+ReAct config:
+  react_config is only valid when mode is "react".
+  Provide it through --config or --config-path, for example:
+    {
+      "mode": "react",
+      "react_config": {
+        "disable_history_in_a_conversation": false,
+        "disable_llm_cache": false
+      }
+    }`;
+function formatModeValue(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function looksLikeAgentConfig(value) {
+    return [
+        "mode",
+        "input",
+        "output",
+        "llms",
+        "react_config",
+        "system_prompt",
+        "data_source",
+        "skills",
+        "memory",
+        "conversation_history_config",
+    ].some((field) => field in value);
+}
+export function parseAgentMode(value, flagName = "--mode") {
+    const mode = value.trim();
+    if (!AGENT_MODE_SET.has(mode)) {
+        throw new Error(`${flagName} must be one of: ${AGENT_MODES.join(", ")}`);
+    }
+    return mode;
+}
+export function normalizeAgentConfigInput(value) {
+    if (!isRecord(value)) {
+        throw new Error("Agent config file must contain a JSON object.");
+    }
+    const nestedConfig = value.config;
+    if (isRecord(nestedConfig) && !looksLikeAgentConfig(value)) {
+        return nestedConfig;
+    }
+    return value;
+}
+export function applyAgentModeToConfig(config, explicitMode) {
+    if (explicitMode) {
+        config.mode = explicitMode;
+        return;
+    }
+    const currentMode = config.mode;
+    if (currentMode === undefined || currentMode === null || currentMode === "") {
+        config.mode = "default";
+        return;
+    }
+    if (typeof currentMode !== "string") {
+        throw new Error(`config.mode must be one of: ${AGENT_MODES.join(", ")}; got ${formatModeValue(currentMode)}`);
+    }
+    const mode = currentMode.trim();
+    if (!AGENT_MODE_SET.has(mode)) {
+        throw new Error(`config.mode must be one of: ${AGENT_MODES.join(", ")}; got ${formatModeValue(currentMode)}`);
+    }
+    config.mode = mode;
+}

package/dist/commands/agent-members.js

@@ -6,6 +6,7 @@ import { getAgent, updateAgent } from "../api/agent-list.js";
 import { getSkill } from "../api/skills.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { renderHelp } from "../help/format.js";
 /** Deep-clone a JSON-serializable object so mutations don't leak to callers. */
 function clone(value) {
     return JSON.parse(JSON.stringify(value));
@@ -353,17 +354,32 @@ async function runSkillList(args) {
 export async function runAgentSkillCommand(args) {
     const [verb, ...rest] = args;
     if (!verb || verb === "--help" || verb === "-h") {
-        console.log(`kweaver agent skill
-
-Subcommands:
-  add <agent-id> <skill-id>... [--strict] [-bd <bd>]      Attach skills to an agent
-  remove <agent-id> <skill-id>... [-bd <bd>]              Detach skills from an agent
-  list <agent-id> [--pretty|--compact] [-bd <bd>]         List skills attached to an agent
-
-Notes:
-  --strict         On add, reject skills that exist but are not in 'published' status.
-                   Default behaviour: warn and continue.
-  Dedupe is automatic for add; remove silently skips not-attached ids.`);
+        console.log(renderHelp({
+            tagline: "Manage skills attached to an agent",
+            usage: "kweaver agent skill <subcommand> [flags]",
+            sections: [{
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "add", desc: "Attach skills to an agent" },
+                        { name: "remove", desc: "Detach skills from an agent" },
+                        { name: "list", desc: "List skills attached to an agent" },
+                    ],
+                }],
+            flags: [
+                { name: "--strict", desc: "On add, reject skills that exist but are not in 'published' status. Default behaviour: warn and continue." },
+                { name: "-bd <bd>", desc: "Business domain" },
+                { name: "--pretty|--compact", desc: "Output formatting for list" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver agent skill add <agent-id> <skill-id>... [--strict] [-bd <bd>]",
+                "kweaver agent skill remove <agent-id> <skill-id>... [-bd <bd>]",
+                "kweaver agent skill list <agent-id> [--pretty|--compact] [-bd <bd>]",
+            ],
+            learnMore: [
+                "Dedupe is automatic for add; remove silently skips not-attached ids.",
+            ],
+        }));
         return 0;
     }
     try {