@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

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
@@ -145,15 +165,26 @@ 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.
 
@@ -189,10 +220,13 @@ 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 skill list/market/get/market-get/register/status/delete/update-metadata/update-package/history/republish/publish-history/content/read-file/download/install/management-content/management-read-file/management-download
 kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
+kweaver context-loader help <subcommand>
 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 search-schema <kn-id> <query> [--scope object,relation,action,metric] [--concept-groups ids]
+kweaver context-loader tool-call <kn-id> <name> --args '<json>'
+kweaver context-loader kn-search|kn-schema-search <kn-id> <query> [...]  (deprecated; use search-schema)
 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
@@ -312,7 +346,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

@@ -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/` 下的拷贝在下次构建时会被覆盖。
+
 ## 快速上手
 
 ### 认证
@@ -138,15 +156,26 @@ 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 尚未提供类型化封装的场景，参数会原样透传。
 
@@ -177,10 +206,13 @@ 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 skill list/market/get/market-get/register/status/delete/update-metadata/update-package/history/republish/publish-history/content/read-file/download/install/management-content/management-read-file/management-download
 kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
+kweaver context-loader help <subcommand>
 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 search-schema <kn-id> <query> [--scope object,relation,action,metric] [--concept-groups ids]
+kweaver context-loader tool-call <kn-id> <name> --args '<json>'
+kweaver context-loader kn-search|kn-schema-search <kn-id> <query> [...]  （deprecated；请使用 search-schema）
 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]
@@ -271,7 +303,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>>;
+}