@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

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

@@ -0,0 +1,49 @@
+/**
+ * `RawSpan`-flavored view of conversation trace data, for diagnose rule
+ * predicates. The HTTP / two-hop / auth concerns live in `./agent-observability`;
+ * this module only normalizes the raw `_source` documents into the minimal
+ * span shape rules read.
+ */
+export { TraceFetchError } from "./agent-observability.js";
+export interface GetSpansByConversationIdOpts {
+    baseUrl: string;
+    token: string;
+    businessDomain: string;
+    conversationId: string;
+    /** Cap on `terms` aggregation bucket count. Default 100. */
+    maxTraceIds?: number;
+    /** Cap on spans returned by the second query. Default 2000. */
+    maxSpans?: number;
+}
+export interface RawSpan {
+    spanId: string;
+    parentSpanId: string | null;
+    name?: string;
+    startTimeUnixNano?: string;
+    endTimeUnixNano?: string;
+    status?: {
+        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;
+}
+export interface GetSpansByConversationIdResult {
+    /** Distinct traceIds observed for this conversation. */
+    traceIds: string[];
+    /** All spans across all observed traceIds, mapped to `RawSpan` shape. */
+    spans: RawSpan[];
+    /** True if the agg saw `sum_other_doc_count > 0` (more traceIds than maxTraceIds). */
+    truncated: boolean;
+}
+/**
+ * ISO timestamp → nanos-since-epoch string. Preserves up to 9 fractional digits.
+ * Falls back to ms precision when the input lacks a fractional component.
+ */
+export declare function isoToNanos(iso: string | undefined): string | undefined;
+export declare function getSpansByConversationId(opts: GetSpansByConversationIdOpts): Promise<GetSpansByConversationIdResult>;

package/dist/api/trace.js

@@ -0,0 +1,85 @@
+/**
+ * `RawSpan`-flavored view of conversation trace data, for diagnose rule
+ * predicates. The HTTP / two-hop / auth concerns live in `./agent-observability`;
+ * this module only normalizes the raw `_source` documents into the minimal
+ * span shape rules read.
+ */
+import { fetchRawSpansByConversation } from "./agent-observability.js";
+export { TraceFetchError } from "./agent-observability.js";
+/**
+ * ISO timestamp → nanos-since-epoch string. Preserves up to 9 fractional digits.
+ * Falls back to ms precision when the input lacks a fractional component.
+ */
+export function isoToNanos(iso) {
+    if (!iso)
+        return undefined;
+    // "YYYY-MM-DDTHH:MM:SS.fffffffffZ" or "...+08:00"
+    const m = iso.match(/^(.+?)\.(\d{1,9})(Z|[+-]\d{2}:?\d{2})$/);
+    if (!m) {
+        const ms = Date.parse(iso);
+        if (Number.isNaN(ms))
+            return undefined;
+        return (BigInt(ms) * 1000000n).toString();
+    }
+    const ms = Date.parse(m[1] + m[3]);
+    if (Number.isNaN(ms))
+        return undefined;
+    const frac = m[2].padEnd(9, "0").slice(0, 9);
+    const seconds = BigInt(Math.floor(ms / 1000));
+    return (seconds * 1000000000n + BigInt(frac)).toString();
+}
+function normalizeToRawSpan(source) {
+    const spanIdRaw = source.spanId ?? source.span_id;
+    const spanId = typeof spanIdRaw === "string" ? spanIdRaw : "";
+    if (!spanId)
+        return null;
+    const parentRaw = source.parentSpanId ?? source.parent_span_id ?? source.parentSpanID;
+    const parentSpanId = typeof parentRaw === "string" && parentRaw !== "" && parentRaw !== "0" ? parentRaw : null;
+    // Prefer pre-normalized nanos (synthetic fixtures); else derive from ISO.
+    let startTimeUnixNano;
+    let endTimeUnixNano;
+    if (typeof source.startTimeUnixNano === "string")
+        startTimeUnixNano = source.startTimeUnixNano;
+    else if (typeof source.startTime === "string")
+        startTimeUnixNano = isoToNanos(source.startTime);
+    if (typeof source.endTimeUnixNano === "string")
+        endTimeUnixNano = source.endTimeUnixNano;
+    else if (typeof source.endTime === "string")
+        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;
+    return {
+        spanId,
+        parentSpanId,
+        name,
+        startTimeUnixNano,
+        endTimeUnixNano,
+        status,
+        attributes,
+        events,
+        traceId,
+    };
+}
+export async function getSpansByConversationId(opts) {
+    const fetched = await fetchRawSpansByConversation({
+        baseUrl: opts.baseUrl,
+        accessToken: opts.token,
+        businessDomain: opts.businessDomain,
+        conversationId: opts.conversationId,
+        maxTraceIds: opts.maxTraceIds,
+        maxSpans: opts.maxSpans,
+    });
+    const spans = [];
+    for (const src of fetched.rawSources) {
+        const span = normalizeToRawSpan(src);
+        if (span)
+            spans.push(span);
+    }
+    return { traceIds: fetched.traceIds, spans, truncated: fetched.truncated };
+}

package/dist/api/vega.d.ts

@@ -238,3 +238,56 @@ export interface ListAllVegaResourcesOptions {
 /** List all Vega resources (no catalog filter). Uses GET /resources — not /resources/list, which
  * conflicts with GET /resources/{id} on some gateways (path segment "list" is treated as an id). */
 export declare function listAllVegaResources(options: ListAllVegaResourcesOptions): Promise<string>;
+export interface ListTablesWithColumnsOptions {
+    baseUrl: string;
+    accessToken: string;
+    /** A vega catalog id, not a legacy data-connection datasource UUID. */
+    id: string;
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+    businessDomain?: string;
+    autoScan?: boolean;
+}
+/**
+ * List tables with column details from a vega catalog.
+ *
+ * Two-stage fetch:
+ *   1. GET /api/vega-backend/v1/catalogs/{id}/resources?category=table — list summaries
+ *   2. For each resource: GET /api/vega-backend/v1/resources/{rid} — pull source_metadata.columns
+ *
+ * If the catalog has no resources and `autoScan=true`, triggers a discover and
+ * retries the list once. The optional `keyword` filters summaries client-side
+ * before the per-resource detail fetches — useful to keep N+1 down to k+1.
+ *
+ * `id` is a vega catalog id.
+ */
+export declare function listTablesWithColumns(options: ListTablesWithColumnsOptions): Promise<string>;
+export interface ScanMetadataOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    /** Retained for signature compatibility; ignored — vega catalog already knows its connector_type. */
+    dsType?: string;
+    businessDomain?: string;
+}
+/**
+ * Trigger a metadata scan for a vega catalog and wait for completion.
+ * `id` is a vega catalog id (e.g. `d7nicrcjto2s73d9g67g`), not a legacy
+ * data-connection datasource UUID.
+ */
+export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;
+export interface ScanDatasourceMetadataOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+/**
+ * Trigger a metadata scan and wait for completion. `id` is a vega catalog id.
+ *
+ * @deprecated Use {@link scanMetadata} directly. This wrapper exists only for
+ * backward compatibility with callers that used the old data-connection-based
+ * `scanDatasourceMetadata` signature.
+ */
+export declare function scanDatasourceMetadata(options: ScanDatasourceMetadataOptions): Promise<string>;

package/dist/api/vega.js

@@ -488,3 +488,147 @@ export async function listAllVegaResources(options) {
         businessDomain,
     });
 }
+/**
+ * List tables with column details from a vega catalog.
+ *
+ * Two-stage fetch:
+ *   1. GET /api/vega-backend/v1/catalogs/{id}/resources?category=table — list summaries
+ *   2. For each resource: GET /api/vega-backend/v1/resources/{rid} — pull source_metadata.columns
+ *
+ * If the catalog has no resources and `autoScan=true`, triggers a discover and
+ * retries the list once. The optional `keyword` filters summaries client-side
+ * before the per-resource detail fetches — useful to keep N+1 down to k+1.
+ *
+ * `id` is a vega catalog id.
+ */
+export async function listTablesWithColumns(options) {
+    const { baseUrl, accessToken, id, keyword, limit, offset, businessDomain = "bd_public", autoScan = true, } = options;
+    async function listResourceSummaries() {
+        const body = await listVegaCatalogResources({
+            baseUrl,
+            accessToken,
+            id,
+            category: "table",
+            limit,
+            offset,
+            businessDomain,
+        });
+        const parsed = JSON.parse(body);
+        return Array.isArray(parsed) ? parsed : (parsed.entries ?? parsed.data ?? []);
+    }
+    let summaries = await listResourceSummaries();
+    if (summaries.length === 0 && autoScan) {
+        await scanMetadata({ baseUrl, accessToken, id, businessDomain });
+        summaries = await listResourceSummaries();
+    }
+    // Keyword filter applied after autoScan guard: if the catalog has tables but
+    // keyword matches none, we must NOT trigger a redundant discover.
+    if (keyword) {
+        const k = keyword.toLowerCase();
+        summaries = summaries.filter((it) => it.name.toLowerCase().includes(k));
+    }
+    const details = await Promise.all(summaries.map(async (s) => {
+        let body;
+        try {
+            body = await getVegaResource({
+                baseUrl,
+                accessToken,
+                id: s.id,
+                businessDomain,
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new Error(`vega resource ${s.id} fetch failed: ${reason}`);
+        }
+        const parsed = JSON.parse(body);
+        if (Array.isArray(parsed.entries)) {
+            const arr = parsed.entries;
+            if (arr.length === 0) {
+                throw new Error(`vega resource ${s.id} returned empty entries`);
+            }
+            return arr[0];
+        }
+        if (Array.isArray(parsed.data)) {
+            const arr = parsed.data;
+            if (arr.length === 0) {
+                throw new Error(`vega resource ${s.id} returned empty data`);
+            }
+            return arr[0];
+        }
+        return parsed;
+    }));
+    const tables = [];
+    for (const d of details) {
+        const columnsRaw = (d.source_metadata?.columns ?? []);
+        const tablePkArray = extractPrimaryKeys(d);
+        const columns = columnsRaw.map((c) => {
+            const name = String(c.name ?? c.field_name ?? "");
+            const flagged = isColumnPrimaryKey(c) || tablePkArray.includes(name);
+            return {
+                name,
+                type: String(c.type ?? c.field_type ?? "varchar"),
+                comment: typeof c.description === "string"
+                    ? c.description
+                    : (typeof c.comment === "string" ? c.comment : undefined),
+                ...(flagged ? { isPrimaryKey: true } : {}),
+            };
+        });
+        const synthesizedPks = tablePkArray.length > 0
+            ? tablePkArray
+            : columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+        tables.push({
+            name: d.name,
+            columns,
+            ...(synthesizedPks.length > 0 ? { primaryKeys: synthesizedPks } : {}),
+        });
+    }
+    return JSON.stringify(tables);
+}
+// Two PK metadata shapes are recognized — both confirmed conventions:
+//   - per-column `is_primary_key: true` (data-connection metadata standard)
+//   - per-column `column_key === "PRI"` (MySQL INFORMATION_SCHEMA pass-through)
+//   - table-level `primary_keys: string[]` (composite-PK carrier)
+// Other plausible spellings (camelCase, singular keys, SQLite `pk` integer) are
+// intentionally NOT recognized here — adding them speculatively risks false
+// matches and creates code paths the test suite can't pin down. Extend only when
+// a real backend response demonstrates the need.
+function isColumnPrimaryKey(col) {
+    if (col.is_primary_key === true)
+        return true;
+    if (typeof col.column_key === "string" && col.column_key.toUpperCase() === "PRI")
+        return true;
+    return false;
+}
+function extractPrimaryKeys(table) {
+    const arr = table.primary_keys;
+    if (Array.isArray(arr)) {
+        return arr.filter((x) => typeof x === "string");
+    }
+    return [];
+}
+/**
+ * Trigger a metadata scan for a vega catalog and wait for completion.
+ * `id` is a vega catalog id (e.g. `d7nicrcjto2s73d9g67g`), not a legacy
+ * data-connection datasource UUID.
+ */
+export async function scanMetadata(options) {
+    const { baseUrl, accessToken, id, businessDomain = "bd_public" } = options;
+    return discoverVegaCatalog({
+        baseUrl,
+        accessToken,
+        id,
+        wait: true,
+        businessDomain,
+    });
+}
+/**
+ * Trigger a metadata scan and wait for completion. `id` is a vega catalog id.
+ *
+ * @deprecated Use {@link scanMetadata} directly. This wrapper exists only for
+ * backward compatibility with callers that used the old data-connection-based
+ * `scanDatasourceMetadata` signature.
+ */
+export async function scanDatasourceMetadata(options) {
+    return scanMetadata(options);
+}

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,11 +180,12 @@ 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)
   context-loader Context-loader MCP/HTTP (config, tools, resources, search-schema, tool-call, query-*, etc.)
+  trace          Diagnose a single trace with rule-based analysis
   help           Show this message`);
 }
 export async function run(argv) {
@@ -287,6 +290,10 @@ export async function run(argv) {
     if (command === "context-loader" || command === "context") {
         return runContextLoaderCommand(rest);
     }
+    if (command === "trace") {
+        const { runTraceCommand } = await import("./commands/trace.js");
+        return await runTraceCommand(rest);
+    }
     console.error(`Unknown command: ${command}`);
     printHelp();
     return 1;

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;
+}