@kweaver-ai/kweaver-sdk 0.4.0

package/bin/kweaver.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import("../dist/cli.js").then(({ run }) => {
+  run(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    });
+});

package/dist/api/agent-chat.d.ts

@@ -0,0 +1,69 @@
+export interface SendChatRequestOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    agentKey: string;
+    agentVersion: string;
+    query: string;
+    conversationId?: string;
+    stream: boolean;
+    verbose?: boolean;
+    businessDomain?: string;
+}
+export interface ChatResult {
+    text: string;
+    conversationId?: string;
+    /** From message.content.middle_answer.progress when stream is false. */
+    progress?: ProgressItem[];
+}
+/** One step from message.content.middle_answer.progress (tool/skill or LLM stage). */
+export interface ProgressItem {
+    agent_name?: string;
+    skill_info?: {
+        name?: string;
+        type?: string;
+        checked?: boolean;
+        args?: Array<{
+            name?: string;
+            type?: string;
+            value?: unknown;
+        }>;
+    };
+    status?: string;
+    answer?: string | Record<string, unknown>;
+    description?: string;
+    result?: string;
+    stage?: string;
+    input_message?: string;
+}
+export interface AgentInfo {
+    id: string;
+    key: string;
+    version: string;
+}
+export declare function buildChatUrl(baseUrl: string, agentId: string): string;
+export declare function buildAgentInfoUrl(baseUrl: string, agentId: string, version: string): string;
+export declare function fetchAgentInfo(options: {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    version: string;
+    businessDomain?: string;
+}): Promise<AgentInfo>;
+export declare function extractText(data: unknown): string;
+export declare function processIncrementalUpdate(data: {
+    key?: string[];
+    content?: unknown;
+    action?: string;
+}, result: Record<string, unknown>): void;
+export declare function sendChatRequest(options: SendChatRequestOptions): Promise<ChatResult>;
+export interface SendChatRequestStreamCallbacks {
+    onTextDelta: (fullText: string) => void;
+    /** Optional: called when message.content.middle_answer.progress updates (tool/skill steps). */
+    onProgress?: (progress: ProgressItem[]) => void;
+}
+/**
+ * Stream-only entry point for TUI: same as sendChatRequest with stream=true,
+ * but invokes onTextDelta(fullText) for each incremental text update instead of writing to stdout.
+ */
+export declare function sendChatRequestStream(options: SendChatRequestOptions, callbacks: SendChatRequestStreamCallbacks): Promise<ChatResult>;

package/dist/api/agent-chat.js

@@ -0,0 +1,379 @@
+import { fetchTextOrThrow, HttpError } from "../utils/http.js";
+import { normalizeDisplayText } from "../utils/display-text.js";
+const CHAT_PATH = "/api/agent-factory/v1/app";
+const AGENT_INFO_PATH = "/api/agent-factory/v3/agent-market/agent";
+export function buildChatUrl(baseUrl, agentId) {
+    const base = baseUrl.replace(/\/+$/, "");
+    return `${base}${CHAT_PATH}/${agentId}/chat/completion`;
+}
+export function buildAgentInfoUrl(baseUrl, agentId, version) {
+    const base = baseUrl.replace(/\/+$/, "");
+    return `${base}${AGENT_INFO_PATH}/${agentId}/version/${version}?is_visit=true`;
+}
+export async function fetchAgentInfo(options) {
+    const { baseUrl, accessToken, agentId, version, businessDomain = "bd_public" } = options;
+    const url = buildAgentInfoUrl(baseUrl, agentId, version);
+    const { body } = await fetchTextOrThrow(url, {
+        method: "GET",
+        headers: {
+            accept: "application/json, text/plain, */*",
+            Authorization: `Bearer ${accessToken}`,
+            token: accessToken,
+            "x-business-domain": businessDomain,
+            "x-language": "zh-CN",
+            "x-requested-with": "XMLHttpRequest",
+        },
+    });
+    const data = JSON.parse(body);
+    if (!data.id || !data.key) {
+        throw new Error("Agent info response did not include id and key.");
+    }
+    return {
+        id: data.id,
+        key: data.key,
+        version: typeof data.version === "string" ? data.version : version,
+    };
+}
+function getByPath(obj, path) {
+    let current = obj;
+    for (const key of path) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function setByPath(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i];
+        const next = path[i + 1];
+        if (!(key in current) || typeof current[key] !== "object") {
+            current[key] = typeof next === "number" ? [] : {};
+        }
+        current = current[key];
+    }
+    current[path[path.length - 1]] = value;
+}
+function stringFromAnswerObject(obj) {
+    const answer = obj.answer;
+    const block = obj.block_answer;
+    const src = answer ?? block;
+    if (!src || typeof src !== "object")
+        return "";
+    const d = typeof src.description === "string" ? src.description : "";
+    const c = typeof src.code === "string" ? src.code : "";
+    const s = typeof src.solution === "string" ? src.solution : "";
+    const parts = [d, c ? `code: ${c}` : "", s ? `solution: ${s}` : ""].filter(Boolean);
+    return parts.join("\n");
+}
+export function extractText(data) {
+    if (!data || typeof data !== "object")
+        return "";
+    const obj = data;
+    const fa = obj.final_answer;
+    if (fa?.answer && typeof fa.answer === "object") {
+        const ans = fa.answer;
+        if (typeof ans.text === "string")
+            return ans.text;
+    }
+    if (typeof fa?.text === "string") {
+        return fa.text;
+    }
+    const msg = obj.message;
+    if (typeof msg?.text === "string") {
+        return msg.text;
+    }
+    if (msg?.content && typeof msg.content === "object") {
+        const content = msg.content;
+        if (typeof content.text === "string")
+            return content.text;
+        const contentFinalAnswer = content.final_answer;
+        if (contentFinalAnswer?.answer && typeof contentFinalAnswer.answer === "object") {
+            const answer = contentFinalAnswer.answer;
+            if (typeof answer.text === "string")
+                return answer.text;
+        }
+        if (typeof contentFinalAnswer?.text === "string") {
+            return contentFinalAnswer.text;
+        }
+        const other = contentFinalAnswer?.answer_type_other;
+        if (other && typeof other === "object") {
+            const desc = stringFromAnswerObject(other);
+            if (desc)
+                return desc;
+        }
+    }
+    const topOther = fa?.answer_type_other;
+    if (topOther && typeof topOther === "object") {
+        const desc = stringFromAnswerObject(topOther);
+        if (desc)
+            return desc;
+    }
+    const answer = obj.answer;
+    if (typeof answer?.text === "string") {
+        return answer.text;
+    }
+    return "";
+}
+export function processIncrementalUpdate(data, result) {
+    const path = data.key;
+    const content = data.content;
+    const action = data.action;
+    if (!path || path.length === 0)
+        return;
+    if (action === "upsert" && content !== undefined) {
+        setByPath(result, path, content);
+    }
+    else if (action === "append") {
+        const existing = getByPath(result, path);
+        const newVal = typeof existing === "string"
+            ? existing + (typeof content === "string" ? content : String(content ?? ""))
+            : String(content ?? "");
+        setByPath(result, path, newVal);
+    }
+    else if (action === "remove") {
+        if (path.length === 1) {
+            delete result[path[0]];
+        }
+    }
+}
+function parseJsonResponse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("Agent chat returned invalid JSON.");
+    }
+}
+function getProgressFromResult(result) {
+    const raw = getByPath(result, ["message", "content", "middle_answer", "progress"]);
+    if (!Array.isArray(raw) || raw.length === 0)
+        return [];
+    return raw.filter((item) => item != null && typeof item === "object").map((item) => {
+        if (!item || typeof item !== "object")
+            return {};
+        const o = item;
+        const answer = o.answer;
+        return {
+            agent_name: typeof o.agent_name === "string" ? o.agent_name : undefined,
+            skill_info: o.skill_info && typeof o.skill_info === "object"
+                ? {
+                    name: typeof o.skill_info.name === "string"
+                        ? normalizeDisplayText(o.skill_info.name)
+                        : undefined,
+                    type: typeof o.skill_info.type === "string"
+                        ? o.skill_info.type
+                        : undefined,
+                    checked: typeof o.skill_info.checked === "boolean"
+                        ? o.skill_info.checked
+                        : undefined,
+                    args: Array.isArray(o.skill_info.args)
+                        ? o.skill_info.args
+                            .filter((arg) => arg && typeof arg === "object")
+                            .map((arg) => ({
+                            name: typeof arg.name === "string" ? normalizeDisplayText(arg.name) : undefined,
+                            type: typeof arg.type === "string" ? arg.type : undefined,
+                            value: typeof arg.value === "string"
+                                ? normalizeDisplayText(arg.value)
+                                : arg.value,
+                        }))
+                        : undefined,
+                }
+                : undefined,
+            status: typeof o.status === "string" ? normalizeDisplayText(o.status) : undefined,
+            answer: typeof answer === "string"
+                ? normalizeDisplayText(answer)
+                : answer && typeof answer === "object" && answer !== null
+                    ? answer
+                    : undefined,
+            description: typeof o.description === "string" ? normalizeDisplayText(o.description) : undefined,
+            result: typeof o.result === "string" ? normalizeDisplayText(o.result) : undefined,
+            stage: typeof o.stage === "string" ? normalizeDisplayText(o.stage) : undefined,
+            input_message: typeof o.input_message === "string" ? normalizeDisplayText(o.input_message) : undefined,
+        };
+    });
+}
+function applySseDataLine(line, state, verbose, onTextDelta, onProgress) {
+    if (!line.startsWith("data: ")) {
+        return;
+    }
+    const dataStr = line.slice(6).trim();
+    if (dataStr === "" || dataStr === "[DONE]") {
+        return;
+    }
+    try {
+        const data = JSON.parse(dataStr);
+        processIncrementalUpdate(data, state.result);
+        if (data.key?.length === 1 && data.key[0] === "conversation_id" && data.action === "upsert") {
+            state.conversationId =
+                typeof data.content === "string" ? data.content : String(data.content ?? "");
+        }
+        const progress = getProgressFromResult(state.result);
+        if (progress.length > 0 && onProgress) {
+            onProgress(progress);
+        }
+        const text = normalizeDisplayText(extractText(state.result));
+        if (text && text !== state.lastText) {
+            if (onTextDelta) {
+                onTextDelta(text);
+            }
+            else {
+                const delta = text.slice(state.lastText.length);
+                process.stdout.write(delta);
+            }
+            state.lastText = text;
+        }
+    }
+    catch {
+        if (verbose) {
+            console.error(`SSE parse skip: ${dataStr}`);
+        }
+    }
+}
+export async function sendChatRequest(options) {
+    const { baseUrl, accessToken, agentId, agentKey, agentVersion, query, conversationId, stream, verbose, businessDomain = "bd_public", } = options;
+    const url = buildChatUrl(baseUrl, agentId);
+    const body = {
+        agent_id: agentId,
+        agent_key: agentKey,
+        agent_version: agentVersion,
+        query,
+        stream,
+    };
+    if (conversationId) {
+        body.conversation_id = conversationId;
+    }
+    const headers = {
+        "Content-Type": "application/json",
+        accept: stream ? "text/event-stream" : "application/json",
+        Authorization: `Bearer ${accessToken}`,
+        "Accept-Language": "zh-CN",
+        "x-Language": "zh-CN",
+        "x-business-domain": businessDomain,
+    };
+    if (verbose) {
+        console.error(`POST ${url}`);
+        console.error(`Headers: ${JSON.stringify(headers)}`);
+        console.error(`Body: ${JSON.stringify(body)}`);
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Agent chat request failed: ${message}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!response.ok) {
+        const text = await response.text();
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    if (stream && contentType.includes("text/event-stream")) {
+        return handleStreamResponse(response, verbose);
+    }
+    const text = await response.text();
+    const json = parseJsonResponse(text);
+    const resultText = normalizeDisplayText(extractText(json));
+    const convId = json.conversation_id;
+    const progress = getProgressFromResult(json);
+    return { text: resultText, conversationId: convId, progress };
+}
+/**
+ * Stream-only entry point for TUI: same as sendChatRequest with stream=true,
+ * but invokes onTextDelta(fullText) for each incremental text update instead of writing to stdout.
+ */
+export async function sendChatRequestStream(options, callbacks) {
+    const opts = { ...options, stream: true };
+    const { baseUrl, accessToken, agentId, agentKey, agentVersion, query, conversationId, verbose, businessDomain = "bd_public", } = opts;
+    const url = buildChatUrl(baseUrl, agentId);
+    const body = {
+        agent_id: agentId,
+        agent_key: agentKey,
+        agent_version: agentVersion,
+        query,
+        stream: true,
+    };
+    if (conversationId) {
+        body.conversation_id = conversationId;
+    }
+    const headers = {
+        "Content-Type": "application/json",
+        accept: "text/event-stream",
+        Authorization: `Bearer ${accessToken}`,
+        "Accept-Language": "zh-CN",
+        "x-Language": "zh-CN",
+        "x-business-domain": businessDomain,
+    };
+    if (verbose) {
+        console.error(`POST ${url}`);
+        console.error(`Headers: ${JSON.stringify(headers)}`);
+        console.error(`Body: ${JSON.stringify(body)}`);
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Agent chat request failed: ${message}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!response.ok) {
+        const text = await response.text();
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    if (contentType.includes("text/event-stream")) {
+        return handleStreamResponse(response, verbose, callbacks.onTextDelta, callbacks.onProgress);
+    }
+    const text = await response.text();
+    const json = parseJsonResponse(text);
+    const resultText = normalizeDisplayText(extractText(json));
+    const convId = json.conversation_id;
+    callbacks.onTextDelta(resultText);
+    return { text: resultText, conversationId: convId, progress: getProgressFromResult(json) };
+}
+async function handleStreamResponse(response, verbose, onTextDelta, onProgress) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new Error("No response body for stream");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const state = {
+        result: {},
+        conversationId: undefined,
+        lastText: "",
+    };
+    const applyLine = (line) => {
+        applySseDataLine(line, state, verbose, onTextDelta, onProgress);
+    };
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            applyLine(line.trimEnd());
+        }
+    }
+    if (buffer.trim()) {
+        applyLine(buffer.trimEnd());
+    }
+    if (!onTextDelta && state.lastText && !state.lastText.endsWith("\n")) {
+        process.stdout.write("\n");
+    }
+    const finalText = normalizeDisplayText(extractText(state.result) || state.lastText);
+    return { text: finalText, conversationId: state.conversationId };
+}

package/dist/api/agent-list.d.ts

@@ -0,0 +1,12 @@
+export interface ListAgentsOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    name?: string;
+    offset?: number;
+    limit?: number;
+    category_id?: string;
+    custom_space_id?: string;
+    is_to_square?: number;
+}
+export declare function listAgents(options: ListAgentsOptions): Promise<string>;

package/dist/api/agent-list.js

@@ -0,0 +1,33 @@
+import { HttpError } from "../utils/http.js";
+export async function listAgents(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", name = "", offset = 0, limit = 50, category_id = "", custom_space_id = "", is_to_square = 1, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/published/agent`;
+    const body = JSON.stringify({
+        offset,
+        limit,
+        category_id,
+        name,
+        custom_space_id,
+        is_to_square,
+    });
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            accept: "application/json, text/plain, */*",
+            "accept-language": "zh-CN",
+            authorization: `Bearer ${accessToken}`,
+            token: accessToken,
+            "x-business-domain": businessDomain,
+            "x-language": "zh-CN",
+            "x-requested-with": "XMLHttpRequest",
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}

package/dist/api/context-loader.d.ts

@@ -0,0 +1,115 @@
+/** Per-call options for context-loader MCP. */
+export interface ContextLoaderCallOptions {
+    mcpUrl: string;
+    knId: string;
+    accessToken: string;
+}
+/** Layer 1: kn_search arguments. */
+export interface KnSearchArgs {
+    query: string;
+    only_schema?: boolean;
+}
+/** Layer 1: kn_schema_search arguments. */
+export interface KnSchemaSearchArgs {
+    query: string;
+    max_concepts?: number;
+}
+/** Condition for query_object_instance and query_instance_subgraph. */
+export interface ConditionSpec {
+    operation: "and" | "or";
+    sub_conditions: Array<{
+        field?: string;
+        operation?: string;
+        value_from?: "const";
+        value?: unknown;
+    }>;
+}
+/** Layer 2: query_object_instance arguments. */
+export interface QueryObjectInstanceArgs {
+    ot_id: string;
+    limit?: number;
+    condition: ConditionSpec;
+}
+/** Layer 2: query_instance_subgraph relation type path. */
+export interface RelationTypePath {
+    object_types: Array<{
+        id: string;
+        condition: ConditionSpec;
+        limit?: number;
+    }>;
+    relation_types: Array<{
+        relation_type_id: string;
+        source_object_type_id: string;
+        target_object_type_id: string;
+    }>;
+}
+/** Layer 2: query_instance_subgraph arguments. */
+export interface QueryInstanceSubgraphArgs {
+    relation_type_paths: RelationTypePath[];
+}
+/** Layer 3: get_logic_properties_values arguments. */
+export interface GetLogicPropertiesValuesArgs {
+    ot_id: string;
+    query: string;
+    _instance_identities: Record<string, string>[];
+    properties: string[];
+    additional_context?: string;
+}
+/** Layer 3: get_action_info arguments. */
+export interface GetActionInfoArgs {
+    at_id: string;
+    _instance_identity: Record<string, string>;
+}
+/** Error when get_logic_properties_values returns MISSING_INPUT_PARAMS. */
+export interface MissingInputParamsError {
+    error_code: "MISSING_INPUT_PARAMS";
+    message: string;
+    missing: Array<{
+        property: string;
+        params: Array<{
+            name: string;
+            type: string;
+            hint: string;
+        }>;
+    }>;
+}
+/** Build retry hint from MISSING_INPUT_PARAMS response. */
+export declare function formatMissingInputParamsHint(err: MissingInputParamsError): string;
+/** Guardrail: value_from only supports "const"; must appear with value. */
+export declare function validateCondition(condition: unknown): void;
+/** Guardrail: _instance_identity must be a plain object (from Layer 2 output, not fabricated). */
+export declare function validateInstanceIdentity(v: unknown, label: string): void;
+/** Guardrail: _instance_identities must be array of plain objects from Layer 2. */
+export declare function validateInstanceIdentities(v: unknown): void;
+/** Layer 1: kn_search. Returns object_types, relation_types, action_types. */
+export declare function knSearch(options: ContextLoaderCallOptions, args: KnSearchArgs): Promise<unknown>;
+/** Layer 1: kn_schema_search. Returns concepts (candidate discovery only). */
+export declare function knSchemaSearch(options: ContextLoaderCallOptions, args: KnSchemaSearchArgs): Promise<unknown>;
+/** Layer 2: query_object_instance. Returns datas with _instance_identity. */
+export declare function queryObjectInstance(options: ContextLoaderCallOptions, args: QueryObjectInstanceArgs): Promise<unknown>;
+/** Layer 2: query_instance_subgraph. Returns entries with nested _instance_identity. */
+export declare function queryInstanceSubgraph(options: ContextLoaderCallOptions, args: QueryInstanceSubgraphArgs): Promise<unknown>;
+/** Layer 3: get_logic_properties_values. Throws with retry hint on MISSING_INPUT_PARAMS. */
+export declare function getLogicPropertiesValues(options: ContextLoaderCallOptions, args: GetLogicPropertiesValuesArgs): Promise<unknown>;
+/** Layer 3: get_action_info. Returns _dynamic_tools. */
+export declare function getActionInfo(options: ContextLoaderCallOptions, args: GetActionInfoArgs): Promise<unknown>;
+/** MCP tools/list. Returns list of available tools. */
+export declare function listTools(options: ContextLoaderCallOptions, params?: {
+    cursor?: string;
+}): Promise<unknown>;
+/** MCP resources/list. Returns list of available resources. */
+export declare function listResources(options: ContextLoaderCallOptions, params?: {
+    cursor?: string;
+}): Promise<unknown>;
+/** MCP resources/read. Returns resource content by URI. */
+export declare function readResource(options: ContextLoaderCallOptions, uri: string): Promise<unknown>;
+/** MCP resources/templates/list. Returns list of resource templates. */
+export declare function listResourceTemplates(options: ContextLoaderCallOptions, params?: {
+    cursor?: string;
+}): Promise<unknown>;
+/** MCP prompts/list. Returns list of available prompts. */
+export declare function listPrompts(options: ContextLoaderCallOptions, params?: {
+    cursor?: string;
+}): Promise<unknown>;
+/** MCP prompts/get. Returns prompt by name with optional arguments. */
+export declare function getPrompt(options: ContextLoaderCallOptions, name: string, args?: Record<string, unknown>): Promise<unknown>;