@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.1

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

@@ -183,6 +183,7 @@ Commands:
   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 +288,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/bkn-ops.js

@@ -5,7 +5,7 @@ import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, va
 import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
-import { listTablesWithColumns, scanDatasourceMetadata } from "../api/datasources.js";
+import { listTablesWithColumns, scanDatasourceMetadata } from "../api/vega.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
 import { resolveFiles } from "./ds.js";
 import { buildTableName } from "./import-csv.js";
@@ -13,7 +13,7 @@ import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createA
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
-import { pollWithBackoff, detectDisplayKey, formatPkDetectionError, parsePkMap, resolvePrimaryKey, confirmYes, } from "./bkn-utils.js";
+import { pollWithBackoff, detectDisplayKey, formatPkDetectionError, parsePkMap, resolvePrimaryKey, confirmYes, assertVegaCatalogId, } from "./bkn-utils.js";
 // ── BKN object name validation ──────────────────────────────────────────────
 // Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
 // validateObjectName (driveradapters/validate.go:85). 40 utf-8 codepoints,
@@ -473,9 +473,11 @@ export async function runKnPullCommand(args) {
     }
 }
 // ── Create from datasource ──────────────────────────────────────────────────
-const KN_CREATE_FROM_DS_HELP = `kweaver bkn create-from-ds <ds-id> --name X [options]
+const KN_CREATE_FROM_DS_HELP = `kweaver bkn create-from-ds <vega-catalog-id> --name X [options]
 
-Create a knowledge network from a datasource (dataviews + object types + optional build).
+Create a knowledge network from a vega catalog datasource (dataviews + object types + optional build).
+<vega-catalog-id> is a vega catalog id (use \`kweaver vega catalog list\` to find one;
+legacy data-connection datasource UUIDs are no longer accepted).
 
 Options:
   --name <s>       Knowledge network name (required)
@@ -548,6 +550,7 @@ export function parseKnCreateFromDsArgs(args) {
     if (!dsId || !name) {
         throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
     }
+    assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
@@ -803,9 +806,11 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
     }
 }
 // ── Create from CSV ─────────────────────────────────────────────────────────
-const KN_CREATE_FROM_CSV_HELP = `kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]
+const KN_CREATE_FROM_CSV_HELP = `kweaver bkn create-from-csv <vega-catalog-id> --files <glob> --name X [options]
 
-Import CSV files into datasource, then create a knowledge network.
+Import CSV files into a vega catalog datasource, then create a knowledge network.
+<vega-catalog-id> is a vega catalog id (use \`kweaver vega catalog list\` to find one;
+legacy data-connection datasource UUIDs are no longer accepted).
 
 Options:
   --files <s>          CSV file paths (comma-separated or glob, required)
@@ -891,6 +896,7 @@ export function parseKnCreateFromCsvArgs(args) {
     if (!dsId || !files || !name) {
         throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
     }
+    assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();

package/dist/commands/bkn-utils.d.ts

@@ -86,4 +86,13 @@ export declare function detectDisplayKey(table: {
         type: string;
     }>;
 }, primaryKey: string): string;
+/**
+ * Reject legacy data-connection datasource UUIDs.
+ *
+ * Since the SDK migration to vega-backend (#114), commands that call
+ * `listTablesWithColumns` / `scanMetadata` expect a vega catalog id (a short
+ * slug like `d7nicrcjto2s73d9g67g`), not the UUID-shaped id stored in
+ * data-connection.
+ */
+export declare function assertVegaCatalogId(id: string): void;
 export declare function confirmYes(prompt: string): Promise<boolean>;

package/dist/commands/bkn-utils.js

@@ -183,6 +183,23 @@ export function detectDisplayKey(table, primaryKey) {
     }
     return primaryKey;
 }
+// ── Vega catalog id guard ────────────────────────────────────────────────────
+const UUID_V4_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/**
+ * Reject legacy data-connection datasource UUIDs.
+ *
+ * Since the SDK migration to vega-backend (#114), commands that call
+ * `listTablesWithColumns` / `scanMetadata` expect a vega catalog id (a short
+ * slug like `d7nicrcjto2s73d9g67g`), not the UUID-shaped id stored in
+ * data-connection.
+ */
+export function assertVegaCatalogId(id) {
+    if (UUID_V4_RE.test(id)) {
+        throw new Error(`expected a vega catalog id, got UUID '${id}'. ` +
+            `This looks like a legacy data-connection datasource UUID. ` +
+            `Run \`kweaver vega catalog list --keyword <name>\` to find the corresponding catalog id.`);
+    }
+}
 // ── Interactive confirmation ─────────────────────────────────────────────────
 export function confirmYes(prompt) {
     return new Promise((resolve) => {

package/dist/commands/ds.js

@@ -3,9 +3,11 @@ import { statSync } from "node:fs";
 import { glob } from "node:fs/promises";
 import { resolve as resolvePath } from "node:path";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTablesWithColumns, scanMetadata, } from "../api/datasources.js";
+import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, } from "../api/datasources.js";
+import { listTablesWithColumns, scanMetadata } from "../api/vega.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { assertVegaCatalogId } from "./bkn-utils.js";
 import { parseCsvFile, buildTableName, splitBatches, buildFieldMappings, buildDagBody, } from "./import-csv.js";
 import { executeDataflow } from "../api/dataflow.js";
 function confirmYes(prompt) {
@@ -196,9 +198,12 @@ async function runDsTablesCommand(args) {
             id = arg;
     }
     if (!id) {
-        console.error("Usage: kweaver ds tables <id> [--keyword X]");
+        console.error("Usage: kweaver ds tables <vega-catalog-id> [--keyword X]\n" +
+            "  <vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one;\n" +
+            "  legacy data-connection datasource UUIDs are no longer accepted).");
         return 1;
     }
+    assertVegaCatalogId(id);
     const token = await ensureValidToken();
     const body = await listTablesWithColumns({
         baseUrl: token.baseUrl,

package/dist/commands/trace.d.ts

@@ -0,0 +1,14 @@
+export interface ParsedTraceArgs {
+    subcommand: "diagnose" | "rules-validate" | "help";
+    conversationId?: string;
+    rulePath?: string;
+    out: string | null;
+    rulesDir: string | null;
+    noBuiltin: boolean;
+    noLlm: boolean;
+    baseUrl: string | null;
+    token: string | null;
+    businessDomain: string | null;
+}
+export declare function parseTraceArgs(argv: string[]): ParsedTraceArgs;
+export declare function runTraceCommand(rest: string[]): Promise<number>;

package/dist/commands/trace.js

@@ -0,0 +1,168 @@
+import yargs from "yargs";
+import { diagnose, TraceNotFoundError } from "../trace-core/diagnose/index.js";
+import { RuleLoadError } from "../trace-core/diagnose/rule-loader.js";
+import { RuleProbeError } from "../trace-core/diagnose/signal-probe.js";
+import { RuleSchema } from "../trace-core/diagnose/schemas.js";
+import { ensureValidToken } from "../auth/oauth.js";
+import yaml from "js-yaml";
+import fs from "node:fs/promises";
+export function parseTraceArgs(argv) {
+    if (argv.length === 0) {
+        return defaults("help");
+    }
+    const head = argv[0];
+    if (head !== "diagnose") {
+        return defaults("help");
+    }
+    if (argv[1] === "rules" && argv[2] === "validate") {
+        return { ...defaults("rules-validate"), rulePath: argv[3] };
+    }
+    // diagnose <traceId> [flags...]
+    const parsed = yargs(argv.slice(1))
+        .option("out", { type: "string", default: undefined })
+        .option("rules", { type: "string", default: undefined })
+        .option("builtin", { type: "boolean", default: true }) // --no-builtin sets this to false
+        .option("llm", { type: "boolean", default: false }) // PR-A: forced false (--no-llm)
+        .option("token", { type: "string" })
+        .option("base-url", { type: "string" })
+        .option("business-domain", { alias: "bd", type: "string" })
+        .help(false)
+        .parseSync();
+    return {
+        subcommand: "diagnose",
+        conversationId: String(parsed._[0] ?? ""),
+        out: parsed.out ?? null,
+        rulesDir: parsed.rules ?? null,
+        noBuiltin: !parsed.builtin,
+        noLlm: !parsed.llm,
+        baseUrl: parsed.baseUrl ?? null,
+        token: parsed.token ?? null,
+        businessDomain: parsed.businessDomain ?? null,
+    };
+}
+function defaults(sub) {
+    return {
+        subcommand: sub,
+        out: null,
+        rulesDir: null,
+        noBuiltin: false,
+        noLlm: true,
+        baseUrl: null,
+        token: null,
+        businessDomain: null,
+    };
+}
+function printHelp() {
+    process.stdout.write(`kweaver trace — trace diagnosis commands
+
+Subcommands:
+  trace diagnose <conversation_id>            Diagnose the trace produced by a conversation; emit YAML report
+                                              (the id is the conversation_id returned by 'agent chat' /
+                                              'agent sessions'; spans are fetched from agent-observability)
+    --out <file>                              Write report to file (default: stdout)
+    --rules <dir>                             Override <cwd>/diagnosis-rules/
+    --no-builtin                              Disable the 5 builtin baseline rules
+    --no-llm                                  PR-A: always on; PR-B will allow disabling
+
+  trace diagnose rules validate <rule.yaml>   Validate a rule yaml file (exit 0 ok, 6 fail)
+
+Auth flags (any subcommand): --token, --base-url, --business-domain (-bd).
+`);
+}
+export async function runTraceCommand(rest) {
+    const args = parseTraceArgs(rest);
+    if (args.subcommand === "help") {
+        printHelp();
+        return 0;
+    }
+    if (args.subcommand === "rules-validate") {
+        return await runRulesValidate(args.rulePath ?? "");
+    }
+    // diagnose
+    if (!args.conversationId) {
+        process.stderr.write("error: missing <conversation_id>\n");
+        return 2;
+    }
+    let baseUrl = args.baseUrl ?? process.env.KWEAVER_BASE_URL ?? "";
+    let token = args.token ?? process.env.KWEAVER_TOKEN ?? "";
+    const bd = args.businessDomain ?? process.env.KWEAVER_BUSINESS_DOMAIN ?? "bd_public";
+    // Fall back to the active platform from `~/.kweaver/` (same as agent trace),
+    // so users don't need to pass --base-url / --token explicitly. Tokens are
+    // auto-refreshed for OAuth platforms; "__NO_AUTH__" is returned for no-auth.
+    if (!baseUrl || !token) {
+        try {
+            const t = await ensureValidToken();
+            if (!baseUrl)
+                baseUrl = t.baseUrl;
+            if (!token)
+                token = t.accessToken;
+        }
+        catch (e) {
+            process.stderr.write(`error: missing --base-url / --token, and no active platform in ~/.kweaver/ — ${e.message}\n`);
+            return 5;
+        }
+    }
+    if (!baseUrl || !token) {
+        process.stderr.write("error: missing --base-url / --token (or KWEAVER_BASE_URL / KWEAVER_TOKEN env)\n");
+        return 5;
+    }
+    try {
+        await diagnose(args.conversationId, {
+            out: args.out,
+            rulesDir: args.rulesDir,
+            noBuiltin: args.noBuiltin,
+            noLlm: true,
+            agentProvider: null,
+            timeoutMs: 60000,
+            baseUrl,
+            token,
+            businessDomain: bd,
+        });
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof TraceNotFoundError) {
+            process.stderr.write(`error: ${e.message}; check time window / tenant\n`);
+            return 4;
+        }
+        if (e instanceof RuleLoadError) {
+            process.stderr.write(`error: ${e.message}\n`);
+            return 6;
+        }
+        if (e instanceof RuleProbeError) {
+            process.stderr.write(`error: ${e.message}\n`);
+            return 6;
+        }
+        process.stderr.write(`error: ${e.message}\n`);
+        return 1;
+    }
+}
+async function runRulesValidate(rulePath) {
+    if (!rulePath) {
+        process.stderr.write("error: missing <rule.yaml> path\n");
+        return 2;
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(rulePath, "utf8");
+    }
+    catch (e) {
+        process.stderr.write(`error: cannot read ${rulePath}: ${e.message}\n`);
+        return 6;
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (e) {
+        process.stderr.write(`error: yaml parse error: ${e.message}\n`);
+        return 6;
+    }
+    const result = RuleSchema.safeParse(parsed);
+    if (!result.success) {
+        process.stderr.write(`error: schema validation failed:\n${result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n")}\n`);
+        return 6;
+    }
+    process.stdout.write(`ok: ${rulePath} validates against diagnosis-rule/v1\n`);
+    return 0;
+}

package/dist/resources/datasources.js

@@ -1,4 +1,5 @@
-import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTables, listTablesWithColumns, scanMetadata, } from "../api/datasources.js";
+import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTables, } from "../api/datasources.js";
+import { listTablesWithColumns, scanMetadata } from "../api/vega.js";
 export class DataSourcesResource {
     ctx;
     constructor(ctx) {

package/dist/trace-core/diagnose/builtin-rules/excessive-tool-calls-per-turn.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;

package/dist/trace-core/diagnose/builtin-rules/excessive-tool-calls-per-turn.js

@@ -0,0 +1,15 @@
+// PR-A approximation: counts tool calls across the entire trace, not per user turn.
+// Real per-turn scoping requires turn segmentation by gen_ai.conversation.id round trips,
+// which is deferred to PR-B (where the synthesizer can also use turn boundaries for narratives).
+// For single-turn traces (the common case in PR-A) this approximation matches the rule semantics.
+export const predicate = (trace, params) => {
+    const max = params.max_tool_calls_per_turn ?? 10;
+    const tools = trace.byKind.get("tool") ?? [];
+    if (tools.length <= max)
+        return [];
+    return [{
+            evidenceSpans: tools.map((t) => t.spanId),
+            excerpt: `tool calls per turn exceeded threshold: ${tools.length} > ${max}`,
+            bindings: { count: tools.length, max_calls: max },
+        }];
+};

package/dist/trace-core/diagnose/builtin-rules/excessive-tool-calls-per-turn.yaml

@@ -0,0 +1,16 @@
+schema_version: diagnosis-rule/v1
+id: excessive_tool_calls_per_turn
+severity: medium
+symptom: excessive_tool_calls_per_user_turn
+taxonomy:
+  signals_axis: execution
+  ms_class: tool_misuse
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "constrain plan to at most {{max_calls}} tool calls per user turn; observed {{count}}"
+verify_with:
+  assertion_templates:
+    - "tool_call_count_per_turn <= {{max_calls}}"
+predicate: builtin:excessive_tool_calls_per_turn
+params:
+  max_tool_calls_per_turn: 10

package/dist/trace-core/diagnose/builtin-rules/llm-response-truncated-no-continue.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;

package/dist/trace-core/diagnose/builtin-rules/llm-response-truncated-no-continue.js

@@ -0,0 +1,44 @@
+function finishReason(s) {
+    // OTel GenAI 1.x emits an array (`finish_reasons`); older spans / fixtures
+    // use the singular string form. Accept both; first non-empty entry wins.
+    const arr = s.attributes["gen_ai.response.finish_reasons"];
+    if (Array.isArray(arr)) {
+        for (const r of arr) {
+            if (typeof r === "string" && r.length > 0)
+                return r;
+        }
+    }
+    const a = s.attributes["gen_ai.response.finish_reason"] ?? s.attributes["llm.finish_reason"];
+    return typeof a === "string" ? a : "";
+}
+function conversationId(s) {
+    const v = s.attributes["gen_ai.conversation.id"];
+    return typeof v === "string" ? v : "";
+}
+export const predicate = (trace) => {
+    const llms = (trace.byKind.get("llm") ?? [])
+        .slice()
+        .sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    for (let i = 0; i < llms.length; i++) {
+        const s = llms[i];
+        if (finishReason(s) !== "length")
+            continue;
+        const convId = conversationId(s);
+        let hasContinuation = false;
+        for (let j = i + 1; j < llms.length; j++) {
+            if (conversationId(llms[j]) === convId) {
+                hasContinuation = true;
+                break;
+            }
+        }
+        if (!hasContinuation) {
+            hits.push({
+                evidenceSpans: [s.spanId],
+                excerpt: `LLM response truncated (finish_reason=length) with no continuation span in conversation '${convId}'`,
+                bindings: { conversation_id: convId },
+            });
+        }
+    }
+    return hits;
+};

package/dist/trace-core/diagnose/builtin-rules/llm-response-truncated-no-continue.yaml

@@ -0,0 +1,15 @@
+schema_version: diagnosis-rule/v1
+id: llm_response_truncated_no_continue
+severity: medium
+symptom: llm_output_truncated_with_no_continuation
+taxonomy:
+  signals_axis: execution
+  ms_class: context_loss
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "after finish_reason=length, send a continuation request or split the task earlier"
+verify_with:
+  assertion_templates:
+    - "if(llm.finish_reason == 'length'): next_step in [continuation, split_task]"
+predicate: builtin:llm_response_truncated_no_continue
+params: {}

package/dist/trace-core/diagnose/builtin-rules/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/trace-core/diagnose/builtin-rules/register.js

@@ -0,0 +1,11 @@
+import { registerPredicate } from "../predicate-registry.js";
+import { predicate as toolLoopNoStateChange } from "./tool-loop-no-state-change.js";
+import { predicate as toolErrorSwallowed } from "./tool-error-swallowed.js";
+import { predicate as retrievalEmptyNoFallback } from "./retrieval-empty-no-fallback.js";
+import { predicate as llmResponseTruncatedNoContinue } from "./llm-response-truncated-no-continue.js";
+import { predicate as excessiveToolCallsPerTurn } from "./excessive-tool-calls-per-turn.js";
+registerPredicate("tool_loop_no_state_change", toolLoopNoStateChange);
+registerPredicate("tool_error_swallowed", toolErrorSwallowed);
+registerPredicate("retrieval_empty_no_fallback", retrievalEmptyNoFallback);
+registerPredicate("llm_response_truncated_no_continue", llmResponseTruncatedNoContinue);
+registerPredicate("excessive_tool_calls_per_turn", excessiveToolCallsPerTurn);

package/dist/trace-core/diagnose/builtin-rules/retrieval-empty-no-fallback.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;