@kweaver-ai/kweaver-sdk 0.6.0 → 0.6.2

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");
@@ -142,7 +151,7 @@ const skillMd = await client.skills.fetchContent("skill-id");
 ## CLI Reference
 
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [-u user] [-p pass] [--playwright] [--insecure|-k]
+kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--insecure|-k]
 kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (headless login)
 kweaver auth export [url|alias] [--json]   (export command to run on a headless host)
 kweaver auth status/list/use/delete/logout
@@ -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: "高血压 治疗" });
@@ -131,7 +144,7 @@ const skillMd = await client.skills.fetchContent("skill-id");
 ## 命令速查
 
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [-u user] [-p pass] [--playwright] [--insecure|-k]
+kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--insecure|-k]
 kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (无浏览器登录)
 kweaver auth export [url|alias] [--json]   (导出在无浏览器机器上运行的命令)
 kweaver auth status/list/use/delete/logout
@@ -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/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;

package/dist/api/vega.js

@@ -458,6 +458,24 @@ export async function executeVegaQuery(options) {
         throw new HttpError(response.status, response.statusText, body);
     return body;
 }
+/** 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 = `${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;
+}
 export async function listAllVegaResources(options) {
     const { baseUrl, accessToken, limit, offset, businessDomain = "bd_public" } = options;
     const base = baseUrl.replace(/\/+$/, "");

package/dist/auth/oauth.d.ts

@@ -14,20 +14,23 @@ export declare function normalizeBaseUrl(value: string): string;
 /**
  * OAuth2 Authorization Code login flow.
  * 1. Register client (if not already registered), OR use a provided client ID
- * 2. Open browser to /oauth2/auth
- * 3. Receive authorization code via local HTTP callback (or manual paste for non-localhost)
+ * 2. Open browser to /oauth2/auth (unless `noBrowser` or browser launch fails)
+ * 3. Receive authorization code via local HTTP callback, or stdin paste (`noBrowser` / fallback)
  * 4. Exchange code for access_token + refresh_token
  * 5. Save token.json + client.json to ~/.kweaver/
  */
 export declare function oauth2Login(baseUrl: string, options?: {
     port?: number;
-    /** Full redirect URI override (e.g. "http://127.0.0.1:9010/callback" or a remote URL). */
-    redirectUri?: string;
     scope?: string;
     clientId?: string;
     clientSecret?: string;
     /** Skip TLS certificate verification (self-signed / dev servers only). */
     tlsInsecure?: boolean;
+    /**
+     * Do not open a browser; print the auth URL and prompt for the callback URL or code (stdin).
+     * For headless servers or when automatic browser launch is unavailable.
+     */
+    noBrowser?: boolean;
 }): Promise<TokenConfig>;
 /**
  * Playwright-automated OAuth2 login.
@@ -44,8 +47,6 @@ export declare function playwrightLogin(baseUrl: string, options?: {
     username?: string;
     password?: string;
     port?: number;
-    /** Full redirect URI override. */
-    redirectUri?: string;
     scope?: string;
     tlsInsecure?: boolean;
 }): Promise<TokenConfig>;

package/dist/auth/oauth.js

@@ -160,8 +160,7 @@ async function isClientStillValid(baseUrl, clientId, redirectUri) {
         });
         if (resp.status === 302) {
             const location = resp.headers.get("location") ?? "";
-            if (location.includes("error=invalid_client") ||
-                location.includes("error=error")) {
+            if (location.includes("error=")) {
                 return false;
             }
             return true;
@@ -199,73 +198,99 @@ async function resolveOrRegisterClient(baseUrl, redirectUri, scope, options) {
     }
     let client = loadClientConfig(baseUrl);
     if (client?.clientId) {
-        const valid = await isClientStillValid(baseUrl, client.clientId, redirectUri);
-        if (valid)
-            return client;
-        process.stderr.write("Cached OAuth2 client is no longer valid on the server. Re-registering…\n");
-        deleteClientConfig(baseUrl);
-        client = null;
+        const storedUri = client.redirectUri ?? redirectUri;
+        const valid = await isClientStillValid(baseUrl, client.clientId, storedUri);
+        if (valid) {
+            if (storedUri !== redirectUri) {
+                process.stderr.write("Redirect URI changed. Re-registering OAuth2 client…\n");
+                deleteClientConfig(baseUrl);
+                client = null;
+            }
+            else {
+                return client;
+            }
+        }
+        else {
+            process.stderr.write("Cached OAuth2 client is no longer valid on the server. Re-registering…\n");
+            deleteClientConfig(baseUrl);
+            client = null;
+        }
     }
     const registered = await registerOAuth2Client(baseUrl, redirectUri, scope);
     saveClientConfig(baseUrl, registered);
     return registered;
 }
 /**
- * Parse a redirect URI to extract host, port, and pathname.
- * Returns null if the URI is not a valid HTTP(S) URL.
+ * Emphasize text on stderr (bold + bright yellow) when stderr is a TTY and `NO_COLOR` is unset.
+ * See https://no-color.org/
  */
-function parseRedirectUri(uri) {
-    try {
-        const parsed = new URL(uri);
-        const host = parsed.hostname;
-        const port = parsed.port ? Number(parsed.port) : (parsed.protocol === "https:" ? 443 : 80);
-        const isLocalhost = host === "127.0.0.1" || host === "localhost" || host === "::1";
-        return { host, port, pathname: parsed.pathname, isLocalhost };
+function stderrEmphasis(text) {
+    const noColor = process.env.NO_COLOR;
+    if (noColor != null && noColor !== "") {
+        return text;
     }
-    catch {
-        return null;
+    if (!process.stderr.isTTY) {
+        return text;
     }
+    return `\x1b[1;33m${text}\x1b[0m`;
 }
 /**
- * Manual code flow for non-localhost redirect URIs.
- * Prints the auth URL, then reads the full callback URL from stdin
- * to extract the authorization code.
+ * Headless login: read authorization code from stdin (full callback URL or raw code).
+ * Used with `--no-browser` or when automatic browser launch fails.
  */
-async function waitForManualCode(authUrl, state) {
+async function promptForCode(authUrl, state, port, pasteMode = "explicit") {
     const { createInterface } = await import("node:readline");
-    process.stderr.write("\nSince the redirect URI is not localhost, you need to complete login manually.\n" +
-        "1. Open this URL in your browser:\n\n" +
-        `   ${authUrl}\n\n` +
-        "2. After login, the browser will redirect to your callback URL.\n" +
-        "3. Copy the full callback URL and paste it here:\n\n");
+    const intro = pasteMode === "explicit"
+        ? "Open this URL on any device (use a private/incognito window if you need the full sign-in form):\n\n"
+        : "Could not open a browser automatically. Open this URL on any device:\n\n";
+    const pasteInstructions = "After login, the browser may show an error page (this is expected if nothing listens on localhost).\n" +
+        "Copy the FULL URL from the address bar and paste it here, or paste only the authorization code.\n" +
+        `The URL looks like: http://127.0.0.1:${port}/callback?code=THIS_PART&state=...\n\n`;
+    process.stderr.write("\n" +
+        intro +
+        `  ${authUrl}\n\n` +
+        stderrEmphasis(pasteInstructions));
     const rl = createInterface({ input: process.stdin, output: process.stderr });
-    const callbackUrl = await new Promise((resolve) => {
-        rl.question("Callback URL> ", (answer) => {
+    const input = await new Promise((resolve, reject) => {
+        rl.on("close", () => reject(new Error("Login cancelled.")));
+        rl.question("Paste URL or code> ", (answer) => {
             rl.close();
             resolve(answer.trim());
         });
     });
-    const parsed = new URL(callbackUrl);
-    const receivedState = parsed.searchParams.get("state");
-    if (receivedState !== state) {
-        throw new Error("OAuth2 state mismatch — possible CSRF attack.");
-    }
-    const error = parsed.searchParams.get("error");
-    if (error) {
-        const desc = parsed.searchParams.get("error_description") ?? "";
-        throw new Error(desc ? `Authorization failed: ${error} — ${desc}` : `Authorization failed: ${error}`);
+    if (input.includes("code=")) {
+        let url;
+        try {
+            url = new URL(input.startsWith("http") ? input : `http://x/?${input}`);
+        }
+        catch {
+            throw new Error("Could not parse the pasted URL. Paste the full callback URL or the code value.");
+        }
+        const receivedState = url.searchParams.get("state");
+        if (receivedState && receivedState !== state) {
+            throw new Error("OAuth2 state mismatch — possible CSRF attack.");
+        }
+        const err = url.searchParams.get("error");
+        if (err) {
+            const desc = url.searchParams.get("error_description") ?? "";
+            throw new Error(desc ? `Authorization failed: ${err} — ${desc}` : `Authorization failed: ${err}`);
+        }
+        const code = url.searchParams.get("code");
+        if (!code) {
+            throw new Error("No authorization code found in the pasted URL.");
+        }
+        return code;
     }
-    const code = parsed.searchParams.get("code");
-    if (!code) {
-        throw new Error("No authorization code found in the callback URL.");
+    if (!input) {
+        throw new Error("No authorization code entered.");
     }
-    return code;
+    return input;
 }
 /**
  * OAuth2 Authorization Code login flow.
  * 1. Register client (if not already registered), OR use a provided client ID
- * 2. Open browser to /oauth2/auth
- * 3. Receive authorization code via local HTTP callback (or manual paste for non-localhost)
+ * 2. Open browser to /oauth2/auth (unless `noBrowser` or browser launch fails)
+ * 3. Receive authorization code via local HTTP callback, or stdin paste (`noBrowser` / fallback)
  * 4. Exchange code for access_token + refresh_token
  * 5. Save token.json + client.json to ~/.kweaver/
  */
@@ -276,12 +301,7 @@ export async function oauth2Login(baseUrl, options) {
         const base = normalizeBaseUrl(baseUrl);
         const port = options?.port ?? DEFAULT_REDIRECT_PORT;
         const scope = options?.scope ?? DEFAULT_SCOPE;
-        // Determine redirect URI: explicit option > port-based default
-        const redirectUri = options?.redirectUri ?? `http://127.0.0.1:${port}/callback`;
-        const parsedRedirect = parseRedirectUri(redirectUri);
-        const isLocalRedirect = parsedRedirect?.isLocalhost ?? true;
-        const listenPort = parsedRedirect?.port ?? port;
-        const callbackPathname = parsedRedirect?.pathname ?? "/callback";
+        const redirectUri = `http://127.0.0.1:${port}/callback`;
         // Step 1: Determine client — use provided client ID or fall back to dynamic registration
         let client;
         try {
@@ -315,9 +335,19 @@ export async function oauth2Login(baseUrl, options) {
             authParams.set("code_challenge_method", "S256");
         }
         const authUrl = `${base}/oauth2/auth?${authParams.toString()}`;
+        const runPasteCodeFlow = async (pasteMode) => {
+            const code = await promptForCode(authUrl, state, port, pasteMode);
+            const exchanged = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
+            const copyCommand = buildCopyCommand(base, client.clientId, client.clientSecret, exchanged.refreshToken, options?.tlsInsecure);
+            process.stderr.write("\nOn a machine without a browser, run:\n\n  " + copyCommand + "\n\n");
+            return exchanged;
+        };
         let token;
-        if (isLocalRedirect) {
-            // Step 4a: Local callback — start HTTP server to receive the authorization code
+        if (options?.noBrowser) {
+            token = await runPasteCodeFlow("explicit");
+        }
+        else {
+            // Step 4: Local HTTP callback, or paste-code if browser cannot be opened
             token = await new Promise((resolve, reject) => {
                 let server;
                 const timeoutId = setTimeout(() => {
@@ -327,8 +357,8 @@ export async function oauth2Login(baseUrl, options) {
                 server = createServer((req, res) => {
                     void (async () => {
                         try {
-                            const url = new URL(req.url ?? "/", `http://127.0.0.1:${listenPort}`);
-                            if (url.pathname !== callbackPathname) {
+                            const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                            if (url.pathname !== "/callback") {
                                 res.writeHead(404);
                                 res.end();
                                 return;
@@ -387,19 +417,25 @@ export async function oauth2Login(baseUrl, options) {
                         }
                     })();
                 });
-                server.listen(listenPort, "127.0.0.1", () => {
-                    import("../utils/browser.js").then(({ openBrowser }) => {
-                        openBrowser(authUrl);
-                    });
-                    process.stderr.write(`If the wrong browser opens, copy this URL to your correct browser:\n  ${authUrl}\n`);
+                server.listen(port, "127.0.0.1", () => {
+                    void (async () => {
+                        const { openBrowser } = await import("../utils/browser.js");
+                        const opened = await openBrowser(authUrl);
+                        process.stderr.write(`If the wrong browser opens, copy this URL to your correct browser:\n  ${authUrl}\n`);
+                        if (!opened) {
+                            clearTimeout(timeoutId);
+                            server.close();
+                            try {
+                                resolve(await runPasteCodeFlow("fallback"));
+                            }
+                            catch (err) {
+                                reject(err instanceof Error ? err : new Error(String(err)));
+                            }
+                        }
+                    })();
                 });
             });
         }
-        else {
-            // Step 4b: Non-localhost redirect — manual code entry flow
-            const code = await waitForManualCode(authUrl, state);
-            token = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
-        }
         setCurrentPlatform(base);
         return token;
     });
@@ -520,10 +556,7 @@ export async function playwrightLogin(baseUrl, options) {
         const base = normalizeBaseUrl(baseUrl);
         const port = options?.port ?? DEFAULT_REDIRECT_PORT;
         const scope = options?.scope ?? DEFAULT_SCOPE;
-        const redirectUri = options?.redirectUri ?? `http://127.0.0.1:${port}/callback`;
-        const parsedRedirect = parseRedirectUri(redirectUri);
-        const listenPort = parsedRedirect?.port ?? port;
-        const callbackPathname = parsedRedirect?.pathname ?? "/callback";
+        const redirectUri = `http://127.0.0.1:${port}/callback`;
         const hasCredentials = !!(options?.username && options?.password);
         // Step 1: Ensure registered OAuth2 client (with stale-client auto-recovery)
         let client;
@@ -564,8 +597,8 @@ export async function playwrightLogin(baseUrl, options) {
             server = createServer((req, res) => {
                 void (async () => {
                     try {
-                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${listenPort}`);
-                        if (url.pathname !== callbackPathname) {
+                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                        if (url.pathname !== "/callback") {
                             res.writeHead(404);
                             res.end();
                             return;
@@ -629,7 +662,7 @@ export async function playwrightLogin(baseUrl, options) {
                     }
                 })();
             });
-            server.listen(listenPort, "127.0.0.1", async () => {
+            server.listen(port, "127.0.0.1", async () => {
                 try {
                     browser = await chromium.launch({ headless: hasCredentials });
                     const context = await browser.newContext({ ignoreHTTPSErrors: !!options?.tlsInsecure });
@@ -670,7 +703,7 @@ export async function playwrightLogin(baseUrl, options) {
  */
 export async function refreshTokenLogin(baseUrl, options) {
     const base = normalizeBaseUrl(baseUrl);
-    const redirectUri = `http://127.0.0.1:${DEFAULT_REDIRECT_PORT}/callback`;
+    const redirectUri = `http://localhost:${DEFAULT_REDIRECT_PORT}/callback`;
     const client = {
         baseUrl: base,
         clientId: options.clientId,

package/dist/cli.js

@@ -21,7 +21,7 @@ Usage:
   kweaver --version | -V
   kweaver --help | -h
 
-  kweaver auth <platform-url> [--alias name] [--no-auth] [-u user] [-p pass] [--playwright] [--insecure|-k]
+  kweaver auth <platform-url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--insecure|-k]
   kweaver auth login <platform-url>          (alias for auth <url>)
   kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (run on host without browser)
   kweaver auth whoami [platform-url|alias] [--json]
@@ -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/auth.js

@@ -28,9 +28,8 @@ Login options:
                          Requires --client-id and --client-secret.
                          Get these from the callback page after browser login or \`auth export\`.
   --port <n>             Local callback port (default: 9010). Use when 9010 is occupied.
-  --redirect-uri <uri>   Full OAuth2 redirect URI override. Localhost URIs start a local server;
-                         non-localhost URIs use a manual paste-the-callback-URL flow.
-                         When set, --port is ignored. Example: --redirect-uri http://127.0.0.1:9010/callback
+  --no-browser           Do not open a browser; print the auth URL and prompt for the callback URL or code (stdin).
+                         Use on headless servers or when automatic browser launch fails.
   -u, --username         Username (with -p triggers Playwright headless login)
   -p, --password         Password
   --playwright           Force Playwright browser login even without -u/-p
@@ -40,7 +39,7 @@ Login options:
     }
     if (target === "login") {
         if (rest[0] === "--help" || rest[0] === "-h") {
-            console.log(`kweaver auth login <platform-url> [--alias <name>] [--no-auth] [-u user] [-p pass] [--playwright] [--refresh-token T --client-id ID --client-secret S]`);
+            console.log(`kweaver auth login <platform-url> [--alias <name>] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--refresh-token T --client-id ID --client-secret S]`);
             return 0;
         }
         const url = rest[0];
@@ -73,19 +72,22 @@ Login options:
             const clientId = readOption(args, "--client-id");
             const clientSecret = readOption(args, "--client-secret");
             const refreshToken = readOption(args, "--refresh-token");
-            const customRedirectUri = readOption(args, "--redirect-uri");
             const customPortStr = readOption(args, "--port");
             const customPort = customPortStr ? parseInt(customPortStr, 10) : undefined;
             const tlsInsecure = args.includes("--insecure") || args.includes("-k");
             const noAuth = args.includes("--no-auth");
+            const noBrowser = args.includes("--no-browser");
+            if (args.includes("--redirect-uri")) {
+                console.error("Warning: --redirect-uri is deprecated and ignored. The redirect URI is always http://127.0.0.1:<port>/callback.");
+            }
             const KNOWN_LOGIN_FLAGS = new Set([
                 "--alias", "--client-id", "--client-secret", "--refresh-token",
-                "--port", "--redirect-uri", "--username", "-u", "--password", "-p",
-                "--playwright", "--insecure", "-k", "--no-auth",
+                "--port", "--no-browser", "--username", "-u", "--password", "-p",
+                "--playwright", "--insecure", "-k", "--no-auth", "--redirect-uri",
             ]);
             const KNOWN_VALUE_FLAGS = new Set([
                 "--alias", "--client-id", "--client-secret", "--refresh-token",
-                "--port", "--redirect-uri", "--username", "-u", "--password", "-p",
+                "--port", "--username", "-u", "--password", "-p", "--redirect-uri",
             ]);
             for (let i = 0; i < args.length; i++) {
                 const a = args[i];
@@ -105,10 +107,21 @@ Login options:
                 console.error("--no-auth cannot be used with --refresh-token.");
                 return 1;
             }
+            if (noAuth && noBrowser) {
+                console.error("--no-auth does not require a browser; --no-browser is ignored.");
+            }
             if (noAuth && (username || password || usePlaywright)) {
                 console.error("--no-auth cannot be used with Playwright login or -u/-p.");
                 return 1;
             }
+            if (noBrowser && (username || password || usePlaywright)) {
+                console.error("--no-browser cannot be used with Playwright login or -u/-p.");
+                return 1;
+            }
+            if (noBrowser && refreshToken) {
+                console.error("--no-browser cannot be used with --refresh-token.");
+                return 1;
+            }
             let token;
             if (noAuth) {
                 token = saveNoAuthPlatform(normalizedTarget, { tlsInsecure });
@@ -127,19 +140,20 @@ Login options:
             else if (username && password) {
                 console.log("Logging in (headless)...");
                 token = await playwrightLogin(normalizedTarget, {
-                    username, password, tlsInsecure,
-                    port: customPort, redirectUri: customRedirectUri ?? undefined,
+                    username, password, tlsInsecure, port: customPort,
                 });
             }
             else if (usePlaywright) {
                 console.log("Opening browser for login (Playwright)...");
                 token = await playwrightLogin(normalizedTarget, {
-                    tlsInsecure,
-                    port: customPort, redirectUri: customRedirectUri ?? undefined,
+                    tlsInsecure, port: customPort,
                 });
             }
             else {
-                if (clientId) {
+                if (noBrowser) {
+                    console.log("OAuth2 login (no browser — open the URL on any device, then paste the callback URL or code)...");
+                }
+                else if (clientId) {
                     console.log(`Opening browser for OAuth2 login (client: ${clientId})...`);
                 }
                 else {
@@ -148,8 +162,7 @@ Login options:
                 token = await oauth2Login(normalizedTarget, {
                     clientId: clientId ?? undefined,
                     clientSecret: clientSecret ?? undefined,
-                    tlsInsecure,
-                    port: customPort, redirectUri: customRedirectUri ?? undefined,
+                    tlsInsecure, port: customPort, noBrowser,
                 });
             }
             if (alias) {

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/dist/utils/browser.js

@@ -1,22 +1,45 @@
+import { readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { release } from "node:os";
+let _isWSL;
+function isWSL() {
+    if (_isWSL !== undefined)
+        return _isWSL;
+    if (process.platform !== "linux")
+        return (_isWSL = false);
+    if (/microsoft/i.test(release()))
+        return (_isWSL = true);
+    try {
+        const procVersion = readFileSync("/proc/version", "utf8");
+        return (_isWSL = /microsoft/i.test(procVersion));
+    }
+    catch {
+        return (_isWSL = false);
+    }
+}
+function resolveCommand(url) {
+    if (process.platform === "darwin") {
+        return { command: "open", args: [url], detached: true };
+    }
+    if (process.platform === "win32") {
+        return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url], detached: false };
+    }
+    if (isWSL()) {
+        return { command: "cmd.exe", args: ["/c", "start", "", url.replace(/&/g, "^&")], detached: true };
+    }
+    return { command: "xdg-open", args: [url], detached: true };
+}
 export function openBrowser(url) {
-    const isWindows = process.platform === "win32";
-    const command = process.platform === "darwin" ? "open" : isWindows ? "rundll32.exe" : "xdg-open";
-    const args = isWindows
-        ? [
-            "url.dll,FileProtocolHandler",
-            url,
-        ]
-        : [url];
+    const { command, args, detached } = resolveCommand(url);
     return new Promise((resolve) => {
         const child = spawn(command, args, {
             stdio: "ignore",
-            detached: !isWindows,
+            detached,
             windowsHide: true,
         });
         child.once("error", () => resolve(false));
         child.once("spawn", () => resolve(true));
-        if (!isWindows) {
+        if (detached) {
             child.unref();
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",