@kweaver-ai/kweaver-sdk 0.6.1 → 0.6.3

package/README.md

@@ -126,9 +126,18 @@ const result = await client.dataflows.execute({
   steps: [{ id: "s1", title: "load", operator: "csv_import", parameters: {} }],
 });
 
-// Vega observability
+// Vega — observability and query
 const catalogs = await client.vega.listCatalogs();
 const health   = await client.vega.health();
+// Structured query — POST /api/vega-backend/v1/query/execute (JSON string body)
+const structured = await client.vega.executeQuery(
+  JSON.stringify({ tables: [{ resource_id: "res-1" }], output_fields: ["*"], limit: 20 }),
+);
+// Direct SQL or OpenSearch DSL — POST /api/vega-backend/v1/resources/query
+// Use {{resource_id}} placeholders so vega-backend routes to the correct catalog connector.
+const rows = await client.vega.sqlQuery(
+  JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
+);
 
 // Context Loader (semantic search over a BKN via MCP)
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
@@ -164,7 +173,7 @@ kweaver bkn action-execution get
 kweaver bkn action-log list/get/cancel
 kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
-kweaver vega health/stats/inspect/catalog/resource/connector-type
+kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
 kweaver context-loader config set/use/list/show
 kweaver context-loader kn-search/query-object-instance/...
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
@@ -184,6 +193,20 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` filters one local natural day. If the value cannot be parsed by `new Date(...)`, the CLI falls back to the most recent 20 runs. `kweaver dataflow logs` defaults to summary output; add `--detail` to print indented `input` and `output` payloads.
 
+### Vega `sql` CLI examples
+
+Direct SQL against catalog-backed resources (`POST /api/vega-backend/v1/resources/query`). In SQL, use **`{{<resource_id>}}`** or **`{{.<resource_id>}}`** (Vega resource id from `vega resource list` / `get`) so the backend resolves the physical table and connector. `--resource-type` accepts the connector type of the target data source (run `kweaver vega connector-type list` to see available types). In simple mode, **quote the entire `--query` value** so the shell does not treat `{` / `}` specially.
+
+```bash
+# Simple mode (recommended): avoid JSON-escaping the query string
+kweaver vega sql --resource-type mysql --query "SELECT * FROM {{res-1}} LIMIT 5"
+
+# Advanced mode: full JSON body (optional fields like query_timeout, stream_size, OpenSearch DSL object)
+kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} LIMIT 5"}'
+```
+
+If both `-d` and `--query` / `--resource-type` are present, **only `-d` is used**.
+
 **No-auth platforms:** If OAuth is not enabled, use `kweaver auth <url> --no-auth` (or run a normal `auth login`; a **404** on `POST /oauth2/clients` switches to no-auth automatically). Credentials are still saved under `~/.kweaver/` and work with `auth use` / `auth list`. Optional: `KWEAVER_NO_AUTH=1` with `KWEAVER_BASE_URL` when no token env is set. SDK: `new KWeaverClient({ baseUrl, auth: false })` or `kweaver.configure({ baseUrl, auth: false })`.
 
 ## Environment Variables

package/README.zh.md

@@ -119,6 +119,19 @@ const queryRows = await client.dataviews.query(viewId, {
   needTotal: true,
 });
 
+// Vega — 可观测性与查询
+const catalogs = await client.vega.listCatalogs();
+const health   = await client.vega.health();
+// 结构化查询 — POST /api/vega-backend/v1/query/execute（body 为 JSON 字符串）
+const structured = await client.vega.executeQuery(
+  JSON.stringify({ tables: [{ resource_id: "res-1" }], output_fields: ["*"], limit: 20 }),
+);
+// 直连 SQL 或 OpenSearch DSL — POST /api/vega-backend/v1/resources/query
+// 使用 {{resource_id}} 占位符以路由到正确的 catalog connector
+const rows = await client.vega.sqlQuery(
+  JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
+);
+
 // Context Loader（通过 MCP 对 BKN 做语义搜索）
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
 const results = await cl.search({ query: "高血压 治疗" });
@@ -149,6 +162,7 @@ kweaver bkn action-execution get
 kweaver bkn action-log list/get/cancel
 kweaver agent list/get/chat/sessions/history
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
+kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
 kweaver context-loader config set/use/list/show
 kweaver context-loader kn-search/query-object-instance/...
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
@@ -168,6 +182,20 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` 会按本地自然日过滤；如果参数无法被 `new Date(...)` 解析，CLI 会回退到最近 20 条运行记录。`kweaver dataflow logs` 默认输出摘要；加上 `--detail` 会打印带缩进的 `input` 和 `output` 载荷。
 
+### Vega `sql` CLI 示例
+
+对 Catalog 资源执行直连 SQL（`POST /api/vega-backend/v1/resources/query`）。SQL 中使用 **`{{<resource_id>}}`** 或 **`{{.<resource_id>}}`**（资源 id 来自 `vega resource list` / `get`），后端据此解析物理表与 connector。`--resource-type` 为目标数据源的连接器类型，可通过 `kweaver vega connector-type list` 查看。简单模式下请**用引号包住整个 `--query` 参数**，避免 shell 对花括号做特殊处理。
+
+```bash
+# 简单模式（推荐）：避免在 JSON 里转义整段 SQL
+kweaver vega sql --resource-type mysql --query "SELECT * FROM {{res-1}} LIMIT 5"
+
+# 高级模式：完整 JSON（可带 query_timeout、stream_size，或 OpenSearch DSL 对象等）
+kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} LIMIT 5"}'
+```
+
+若同时提供 `-d` 与 `--query` / `--resource-type`，**仅以 `-d` 为准**。
+
 **无 OAuth 的平台：** 使用 `kweaver auth <url> --no-auth`，或照常 `auth login`；若 `POST /oauth2/clients` 返回 **404**，CLI 会提示并自动保存为 no-auth。凭据仍在 `~/.kweaver/`，可用 `auth use` / `auth list` 切换。可选环境变量 `KWEAVER_NO_AUTH=1`（未设置 `KWEAVER_TOKEN` 时）配合 `KWEAVER_BASE_URL`。SDK：`new KWeaverClient({ baseUrl, auth: false })` 或 `kweaver.configure({ baseUrl, auth: false })`。
 
 ## 环境变量

package/dist/api/skills.d.ts

@@ -1,7 +1,7 @@
 export type SkillStatus = "unpublish" | "published" | "offline";
 export type SkillFileType = "zip" | "content";
 export interface SkillSummary {
-    skill_id: string;
+    id: string;
     name: string;
     description?: string;
     version?: string;
@@ -26,20 +26,20 @@ export interface SkillFileSummary {
     mime_type?: string;
 }
 export interface SkillContentIndex {
-    skill_id: string;
+    id: string;
     url: string;
     files: SkillFileSummary[];
     status?: SkillStatus;
 }
 export interface SkillFileReadResult {
-    skill_id: string;
+    id: string;
     rel_path: string;
     url: string;
     mime_type?: string;
     file_type?: string;
 }
 export interface RegisterSkillResult {
-    skill_id: string;
+    id: string;
     name: string;
     description?: string;
     version?: string;
@@ -47,11 +47,11 @@ export interface RegisterSkillResult {
     files?: string[];
 }
 export interface DeleteSkillResult {
-    skill_id: string;
+    id: string;
     deleted: boolean;
 }
 export interface UpdateSkillStatusResult {
-    skill_id: string;
+    id: string;
     status: SkillStatus;
 }
 export interface SkillListResult {

package/dist/api/skills.js

@@ -18,6 +18,20 @@ function unwrapEnvelope(raw) {
     }
     return parsed;
 }
+/** Rename `skill_id` → `id` for consistent output with other modules. */
+function normalizeSkillId(obj) {
+    if (!obj || typeof obj !== "object")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(normalizeSkillId);
+    const record = obj;
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        const newKey = key === "skill_id" ? "id" : key;
+        out[newKey] = typeof value === "object" ? normalizeSkillId(value) : value;
+    }
+    return out;
+}
 function appendCommonListParams(url, opts) {
     if (opts.page !== undefined)
         url.searchParams.set("page", String(opts.page));
@@ -60,23 +74,23 @@ export async function listSkills(options) {
     if (options.createUser)
         url.searchParams.set("create_user", options.createUser);
     const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function listSkillMarket(options) {
     const url = new URL(buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/market`));
     appendCommonListParams(url, options);
     const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function getSkill(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}`);
     const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function deleteSkill(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}`);
     const { body } = await fetchTextOrThrow(url, { method: "DELETE", headers: baseHeaders(options) });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function updateSkillStatus(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/status`);
@@ -85,7 +99,7 @@ export async function updateSkillStatus(options) {
         headers: { ...baseHeaders(options), "content-type": "application/json" },
         body: JSON.stringify({ status: options.status }),
     });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function registerSkillContent(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills`);
@@ -102,7 +116,7 @@ export async function registerSkillContent(options) {
         headers: { ...baseHeaders(options), "content-type": "application/json" },
         body: JSON.stringify(payload),
     });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function registerSkillZip(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills`);
@@ -118,12 +132,12 @@ export async function registerSkillZip(options) {
         headers: baseHeaders(options),
         body: form,
     });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function getSkillContentIndex(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/content`);
     const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function fetchSkillContent(options) {
     const index = await getSkillContentIndex(options);
@@ -137,7 +151,7 @@ export async function readSkillFile(options) {
         headers: { ...baseHeaders(options), "content-type": "application/json" },
         body: JSON.stringify({ rel_path: options.relPath }),
     });
-    return unwrapEnvelope(body);
+    return normalizeSkillId(unwrapEnvelope(body));
 }
 export async function fetchSkillFile(options) {
     const file = await readSkillFile(options);

package/dist/api/vega.d.ts

@@ -220,6 +220,14 @@ export interface ExecuteVegaQueryOptions {
     businessDomain?: string;
 }
 export declare function executeVegaQuery(options: ExecuteVegaQueryOptions): Promise<string>;
+export interface VegaSQLQueryOptions {
+    baseUrl: string;
+    accessToken: string;
+    body: string;
+    businessDomain?: string;
+}
+/** POST /api/vega-backend/v1/resources/query — direct SQL (or OpenSearch DSL) against catalog-backed resources. */
+export declare function vegaSQLQuery(options: VegaSQLQueryOptions): Promise<string>;
 export interface ListAllVegaResourcesOptions {
     baseUrl: string;
     accessToken: string;
@@ -227,4 +235,6 @@ export interface ListAllVegaResourcesOptions {
     offset?: number;
     businessDomain?: string;
 }
+/** List all Vega resources (no catalog filter). Uses GET /resources — not /resources/list, which
+ * conflicts with GET /resources/{id} on some gateways (path segment "list" is treated as an id). */
 export declare function listAllVegaResources(options: ListAllVegaResourcesOptions): Promise<string>;

package/dist/api/vega.js

@@ -458,20 +458,33 @@ export async function executeVegaQuery(options) {
         throw new HttpError(response.status, response.statusText, body);
     return body;
 }
-export async function listAllVegaResources(options) {
-    const { baseUrl, accessToken, limit, offset, businessDomain = "bd_public" } = options;
+/** POST /api/vega-backend/v1/resources/query — direct SQL (or OpenSearch DSL) against catalog-backed resources. */
+export async function vegaSQLQuery(options) {
+    const { baseUrl, accessToken, body: requestBody, businessDomain = "bd_public" } = options;
     const base = baseUrl.replace(/\/+$/, "");
-    const url = new URL(`${base}${VEGA_BASE}/resources/list`);
-    if (limit !== undefined)
-        url.searchParams.set("limit", String(limit));
-    if (offset !== undefined)
-        url.searchParams.set("offset", String(offset));
-    const response = await fetch(url.toString(), {
-        method: "GET",
-        headers: buildHeaders(accessToken, businessDomain),
+    const url = `${base}${VEGA_BASE}/resources/query`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: requestBody,
     });
     const body = await response.text();
     if (!response.ok)
         throw new HttpError(response.status, response.statusText, body);
     return body;
 }
+/** List all Vega resources (no catalog filter). Uses GET /resources — not /resources/list, which
+ * conflicts with GET /resources/{id} on some gateways (path segment "list" is treated as an id). */
+export async function listAllVegaResources(options) {
+    const { baseUrl, accessToken, limit, offset, businessDomain = "bd_public" } = options;
+    return listVegaResources({
+        baseUrl,
+        accessToken,
+        limit,
+        offset,
+        businessDomain,
+    });
+}

package/dist/cli.js

@@ -102,6 +102,7 @@ Usage:
   kweaver vega health|stats|inspect
   kweaver vega catalog list|get|health|test-connection|discover|resources [options]
   kweaver vega resource list|get|query [options]
+  kweaver vega query execute|sql [options]
   kweaver vega connector-type list|get [options]
 
   kweaver context-loader config set|use|list|remove|show [options]
@@ -128,7 +129,7 @@ Commands:
                  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)
-  vega           Vega observability (catalog, resource, connector-type, health/stats/inspect)
+  vega           Vega observability (catalog, resource, query/sql, connector-type, health/stats/inspect)
   context-loader Context-loader MCP (config, tools, resources, prompts, kn-search, query-*, etc.)
   help           Show this message`);
 }

package/dist/commands/agent-chat.js

@@ -84,7 +84,7 @@ export function parseChatArgs(args) {
             stream = false;
             continue;
         }
-        if (arg === "--verbose" || arg === "-v") {
+        if (arg === "--verbose" || arg === "-v" || arg === "--debug") {
             verbose = true;
             continue;
         }

package/dist/commands/agent.d.ts

@@ -1,3 +1,12 @@
+/** Build llm_config with valid defaults for fields that mf-model-api validates. */
+export declare function buildLlmConfig(id: string, name: string, maxTokens: number): Record<string, unknown>;
+/** Resolve LLM model name from mf-model-manager API by model ID. Falls back to llmId on failure. */
+export declare function resolveLlmName(options: {
+    baseUrl: string;
+    accessToken: string;
+    llmId: string;
+    businessDomain?: string;
+}): Promise<string>;
 export interface AgentListOptions {
     name: string;
     offset: number;

package/dist/commands/agent.js

@@ -7,6 +7,44 @@ import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { promises as fs } from "fs";
 import { join, dirname, basename, extname } from "path";
+import { buildHeaders } from "../api/headers.js";
+/** Build llm_config with valid defaults for fields that mf-model-api validates. */
+export function buildLlmConfig(id, name, maxTokens) {
+    return {
+        id,
+        name,
+        max_tokens: maxTokens,
+        temperature: 0.7,
+        top_p: 1,
+        top_k: 1,
+    };
+}
+/** Resolve LLM model name from mf-model-manager API by model ID. Falls back to llmId on failure. */
+export async function resolveLlmName(options) {
+    const { baseUrl, accessToken, llmId, businessDomain = "bd_public" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/mf-model-manager/v1/llm/list?page=1&size=50`;
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: buildHeaders(accessToken, businessDomain),
+        });
+        if (!response.ok)
+            return llmId;
+        const body = (await response.json());
+        const items = (body.data ?? body.entries ?? []);
+        const match = items.find((m) => String(m.model_id ?? m.id) === llmId);
+        if (match) {
+            const name = match.model_name ?? match.name;
+            if (typeof name === "string" && name)
+                return name;
+        }
+        return llmId;
+    }
+    catch {
+        return llmId;
+    }
+}
 /**
  * 生成带时间戳的文件路径
  * @param path 用户提供的路径
@@ -480,7 +518,7 @@ Subcommands:
   chat <agent_id> -m "message"       Send a single message (non-interactive)
   sessions <agent_id>                List all conversations for an agent
   history <agent_id> <conversation_id> Show message history for a conversation
-  trace <conversation_id>            Get trace data for a conversation`);
+  trace <agent_id> <conversation_id>  Get trace data for a conversation`);
         return Promise.resolve(0);
     }
     const dispatch = async () => {
@@ -1144,9 +1182,6 @@ Optional:
             output: { default_format: "markdown" },
             system_prompt: systemPrompt,
         };
-        if (llmId) {
-            config.llms = [{ is_default: true, llm_config: { id: llmId, name: llmId, max_tokens: llmMaxTokens } }];
-        }
     }
     const payload = {
         name,
@@ -1161,6 +1196,11 @@ Optional:
         payload.key = key;
     try {
         const token = await ensureValidToken();
+        // Resolve LLM model name from model-factory before creating agent
+        if (llmId && !configStr) {
+            const llmName = await resolveLlmName({ baseUrl: token.baseUrl, accessToken: token.accessToken, llmId, businessDomain });
+            config.llms = [{ is_default: true, llm_config: buildLlmConfig(llmId, llmName, llmMaxTokens) }];
+        }
         const body = await createAgent({
             baseUrl: token.baseUrl,
             accessToken: token.accessToken,

package/dist/commands/bkn-schema.js

@@ -1185,8 +1185,13 @@ query/execute: Query or execute actions. execute has side effects - only use whe
                 console.error("Usage: kweaver bkn action-type create <kn-id> '<json>'");
                 return 1;
             }
+            // Wrap in {"entries": [...]} if needed (ontology-manager expects this envelope)
+            const entry = JSON.parse(bodyJson);
+            const wrapped = entry && typeof entry === "object" && "entries" in entry
+                ? bodyJson
+                : JSON.stringify({ entries: Array.isArray(entry) ? entry : [entry] });
             const token = await ensureValidToken();
-            const result = await createActionTypes({ baseUrl: token.baseUrl, accessToken: token.accessToken, knId, body: bodyJson, businessDomain: parsed.businessDomain });
+            const result = await createActionTypes({ baseUrl: token.baseUrl, accessToken: token.accessToken, knId, body: wrapped, businessDomain: parsed.businessDomain });
             console.log(formatCallOutput(result, parsed.pretty));
             return 0;
         }

package/dist/commands/dataflow.js

@@ -6,6 +6,7 @@ import yargs from "yargs";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { getDataflowLogsPage, listDataflowRuns, listDataflows, runDataflowWithFile, runDataflowWithRemoteUrl, } from "../api/dataflow2.js";
+import { createDataflow } from "../api/dataflow.js";
 function renderTable(rows) {
     if (rows.length === 0)
         return "";
@@ -101,16 +102,47 @@ export async function runDataflowCommand(args) {
         .fail((message, error) => {
         throw error ?? new Error(message);
     })
-        .command("list", "List all dataflows", (command) => command.option("biz-domain", {
+        .command("create <json>", "Create a new dataflow (DAG) from a JSON definition", (command) => command
+        .positional("json", {
+        type: "string",
+        describe: "JSON body string or @file-path to read from file",
+    })
+        .option("biz-domain", { alias: "bd", type: "string" }), async (argv) => {
+        exitCode = await with401RefreshRetry(async () => {
+            const base = await requireTokenAndBusinessDomain(argv.bizDomain);
+            let raw = argv.json;
+            if (raw.startsWith("@")) {
+                const filePath = raw.slice(1);
+                await access(filePath, constants.R_OK);
+                raw = (await readFile(filePath, "utf8")).toString();
+            }
+            const body = JSON.parse(raw);
+            const dagId = await createDataflow({ ...base, body });
+            console.log(JSON.stringify({ id: dagId }, null, 2));
+            return 0;
+        });
+    })
+        .command("list", "List all dataflows", (command) => command
+        .option("biz-domain", {
         alias: "bd",
         type: "string",
+    })
+        .option("table", {
+        type: "boolean",
+        default: false,
+        describe: "Output as human-readable table instead of JSON",
     }), async (argv) => {
         exitCode = await with401RefreshRetry(async () => {
             const base = await requireTokenAndBusinessDomain(argv.bizDomain);
             const body = await listDataflows(base);
-            const table = renderTable(buildListTableRows(body.dags));
-            if (table) {
-                console.log(table);
+            if (argv.table) {
+                const table = renderTable(buildListTableRows(body.dags));
+                if (table) {
+                    console.log(table);
+                }
+            }
+            else {
+                console.log(JSON.stringify(body, null, 2));
             }
             return 0;
         });
@@ -160,6 +192,11 @@ export async function runDataflowCommand(args) {
         .command("runs <dagId>", "List run records for one dataflow", (command) => command
         .positional("dagId", { type: "string" })
         .option("since", { type: "string" })
+        .option("table", {
+        type: "boolean",
+        default: false,
+        describe: "Output as human-readable table instead of JSON",
+    })
         .option("biz-domain", { alias: "bd", type: "string" }), async (argv) => {
         exitCode = await with401RefreshRetry(async () => {
             const base = await requireTokenAndBusinessDomain(argv.bizDomain);
@@ -203,9 +240,14 @@ export async function runDataflowCommand(args) {
                     results = results.concat(next.results);
                 }
             }
-            const table = renderTable(buildRunTableRows(results));
-            if (table) {
-                console.log(table);
+            if (argv.table) {
+                const table = renderTable(buildRunTableRows(results));
+                if (table) {
+                    console.log(table);
+                }
+            }
+            else {
+                console.log(JSON.stringify(results, null, 2));
             }
             return 0;
         });

package/dist/commands/skill.js

@@ -23,8 +23,8 @@ function printSkillHelp(subcommand) {
                        [--source src] [--extend-info json] [-bd value] [--pretty|--compact]`);
         return;
     }
-    if (subcommand === "status") {
-        console.log("kweaver skill status <skill-id> <unpublish|published|offline> [-bd value] [--pretty|--compact]");
+    if (subcommand === "set-status" || subcommand === "status") {
+        console.log("kweaver skill set-status <skill-id> <unpublish|published|offline> [-bd value] [--pretty|--compact]");
         return;
     }
     if (subcommand === "delete") {
@@ -54,7 +54,7 @@ Subcommands:
   market [--name kw] [--source src] [--page N] [--page-size N] [-bd value]
   get <skill-id> [-bd value]
   register --content-file <path> | --zip-file <path> [--source src] [--extend-info json]
-  status <skill-id> <unpublish|published|offline> [-bd value]
+  set-status <skill-id> <unpublish|published|offline> [-bd value]
   delete <skill-id> [-y] [-bd value]
   content <skill-id> [--raw] [--output file] [-bd value]
   read-file <skill-id> <rel-path> [--raw] [--output file] [-bd value]
@@ -419,7 +419,7 @@ export async function runSkillCommand(args) {
                     return 0;
                 }
             }
-            if (subcommand === "status") {
+            if (subcommand === "set-status" || subcommand === "status") {
                 const opts = parseStatusArgs(rest);
                 const result = await updateSkillStatus({ ...token, ...opts });
                 console.log(format(result, opts.pretty));

package/dist/commands/vega.js

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, listAllVegaResources, } from "../api/vega.js";
+import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, vegaSQLQuery, listAllVegaResources, } from "../api/vega.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 // ---------------------------------------------------------------------------
@@ -35,7 +35,9 @@ Subcommands:
   dataset delete-docs-query <resource-id> -d <filter-json>
   dataset build <resource-id> [--mode full|incremental|realtime]
   dataset build-status <resource-id> <task-id>
-  query execute -d <json>
+  query execute -d <json>               Structured query (tables, joins, filters)
+  sql --resource-type <t> --query <sql>  Direct SQL / DSL; use {{<resource_id>}} in SQL (quoted)
+  sql -d <json>                         Same API with full JSON body (advanced)
   connector-type list                 List connector types
   connector-type get <type>           Get connector type details
   connector-type register -d <json>   Register a new connector type
@@ -103,6 +105,8 @@ export async function runVegaCommand(args) {
             return runVegaDatasetCommand(rest);
         if (subcommand === "query")
             return runVegaQueryCommand(rest);
+        if (subcommand === "sql")
+            return runVegaSql(rest);
         if (subcommand === "connector-type")
             return runVegaConnectorTypeCommand(rest);
         return Promise.resolve(-1);
@@ -1321,6 +1325,101 @@ Options:
     return 0;
 }
 // ---------------------------------------------------------------------------
+// sql (POST /resources/query)
+// ---------------------------------------------------------------------------
+async function runVegaSql(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`kweaver vega sql --resource-type <type> --query "<sql-or-dsl>"
+kweaver vega sql -d <json>
+
+POST /api/vega-backend/v1/resources/query — execute SQL (MySQL/MariaDB/PostgreSQL) or OpenSearch DSL.
+
+Simple mode (no JSON escaping for query + type):
+  --resource-type <t>   Required with --query unless using -d
+  --query <string>      One shell argument: the full SQL (or DSL string). Always quote it.
+
+Advanced mode (full request body, optional fields):
+  -d, --data <json>     Raw JSON body. When present, this mode is used and any --query / --resource-type are ignored.
+
+Resource placeholders (how to reference Vega tables in SQL):
+  {{<resource_id>}}     Required token form: double braces around the Vega resource id (from vega resource list / get).
+  {{.<resource_id>}}    Alternate form with a dot after {{ ; same replacement and routing.
+
+  The backend swaps each placeholder for that resource's physical SourceIdentifier and picks the catalog connector.
+  Without at least one placeholder, queries often fail (e.g. connector config is incomplete) unless a default connector exists.
+
+  Shell (simple mode) — wrap the whole SQL so braces are not interpreted by the shell:
+    kweaver vega sql --resource-type mysql --query "SELECT * FROM {{abc123xyz}} LIMIT 5"
+
+  Shell (-d mode) — placeholders live inside the JSON string value; use single quotes around the JSON so inner double quotes work:
+    kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{abc123xyz}} LIMIT 5"}'
+
+Body fields (JSON / simple mode mapping):
+  query          (required) SQL string or OpenSearch DSL object
+  resource_type  (required) e.g. mysql, mariadb, postgresql, opensearch (see vega connector-type list)
+  stream_size    optional batch size for streaming (100–10000, default 10000)
+  query_timeout  optional seconds (1–3600, default 60)
+  query_id       optional cursor session id
+
+Do not use --type; use --resource-type.
+
+Common flags:
+  -bd, --biz-domain <s>   Business domain (default: bd_public)
+  --pretty               Pretty-print JSON (default)`);
+        return 0;
+    }
+    let data;
+    let query;
+    let resourceType;
+    const { remaining, businessDomain, pretty } = parseCommonFlags(args);
+    for (let i = 0; i < remaining.length; i += 1) {
+        const arg = remaining[i];
+        if (arg === "--type") {
+            console.error("Use --resource-type instead of --type (e.g. --resource-type mysql).");
+            return 1;
+        }
+        if ((arg === "-d" || arg === "--data") && remaining[i + 1]) {
+            data = remaining[++i];
+            continue;
+        }
+        if (arg === "--query" && remaining[i + 1]) {
+            query = remaining[++i];
+            continue;
+        }
+        if (arg === "--resource-type" && remaining[i + 1]) {
+            resourceType = remaining[++i];
+            continue;
+        }
+    }
+    let requestBody;
+    if (data !== undefined) {
+        try {
+            JSON.parse(data);
+        }
+        catch {
+            console.error(`Invalid JSON: ${data}`);
+            return 1;
+        }
+        requestBody = data;
+    }
+    else {
+        if (!query || !resourceType) {
+            console.error("Usage: kweaver vega sql --resource-type <type> --query \"<sql-or-dsl>\"\n       kweaver vega sql -d <json>");
+            return 1;
+        }
+        requestBody = JSON.stringify({ query, resource_type: resourceType });
+    }
+    const token = await ensureValidToken();
+    const body = await vegaSQLQuery({
+        baseUrl: token.baseUrl,
+        accessToken: token.accessToken,
+        body: requestBody,
+        businessDomain,
+    });
+    console.log(formatCallOutput(body, pretty));
+    return 0;
+}
+// ---------------------------------------------------------------------------
 // Connector-type router
 // ---------------------------------------------------------------------------
 async function runVegaConnectorTypeCommand(args) {

package/dist/resources/vega.d.ts

@@ -47,6 +47,8 @@ export declare class VegaResource {
     buildDataset(id: string, mode?: string): Promise<unknown>;
     getDatasetBuildStatus(id: string, taskId: string): Promise<unknown>;
     executeQuery(body: string): Promise<unknown>;
+    /** POST /resources/query — direct SQL or OpenSearch DSL (see kweaver vega sql --help). */
+    sqlQuery(body: string): Promise<unknown>;
     listAllResources(opts?: {
         limit?: number;
         offset?: number;

package/dist/resources/vega.js

@@ -1,4 +1,4 @@
-import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, listAllVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, } from "../api/vega.js";
+import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, vegaSQLQuery, listAllVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, } from "../api/vega.js";
 function unwrapArray(raw) {
     const parsed = JSON.parse(raw);
     if (Array.isArray(parsed))
@@ -114,6 +114,11 @@ export class VegaResource {
         const raw = await executeVegaQuery({ ...this.ctx.base(), body });
         return JSON.parse(raw);
     }
+    /** POST /resources/query — direct SQL or OpenSearch DSL (see kweaver vega sql --help). */
+    async sqlQuery(body) {
+        const raw = await vegaSQLQuery({ ...this.ctx.base(), body });
+        return JSON.parse(raw);
+    }
     // ── Resource List All ──────────────────────────────────────────────────────
     async listAllResources(opts = {}) {
         const raw = await listAllVegaResources({ ...this.ctx.base(), ...opts });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,6 @@
     "lint": "tsc --noEmit -p tsconfig.json",
     "test": "node --import tsx --test test/*.test.ts",
     "test:e2e": "node --import tsx --test test/e2e/*.test.ts",
-    "test:e2e:live": "KWEAVER_BASE_URL=${KWEAVER_BASE_URL:-https://43.129.210.161} KWEAVER_NO_AUTH=1 KWEAVER_TLS_INSECURE=1 node --import tsx --test test/e2e/*.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [