@kweaver-ai/kweaver-sdk 0.4.4 → 0.4.5

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

@@ -4,8 +4,21 @@ 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,6 +1,8 @@
-import { getCurrentPlatform, loadTokenConfig, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
+import { getCurrentPlatform, loadClientConfig, loadTokenConfig, 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;
 export function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }
@@ -80,6 +82,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 +178,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 +240,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/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";
@@ -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;
     }

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.5",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",