@kweaver-ai/kweaver-sdk 0.4.4 → 0.4.6

package/dist/api/agent-chat.js

@@ -254,7 +254,8 @@ export async function sendChatRequest(options) {
     };
     if (verbose) {
         console.error(`POST ${url}`);
-        console.error(`Headers: ${JSON.stringify(headers)}`);
+        const safeHeaders = Object.fromEntries(Object.entries(headers).map(([k, v]) => k.toLowerCase() === "authorization" ? [k, "Bearer ***"] : [k, v]));
+        console.error(`Headers: ${JSON.stringify(safeHeaders)}`);
         console.error(`Body: ${JSON.stringify(body)}`);
     }
     let response;
@@ -312,7 +313,8 @@ export async function sendChatRequestStream(options, callbacks) {
     };
     if (verbose) {
         console.error(`POST ${url}`);
-        console.error(`Headers: ${JSON.stringify(headers)}`);
+        const safeHeaders = Object.fromEntries(Object.entries(headers).map(([k, v]) => k.toLowerCase() === "authorization" ? [k, "Bearer ***"] : [k, v]));
+        console.error(`Headers: ${JSON.stringify(safeHeaders)}`);
         console.error(`Body: ${JSON.stringify(body)}`);
     }
     let response;

package/dist/api/context-loader.js

@@ -1,5 +1,6 @@
 import { fetchTextOrThrow } from "../utils/http.js";
 const MCP_PROTOCOL_VERSION = "2024-11-05";
+const SESSION_TTL_MS = 300_000; // 5 minutes
 const sessionCache = new Map();
 function sessionKey(options) {
     return `${options.mcpUrl}:${options.knId}`;
@@ -20,8 +21,11 @@ function buildHeaders(options, sessionId) {
 async function ensureSession(options) {
     const key = sessionKey(options);
     const cached = sessionCache.get(key);
+    if (cached && Date.now() - cached.createdAt < SESSION_TTL_MS)
+        return cached.id;
+    // Remove stale entry if expired
     if (cached)
-        return cached;
+        sessionCache.delete(key);
     const initBody = JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
@@ -50,7 +54,7 @@ async function ensureSession(options) {
         headers: buildHeaders(options, sessionId),
         body: initNotifBody,
     });
-    sessionCache.set(key, sessionId);
+    sessionCache.set(key, { id: sessionId, createdAt: Date.now() });
     return sessionId;
 }
 function isMissingInputParams(obj) {

package/dist/api/conversations.js

@@ -30,7 +30,7 @@ export async function listConversations(opts) {
     }
     const body = await response.text();
     if (!response.ok) {
-        return "[]";
+        throw new Error(`listConversations failed: HTTP ${response.status} ${response.statusText} — ${body.slice(0, 200)}`);
     }
     return body || "[]";
 }
@@ -58,7 +58,7 @@ export async function listMessages(opts) {
     }
     const body = await response.text();
     if (!response.ok) {
-        return "[]";
+        throw new Error(`listMessages failed: HTTP ${response.status} ${response.statusText} — ${body.slice(0, 200)}`);
     }
     return body || "[]";
 }

package/dist/api/datasources.js

@@ -204,7 +204,8 @@ export async function scanMetadata(options) {
     const scanResult = await scanResponse.json();
     const taskId = scanResult.id ?? "";
     for (let i = 0; i < 30; i += 1) {
-        await new Promise((r) => setTimeout(r, 2000));
+        const delay = Math.min(2000 * Math.pow(1.5, i), 15000);
+        await new Promise((r) => setTimeout(r, delay));
         const statusResponse = await fetch(statusUrl(taskId), {
             method: "GET",
             headers: buildHeaders(accessToken, businessDomain),

package/dist/auth/oauth.d.ts

@@ -1,11 +1,40 @@
 import { type TokenConfig } from "../config/store.js";
 export declare function normalizeBaseUrl(value: string): string;
+/**
+ * OAuth2 Authorization Code login flow.
+ * 1. Register client (if not already registered)
+ * 2. Open browser to /oauth2/auth
+ * 3. Receive authorization code via local HTTP callback
+ * 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;
+    scope?: string;
+}): Promise<TokenConfig>;
+/**
+ * Playwright cookie login (legacy fallback).
+ * Does NOT produce a refresh_token — token expires in 1 hour with no auto-refresh.
+ */
 export declare function playwrightLogin(baseUrl: string, options?: {
     username?: string;
     password?: string;
 }): Promise<TokenConfig>;
+/**
+ * Exchange refresh_token for a new access token (OAuth2 password grant style, same as Python ConfigAuth).
+ * Persists the new token to ~/.kweaver/ and returns it.
+ */
+export declare function refreshAccessToken(token: TokenConfig): Promise<TokenConfig>;
 export declare function ensureValidToken(opts?: {
     forceRefresh?: boolean;
 }): Promise<TokenConfig>;
+/**
+ * Run an operation; on HTTP 401, refresh the access token once and retry.
+ * Does not call `ensureValidToken` first — use for CLI routers so `--help` works without login.
+ */
+export declare function with401RefreshRetry<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Load a valid token, run `fn(token)`, and on 401 refresh once and retry with the new token.
+ */
 export declare function withTokenRetry<T>(fn: (token: TokenConfig) => Promise<T>): Promise<T>;
 export declare function formatHttpError(error: unknown): string;

package/dist/auth/oauth.js

@@ -1,9 +1,169 @@
-import { getCurrentPlatform, loadTokenConfig, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
+import { getCurrentPlatform, loadClientConfig, loadTokenConfig, saveClientConfig, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
 import { HttpError, NetworkRequestError } from "../utils/http.js";
 const TOKEN_TTL_SECONDS = 3600;
+/** Seconds before access token expiry to trigger refresh (matches Python ConfigAuth). */
+const REFRESH_THRESHOLD_SEC = 60;
+const DEFAULT_REDIRECT_PORT = 9010;
+const DEFAULT_SCOPE = "openid offline all";
 export function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }
+/**
+ * OAuth2 Authorization Code login flow.
+ * 1. Register client (if not already registered)
+ * 2. Open browser to /oauth2/auth
+ * 3. Receive authorization code via local HTTP callback
+ * 4. Exchange code for access_token + refresh_token
+ * 5. Save token.json + client.json to ~/.kweaver/
+ */
+export async function oauth2Login(baseUrl, options) {
+    const { createServer } = await import("node:http");
+    const { randomBytes } = await import("node:crypto");
+    const base = normalizeBaseUrl(baseUrl);
+    const port = options?.port ?? DEFAULT_REDIRECT_PORT;
+    const scope = options?.scope ?? DEFAULT_SCOPE;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    // Step 1: Ensure registered client
+    let client = loadClientConfig(base);
+    if (!client?.clientId) {
+        client = await registerOAuth2Client(base, redirectUri, scope);
+        saveClientConfig(base, client);
+    }
+    // Step 2: Generate CSRF state
+    const state = randomBytes(12).toString("hex");
+    // Step 3: Build authorization URL
+    const authParams = new URLSearchParams({
+        redirect_uri: redirectUri,
+        "x-forwarded-prefix": "",
+        client_id: client.clientId,
+        scope,
+        response_type: "code",
+        state,
+        lang: "zh-cn",
+        product: "adp",
+    });
+    const authUrl = `${base}/oauth2/auth?${authParams.toString()}`;
+    // Step 4: Start local callback server, wait for code
+    const code = await new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            server.close();
+            reject(new Error("OAuth2 login timed out (120s). No authorization code received."));
+        }, 120_000);
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+            if (url.pathname === "/callback") {
+                const receivedState = url.searchParams.get("state");
+                const receivedCode = url.searchParams.get("code");
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<html><body><h2>Login successful. You can close this tab.</h2></body></html>");
+                clearTimeout(timeoutId);
+                server.close();
+                if (receivedState !== state) {
+                    reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
+                }
+                else if (!receivedCode) {
+                    reject(new Error("No authorization code received in callback."));
+                }
+                else {
+                    resolve(receivedCode);
+                }
+            }
+            else {
+                res.writeHead(404);
+                res.end();
+            }
+        });
+        server.listen(port, "127.0.0.1", () => {
+            // Step 5: Open browser
+            import("node:child_process").then(({ exec }) => {
+                const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+                exec(`${cmd} "${authUrl}"`);
+            });
+        });
+    });
+    // Step 6: Exchange code for tokens
+    const token = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri);
+    setCurrentPlatform(base);
+    return token;
+}
+async function registerOAuth2Client(baseUrl, redirectUri, scope) {
+    const logoutUri = redirectUri.replace("/callback", "/successful-logout");
+    const response = await fetch(`${baseUrl}/oauth2/clients`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            client_name: "kweaver-sdk",
+            grant_types: ["authorization_code", "implicit", "refresh_token"],
+            response_types: ["token id_token", "code", "token"],
+            scope: "openid offline all",
+            redirect_uris: [redirectUri],
+            post_logout_redirect_uris: [logoutUri],
+            metadata: {
+                device: {
+                    name: "kweaver-sdk",
+                    client_type: "web",
+                    description: "KWeaver TypeScript SDK",
+                },
+            },
+        }),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    const data = JSON.parse(text);
+    return {
+        baseUrl,
+        clientId: data.client_id,
+        clientSecret: data.client_secret,
+        redirectUri,
+        logoutRedirectUri: logoutUri,
+        scope,
+        lang: "zh-cn",
+        product: "adp",
+        xForwardedPrefix: "",
+    };
+}
+async function exchangeCodeForToken(baseUrl, code, clientId, clientSecret, redirectUri) {
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+    const response = await fetch(`${baseUrl}/oauth2/token`, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${credentials}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+        }).toString(),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    const data = JSON.parse(text);
+    const now = new Date();
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 3600;
+    const token = {
+        baseUrl,
+        accessToken: data.access_token,
+        tokenType: data.token_type ?? "Bearer",
+        scope: data.scope ?? "",
+        expiresIn,
+        expiresAt: new Date(now.getTime() + expiresIn * 1000).toISOString(),
+        refreshToken: data.refresh_token ?? "",
+        idToken: data.id_token ?? "",
+        obtainedAt: now.toISOString(),
+    };
+    saveTokenConfig(token);
+    return token;
+}
+/**
+ * Playwright cookie login (legacy fallback).
+ * Does NOT produce a refresh_token — token expires in 1 hour with no auto-refresh.
+ */
 export async function playwrightLogin(baseUrl, options) {
     let chromium;
     try {
@@ -80,6 +240,85 @@ export async function playwrightLogin(baseUrl, options) {
         await browser.close();
     }
 }
+function tokenNeedsRefresh(token) {
+    if (!token.expiresAt) {
+        return false;
+    }
+    const expiresAtMs = Date.parse(token.expiresAt);
+    if (Number.isNaN(expiresAtMs)) {
+        return false;
+    }
+    const thresholdMs = REFRESH_THRESHOLD_SEC * 1000;
+    return expiresAtMs - thresholdMs <= Date.now();
+}
+/**
+ * Exchange refresh_token for a new access token (OAuth2 password grant style, same as Python ConfigAuth).
+ * Persists the new token to ~/.kweaver/ and returns it.
+ */
+export async function refreshAccessToken(token) {
+    const baseUrl = normalizeBaseUrl(token.baseUrl);
+    const refreshToken = token.refreshToken?.trim();
+    if (!refreshToken) {
+        throw new Error(`Token expired and no refresh_token available for ${baseUrl}. Run \`kweaver auth login ${baseUrl}\` again.`);
+    }
+    const client = loadClientConfig(baseUrl);
+    const clientId = client?.clientId?.trim() ?? "";
+    const clientSecret = client?.clientSecret?.trim() ?? "";
+    if (!clientId || !clientSecret) {
+        throw new Error(`Token refresh requires OAuth client credentials (client.json). Run \`kweaver auth login ${baseUrl}\` again.`);
+    }
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+    const url = `${baseUrl}/oauth2/token`;
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+    });
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Basic ${credentials}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: body.toString(),
+        });
+    }
+    catch (cause) {
+        const hint = cause instanceof Error ? cause.message : String(cause);
+        throw new NetworkRequestError("POST", url, hint, "Check network connectivity and that the platform exposes /oauth2/token.");
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Invalid JSON from ${url} during token refresh.`);
+    }
+    if (typeof data.access_token !== "string") {
+        throw new Error(`Token refresh response missing access_token from ${url}.`);
+    }
+    const now = new Date();
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 3600;
+    const newToken = {
+        baseUrl,
+        accessToken: data.access_token,
+        tokenType: data.token_type ?? "Bearer",
+        scope: data.scope ?? token.scope ?? "",
+        expiresIn,
+        expiresAt: new Date(now.getTime() + expiresIn * 1000).toISOString(),
+        refreshToken: data.refresh_token ?? refreshToken,
+        idToken: data.id_token ?? token.idToken ?? "",
+        obtainedAt: now.toISOString(),
+    };
+    saveTokenConfig(newToken);
+    return newToken;
+}
 export async function ensureValidToken(opts) {
     const envToken = process.env.KWEAVER_TOKEN;
     const envBaseUrl = process.env.KWEAVER_BASE_URL;
@@ -97,21 +336,61 @@ export async function ensureValidToken(opts) {
     if (!currentPlatform) {
         throw new Error("No active platform selected. Run `kweaver auth login <platform-url>` first.");
     }
-    if (opts?.forceRefresh) {
-        throw new Error(`Token refresh is not supported. Run \`kweaver auth login ${currentPlatform}\` again.`);
-    }
-    const token = loadTokenConfig(currentPlatform);
+    let token = loadTokenConfig(currentPlatform);
     if (!token) {
         throw new Error(`No saved token for ${currentPlatform}. Run \`kweaver auth login ${currentPlatform}\` first.`);
     }
-    if (token.expiresAt) {
-        const expiresAtMs = Date.parse(token.expiresAt);
-        if (!Number.isNaN(expiresAtMs) && expiresAtMs - 60_000 <= Date.now()) {
-            throw new Error(`Access token expired. Run \`kweaver auth login ${currentPlatform}\` again.`);
+    if (opts?.forceRefresh) {
+        return refreshAccessToken(token);
+    }
+    if (tokenNeedsRefresh(token)) {
+        try {
+            return await refreshAccessToken(token);
+        }
+        catch (err) {
+            throw new Error(`Access token expired or near expiry and refresh failed for ${currentPlatform}.\n` +
+                (err instanceof Error ? `${err.message}\n` : "") +
+                `Run \`kweaver auth login ${currentPlatform}\` again.`, { cause: err });
         }
     }
     return token;
 }
+/**
+ * Run an operation; on HTTP 401, refresh the access token once and retry.
+ * Does not call `ensureValidToken` first — use for CLI routers so `--help` works without login.
+ */
+export async function with401RefreshRetry(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 401) {
+            const currentPlatform = getCurrentPlatform();
+            if (!currentPlatform) {
+                throw error;
+            }
+            const platformUrl = normalizeBaseUrl(currentPlatform);
+            const latest = loadTokenConfig(platformUrl);
+            if (!latest) {
+                throw error;
+            }
+            try {
+                await refreshAccessToken(latest);
+            }
+            catch (retryErr) {
+                const oauthHint = formatOAuthErrorBody(retryErr instanceof HttpError ? retryErr.body : "");
+                const extra = oauthHint ? `\n\n${oauthHint}` : "";
+                throw new Error(`Authentication failed (401). Token refresh did not succeed for ${platformUrl}.${extra}\n` +
+                    `Run \`kweaver auth login ${platformUrl}\` again.`, { cause: retryErr });
+            }
+            return await fn();
+        }
+        throw error;
+    }
+}
+/**
+ * Load a valid token, run `fn(token)`, and on 401 refresh once and retry with the new token.
+ */
 export async function withTokenRetry(fn) {
     const token = await ensureValidToken();
     try {
@@ -119,9 +398,18 @@ export async function withTokenRetry(fn) {
     }
     catch (error) {
         if (error instanceof HttpError && error.status === 401) {
-            const platform = token.baseUrl;
-            throw new Error(`Authentication failed (401). Token may be expired or revoked.\n` +
-                `Run \`kweaver auth login ${platform}\` again.`);
+            const platformUrl = normalizeBaseUrl(token.baseUrl);
+            const latest = loadTokenConfig(platformUrl) ?? token;
+            try {
+                const refreshed = await refreshAccessToken(latest);
+                return await fn(refreshed);
+            }
+            catch (retryErr) {
+                const oauthHint = formatOAuthErrorBody(retryErr instanceof HttpError ? retryErr.body : "");
+                const extra = oauthHint ? `\n\n${oauthHint}` : "";
+                throw new Error(`Authentication failed (401). Token refresh did not succeed for ${platformUrl}.${extra}\n` +
+                    `Run \`kweaver auth login ${platformUrl}\` again.`, { cause: retryErr });
+            }
         }
         throw error;
     }

package/dist/commands/agent.js

@@ -1,5 +1,4 @@
-import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { HttpError } from "../utils/http.js";
+import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { runAgentChatCommand } from "./agent-chat.js";
 import { listAgents, getAgent, getAgentByKey, createAgent, updateAgent, deleteAgent, publishAgent, unpublishAgent, } from "../api/agent-list.js";
 import { listConversations, listMessages } from "../api/conversations.js";
@@ -347,24 +346,16 @@ Options:
         }
     }
     try {
-        const code = await dispatch();
-        if (code === -1) {
-            console.error(`Unknown agent subcommand: ${subcommand}`);
-            return 1;
-        }
-        return code;
-    }
-    catch (error) {
-        if (error instanceof HttpError && error.status === 401) {
-            try {
-                await ensureValidToken({ forceRefresh: true });
-                return await dispatch();
-            }
-            catch (retryError) {
-                console.error(formatHttpError(retryError));
+        return await with401RefreshRetry(async () => {
+            const code = await dispatch();
+            if (code === -1) {
+                console.error(`Unknown agent subcommand: ${subcommand}`);
                 return 1;
             }
-        }
+            return code;
+        });
+    }
+    catch (error) {
         console.error(formatHttpError(error));
         return 1;
     }

package/dist/commands/auth.js

@@ -1,5 +1,5 @@
 import { clearPlatformSession, deletePlatform, getConfigDir, getCurrentPlatform, getPlatformAlias, hasPlatform, listPlatforms, loadTokenConfig, resolvePlatformIdentifier, setCurrentPlatform, setPlatformAlias, } from "../config/store.js";
-import { formatHttpError, normalizeBaseUrl, playwrightLogin, } from "../auth/oauth.js";
+import { formatHttpError, normalizeBaseUrl, oauth2Login, playwrightLogin, } from "../auth/oauth.js";
 export async function runAuthCommand(args) {
     const target = args[0];
     const rest = args.slice(1);
@@ -27,13 +27,23 @@ kweaver auth delete <url>    Delete saved credentials`);
             const alias = readOption(args, "--alias");
             const username = readOption(args, "--username") ?? readOption(args, "-u");
             const password = readOption(args, "--password") ?? readOption(args, "-p");
+            const usePlaywright = args.includes("--playwright");
+            let token;
             if (username && password) {
+                // Headless Playwright login with credentials
                 console.log("Logging in (headless)...");
+                token = await playwrightLogin(normalizedTarget, { username, password });
+            }
+            else if (usePlaywright) {
+                // Explicit Playwright fallback
+                console.log("Opening browser for login (Playwright)...");
+                token = await playwrightLogin(normalizedTarget);
             }
             else {
-                console.log("Opening browser for login...");
+                // Default: OAuth2 authorization code flow (supports refresh_token)
+                console.log("Opening browser for OAuth2 login...");
+                token = await oauth2Login(normalizedTarget);
             }
-            const token = await playwrightLogin(normalizedTarget, username && password ? { username, password } : undefined);
             if (alias) {
                 setPlatformAlias(normalizedTarget, alias);
             }
@@ -49,6 +59,12 @@ kweaver auth delete <url>    Delete saved credentials`);
             }
             console.log(`Current platform: ${normalizedTarget}`);
             console.log(`Access token saved: yes`);
+            if (token.refreshToken) {
+                console.log(`Refresh token: yes (auto-refresh enabled)`);
+            }
+            else {
+                console.log(`Refresh token: no (token will expire in 1 hour)`);
+            }
             if (token.expiresAt) {
                 console.log(`Token expires at: ${token.expiresAt}`);
             }
@@ -79,6 +95,7 @@ kweaver auth delete <url>    Delete saved credentials`);
             `Current platform: ${token.baseUrl === currentPlatform ? "yes" : "no"}`,
             `Token present: yes`,
         ];
+        lines.push(`Refresh token: ${token.refreshToken ? "yes (auto-refresh enabled)" : "no"}`);
         if (token.expiresAt) {
             const expiry = new Date(token.expiresAt);
             const remainingMs = expiry.getTime() - Date.now();
@@ -86,6 +103,9 @@ kweaver auth delete <url>    Delete saved credentials`);
                 const remainingMin = Math.ceil(remainingMs / 60_000);
                 lines.push(`Token status: active (expires in ${remainingMin} min)`);
             }
+            else if (token.refreshToken) {
+                lines.push(`Token status: expired (will auto-refresh on next command)`);
+            }
             else {
                 lines.push(`Token status: expired (run \`kweaver auth login ${token.baseUrl}\` again)`);
             }

package/dist/commands/bkn.js

@@ -3,8 +3,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, validateNetwork } from "@kweaver-ai/bkn";
-import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { HttpError } from "../utils/http.js";
+import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, getObjectType, createObjectTypes, updateObjectType, deleteObjectTypes, getRelationType, createRelationTypes, updateRelationType, deleteRelationTypes, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
 import { objectTypeQuery, objectTypeProperties, subgraph, actionTypeQuery, actionTypeExecute, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "../api/ontology-query.js";
 import { semanticSearch } from "../api/semantic-search.js";
@@ -529,7 +528,7 @@ export function parseKnObjectTypeQueryArgs(args) {
         body.search_after = searchAfter;
     }
     if (typeof body.limit !== "number" || !Number.isFinite(body.limit) || body.limit < 1) {
-        throw new Error("Missing limit. Provide it in body JSON or via --limit <n>.");
+        body.limit = 30;
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
@@ -627,26 +626,16 @@ export async function runKnCommand(args) {
         return Promise.resolve(-1);
     };
     try {
-        const code = await dispatch();
-        if (code === -1) {
-            console.error(`Unknown bkn subcommand: ${subcommand}`);
-            return 1;
-        }
-        return code;
-    }
-    catch (error) {
-        // Auto-retry on 401: force-refresh the token and re-run the subcommand.
-        // The subcommand will call ensureValidToken() again and pick up the fresh token.
-        if (error instanceof HttpError && error.status === 401) {
-            try {
-                await ensureValidToken({ forceRefresh: true });
-                return await dispatch();
-            }
-            catch (retryError) {
-                console.error(formatHttpError(retryError));
+        return await with401RefreshRetry(async () => {
+            const code = await dispatch();
+            if (code === -1) {
+                console.error(`Unknown bkn subcommand: ${subcommand}`);
                 return 1;
             }
-        }
+            return code;
+        });
+    }
+    catch (error) {
         console.error(formatHttpError(error));
         return 1;
     }
@@ -927,7 +916,8 @@ kweaver bkn object-type properties <kn-id> <ot-id> '<json>' [--pretty] [-bd valu
 list: List object types (schema) from ontology-manager.
 get: Get single object type details.
 create/update/delete: Schema CRUD (create requires dataview-id).
-query/properties: Query via ontology-query API. For query, --limit and --search-after are merged into the JSON body.
+query: Query via ontology-query API. Default limit is 30 if not specified. Use --search-after for pagination.
+properties: Query instance properties by primary key.
 
 properties JSON format: {"_instance_identities":[{"<primary-key>":"<value>"}],"properties":["prop1","prop2"]}`);
         return 0;
@@ -1027,6 +1017,10 @@ properties JSON format: {"_instance_identities":[{"<primary-key>":"<value>"}],"p
                 body: options.body,
                 businessDomain: options.businessDomain,
             });
+            const OUTPUT_WARN_BYTES = 100_000;
+            if (result.length > OUTPUT_WARN_BYTES) {
+                console.error(`[warn] Response is ${(result.length / 1024).toFixed(0)}KB. Use a smaller --limit or --search-after to paginate.`);
+            }
             console.log(formatCallOutput(result, options.pretty));
             return 0;
         }
@@ -1354,6 +1348,9 @@ Query subgraph via ontology-query API. JSON body format see references/json-form
             businessDomain,
             queryType,
         });
+        if (result.length > 100_000) {
+            console.error(`[warn] Response is ${(result.length / 1024).toFixed(0)}KB. Consider narrowing the subgraph query.`);
+        }
         console.log(formatCallOutput(result, pretty));
         return 0;
     }

package/dist/commands/call.js

@@ -1,4 +1,4 @@
-import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
+import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { HttpError } from "../utils/http.js";
 import { resolveBusinessDomain } from "../config/store.js";
 export function parseCallArgs(args) {
@@ -168,19 +168,9 @@ Options:
         return 0;
     };
     try {
-        return await execute();
+        return await with401RefreshRetry(async () => execute());
     }
     catch (error) {
-        if (error instanceof HttpError && error.status === 401) {
-            try {
-                await ensureValidToken({ forceRefresh: true });
-                return await execute();
-            }
-            catch (retryError) {
-                console.error(formatHttpError(retryError));
-                return 1;
-            }
-        }
         console.error(formatHttpError(error));
         return 1;
     }

package/dist/commands/context-loader.js

@@ -1,5 +1,4 @@
-import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { HttpError } from "../utils/http.js";
+import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { knSearch, knSchemaSearch, queryObjectInstance, queryInstanceSubgraph, getLogicPropertiesValues, getActionInfo, listTools, listResources, readResource, listResourceTemplates, listPrompts, getPrompt, } from "../api/context-loader.js";
 import { addContextLoaderEntry, getCurrentContextLoaderKn, getCurrentPlatform, loadContextLoaderConfig, removeContextLoaderEntry, setCurrentContextLoader, } from "../config/store.js";
 const MCP_NOT_CONFIGURED = "Context-loader MCP is not configured. Run: kweaver context-loader config set --kn-id <kn-id>";
@@ -92,24 +91,16 @@ Examples:
         return -1;
     };
     try {
-        const code = await dispatch();
-        if (code === -1) {
-            console.error(`Unknown context-loader subcommand: ${subcommand}`);
-            return 1;
-        }
-        return code;
-    }
-    catch (error) {
-        if (error instanceof HttpError && error.status === 401) {
-            try {
-                await ensureValidToken({ forceRefresh: true });
-                return await dispatch();
-            }
-            catch (retryError) {
-                console.error(formatHttpError(retryError));
+        return await with401RefreshRetry(async () => {
+            const code = await dispatch();
+            if (code === -1) {
+                console.error(`Unknown context-loader subcommand: ${subcommand}`);
                 return 1;
             }
-        }
+            return code;
+        });
+    }
+    catch (error) {
         console.error(formatHttpError(error));
         return 1;
     }

package/dist/commands/ds.js

@@ -1,6 +1,5 @@
 import { createInterface } from "node:readline";
-import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { HttpError } from "../utils/http.js";
+import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTablesWithColumns, } from "../api/datasources.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
@@ -50,24 +49,16 @@ Subcommands:
         return Promise.resolve(-1);
     };
     try {
-        const code = await dispatch();
-        if (code === -1) {
-            console.error(`Unknown ds subcommand: ${subcommand}`);
-            return 1;
-        }
-        return code;
-    }
-    catch (error) {
-        if (error instanceof HttpError && error.status === 401) {
-            try {
-                await ensureValidToken({ forceRefresh: true });
-                return await dispatch();
-            }
-            catch (retryError) {
-                console.error(formatHttpError(retryError));
+        return await with401RefreshRetry(async () => {
+            const code = await dispatch();
+            if (code === -1) {
+                console.error(`Unknown ds subcommand: ${subcommand}`);
                 return 1;
             }
-        }
+            return code;
+        });
+    }
+    catch (error) {
         console.error(formatHttpError(error));
         return 1;
     }

package/dist/commands/vega.js

@@ -1,5 +1,4 @@
-import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { HttpError } from "../utils/http.js";
+import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { vegaHealth, listVegaCatalogs, getVegaCatalog, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, previewVegaResource, listVegaConnectorTypes, getVegaConnectorType, listVegaDiscoverTasks, } from "../api/vega.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
@@ -78,24 +77,16 @@ export async function runVegaCommand(args) {
         return Promise.resolve(-1);
     };
     try {
-        const code = await dispatch();
-        if (code === -1) {
-            console.error(`Unknown vega subcommand: ${subcommand}`);
-            return 1;
-        }
-        return code;
-    }
-    catch (error) {
-        if (error instanceof HttpError && error.status === 401) {
-            try {
-                await ensureValidToken({ forceRefresh: true });
-                return await dispatch();
-            }
-            catch (retryError) {
-                console.error(formatHttpError(retryError));
+        return await with401RefreshRetry(async () => {
+            const code = await dispatch();
+            if (code === -1) {
+                console.error(`Unknown vega subcommand: ${subcommand}`);
                 return 1;
             }
-        }
+            return code;
+        });
+    }
+    catch (error) {
         console.error(formatHttpError(error));
         return 1;
     }

package/dist/config/store.d.ts

@@ -9,6 +9,18 @@ export interface TokenConfig {
     idToken?: string;
     obtainedAt: string;
 }
+/** OAuth2 client registration (per platform), used for refresh_token grant. */
+export interface ClientConfig {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri?: string;
+    logoutRedirectUri?: string;
+    scope?: string;
+    lang?: string;
+    product?: string;
+    xForwardedPrefix?: string;
+}
 /** Single context-loader entry (named kn_id). */
 export interface ContextLoaderEntry {
     name: string;
@@ -34,6 +46,8 @@ export declare function getPlatformAlias(baseUrl: string): string | null;
 export declare function resolvePlatformIdentifier(value: string): string | null;
 export declare function loadTokenConfig(baseUrl?: string): TokenConfig | null;
 export declare function saveTokenConfig(config: TokenConfig): void;
+export declare function loadClientConfig(baseUrl?: string): ClientConfig | null;
+export declare function saveClientConfig(baseUrl: string, config: ClientConfig): void;
 export declare function loadContextLoaderConfig(baseUrl?: string): ContextLoaderConfig | null;
 export declare function saveContextLoaderConfig(baseUrl: string, config: ContextLoaderConfig): void;
 export interface CurrentContextLoaderKn {

package/dist/config/store.js

@@ -188,6 +188,19 @@ export function saveTokenConfig(config) {
     ensurePlatformDir(config.baseUrl);
     writeJsonFile(getPlatformFile(config.baseUrl, "token.json"), config);
 }
+export function loadClientConfig(baseUrl) {
+    ensureStoreReady();
+    const targetBaseUrl = baseUrl ?? getCurrentPlatform();
+    if (!targetBaseUrl) {
+        return null;
+    }
+    return readJsonFile(getPlatformFile(targetBaseUrl, "client.json"));
+}
+export function saveClientConfig(baseUrl, config) {
+    ensureStoreReady();
+    ensurePlatformDir(baseUrl);
+    writeJsonFile(getPlatformFile(baseUrl, "client.json"), { ...config, baseUrl });
+}
 function migrateLegacyContextLoader(raw) {
     const leg = raw;
     if (leg?.knId && !Array.isArray(raw.configs)) {

package/package.json

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