@kweaver-ai/kweaver-sdk 0.7.3 → 0.8.1

package/README.md

@@ -16,6 +16,26 @@ npm install @kweaver-ai/kweaver-sdk
 
 Requires **Node.js >= 22**.
 
+## API reference (TypeDoc)
+
+Generate HTML from source + TSDoc, then open `docs/reference/typescript-api-html/index.html` (gitignored), or serve locally:
+
+HTML reference auto-discovers **`src/resources/*`**, **`src/api/*`**, and **`src/auth/*`** via TypeDoc's `entryPointStrategy: "expand"` (`typedoc.json`), so newly added modules appear without editing the config. The English build uses `README.md` as the cover page; the Chinese build uses `README.zh.md`. **"Defined in"** GitHub links read `gitRevision` from `TYPEDOC_GIT_REVISION` → `GITHUB_SHA` → fallback `"main"`; CI should pin links to the build SHA: `TYPEDOC_GIT_REVISION=$GITHUB_SHA npm run docs`.
+
+TypeDoc does **not** ship a single-site EN/ZH toggle. Use two outputs: English UI (default) and Chinese UI strings (`docs:zh`, primarily localizes navigation chrome). API descriptions come from TSDoc and stay English unless you maintain duplicate comments elsewhere.
+
+```bash
+cd packages/typescript
+npm install
+npm run docs             # English UI → docs/reference/typescript-api-html/
+npm run docs:serve       # generate + serve http://127.0.0.1:8766
+npm run docs:zh          # Chinese UI + README.zh.md → docs/reference/typescript-api-html-zh/
+npm run docs:serve:zh    # generate + serve http://127.0.0.1:8767
+npm run docs:all         # both folders
+```
+
+> Files inside `docs/reference/**` are generated. Edit `packages/typescript/README*.md` and TSDoc comments in source instead — anything copied into `media/` is overwritten on the next build.
+
 ## Quick Start
 
 ### Authenticate
@@ -174,12 +194,15 @@ kweaver token
 kweaver ds list/get/delete/tables/connect
 kweaver ds import-csv <ds_id> --files <glob> [--table-prefix <p>] [--batch-size 500] [--recreate]
 kweaver dataflow list/run/runs/logs
+kweaver model llm list/get/add/edit/delete/test/chat/--template
+kweaver model small list/get/add/edit/delete/test/embeddings/rerank/--template
 kweaver dataview list/find/get/query/delete
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn create-from-ds <ds_id> --name <name> [--tables t1,t2] [--build]
 kweaver bkn create-from-csv <ds_id> --files <glob> --name <name> [--build]
 kweaver bkn validate/push/pull
 kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn metric list/get/create/search/validate/update/delete/query/dry-run
 kweaver bkn relation-type list/get/create/update/delete
 kweaver bkn action-type list/query/execute
 kweaver bkn subgraph / search
@@ -211,6 +234,30 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` filters one local natural day. If the value cannot be parsed by `new Date(...)`, the CLI falls back to the most recent 20 runs. `kweaver dataflow logs` defaults to summary output; add `--detail` to print indented `input` and `output` payloads.
 
+### Model factory CLI examples
+
+`model` talks to **mf-model-manager** (`/api/mf-model-manager/v1`) for CRUD and **mf-model-api** (`/api/mf-model-api/v1`) for OpenAI-compatible **`chat`**, **`small embeddings`**, and **`small rerank`**. Override origins with `--mf-base-url` / `--mf-api-base-url` or `KWEAVER_MF_MODEL_MANAGER_URL` / `KWEAVER_MF_MODEL_API_URL`. `model llm --template` / `model small --template` prints one offline **`basic`** JSON stub per branch (no API calls). **LLM** `model_type` on the platform is one of **`llm`** (text), **`rlm`** (reasoning), or **`vu`** (vision / multimodal); filter with `kweaver model llm list --type …`. See [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md#llm-model-types).
+
+```bash
+kweaver model llm list --limit 30
+kweaver model llm list --type rlm
+kweaver model llm get <model_id>
+kweaver model llm add --body-file ./llm.json --upstream-url https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions --api-model qwen-plus --api-key-file ~/.dashscope_key
+kweaver model llm chat <model_id> -m "Hello" --no-stream
+kweaver model llm --template > ./llm.json
+kweaver model small list
+kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 512 --embedding-dim 1536 \
+  --model-config-file ./cfg.json
+kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 8192 --embedding-dim 1024 \
+  --upstream-url https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings --api-model text-embedding-v4 --api-key-file ~/.dashscope_key
+kweaver model small test <model_id>
+kweaver model small embeddings <model_id> -i "hello" -i "world"
+kweaver model small rerank <model_id> -q "query" -d "doc a" -d "doc b"
+kweaver model small --template > ./embedding-model-config.json
+```
+
+Full flags: `kweaver model --help` and [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md).
+
 ### Vega `sql` CLI examples
 
 Direct SQL against catalog-backed resources (`POST /api/vega-backend/v1/resources/query`). In SQL, use **`{{<resource_id>}}`** or **`{{.<resource_id>}}`** (Vega resource id from `vega resource list` / `get`) so the backend resolves the physical table and connector. `--resource-type` accepts the connector type of the target data source (run `kweaver vega connector-type list` to see available types). In simple mode, **quote the entire `--query` value** so the shell does not treat `{` / `}` specially.
@@ -256,6 +303,8 @@ kweaver tool debug --toolbox <BOX_ID> <TOOL_ID> \
 | Variable | Description |
 |---|---|
 | `KWEAVER_BASE_URL` | KWeaver instance URL |
+| `KWEAVER_MF_MODEL_MANAGER_URL` | Optional override for mf-model-manager API (defaults from `KWEAVER_BASE_URL` + `/api/mf-model-manager/v1`) |
+| `KWEAVER_MF_MODEL_API_URL` | Optional override for mf-model-api (defaults from `KWEAVER_BASE_URL` + `/api/mf-model-api/v1`) |
 | `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
 | `KWEAVER_TOKEN` | Access token |
 | `KWEAVER_TOKEN_SOURCE` | Internal sentinel set by the CLI when `--token` is passed; do not set manually |

package/README.zh.md

@@ -16,6 +16,24 @@ npm install @kweaver-ai/kweaver-sdk
 
 需要 **Node.js >= 22**。
 
+## API 参考（TypeDoc）
+
+由源码与 TSDoc 生成 HTML，产物在 `docs/reference/typescript-api-html/index.html`（已 gitignore）。`typedoc.json` 用 **`entryPointStrategy: "expand"`** 自动展开 **`src/resources`**、**`src/api`**、**`src/auth`** 整目录，新增模块无需改配置。英文构建用 `README.md`，中文构建用 `README.zh.md`。**「Defined in」** 链接的 `gitRevision` 取 `TYPEDOC_GIT_REVISION` → `GITHUB_SHA` → 回退 `"main"`；CI 中固定到当前 SHA：`TYPEDOC_GIT_REVISION=$GITHUB_SHA npm run docs`。
+
+TypeDoc **不会在同一个站点里提供中英文切换**。做法是生成两套目录：英文界面（默认）与中文界面（**`npm run docs:zh`**），主要翻译导航等界面文案；**API 说明仍以源码里的 TSDoc（英文）为准**。
+
+```bash
+cd packages/typescript
+npm install
+npm run docs             # 英文界面 → docs/reference/typescript-api-html/
+npm run docs:serve       # 生成并访问 http://127.0.0.1:8766
+npm run docs:zh          # 中文界面 + README.zh.md → docs/reference/typescript-api-html-zh/
+npm run docs:serve:zh    # 生成并访问 http://127.0.0.1:8767
+npm run docs:all         # 两套产物都生成
+```
+
+> `docs/reference/**` 下的所有文件均为生成产物。请编辑 `packages/typescript/README*.md` 与源码 TSDoc 注释；`media/` 下的拷贝在下次构建时会被覆盖。
+
 ## 快速上手
 
 ### 认证
@@ -165,9 +183,12 @@ kweaver config show / list-bd / set-bd <value>   # 业务域；show/list-bd 在
 kweaver token
 kweaver ds list/get/delete/tables/connect
 kweaver dataflow list/run/runs/logs
+kweaver model llm list/get/add/edit/delete/test/chat/--template
+kweaver model small list/get/add/edit/delete/test/embeddings/rerank/--template
 kweaver dataview list/find/get/query/delete
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn metric list/get/create/search/validate/update/delete/query/dry-run
 kweaver bkn relation-type list/get/create/update/delete
 kweaver bkn action-type list/query/execute
 kweaver bkn subgraph
@@ -197,6 +218,27 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` 会按本地自然日过滤；如果参数无法被 `new Date(...)` 解析，CLI 会回退到最近 20 条运行记录。`kweaver dataflow logs` 默认输出摘要；加上 `--detail` 会打印带缩进的 `input` 和 `output` 载荷。
 
+### 模型工厂 CLI 示例
+
+- **mf-model-manager**：`/api/mf-model-manager/v1`（配置 CRUD、`test`）
+- **mf-model-api**：`/api/mf-model-api/v1`（OpenAI 兼容 **`chat`**，以及小模型 **`embeddings` / `rerank`**）
+
+离线模版：`model llm --template` / `model small --template` 输出内置 **`basic`** JSON（不调后端）。大模型 **`model_type`** 在后端仅为 **`llm`**（文本）、**`rlm`**（推理）、**`vu`**（视觉/多模态，接口缩写不是 `vlm`）；列表过滤：`kweaver model llm list --type …`。详见 [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md#llm-model-types)。
+
+```bash
+kweaver model llm list --limit 30
+kweaver model llm list --type vu
+kweaver model llm chat <model_id> -m "你好" --no-stream
+kweaver model llm --template > ./llm.json
+kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 512 --embedding-dim 1536 \
+  --model-config-file ./cfg.json
+kweaver model small embeddings <model_id> -i "hello" -i "world"
+kweaver model small rerank <model_id> -q "查询" -d "文档a" -d "文档b"
+kweaver model small --template > ./embedding-model-config.json
+```
+
+完整说明见 [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md) 与 `kweaver model --help`。
+
 ### Vega `sql` CLI 示例
 
 对 Catalog 资源执行直连 SQL（`POST /api/vega-backend/v1/resources/query`）。SQL 中使用 **`{{<resource_id>}}`** 或 **`{{.<resource_id>}}`**（资源 id 来自 `vega resource list` / `get`），后端据此解析物理表与 connector。`--resource-type` 为目标数据源的连接器类型，可通过 `kweaver vega connector-type list` 查看。简单模式下请**用引号包住整个 `--query` 参数**，避免 shell 对花括号做特殊处理。
@@ -218,6 +260,8 @@ kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} L
 | 变量 | 说明 |
 |---|---|
 | `KWEAVER_BASE_URL` | KWeaver 实例地址 |
+| `KWEAVER_MF_MODEL_MANAGER_URL` | 可选：mf-model-manager API 根地址（默认 `KWEAVER_BASE_URL` + `/api/mf-model-manager/v1`） |
+| `KWEAVER_MF_MODEL_API_URL` | 可选：mf-model-api 根地址（默认 `KWEAVER_BASE_URL` + `/api/mf-model-api/v1`） |
 | `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
 | `KWEAVER_TOKEN` | 访问令牌 |
 | `KWEAVER_TOKEN_SOURCE` | CLI 传入 `--token` 时由程序设置的内部标记；请勿手动设置 |

package/bin/kweaver.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 
+// Wait for stdout and stderr to fully flush before terminating. Checking
+// writableNeedDrain alone is not enough — a single console.log under the
+// highWaterMark returns synchronously while bytes are still queued, so
+// process.exit() can truncate piped output (~7-8KB) under spawn capture.
+// Empty write + callback fires only after all preceding writes drain.
 function exit(code) {
-  if (process.stdout.writableNeedDrain || process.stderr.writableNeedDrain) {
-    const done = () => {
-      if (!process.stdout.writableNeedDrain && !process.stderr.writableNeedDrain) {
-        process.exit(code);
-      }
-    };
-    process.stdout.once("drain", done);
-    process.stderr.once("drain", done);
-  } else {
-    process.exit(code);
-  }
+  let pending = 2;
+  const done = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(code);
+  };
+  process.stdout.write("", done);
+  process.stderr.write("", done);
 }
 
 import("../dist/cli.js").then(({ run }) => {

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

@@ -0,0 +1,51 @@
+/**
+ * Single source of truth for `/api/agent-observability/v1/traces/_search` —
+ * the OpenSearch-style endpoint that backs both `kweaver agent trace` and
+ * `kweaver trace diagnose`.
+ *
+ * Owns: endpoint URL, auth/headers (via `./headers.ts`), the two-hop strategy
+ * (conversation_id → traceIds → spans), and HTTP error handling.
+ *
+ * Does NOT own normalization: callers receive raw OpenSearch `_source` objects
+ * and shape them as needed (TraceSpan for UI rendering, RawSpan for diagnose
+ * rules). This keeps the wire contract in one place while letting each consumer
+ * pick its own minimal field set.
+ */
+export declare const TRACE_SEARCH_PATH = "/api/agent-observability/v1/traces/_search";
+export declare class TraceFetchError extends Error {
+    readonly status?: number | undefined;
+    readonly url?: string | undefined;
+    constructor(message: string, status?: number | undefined, url?: string | undefined);
+}
+export interface FetchRawSpansByConversationOpts {
+    baseUrl: string;
+    accessToken: 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 FetchRawSpansByConversationResult {
+    /** Distinct traceIds observed for this conversation, in agg-bucket order. */
+    traceIds: string[];
+    /** Raw `_source` objects, unmodified. Callers do their own normalization. */
+    rawSources: Array<Record<string, unknown>>;
+    /** True if the agg saw `sum_other_doc_count > 0` (more traceIds than maxTraceIds). */
+    truncated: boolean;
+}
+export declare function postTraceSearch(baseUrl: string, accessToken: string, businessDomain: string, body: unknown): Promise<Record<string, unknown>>;
+/**
+ * Two-hop fetch of all `_source` documents belonging to a conversation.
+ *
+ * Hop 1: aggregate `traceId.keyword` for spans tagged with
+ *        `attributes.gen_ai.conversation.id.keyword == conversationId`.
+ * Hop 2: fetch every span whose `traceId.keyword` is in the agg buckets.
+ *
+ * Fixture-compat fast path: when the first response carries no `aggregations`
+ * but does carry `hits.hits`, that is taken as a flat spans payload and hop 2
+ * is skipped. Existing e2e fixtures (single OpenSearch payload per file) thus
+ * remain usable with a single mock-fetch response.
+ */
+export declare function fetchRawSpansByConversation(opts: FetchRawSpansByConversationOpts): Promise<FetchRawSpansByConversationResult>;

package/dist/api/agent-observability.js

@@ -0,0 +1,108 @@
+/**
+ * Single source of truth for `/api/agent-observability/v1/traces/_search` —
+ * the OpenSearch-style endpoint that backs both `kweaver agent trace` and
+ * `kweaver trace diagnose`.
+ *
+ * Owns: endpoint URL, auth/headers (via `./headers.ts`), the two-hop strategy
+ * (conversation_id → traceIds → spans), and HTTP error handling.
+ *
+ * Does NOT own normalization: callers receive raw OpenSearch `_source` objects
+ * and shape them as needed (TraceSpan for UI rendering, RawSpan for diagnose
+ * rules). This keeps the wire contract in one place while letting each consumer
+ * pick its own minimal field set.
+ */
+import { buildHeaders } from "./headers.js";
+export const TRACE_SEARCH_PATH = "/api/agent-observability/v1/traces/_search";
+export class TraceFetchError extends Error {
+    status;
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.name = "TraceFetchError";
+    }
+}
+export async function postTraceSearch(baseUrl, accessToken, businessDomain, body) {
+    const url = `${baseUrl.replace(/\/+$/, "")}${TRACE_SEARCH_PATH}`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...buildHeaders(accessToken, businessDomain),
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new TraceFetchError(`trace search failed: HTTP ${res.status} ${res.statusText} — ${text.slice(0, 200)}`, res.status, url);
+    }
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new TraceFetchError(`trace search: invalid JSON response — ${err.message}`);
+    }
+}
+/**
+ * Two-hop fetch of all `_source` documents belonging to a conversation.
+ *
+ * Hop 1: aggregate `traceId.keyword` for spans tagged with
+ *        `attributes.gen_ai.conversation.id.keyword == conversationId`.
+ * Hop 2: fetch every span whose `traceId.keyword` is in the agg buckets.
+ *
+ * Fixture-compat fast path: when the first response carries no `aggregations`
+ * but does carry `hits.hits`, that is taken as a flat spans payload and hop 2
+ * is skipped. Existing e2e fixtures (single OpenSearch payload per file) thus
+ * remain usable with a single mock-fetch response.
+ */
+export async function fetchRawSpansByConversation(opts) {
+    const { baseUrl, accessToken, businessDomain, conversationId } = opts;
+    const maxTraceIds = opts.maxTraceIds ?? 100;
+    const maxSpans = opts.maxSpans ?? 2000;
+    const aggResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
+        size: 0,
+        query: { term: { "attributes.gen_ai.conversation.id.keyword": conversationId } },
+        aggs: { tids: { terms: { field: "traceId.keyword", size: maxTraceIds } } },
+    });
+    const aggregations = aggResult.aggregations;
+    if (!aggregations) {
+        const directHits = aggResult.hits?.hits;
+        if (Array.isArray(directHits)) {
+            const rawSources = [];
+            const traceIds = new Set();
+            for (const h of directHits) {
+                if (!h._source)
+                    continue;
+                rawSources.push(h._source);
+                const tid = h._source.traceId ?? h._source.trace_id;
+                if (typeof tid === "string" && tid.length > 0)
+                    traceIds.add(tid);
+            }
+            return { traceIds: [...traceIds], rawSources, truncated: false };
+        }
+    }
+    const tids = aggregations?.tids;
+    const buckets = tids?.buckets ?? [];
+    const truncated = (tids?.sum_other_doc_count ?? 0) > 0;
+    const traceIds = buckets
+        .map((b) => b.key)
+        .filter((k) => typeof k === "string" && k.length > 0);
+    if (traceIds.length === 0) {
+        return { traceIds: [], rawSources: [], truncated: false };
+    }
+    const spansResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
+        size: maxSpans,
+        query: { terms: { "traceId.keyword": traceIds } },
+        sort: [{ startTime: "asc" }],
+    });
+    const hits = spansResult.hits?.hits ?? [];
+    const rawSources = [];
+    for (const h of hits) {
+        if (h._source)
+            rawSources.push(h._source);
+    }
+    return { traceIds, rawSources, truncated };
+}

package/dist/api/bkn-backend.d.ts

@@ -14,6 +14,7 @@ export interface BknBackendBaseOptions {
 export interface BknBackendKnOptions extends BknBackendBaseOptions {
     knId: string;
 }
+export declare function knUrl(baseUrl: string, knId: string, path: string): string;
 export interface ConceptGroupOptions extends BknBackendKnOptions {
     cgId: string;
 }

package/dist/api/bkn-backend.js

@@ -20,7 +20,7 @@ export async function uploadBkn(options) {
     return body;
 }
 const BKN_BASE = "/api/bkn-backend/v1";
-function knUrl(baseUrl, knId, path) {
+export function knUrl(baseUrl, knId, path) {
     const base = baseUrl.replace(/\/+$/, "");
     return `${base}${BKN_BASE}/knowledge-networks/${encodeURIComponent(knId)}/${path}`;
 }

package/dist/api/bkn-metrics.d.ts

@@ -0,0 +1,59 @@
+import type { BknBackendKnOptions } from "./bkn-backend.js";
+export interface ListMetricsOptions extends BknBackendKnOptions {
+    namePattern?: string;
+    sort?: "update_time" | "name";
+    direction?: "asc" | "desc";
+    offset?: number;
+    limit?: number;
+    tag?: string;
+    groupId?: string;
+    branch?: string;
+}
+export declare function listMetrics(options: ListMetricsOptions): Promise<string>;
+export interface CreateMetricsOptions extends BknBackendKnOptions {
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+}
+export declare function createMetrics(options: CreateMetricsOptions): Promise<string>;
+export interface SearchMetricsOptions extends BknBackendKnOptions {
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+}
+export declare function searchMetrics(options: SearchMetricsOptions): Promise<string>;
+export interface ValidateMetricsOptions extends BknBackendKnOptions {
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+    importMode?: "normal" | "ignore" | "overwrite";
+}
+export declare function validateMetrics(options: ValidateMetricsOptions): Promise<string>;
+export interface GetMetricOptions extends BknBackendKnOptions {
+    metricId: string;
+    branch?: string;
+}
+export declare function getMetric(options: GetMetricOptions): Promise<string>;
+export interface UpdateMetricOptions extends BknBackendKnOptions {
+    metricId: string;
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+}
+export declare function updateMetric(options: UpdateMetricOptions): Promise<string>;
+export interface DeleteMetricOptions extends BknBackendKnOptions {
+    metricId: string;
+    branch?: string;
+}
+export declare function deleteMetric(options: DeleteMetricOptions): Promise<string>;
+export interface GetMetricsByIdsOptions extends BknBackendKnOptions {
+    /** Comma-separated metric IDs in a single path segment. */
+    metricIds: string;
+    branch?: string;
+}
+export declare function getMetrics(options: GetMetricsByIdsOptions): Promise<string>;
+export interface DeleteMetricsByIdsOptions extends BknBackendKnOptions {
+    metricIds: string;
+    branch?: string;
+}
+export declare function deleteMetrics(options: DeleteMetricsByIdsOptions): Promise<string>;

package/dist/api/bkn-metrics.js

@@ -0,0 +1,129 @@
+import { HttpError } from "../utils/http.js";
+import { buildHeaders } from "./headers.js";
+import { knUrl } from "./bkn-backend.js";
+async function readTextOrThrow(response) {
+    const text = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    return text;
+}
+function appendSearchParams(url, entries) {
+    for (const [k, v] of entries) {
+        if (v === undefined)
+            continue;
+        url.searchParams.set(k, String(v));
+    }
+}
+export async function listMetrics(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", namePattern, sort, direction, offset, limit, tag, groupId, branch, } = options;
+    const url = new URL(knUrl(baseUrl, knId, "metrics"));
+    appendSearchParams(url, [
+        ["name_pattern", namePattern],
+        ["sort", sort],
+        ["direction", direction],
+        ["offset", offset],
+        ["limit", limit],
+        ["tag", tag],
+        ["group_id", groupId],
+        ["branch", branch],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function createMetrics(options) {
+    return postWithMethodOverride(options, "POST");
+}
+export async function searchMetrics(options) {
+    return postWithMethodOverride(options, "GET");
+}
+async function postWithMethodOverride(options, methodOverride) {
+    const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", branch, strictMode } = options;
+    const url = new URL(knUrl(baseUrl, knId, "metrics"));
+    appendSearchParams(url, [
+        ["branch", branch],
+        ["strict_mode", strictMode],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+            "X-HTTP-Method-Override": methodOverride,
+        },
+        body,
+    });
+    return readTextOrThrow(response);
+}
+export async function validateMetrics(options) {
+    const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", branch, strictMode, importMode } = options;
+    const url = new URL(knUrl(baseUrl, knId, "metrics/validation"));
+    appendSearchParams(url, [
+        ["branch", branch],
+        ["strict_mode", strictMode],
+        ["import_mode", importMode],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
+        body,
+    });
+    return readTextOrThrow(response);
+}
+export async function getMetric(options) {
+    const { baseUrl, accessToken, knId, metricId, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${encodeURIComponent(metricId)}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function updateMetric(options) {
+    const { baseUrl, accessToken, knId, metricId, body, businessDomain = "bd_public", branch, strictMode } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${encodeURIComponent(metricId)}`));
+    appendSearchParams(url, [
+        ["branch", branch],
+        ["strict_mode", strictMode],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "PUT",
+        headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
+        body,
+    });
+    return readTextOrThrow(response);
+}
+export async function deleteMetric(options) {
+    const { baseUrl, accessToken, knId, metricId, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${encodeURIComponent(metricId)}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function getMetrics(options) {
+    const { baseUrl, accessToken, knId, metricIds, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${metricIds}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function deleteMetrics(options) {
+    const { baseUrl, accessToken, knId, metricIds, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${metricIds}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}

package/dist/api/conversations.d.ts

@@ -16,16 +16,57 @@ export interface ListMessagesOptions {
 export interface GetTracesOptions {
     baseUrl: string;
     accessToken: string;
-    agentId: string;
     conversationId: string;
+    /** Deprecated. trace-ai keys spans by conversation_id only; kept for CLI compatibility. */
+    agentId?: string;
     businessDomain?: string;
+    /** Max distinct traceIds to fetch for one conversation. Default 100. */
+    maxTraceIds?: number;
+    /** Max spans returned by the second hop. Default 2000. */
+    maxSpans?: number;
+}
+export interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind?: string;
+    startTime: string;
+    endTime?: string;
+    durationInNanos?: number;
+    status?: {
+        code?: string | number;
+        message?: string;
+    };
+    serviceName?: string;
+    attributes?: Record<string, unknown>;
+    events?: Array<{
+        name?: string;
+        time?: string;
+        attributes?: Record<string, unknown>;
+    }>;
+    /** Raw _source object from the trace store, kept verbatim for formatters that need extra fields. */
+    raw?: Record<string, unknown>;
+}
+export interface TracesByConversationResult {
+    conversationId: string;
+    traceIds: string[];
+    spans: TraceSpan[];
+    /** True if the traceId aggregation hit its bucket cap and may be incomplete. */
+    truncated: boolean;
 }
 /**
  * List conversations for an agent.
  * Returns empty array on 404 (endpoint may not be available in all deployments).
  */
 export declare function listConversations(opts: ListConversationsOptions): Promise<string>;
-export declare function getTracesByConversation(opts: GetTracesOptions): Promise<string>;
+/**
+ * Fetch all spans belonging to a conversation, shaped as `TraceSpan[]` for UI
+ * rendering (tree/perf/evidence/reasoning views). The wire-level two-hop and
+ * auth/header concerns live in `./agent-observability`; this function only
+ * normalizes the raw `_source` documents.
+ */
+export declare function getTracesByConversation(opts: GetTracesOptions): Promise<TracesByConversationResult>;
 /**
  * List messages for a conversation.
  * Returns empty array on 404 (endpoint may not be available in all deployments).