@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.2

package/dist/api/semantic-search.js

@@ -22,6 +22,11 @@ export async function semanticSearch(options) {
     }
     return body;
 }
+/**
+ * @deprecated Use Context Loader `search_schema` for new schema discovery integrations.
+ * The HTTP `kn_search` endpoint is kept only as a compatibility entry point
+ * and may not receive new `search_schema` capabilities.
+ */
 export async function knSearchHttp(options) {
     const { baseUrl, accessToken, knId, query, businessDomain = "bd_public", onlySchema = false, } = options;
     const base = baseUrl.replace(/\/+$/, "");

package/dist/api/skills.d.ts

@@ -1,11 +1,13 @@
 export type SkillStatus = "unpublish" | "published" | "offline";
 export type SkillFileType = "zip" | "content";
+export type SkillEditableStatus = SkillStatus | "editing";
+export type SkillCategory = "other_category" | "system";
 export interface SkillSummary {
     id: string;
     name: string;
     description?: string;
     version?: string;
-    status?: SkillStatus;
+    status?: SkillEditableStatus;
     source?: string;
     create_user?: string;
     create_time?: number;
@@ -29,7 +31,7 @@ export interface SkillContentIndex {
     id: string;
     url: string;
     files: SkillFileSummary[];
-    status?: SkillStatus;
+    status?: SkillEditableStatus;
 }
 export interface SkillFileReadResult {
     id: string;
@@ -54,6 +56,22 @@ export interface UpdateSkillStatusResult {
     id: string;
     status: SkillStatus;
 }
+export interface UpdateSkillMetadataResult {
+    id: string;
+    version?: string;
+    status?: SkillEditableStatus;
+}
+export interface UpdateSkillPackageResult {
+    id: string;
+    version?: string;
+    status?: SkillEditableStatus;
+}
+export interface SkillReleaseHistoryInfo extends SkillSummary {
+    category?: SkillCategory;
+    release_desc?: string;
+    release_user?: string;
+    release_time?: number;
+}
 export interface SkillListResult {
     total_count?: number;
     total?: number;
@@ -104,6 +122,23 @@ export interface RegisterSkillZipOptions extends SkillApiBaseOptions {
     source?: string;
     extendInfo?: Record<string, unknown>;
 }
+export interface UpdateSkillMetadataOptions extends SkillApiBaseOptions {
+    skillId: string;
+    name: string;
+    description: string;
+    category: SkillCategory;
+    source?: string;
+    extendInfo?: Record<string, unknown>;
+}
+export interface UpdateSkillPackageContentOptions extends SkillApiBaseOptions {
+    skillId: string;
+    content: string;
+}
+export interface UpdateSkillPackageZipOptions extends SkillApiBaseOptions {
+    skillId: string;
+    filename: string;
+    bytes: Uint8Array;
+}
 export interface UpdateSkillStatusOptions extends SkillApiBaseOptions {
     skillId: string;
     status: SkillStatus;
@@ -119,23 +154,61 @@ export interface DownloadedSkillArchive {
     fileName: string;
     bytes: Uint8Array;
 }
+export interface SkillHistoryVersionOptions extends SkillApiBaseOptions {
+    skillId: string;
+    version: string;
+}
 export interface InstallSkillArchiveOptions {
     bytes: Uint8Array;
     directory: string;
     force?: boolean;
 }
+export interface SkillManagementContentData {
+    skill_id: string;
+    name: string;
+    description: string;
+    version: string;
+    status: SkillEditableStatus;
+    source: string;
+    file_type: "zip" | "content";
+    url?: string;
+    content?: string;
+    files: SkillFileSummary[];
+}
+export interface GetSkillManagementContentOptions extends SkillApiBaseOptions {
+    skillId: string;
+    responseMode?: "url" | "content";
+}
+export interface ReadSkillManagementFileOptions extends SkillApiBaseOptions {
+    skillId: string;
+    relPath: string;
+}
+export interface DownloadSkillManagementOptions extends SkillApiBaseOptions {
+    skillId: string;
+    responseMode?: "url" | "content";
+}
 export declare function listSkills(options: ListSkillsOptions): Promise<SkillListResult>;
 export declare function listSkillMarket(options: ListSkillMarketOptions): Promise<SkillListResult>;
 export declare function getSkill(options: GetSkillOptions): Promise<SkillInfo>;
+export declare function getSkillMarketDetail(options: GetSkillOptions): Promise<SkillInfo>;
 export declare function deleteSkill(options: GetSkillOptions): Promise<DeleteSkillResult>;
 export declare function updateSkillStatus(options: UpdateSkillStatusOptions): Promise<UpdateSkillStatusResult>;
+export declare function updateSkillMetadata(options: UpdateSkillMetadataOptions): Promise<UpdateSkillMetadataResult>;
 export declare function registerSkillContent(options: RegisterSkillContentOptions): Promise<RegisterSkillResult>;
 export declare function registerSkillZip(options: RegisterSkillZipOptions): Promise<RegisterSkillResult>;
+export declare function updateSkillPackageContent(options: UpdateSkillPackageContentOptions): Promise<UpdateSkillPackageResult>;
+export declare function updateSkillPackageZip(options: UpdateSkillPackageZipOptions): Promise<UpdateSkillPackageResult>;
 export declare function getSkillContentIndex(options: GetSkillOptions): Promise<SkillContentIndex>;
 export declare function fetchSkillContent(options: GetSkillOptions): Promise<string>;
 export declare function readSkillFile(options: ReadSkillFileOptions): Promise<SkillFileReadResult>;
 export declare function fetchSkillFile(options: ReadSkillFileOptions): Promise<Uint8Array>;
 export declare function downloadSkill(options: DownloadSkillOptions): Promise<DownloadedSkillArchive>;
+export declare function listSkillHistory(options: GetSkillOptions): Promise<SkillReleaseHistoryInfo[]>;
+export declare function republishSkillHistory(options: SkillHistoryVersionOptions): Promise<UpdateSkillPackageResult>;
+export declare function publishSkillHistory(options: SkillHistoryVersionOptions): Promise<UpdateSkillPackageResult>;
+export declare function getSkillManagementContent(options: GetSkillManagementContentOptions): Promise<SkillManagementContentData>;
+export declare function readSkillManagementFile(options: ReadSkillManagementFileOptions): Promise<SkillFileReadResult>;
+export declare function downloadSkillManagementArchive(options: DownloadSkillManagementOptions): Promise<DownloadedSkillArchive>;
 export declare function installSkillArchive(options: InstallSkillArchiveOptions): {
     directory: string;
 };

package/dist/api/skills.js

@@ -87,6 +87,11 @@ export async function getSkill(options) {
     const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
     return normalizeSkillId(unwrapEnvelope(body));
 }
+export async function getSkillMarketDetail(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/market/${encodeURIComponent(options.skillId)}`);
+    const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
 export async function deleteSkill(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}`);
     const { body } = await fetchTextOrThrow(url, { method: "DELETE", headers: baseHeaders(options) });
@@ -101,14 +106,49 @@ export async function updateSkillStatus(options) {
     });
     return normalizeSkillId(unwrapEnvelope(body));
 }
+export async function updateSkillMetadata(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/metadata`);
+    const payload = {
+        name: options.name,
+        description: options.description,
+        category: options.category,
+    };
+    if (options.source)
+        payload.source = options.source;
+    if (options.extendInfo)
+        payload.extend_info = options.extendInfo;
+    const { body } = await fetchTextOrThrow(url, {
+        method: "PUT",
+        headers: { ...baseHeaders(options), "content-type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
 export async function registerSkillContent(options) {
+    // Backend's file_type=content path is half-implemented: it stores
+    // the markdown body but skips skill_file_index, so the skill is
+    // unreadable after publish (GET /skills/:id/content -> 404).
+    // Bundle the content into a 1-file SKILL.md zip and route through
+    // the zip path, which writes skill_file_index correctly.
+    const { default: JSZip } = await import("jszip");
+    const zip = new JSZip();
+    zip.file("SKILL.md", options.content);
+    const bytes = new Uint8Array(await zip.generateAsync({ type: "uint8array", compression: "DEFLATE" }));
+    return registerSkillZip({
+        baseUrl: options.baseUrl,
+        accessToken: options.accessToken,
+        businessDomain: options.businessDomain,
+        filename: "SKILL.md.zip",
+        bytes,
+        source: options.source,
+        extendInfo: options.extendInfo,
+    });
+}
+export async function registerSkillZip(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills`);
     const form = new FormData();
-    form.set("file_type", "content");
-    // Backend's gin form-binder rejects plain string field for `file`
-    // (typed json.RawMessage); needs an actual multipart file part with
-    // filename. See utils/gin.go GetBindMultipartFormRaw.
-    form.set("file", new Blob([options.content], { type: "text/markdown" }), "SKILL.md");
+    form.set("file_type", "zip");
+    form.set("file", new Blob([Buffer.from(options.bytes)]), options.filename);
     if (options.source)
         form.set("source", options.source);
     if (options.extendInfo)
@@ -120,17 +160,22 @@ export async function registerSkillContent(options) {
     });
     return normalizeSkillId(unwrapEnvelope(body));
 }
-export async function registerSkillZip(options) {
-    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills`);
+export async function updateSkillPackageContent(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/package`);
+    const { body } = await fetchTextOrThrow(url, {
+        method: "PUT",
+        headers: { ...baseHeaders(options), "content-type": "application/json" },
+        body: JSON.stringify({ file_type: "content", file: options.content }),
+    });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
+export async function updateSkillPackageZip(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/package`);
     const form = new FormData();
     form.set("file_type", "zip");
     form.set("file", new Blob([Buffer.from(options.bytes)]), options.filename);
-    if (options.source)
-        form.set("source", options.source);
-    if (options.extendInfo)
-        form.set("extend_info", JSON.stringify(options.extendInfo));
     const { body } = await fetchTextOrThrow(url, {
-        method: "POST",
+        method: "PUT",
         headers: baseHeaders(options),
         body: form,
     });
@@ -169,6 +214,57 @@ export async function downloadSkill(options) {
         bytes: body,
     };
 }
+export async function listSkillHistory(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/history`);
+    const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
+export async function republishSkillHistory(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/history/republish`);
+    const { body } = await fetchTextOrThrow(url, {
+        method: "POST",
+        headers: { ...baseHeaders(options), "content-type": "application/json" },
+        body: JSON.stringify({ version: options.version }),
+    });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
+export async function publishSkillHistory(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/history/publish`);
+    const { body } = await fetchTextOrThrow(url, {
+        method: "POST",
+        headers: { ...baseHeaders(options), "content-type": "application/json" },
+        body: JSON.stringify({ version: options.version }),
+    });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
+// ── Management Content (editing-state) API ───────────────────────────────────
+export async function getSkillManagementContent(options) {
+    const url = new URL(buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/management/content`));
+    if (options.responseMode)
+        url.searchParams.set("response_mode", options.responseMode);
+    const { body } = await fetchTextOrThrow(url, { headers: baseHeaders(options) });
+    return unwrapEnvelope(body);
+}
+export async function readSkillManagementFile(options) {
+    const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/management/files/read`);
+    const { body } = await fetchTextOrThrow(url, {
+        method: "POST",
+        headers: { ...baseHeaders(options), "content-type": "application/json" },
+        body: JSON.stringify({ rel_path: options.relPath }),
+    });
+    return normalizeSkillId(unwrapEnvelope(body));
+}
+export async function downloadSkillManagementArchive(options) {
+    const url = new URL(buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills/${encodeURIComponent(options.skillId)}/management/download`));
+    if (options.responseMode)
+        url.searchParams.set("response_mode", options.responseMode);
+    const { response, body } = await fetchBytesOrThrow(url, { headers: baseHeaders(options) });
+    const serverName = parseContentDisposition(response.headers.get("content-disposition"));
+    return {
+        fileName: basename(serverName || `${options.skillId}.zip`),
+        bytes: body,
+    };
+}
 export function installSkillArchive(options) {
     const targetDir = resolve(options.directory);
     const existed = existsSync(targetDir);

package/dist/api/trace.d.ts

@@ -25,6 +25,11 @@ export interface RawSpan {
         code?: string;
     };
     attributes?: Record<string, unknown>;
+    events?: Array<{
+        name?: string;
+        time?: string;
+        attributes?: Record<string, unknown>;
+    }>;
     /** OTel traceId for the trace this span belongs to (when known). */
     traceId?: string;
 }

package/dist/api/trace.js

@@ -48,6 +48,9 @@ function normalizeToRawSpan(source) {
         endTimeUnixNano = isoToNanos(source.endTime);
     const status = source.status;
     const attributes = source.attributes;
+    const events = Array.isArray(source.events)
+        ? source.events
+        : undefined;
     const name = typeof source.name === "string" ? source.name : undefined;
     const traceIdRaw = source.traceId ?? source.trace_id;
     const traceId = typeof traceIdRaw === "string" ? traceIdRaw : undefined;
@@ -59,6 +62,7 @@ function normalizeToRawSpan(source) {
         endTimeUnixNano,
         status,
         attributes,
+        events,
         traceId,
     };
 }

package/dist/cli.js

@@ -108,8 +108,9 @@ Usage:
   kweaver config list-bd
   kweaver config show
 
-  kweaver skill list|get|register|status|delete [options]
+  kweaver skill list|get|market-get|register|status|delete [options]
   kweaver skill market [options]
+  kweaver skill update-metadata|update-package|history|republish|publish-history [options]
   kweaver skill content <skill-id> [--raw] [--output file]
   kweaver skill read-file <skill-id> <rel-path> [--raw] [--output file]
   kweaver skill download|install <skill-id> [path] [options]
@@ -134,14 +135,15 @@ Usage:
   kweaver vega query execute|sql [options]
   kweaver vega connector-type list|get [options]
 
+  kweaver context-loader help <subcommand>
   kweaver context-loader config set|use|list|remove|show [options]                (deprecated; not supported with --token)
   kweaver context-loader tools|resources|templates|prompts <kn-id> [--cursor]
   kweaver context-loader resource <kn-id> <uri>
   kweaver context-loader prompt <kn-id> <name> [--args json]
-  kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--max N]
+  kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--concept-groups ids] [--max N]
   kweaver context-loader tool-call <kn-id> <name> --args '<json>'
-  kweaver context-loader kn-search <kn-id> <query> [--only-schema]                 (compat HTTP)
-  kweaver context-loader kn-schema-search <kn-id> <query> [--max N]                (compat HTTP)
+  kweaver context-loader kn-search <kn-id> <query> [--only-schema]                 (deprecated; use search-schema)
+  kweaver context-loader kn-schema-search <kn-id> <query> [--max N]                (deprecated; use search-schema)
   kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
                                                           (omit <kn-id> to fall back to deprecated saved config)
   (alias: kweaver context ...)
@@ -178,7 +180,7 @@ Commands:
   bkn            Knowledge network (CRUD, build, validate, export, stats, push/pull,
                  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)
+  skill          Skill registry and market (register, edit, history, progressive read, download/install)
   toolbox        Agent toolbox lifecycle (create, list, publish, delete, export, import)
   tool           Tools inside a toolbox (upload OpenAPI spec, list, enable/disable)
   vega           Vega observability (catalog, resource, query/sql, connector-type, health/stats/inspect)

package/dist/commands/agent/mode.d.ts

@@ -0,0 +1,6 @@
+export declare const AGENT_MODES: readonly ["default", "dolphin", "react"];
+export type AgentMode = typeof AGENT_MODES[number];
+export declare const AGENT_MODE_HELP = "  --mode <mode>          Agent mode: default, dolphin, react (default: default)\n\nAgent mode config:\n  config.mode accepts \"default\", \"dolphin\", or \"react\".\n  If --mode is provided, it overrides config.mode.\n  If neither --mode nor config.mode is provided, the CLI sends config.mode=\"default\".\n\nReAct config:\n  react_config is only valid when mode is \"react\".\n  Provide it through --config or --config-path, for example:\n    {\n      \"mode\": \"react\",\n      \"react_config\": {\n        \"disable_history_in_a_conversation\": false,\n        \"disable_llm_cache\": false\n      }\n    }";
+export declare function parseAgentMode(value: string, flagName?: string): AgentMode;
+export declare function normalizeAgentConfigInput(value: unknown): Record<string, unknown>;
+export declare function applyAgentModeToConfig(config: Record<string, unknown>, explicitMode?: AgentMode): void;

package/dist/commands/agent/mode.js

@@ -0,0 +1,75 @@
+export const AGENT_MODES = ["default", "dolphin", "react"];
+const AGENT_MODE_SET = new Set(AGENT_MODES);
+export const AGENT_MODE_HELP = `  --mode <mode>          Agent mode: default, dolphin, react (default: default)
+
+Agent mode config:
+  config.mode accepts "default", "dolphin", or "react".
+  If --mode is provided, it overrides config.mode.
+  If neither --mode nor config.mode is provided, the CLI sends config.mode="default".
+
+ReAct config:
+  react_config is only valid when mode is "react".
+  Provide it through --config or --config-path, for example:
+    {
+      "mode": "react",
+      "react_config": {
+        "disable_history_in_a_conversation": false,
+        "disable_llm_cache": false
+      }
+    }`;
+function formatModeValue(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function looksLikeAgentConfig(value) {
+    return [
+        "mode",
+        "input",
+        "output",
+        "llms",
+        "react_config",
+        "system_prompt",
+        "data_source",
+        "skills",
+        "memory",
+        "conversation_history_config",
+    ].some((field) => field in value);
+}
+export function parseAgentMode(value, flagName = "--mode") {
+    const mode = value.trim();
+    if (!AGENT_MODE_SET.has(mode)) {
+        throw new Error(`${flagName} must be one of: ${AGENT_MODES.join(", ")}`);
+    }
+    return mode;
+}
+export function normalizeAgentConfigInput(value) {
+    if (!isRecord(value)) {
+        throw new Error("Agent config file must contain a JSON object.");
+    }
+    const nestedConfig = value.config;
+    if (isRecord(nestedConfig) && !looksLikeAgentConfig(value)) {
+        return nestedConfig;
+    }
+    return value;
+}
+export function applyAgentModeToConfig(config, explicitMode) {
+    if (explicitMode) {
+        config.mode = explicitMode;
+        return;
+    }
+    const currentMode = config.mode;
+    if (currentMode === undefined || currentMode === null || currentMode === "") {
+        config.mode = "default";
+        return;
+    }
+    if (typeof currentMode !== "string") {
+        throw new Error(`config.mode must be one of: ${AGENT_MODES.join(", ")}; got ${formatModeValue(currentMode)}`);
+    }
+    const mode = currentMode.trim();
+    if (!AGENT_MODE_SET.has(mode)) {
+        throw new Error(`config.mode must be one of: ${AGENT_MODES.join(", ")}; got ${formatModeValue(currentMode)}`);
+    }
+    config.mode = mode;
+}