@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/README.md

@@ -126,23 +126,19 @@ const graph     = await client.bkn.querySubgraph("bkn-id", { /* path spec */ });
 await client.bkn.executeAction("bkn-id", "at-id", { /* params */ });
 const logs      = await client.bkn.listActionLogs("bkn-id");
 
-// Data sources & data views
+// Data sources & vega-backend resources
 const dsList = await client.datasources.list();
 const tables = await client.datasources.listTables("ds-id");
-const viewId = await client.dataviews.create({ name: "v", datasourceId: "ds-id", table: "orders" });
-const views = await client.dataviews.list({ datasourceId: "ds-id" });
-const fuzzy = await client.dataviews.find("BOM", { wait: false });
-const exact = await client.dataviews.find("orders", {
+const resId  = await client.resources.create({ name: "v", datasourceId: "ds-id", table: "orders" });
+const resList = await client.resources.list({ datasourceId: "ds-id" });
+const fuzzy  = await client.resources.find("BOM", { wait: false });
+const exact  = await client.resources.find("orders", {
   datasourceId: "ds-id",
   exact: true,
   wait: true,
 });
-const dv = await client.dataviews.get(viewId);
-const queryRows = await client.dataviews.query(viewId, {
-  sql: "SELECT id, name FROM orders LIMIT 10",
-  limit: 10,
-  needTotal: true,
-});
+const res       = await client.resources.get(resId);
+const queryRows = await client.resources.query(resId, { limit: 10, needTotal: true });
 
 // Dataflow automation (CSV import pipeline, etc.)
 const result = await client.dataflows.execute({
@@ -165,61 +161,53 @@ const rows = await client.vega.sqlQuery(
 
 // Context Loader (MCP search_schema plus generic tools/call)
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
-const schema  = await cl.searchSchema({ query: "hypertension treatment" });
+const schema  = await cl.searchSchema({
+  query: "hypertension treatment",
+  search_scope: { concept_groups: ["clinical"] },
+});
 const rawTool = await cl.callTool("search_schema", { query: "hypertension treatment" });
 
 // Skills (registry + market + progressive read)
 const skills = await client.skills.market({ name: "kweaver" });
 const skillMd = await client.skills.fetchContent("skill-id");
+const draft = await client.skills.updateMetadata("skill-id", {
+  name: "Demo",
+  description: "Demo skill",
+  category: "system",
+});
+const history = await client.skills.history("skill-id");
 ```
 
-`searchSchema()` is the typed wrapper for the Context Loader MCP `search_schema` tool. It defaults `response_format` to `json` and accepts `query`, `response_format`, `search_scope`, `max_concepts`, `schema_brief`, and `enable_rerank`. The parsed response may contain `object_types`, `relation_types`, `action_types`, and `metric_types`.
+`searchSchema()` is the typed wrapper for the Context Loader MCP `search_schema` tool. It defaults `response_format` to `json` and accepts `query`, `response_format`, `search_scope`, `max_concepts`, `schema_brief`, and `enable_rerank`. `search_scope.concept_groups` limits schema discovery to BKN concept group IDs; it is not an instance-data filter. The parsed response may contain `object_types`, `relation_types`, `action_types`, and `metric_types`.
+
+`client.bkn.knSearch(...)` is deprecated. Use `client.contextLoader(...).searchSchema(...)` for new schema discovery integrations.
 
 Use `callTool(name, args)` when you need native MCP `tools/call` access for newly added server tools before the SDK adds a typed wrapper. Arguments are passed through unchanged.
 
 ## CLI Reference
 
+`kweaver` follows a `gh`-style help layout (see [docs/cli_conventions.md §8](../../docs/cli_conventions.md#8-help-文本格式must)):
+
+```text
+kweaver [--help|-h]                       # gh-style top-level overview
+kweaver help <command>                    # forward to <command> --help
+kweaver help all                          # full per-action signatures (migration fallback)
+kweaver <command> [--help|-h]             # subcommand overview + actions
+kweaver <command> <subcommand> [--help|-h]  # action-level flags + examples
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--new-password <pwd>] [--http-signin] [--insecure|-k]
-# -u/-p (with or without --http-signin): HTTP POST /oauth2/signin (yields refresh_token). Missing -u/-p are prompted from stdin (password hidden when TTY).
-# If the server returns error 401001017 (initial password), TTY users get a prompt to set a new password; non-interactive scripts must pass --new-password <pwd>.
-kweaver auth change-password [<url>] [-u <account>] [-o <old>] [-n <new>] [--insecure|-k]
-# EACP POST /api/eacp/v1/auth1/modifypassword — no OAuth token required. Omit -o/-n on a TTY to be prompted.
-kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (headless login)
-kweaver auth export [url|alias] [--json]   (export command to run on a headless host)
-kweaver auth status / whoami [url|alias] [--json]   # whoami: --json; with KWEAVER_BASE_URL+KWEAVER_TOKEN when no ~/.kweaver/ platform
-kweaver auth list/use/delete/logout
-kweaver config show / list-bd / set-bd <value>   # platform business domain — show/list-bd work with KWEAVER_BASE_URL (+ KWEAVER_TOKEN for list-bd)
-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
-kweaver bkn action-execution get
-kweaver bkn action-log list/get/cancel
-kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
-kweaver skill list/market/get/register/status/delete/content/read-file/download/install
-kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
-kweaver context-loader tools|resources|templates|prompts <kn-id>
-kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id> <query|name> [...]
-kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
-kweaver context-loader config set/use/list/show                       (deprecated; <kn-id> may be omitted to fall back to saved config)
-kweaver toolbox create/list/publish/unpublish/delete
-kweaver tool upload/list/enable/disable/execute/debug (execute and debug accept --path for OpenAPI path params)
-kweaver call <path> [-X METHOD] [-d BODY] [-H header] [-F key=value]
+
+Top-level command groups:
+
+```text
+AUTHENTICATION & CONFIG  auth · token · config
+DECISION AGENT           agent · toolbox · tool
+AI DATA PLATFORM         bkn · ds · resource · dataflow · vega · context-loader
+TRACE AI                 trace
+FOUNDATION               call · explore · model · skill · help
 ```
 
+For a structured browsable index of every action and flag, run `kweaver help all`.
+
 ### Dataflow CLI examples
 
 ```bash
@@ -332,7 +320,7 @@ When `--token` is used, write-disk commands (`auth login` / `logout` / `use` / `
 
 `auth whoami` / `auth status` distinguish the two stateless modes: `Source: CLI (flag: --token)` for flag mode, `env (KWEAVER_TOKEN)` for env mode (`whoami --json` uses `"source": "flag"` vs `"source": "env"`).
 
-`kweaver context-loader` runtime subcommands accept `<kn-id>` as the first positional (e.g. `kweaver context-loader tools <kn-id>`) or via the global `--kn-id <id>` / `-k <id>` flag, so they work in stateless mode without any saved config. The `context-loader config set|use|list|remove|show` management group is deprecated, prints a warning on use, and is disabled in its entirety under `--token`.
+`kweaver context-loader` runtime subcommands accept `<kn-id>` as the first positional (e.g. `kweaver context-loader tools <kn-id>`) or via the global `--kn-id <id>` / `-k <id>` flag, so they work in stateless mode without any saved config. Use `kweaver context-loader help <subcommand>` or `<subcommand> --help` to inspect arguments before login/network checks. The `context-loader config set|use|list|remove|show` management group is deprecated, prints a warning on use, and is disabled in its entirety under `--token`.
 
 ### TLS Certificate Troubleshooting
 

package/README.zh.md

@@ -124,22 +124,18 @@ const graph     = await client.bkn.querySubgraph("bkn-id", { /* 路径规格 */
 await client.bkn.executeAction("bkn-id", "at-id", { /* 参数 */ });
 const logs      = await client.bkn.listActionLogs("bkn-id");
 
-// 数据源与数据视图
-const dsList = await client.datasources.list();
-const viewId = await client.dataviews.create({ name: "v", datasourceId: "ds-id", table: "orders" });
-const views = await client.dataviews.list({ datasourceId: "ds-id" });
-const fuzzy = await client.dataviews.find("BOM", { wait: false });
-const exact = await client.dataviews.find("orders", {
+// 数据源 & vega-backend 资源
+const dsList    = await client.datasources.list();
+const resId     = await client.resources.create({ name: "v", datasourceId: "ds-id", table: "orders" });
+const resList   = await client.resources.list({ datasourceId: "ds-id" });
+const fuzzy     = await client.resources.find("BOM", { wait: false });
+const exact     = await client.resources.find("orders", {
   datasourceId: "ds-id",
   exact: true,
   wait: true,
 });
-const dv = await client.dataviews.get(viewId);
-const queryRows = await client.dataviews.query(viewId, {
-  sql: "SELECT id, name FROM orders LIMIT 10",
-  limit: 10,
-  needTotal: true,
-});
+const res       = await client.resources.get(resId);
+const queryRows = await client.resources.query(resId, { limit: 10, needTotal: true });
 
 // Vega — 可观测性与查询
 const catalogs = await client.vega.listCatalogs();
@@ -156,54 +152,53 @@ const rows = await client.vega.sqlQuery(
 
 // Context Loader（MCP search_schema + 通用 tools/call）
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
-const schema  = await cl.searchSchema({ query: "高血压 治疗" });
+const schema  = await cl.searchSchema({
+  query: "高血压 治疗",
+  search_scope: { concept_groups: ["clinical"] },
+});
 const rawTool = await cl.callTool("search_schema", { query: "高血压 治疗" });
 
 // Skill（注册表/市场/渐进式读取）
 const skills = await client.skills.market({ name: "kweaver" });
 const skillMd = await client.skills.fetchContent("skill-id");
+const draft = await client.skills.updateMetadata("skill-id", {
+  name: "Demo",
+  description: "Demo skill",
+  category: "system",
+});
+const history = await client.skills.history("skill-id");
 ```
 
-`searchSchema()` 是 Context Loader MCP `search_schema` 的类型化封装，默认 `response_format` 为 `json`，支持 `query`、`response_format`、`search_scope`、`max_concepts`、`schema_brief`、`enable_rerank`。解析后的返回结果可能包含 `object_types`、`relation_types`、`action_types`、`metric_types`。
+`searchSchema()` 是 Context Loader MCP `search_schema` 的类型化封装，默认 `response_format` 为 `json`，支持 `query`、`response_format`、`search_scope`、`max_concepts`、`schema_brief`、`enable_rerank`。`search_scope.concept_groups` 用于按 BKN 概念分组 ID 限定 Schema 发现范围，不是实例数据过滤条件。解析后的返回结果可能包含 `object_types`、`relation_types`、`action_types`、`metric_types`。
+
+`client.bkn.knSearch(...)` 已过时。新接入的 Schema 发现请使用 `client.contextLoader(...).searchSchema(...)`。
 
 需要直接使用 MCP 原生 `tools/call` 时，使用 `callTool(name, args)`。这适用于服务端新增工具但 SDK 尚未提供类型化封装的场景，参数会原样透传。
 
 ## 命令速查
 
+`kweaver` 采用 `gh` 风格 help 布局（详见 [docs/cli_conventions.md §8](../../docs/cli_conventions.md#8-help-文本格式must)）：
+
+```text
+kweaver --help                            # gh 风格顶层概览
+kweaver help <command>                    # 转发到 `<command> --help`
+kweaver help all                          # 完整 per-action 签名（迁移期兜底）
+kweaver <command> --help                  # 子命令概览 + 动作列表
+kweaver <command> <subcommand> --help     # 动作级 flag + 示例
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--new-password <pwd>] [--http-signin] [--insecure|-k]
-# -u/-p（无论是否带 --http-signin）：HTTP POST /oauth2/signin（可拿 refresh_token）；缺失的用户名/密码会从 stdin 提示输入（TTY 下密码隐藏）
-# 若服务端返回 401001017（初始密码），交互终端会引导修改；非交互请使用 --new-password <pwd>。
-kweaver auth change-password [<url>] [-u <account>] [-o <old>] [-n <new>] [--insecure|-k]
-kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (无浏览器登录)
-kweaver auth export [url|alias] [--json]   (导出在无浏览器机器上运行的命令)
-kweaver auth status / whoami [url|alias] [--json]   # whoami 支持 --json；无 ~/.kweaver/ 当前平台时可配 KWEAVER_BASE_URL+KWEAVER_TOKEN
-kweaver auth list/use/delete/logout
-kweaver config show / list-bd / set-bd <value>   # 业务域；show/list-bd 在无已保存平台时可与 env 配对
-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
-kweaver bkn action-execution get
-kweaver bkn action-log list/get/cancel
-kweaver agent list/get/chat/sessions/history
-kweaver skill list/market/get/register/status/delete/content/read-file/download/install
-kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
-kweaver context-loader tools|resources|templates|prompts <kn-id>
-kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id> <query|name> [...]
-kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
-kweaver context-loader config set/use/list/show                       （deprecated；省略 <kn-id> 时回退到已保存配置）
-kweaver call <path> [-X METHOD] [-d BODY] [-H header]
+
+顶层命令分组：
+
+```text
+AUTHENTICATION & CONFIG  auth · token · config
+DECISION AGENT           agent · toolbox · tool
+AI DATA PLATFORM         bkn · ds · resource · dataflow · vega · context-loader
+TRACE AI                 trace
+FOUNDATION               call · explore · model · skill · help
 ```
 
+需要查阅每个动作的完整签名（可浏览 / 可 grep）时，运行 `kweaver help all`。
+
 ### Dataflow CLI 示例
 
 ```bash
@@ -289,7 +284,7 @@ kweaver --base-url https://platform.example.com --token "$TOK" bkn list
 
 `auth whoami` / `auth status` 通过文案区分来源：flag 模式为 `CLI (flag: --token)`，env 模式为 `env (KWEAVER_TOKEN)`（`whoami --json` 为 `"source": "flag"` 与 `"source": "env"`）。
 
-`kweaver context-loader` 运行时子命令将 `<kn-id>` 作为第一个位置参数（如 `kweaver context-loader tools <kn-id>`），也支持全局 `--kn-id <id>` / `-k <id>` flag，因此在 stateless 模式下可直接使用，无需任何持久化配置。`context-loader config set|use|list|remove|show` 管理子命令已被标记为 deprecated（每次调用打印警告），且在 `--token` 下整组被禁用。
+`kweaver context-loader` 运行时子命令将 `<kn-id>` 作为第一个位置参数（如 `kweaver context-loader tools <kn-id>`），也支持全局 `--kn-id <id>` / `-k <id>` flag，因此在 stateless 模式下可直接使用，无需任何持久化配置。调试参数时可先执行 `kweaver context-loader help <subcommand>` 或 `<subcommand> --help`，这些 help 路径不会触发登录、配置读取或网络请求。`context-loader config set|use|list|remove|show` 管理子命令已被标记为 deprecated（每次调用打印警告），且在 `--token` 下整组被禁用。
 
 ### TLS 证书问题排查
 

package/dist/agent-providers/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export { AgentRegistry, defaultRegistry } from "./registry.js";
+export { PromptTemplateRegistry, defaultPromptRegistry, render, type PromptTemplate, } from "./prompt-template.js";
+export { StubAgentProvider } from "./providers/stub.js";
+export type { StubAgentProviderOpts, StubResponseFn } from "./providers/stub.js";
+export { ClaudeCodeSubprocessProvider } from "./providers/claude-code-subprocess.js";
+export type { ClaudeCodeSubprocessProviderOpts } from "./providers/claude-code-subprocess.js";

package/dist/agent-providers/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { AgentRegistry, defaultRegistry } from "./registry.js";
+export { PromptTemplateRegistry, defaultPromptRegistry, render, } from "./prompt-template.js";
+export { StubAgentProvider } from "./providers/stub.js";
+export { ClaudeCodeSubprocessProvider } from "./providers/claude-code-subprocess.js";

package/dist/agent-providers/prompt-template.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tiny prompt template registry — load `.prompt.md` files from a directory,
+ * resolve by `builtin:<name>` reference, render with a flat variables map.
+ *
+ * Why not a templating engine: the templates ship with the SDK, vars are
+ * trusted internal data (rule yaml + trace metadata), and the substitution
+ * is one-pass `{{key}}` → string. A 30-line implementation beats pulling in
+ * Handlebars / Mustache and the security surface they bring.
+ */
+export interface PromptTemplate {
+    /** `builtin:rubric-judge-v1`, `builtin:within-trace-synthesizer-v1`, etc. */
+    ref: string;
+    /** Raw template body with `{{var}}` placeholders. */
+    body: string;
+    /** Absolute path to the source file, kept for debugging. */
+    sourcePath: string;
+}
+export declare class PromptTemplateRegistry {
+    private byRef;
+    has(ref: string): boolean;
+    get(ref: string): PromptTemplate;
+    list(): string[];
+    /**
+     * Register a prompt body directly (used by tests; production loads from disk).
+     */
+    registerInline(ref: string, body: string, sourcePath?: string): void;
+    /**
+     * Scan a directory for `*.prompt.md` files and register each as
+     * `builtin:<basename-without-suffix>`. Skips non-files / non-matching
+     * extensions silently — callers can `list()` to confirm what loaded.
+     */
+    loadBuiltinDir(dir: string): Promise<void>;
+}
+/**
+ * Substitute `{{key}}` occurrences with `String(vars[key])`.
+ *
+ * Unknown keys throw — silent substitution masks template / data drift
+ * (e.g. spec rename `tool_name` → `name` would otherwise leave `{{tool_name}}`
+ * verbatim in the prompt and the agent would politely answer about its
+ * literal value).
+ *
+ * `vars[key]` of type `object | array` is JSON-stringified with 2-space
+ * indent — the common case is "interpolate a JSON evidence blob into a
+ * markdown prompt block".
+ */
+export declare function render(template: PromptTemplate, vars: Record<string, unknown>): string;
+export declare const defaultPromptRegistry: PromptTemplateRegistry;
+/**
+ * Supported output locales for agent-judged natural-language fields.
+ * JSON keys, enum values, and span IDs are ALWAYS English regardless of
+ * locale — only prose fields (`headline`, `reasoning`, `description`,
+ * `reason`, `excerpt`) get localized. This keeps downstream report
+ * consumers locale-independent.
+ */
+export type AgentOutputLang = 'en' | 'zh';
+/**
+ * Render the boilerplate "respond in <language>" instruction injected via
+ * the `{{language_instruction}}` placeholder in rubric / synthesizer
+ * prompts. English returns "" so the placeholder collapses cleanly —
+ * prompts default to English without needing an instruction.
+ */
+export declare function languageInstructionFor(lang: AgentOutputLang): string;

package/dist/agent-providers/prompt-template.js

@@ -0,0 +1,105 @@
+/**
+ * Tiny prompt template registry — load `.prompt.md` files from a directory,
+ * resolve by `builtin:<name>` reference, render with a flat variables map.
+ *
+ * Why not a templating engine: the templates ship with the SDK, vars are
+ * trusted internal data (rule yaml + trace metadata), and the substitution
+ * is one-pass `{{key}}` → string. A 30-line implementation beats pulling in
+ * Handlebars / Mustache and the security surface they bring.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+export class PromptTemplateRegistry {
+    byRef = new Map();
+    has(ref) {
+        return this.byRef.has(ref);
+    }
+    get(ref) {
+        const tpl = this.byRef.get(ref);
+        if (!tpl) {
+            throw new Error(`prompt template not registered: '${ref}'; registered refs: [${[...this.byRef.keys()].join(", ") || "(none)"}]`);
+        }
+        return tpl;
+    }
+    list() {
+        return [...this.byRef.keys()];
+    }
+    /**
+     * Register a prompt body directly (used by tests; production loads from disk).
+     */
+    registerInline(ref, body, sourcePath = "<inline>") {
+        this.byRef.set(ref, { ref, body, sourcePath });
+    }
+    /**
+     * Scan a directory for `*.prompt.md` files and register each as
+     * `builtin:<basename-without-suffix>`. Skips non-files / non-matching
+     * extensions silently — callers can `list()` to confirm what loaded.
+     */
+    async loadBuiltinDir(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const e of entries) {
+            if (!e.isFile())
+                continue;
+            if (!e.name.endsWith(".prompt.md"))
+                continue;
+            const filePath = path.join(dir, e.name);
+            const body = await fs.readFile(filePath, "utf8");
+            const base = e.name.slice(0, -".prompt.md".length);
+            this.byRef.set(`builtin:${base}`, { ref: `builtin:${base}`, body, sourcePath: filePath });
+        }
+    }
+}
+/**
+ * Substitute `{{key}}` occurrences with `String(vars[key])`.
+ *
+ * Unknown keys throw — silent substitution masks template / data drift
+ * (e.g. spec rename `tool_name` → `name` would otherwise leave `{{tool_name}}`
+ * verbatim in the prompt and the agent would politely answer about its
+ * literal value).
+ *
+ * `vars[key]` of type `object | array` is JSON-stringified with 2-space
+ * indent — the common case is "interpolate a JSON evidence blob into a
+ * markdown prompt block".
+ */
+export function render(template, vars) {
+    return template.body.replace(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, (_, key) => {
+        if (!(key in vars)) {
+            throw new Error(`prompt template '${template.ref}' references unknown variable '{{${key}}}'; provided vars: [${Object.keys(vars).join(", ")}]`);
+        }
+        const v = vars[key];
+        if (v === null || v === undefined)
+            return "";
+        if (typeof v === "string")
+            return v;
+        if (typeof v === "number" || typeof v === "boolean")
+            return String(v);
+        return JSON.stringify(v, null, 2);
+    });
+}
+export const defaultPromptRegistry = new PromptTemplateRegistry();
+/**
+ * Render the boilerplate "respond in <language>" instruction injected via
+ * the `{{language_instruction}}` placeholder in rubric / synthesizer
+ * prompts. English returns "" so the placeholder collapses cleanly —
+ * prompts default to English without needing an instruction.
+ */
+export function languageInstructionFor(lang) {
+    if (lang === "zh") {
+        return [
+            "**Language: respond in Simplified Chinese (简体中文) for all natural-language fields** ",
+            "(e.g. `headline`, `reasoning`, `description`, `reason`, `excerpt`). JSON keys, ",
+            "enum values (like `severity: high`, `category: stale_results`), and span IDs ",
+            "MUST stay in English exactly as specified by the schema — only prose is localized.",
+        ].join("");
+    }
+    return "";
+}

package/dist/agent-providers/prompts/rubric-judge-v1.prompt.md

@@ -0,0 +1,51 @@
+# Trace-Diagnose Rubric Judge
+
+You are evaluating one rule against one agent trace. Read the rule's
+judge question, the supplied inputs, and reply with a single JSON object
+that satisfies the supplied output schema.
+
+## Rule
+- **rule_id**: `{{rule_id}}`
+- **trace_id**: `{{trace_id}}`
+
+## Judge Question
+{{judge_question}}
+
+## Inputs
+The rule's `inputs` have been resolved from the trace and serialized
+below. Each key matches the rule's `inputs[*].kind`; the value is what
+the binding extracted (string for `extract_from_root_attr`, ordered array
+for `filter_by_kind`, parsed JSON for `literal`). When inputs reference
+spans, each span includes its `spanId` — your `first_violating_step_id`
+must be one of those IDs.
+
+```json
+{{inputs}}
+```
+
+## Output Schema
+Your reply MUST be a single JSON object matching this schema. No prose,
+no markdown fences, no explanation outside the JSON — the response is
+parsed programmatically and rejected on any deviation.
+
+```json
+{{output_schema}}
+```
+
+{{language_instruction}}
+
+## Output Rules
+1. `first_violating_step_id` MUST be a real span id from the inputs above
+   — the diagnose pipeline correlates rubric findings with symbolic
+   findings on this id.
+2. `reasoning` should be one or two sentences, concrete and pointed at
+   evidence in the inputs (cite span ids).
+3. If `severity` is part of the schema, use the user-facing impact, not
+   the agent's internal struggle — a single retry that finished successfully
+   is `low` even if the mechanism was wasteful.
+4. If `confidence` is part of the schema, set it to `low` when the inputs
+   don't clearly demonstrate the symptom; `high` when multiple spans
+   converge on the same conclusion.
+5. If the judge question lists categorical options, pick the closest one
+   even if it isn't perfect — don't fall through to `other` unless the
+   evidence actively rules out every named category.

package/dist/agent-providers/prompts/within-trace-synthesizer-v1.prompt.md

@@ -0,0 +1,60 @@
+# Within-Trace Synthesizer
+
+You are given the findings produced by both pillars of trace diagnosis
+on **one trace** — symbolic (deterministic predicates) and rubric
+(LLM-judged semantic verdicts). Your job is to compose a short narrative
+that helps a developer act on them quickly.
+
+## Trace
+- **trace_id**: `{{trace_id}}`
+- **agent_id**: `{{agent_id}}`
+
+## Findings
+Each finding is one antipattern detected by one rule. `judgmentKind` is
+either `symbolic` (cheap, deterministic) or `rubric` (agent-judged).
+Multiple findings may describe the same incident from different angles —
+your job is to detect those overlaps.
+
+```json
+{{findings}}
+```
+
+## Output Schema
+Reply with a single JSON object satisfying this schema. No prose, no
+markdown fences — the response is parsed programmatically.
+
+```json
+{{output_schema}}
+```
+
+{{language_instruction}}
+
+## Composition Rules
+1. **headline** ≤ 160 characters; one sentence; lead with the user-facing
+   symptom, not the rule mechanics. ("Agent failed to recognize stale
+   retrieval results across 3 retries", not "tool_loop_no_state_change
+   fired with loop_count=3".)
+2. **primary_root_cause** points at the finding(s) that, if fixed, would
+   prevent the rest. If two findings describe the same incident (one
+   symbolic, one rubric), include both in `finding_ids` and explain the
+   relationship in `description`. Set `target_for_fix` to the most
+   actionable artifact among the cited findings' `suggested_fix.target`.
+   Use `null` only if no finding can plausibly be a root cause (rare).
+3. **fix_priority** orders ALL findings by what to address first. Severity
+   is the default tiebreak; promote a low-severity finding above a
+   higher one when the low one is a precondition for the high one (e.g.
+   "fix the swallowed tool error first; the truncation that follows
+   will go away on its own"). Give a one-line `reason` for each.
+4. **cross_finding_links** captures relationships:
+   - `same_incident`: two findings on the same span sequence, one symbolic
+     + one rubric — typical pairing pattern.
+   - `cascading`: finding A's symptom directly caused finding B.
+   - `redundant`: two rubric judgments produced similar verdicts on
+     unrelated symbolic findings — flag for rule pruning.
+   - `overlapping_evidence_spans`: spans overlap but the relation is
+     unclear; use as a last resort.
+   Only include links where you can name a concrete relation; an empty
+   `cross_finding_links` array is fine.
+5. Be concrete: every claim should be traceable to a finding by index.
+   If the findings array is empty, headline = "No findings", everything
+   else = null / empty arrays.

package/dist/agent-providers/providers/claude-code-subprocess.d.ts

@@ -0,0 +1,74 @@
+/**
+ * AgentProvider that spawns the Claude Code CLI as a one-shot subprocess.
+ *
+ *   $ claude -p --output-format=json --dangerously-skip-permissions <prompt-on-stdin>
+ *
+ * Why subprocess + the `claude` CLI (vs an HTTP / SDK transport):
+ *   - Zero remote service dependency for trace-ai diagnose — dogfoods
+ *     the same CLI the user already authenticates / configures.
+ *   - One binary to install across user laptops + CI.
+ *   - `--output-format=json` returns a stable envelope (`{ result: <text> }`)
+ *     so we can deterministically extract the model's answer.
+ *
+ * The model's textual response is expected to be JSON matching the
+ * caller's `outputSchema`. The provider:
+ *   1. spawns the CLI, pipes `prompt` to stdin
+ *   2. parses the CLI's stdout envelope (json mode)
+ *   3. extracts the inner text, parses it as JSON
+ *   4. validates against `outputSchema`
+ *   5. on parse / schema failure, retries the *whole* invocation once
+ *      with a "fix the JSON" suffix appended (bounded; PR-B doesn't
+ *      do exponential backoff)
+ *
+ * Failure modes surface as typed `AgentProviderError`:
+ *   not_available   `claude` not on PATH, or `isAvailable()` was false
+ *   timeout         subprocess exceeded timeoutMs
+ *   transport       non-zero exit / no stdout
+ *   invalid_json    envelope parsed but inner text wasn't JSON (after retry)
+ *   schema_violation inner JSON didn't satisfy outputSchema (after retry)
+ */
+import type { AgentProvider, JudgmentRequest, JudgmentResponse, ProviderCapability } from "../types.js";
+export interface ClaudeCodeSubprocessProviderOpts {
+    /** Override the binary on PATH (default: 'claude'). */
+    binary?: string;
+    /** Extra CLI args, prepended before our defaults. */
+    extraArgs?: string[];
+    /** Default timeout per invoke (ms). Per-call timeoutMs in JudgmentRequest takes precedence. */
+    defaultTimeoutMs?: number;
+    /** Working directory for the subprocess (default: process.cwd()). */
+    cwd?: string;
+    /** Environment overrides (merged with process.env). */
+    env?: Record<string, string>;
+    /** Override `name` reported on the provider (default: 'claude-code'). */
+    name?: string;
+    /**
+     * Map the tier intent on a JudgmentRequest to a concrete claude model name.
+     * Defaults: fast='haiku', std='sonnet'. `--model {value}` is appended to
+     * spawn args only when `req.tier` is set; undefined tier omits the flag
+     * and lets claude CLI pick its own default (preserves PR-B behavior).
+     */
+    modelByTier?: {
+        fast?: string;
+        std?: string;
+    };
+}
+export declare class ClaudeCodeSubprocessProvider implements AgentProvider {
+    readonly name: string;
+    readonly capabilities: ReadonlySet<ProviderCapability>;
+    private binary;
+    private extraArgs;
+    private defaultTimeoutMs;
+    private cwd;
+    private env;
+    private availabilityCache;
+    private modelByTier;
+    constructor(opts?: ClaudeCodeSubprocessProviderOpts);
+    /** Visible for testing. Builds the spawn args list including --model when tier is set. */
+    buildSpawnArgs(tier: "fast" | "std" | undefined): string[];
+    /**
+     * Cached for 60s — repeated rubric rules don't each pay the spawn cost
+     * of `claude --version`. Cache is per-instance, not process-wide.
+     */
+    isAvailable(): Promise<boolean>;
+    invoke<TOutput>(req: JudgmentRequest<TOutput>): Promise<JudgmentResponse<TOutput>>;
+}