@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

package/dist/index.js

@@ -44,7 +44,7 @@ export { ContextLoaderResource } from "./resources/context-loader.js";
 export { SkillsResource } from "./resources/skills.js";
 export { ToolboxesResource } from "./resources/toolboxes.js";
 export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
-export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
+export { listSkills, listSkillMarket, getSkill, getSkillMarketDetail, deleteSkill, updateSkillStatus, updateSkillMetadata, registerSkillContent, registerSkillZip, updateSkillPackageContent, updateSkillPackageZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, listSkillHistory, republishSkillHistory, publishSkillHistory, installSkillArchive, getSkillManagementContent, readSkillManagementFile, downloadSkillManagementArchive, } from "./api/skills.js";
 export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
 export { DataViewsResource } from "./resources/dataviews.js";
 export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";

package/dist/resources/bkn.d.ts

@@ -49,6 +49,11 @@ export declare class BknResource {
     /**
      * Search KN schema — finds matching object types, relation types, and action types.
      * Uses the public agent-retrieval HTTP compatibility endpoint.
+     *
+     * @deprecated Use `client.contextLoader(...).searchSchema(...)` for new
+     * schema discovery integrations. `knSearch` is kept only for compatibility
+     * with the legacy HTTP `kn_search` endpoint and may not receive new
+     * `search_schema` capabilities.
      */
     knSearch(knId: string, query: string, opts?: {
         onlySchema?: boolean;

package/dist/resources/bkn.js

@@ -90,6 +90,11 @@ export class BknResource {
     /**
      * Search KN schema — finds matching object types, relation types, and action types.
      * Uses the public agent-retrieval HTTP compatibility endpoint.
+     *
+     * @deprecated Use `client.contextLoader(...).searchSchema(...)` for new
+     * schema discovery integrations. `knSearch` is kept only for compatibility
+     * with the legacy HTTP `kn_search` endpoint and may not receive new
+     * `search_schema` capabilities.
      */
     async knSearch(knId, query, opts = {}) {
         const raw = await knSearchHttp({

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/resources/skills.d.ts

@@ -1,5 +1,5 @@
 import type { ClientContext } from "../client.js";
-import { type SkillListResult, type SkillStatus } from "../api/skills.js";
+import { type SkillCategory, type SkillListResult, type SkillStatus } from "../api/skills.js";
 export declare class SkillsResource {
     private readonly ctx;
     constructor(ctx: ClientContext);
@@ -24,6 +24,7 @@ export declare class SkillsResource {
         source?: string;
     }): Promise<SkillListResult>;
     get(skillId: string): Promise<import("../api/skills.js").SkillInfo>;
+    getMarket(skillId: string): Promise<import("../api/skills.js").SkillInfo>;
     registerContent(content: string, opts?: {
         source?: string;
         extendInfo?: Record<string, unknown>;
@@ -34,6 +35,18 @@ export declare class SkillsResource {
     }): Promise<import("../api/skills.js").RegisterSkillResult>;
     delete(skillId: string): Promise<import("../api/skills.js").DeleteSkillResult>;
     updateStatus(skillId: string, status: SkillStatus): Promise<import("../api/skills.js").UpdateSkillStatusResult>;
+    updateMetadata(skillId: string, metadata: {
+        name: string;
+        description: string;
+        category: SkillCategory;
+        source?: string;
+        extendInfo?: Record<string, unknown>;
+    }): Promise<import("../api/skills.js").UpdateSkillMetadataResult>;
+    updatePackageContent(skillId: string, content: string): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
+    updatePackageZip(skillId: string, filename: string, bytes: Uint8Array): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
+    history(skillId: string): Promise<import("../api/skills.js").SkillReleaseHistoryInfo[]>;
+    republishHistory(skillId: string, version: string): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
+    publishHistory(skillId: string, version: string): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
     content(skillId: string): Promise<import("../api/skills.js").SkillContentIndex>;
     fetchContent(skillId: string): Promise<string>;
     readFile(skillId: string, relPath: string): Promise<import("../api/skills.js").SkillFileReadResult>;
@@ -44,4 +57,7 @@ export declare class SkillsResource {
     }): Promise<{
         directory: string;
     }>;
+    getManagementContent(skillId: string, responseMode?: "url" | "content"): Promise<import("../api/skills.js").SkillManagementContentData>;
+    readManagementFile(skillId: string, relPath: string): Promise<import("../api/skills.js").SkillFileReadResult>;
+    downloadManagementArchive(skillId: string, responseMode?: "url" | "content"): Promise<import("../api/skills.js").DownloadedSkillArchive>;
 }

package/dist/resources/skills.js

@@ -1,4 +1,4 @@
-import { deleteSkill, downloadSkill, fetchSkillContent, fetchSkillFile, getSkill, getSkillContentIndex, installSkillArchive, listSkillMarket, listSkills, readSkillFile, registerSkillContent, registerSkillZip, updateSkillStatus, } from "../api/skills.js";
+import { deleteSkill, downloadSkill, downloadSkillManagementArchive, fetchSkillContent, fetchSkillFile, getSkill, getSkillMarketDetail, getSkillContentIndex, getSkillManagementContent, installSkillArchive, listSkillMarket, listSkillHistory, listSkills, publishSkillHistory, readSkillFile, readSkillManagementFile, republishSkillHistory, registerSkillContent, registerSkillZip, updateSkillMetadata, updateSkillPackageContent, updateSkillPackageZip, updateSkillStatus, } from "../api/skills.js";
 export class SkillsResource {
     ctx;
     constructor(ctx) {
@@ -13,6 +13,9 @@ export class SkillsResource {
     async get(skillId) {
         return getSkill({ ...this.ctx.base(), skillId });
     }
+    async getMarket(skillId) {
+        return getSkillMarketDetail({ ...this.ctx.base(), skillId });
+    }
     async registerContent(content, opts = {}) {
         return registerSkillContent({ ...this.ctx.base(), content, ...opts });
     }
@@ -25,6 +28,24 @@ export class SkillsResource {
     async updateStatus(skillId, status) {
         return updateSkillStatus({ ...this.ctx.base(), skillId, status });
     }
+    async updateMetadata(skillId, metadata) {
+        return updateSkillMetadata({ ...this.ctx.base(), skillId, ...metadata });
+    }
+    async updatePackageContent(skillId, content) {
+        return updateSkillPackageContent({ ...this.ctx.base(), skillId, content });
+    }
+    async updatePackageZip(skillId, filename, bytes) {
+        return updateSkillPackageZip({ ...this.ctx.base(), skillId, filename, bytes });
+    }
+    async history(skillId) {
+        return listSkillHistory({ ...this.ctx.base(), skillId });
+    }
+    async republishHistory(skillId, version) {
+        return republishSkillHistory({ ...this.ctx.base(), skillId, version });
+    }
+    async publishHistory(skillId, version) {
+        return publishSkillHistory({ ...this.ctx.base(), skillId, version });
+    }
     async content(skillId) {
         return getSkillContentIndex({ ...this.ctx.base(), skillId });
     }
@@ -44,4 +65,14 @@ export class SkillsResource {
         const archive = await this.download(skillId);
         return installSkillArchive({ bytes: archive.bytes, directory, force: opts.force });
     }
+    // ── Management Content ───────────────────────────────────────────────────────
+    async getManagementContent(skillId, responseMode) {
+        return getSkillManagementContent({ ...this.ctx.base(), skillId, responseMode });
+    }
+    async readManagementFile(skillId, relPath) {
+        return readSkillManagementFile({ ...this.ctx.base(), skillId, relPath });
+    }
+    async downloadManagementArchive(skillId, responseMode) {
+        return downloadSkillManagementArchive({ ...this.ctx.base(), skillId, responseMode });
+    }
 }

package/dist/trace-ai/diagnose/agent-binding.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Stage-2 — rubric judgments: resolve rubric.inputs against a TraceTree,
+ * render the prompt template, invoke the agent provider, and map the
+ * schema-validated output to a `Finding`.
+ *
+ * Why this layer exists separate from `signal-probe`:
+ *   - Async / I/O-bound (subprocess or HTTP) vs. sync predicates
+ *   - Per-rule provider lookup + skip-on-unavailable
+ *   - Error semantics differ (skip + record vs. throw RuleProbeError)
+ *
+ * Convergence invariant (enforced upstream in schemas.ts): every rubric
+ * `output_schema.required` includes `first_violating_step_id`, so each
+ * rubric finding always points at a concrete span and can be correlated
+ * with symbolic findings on the same span by the synthesizer.
+ */
+import type { Finding, Rule, RubricInputSpec, TraceTree } from "./types.js";
+import type { AgentRegistry } from "../../agent-providers/registry.js";
+import { PromptTemplateRegistry, type AgentOutputLang } from "../../agent-providers/prompt-template.js";
+import type { ArtifactWriter } from "../scan/artifacts/writer.js";
+export interface RubricEvaluateOpts {
+    rules: Rule[];
+    tree: TraceTree;
+    registry: AgentRegistry;
+    promptRegistry: PromptTemplateRegistry;
+    /** If true, all rubric rules are skipped with reason='no-llm-flag-set'. */
+    noLlm?: boolean;
+    /** Per-invocation timeout in ms; provider may apply its own ceiling. */
+    timeoutMs?: number;
+    /** Output locale for natural-language fields in the agent reply. Default 'en'. */
+    lang?: AgentOutputLang;
+    /** When provided, writes Stage-2 prompt/response artifacts per rule invocation. */
+    artifacts?: ArtifactWriter;
+    /** User query extracted from trace input.messages (2026-05-13). */
+    userQuery?: string | null;
+    /** Conversation/query ID for suggested_eval_case correlation (2026-05-13). */
+    queryId?: string | null;
+}
+export interface RubricEvaluateResult {
+    findings: Finding[];
+    skipped: {
+        ruleId: string;
+        reason: string;
+    }[];
+}
+/** Resolve one rubric input spec against the trace and return a value
+ *  suitable for prompt interpolation. Pure for testability. */
+export declare function resolveRubricInput(spec: RubricInputSpec, tree: TraceTree): unknown;
+export declare class AgentBindingError extends Error {
+    constructor(message: string);
+}
+export declare function renderChangeTemplate(tpl: string, bindings: Record<string, unknown>): string;
+/**
+ * Evaluate every rubric rule in `rules` and return findings + skip records.
+ *
+ * A rule is *skipped* (not failed) when:
+ *   - `--no-llm` is set → reason: 'no-llm-flag-set'
+ *   - rule's named provider isn't registered or `isAvailable()` is false
+ *     → reason: `provider-not-available:<name>`
+ *   - rule's prompt template isn't registered
+ *     → reason: `prompt-template-missing:<ref>`
+ *
+ * Schema violations / transport errors from the provider are surfaced
+ * as `AgentBindingError` (let the CLI decide whether to fail the whole
+ * run or skip the single rule). Default callsite (`index.ts`) catches
+ * these and records them in `rules_skipped` rather than aborting.
+ */
+export declare function evaluateRubricRules(opts: RubricEvaluateOpts): Promise<RubricEvaluateResult>;

package/dist/trace-ai/diagnose/agent-binding.js

@@ -0,0 +1,257 @@
+/**
+ * Stage-2 — rubric judgments: resolve rubric.inputs against a TraceTree,
+ * render the prompt template, invoke the agent provider, and map the
+ * schema-validated output to a `Finding`.
+ *
+ * Why this layer exists separate from `signal-probe`:
+ *   - Async / I/O-bound (subprocess or HTTP) vs. sync predicates
+ *   - Per-rule provider lookup + skip-on-unavailable
+ *   - Error semantics differ (skip + record vs. throw RuleProbeError)
+ *
+ * Convergence invariant (enforced upstream in schemas.ts): every rubric
+ * `output_schema.required` includes `first_violating_step_id`, so each
+ * rubric finding always points at a concrete span and can be correlated
+ * with symbolic findings on the same span by the synthesizer.
+ */
+import { AgentProviderError } from "../../agent-providers/types.js";
+import { render as renderPrompt, languageInstructionFor, } from "../../agent-providers/prompt-template.js";
+/** Resolve one rubric input spec against the trace and return a value
+ *  suitable for prompt interpolation. Pure for testability. */
+export function resolveRubricInput(spec, tree) {
+    const colon = spec.source.indexOf(":");
+    if (colon === -1) {
+        throw new AgentBindingError(`rubric input source missing prefix (expected '<scheme>:...'): '${spec.source}'`);
+    }
+    const scheme = spec.source.slice(0, colon);
+    const payload = spec.source.slice(colon + 1);
+    switch (scheme) {
+        case "extract_from_root_attr": {
+            // dotted path against root.attributes (nested attr lookups are common).
+            const root = tree.root;
+            if (!root)
+                return null;
+            return getDottedPath(root.attributes, payload);
+        }
+        case "filter_by_kind": {
+            // payload form: '[kind1,kind2,...]' or 'kind1,kind2,...'
+            const inner = payload.replace(/^\[|\]$/g, "");
+            const kinds = inner.split(",").map((s) => s.trim()).filter(Boolean);
+            const acc = [];
+            for (const k of kinds) {
+                const spans = tree.byKind.get(k) ?? [];
+                for (const s of spans) {
+                    acc.push({
+                        spanId: s.spanId,
+                        name: s.name,
+                        kind: s.kind,
+                        attributes: s.attributes,
+                        durationMs: s.durationMs,
+                        status: s.status,
+                    });
+                }
+            }
+            // Order chronologically so the agent reads a coherent timeline.
+            acc.sort((a, b) => {
+                const sa = tree.byId.get(a.spanId)?.startTimeUnixNano ?? "0";
+                const sb = tree.byId.get(b.spanId)?.startTimeUnixNano ?? "0";
+                return Number(BigInt(sa) - BigInt(sb));
+            });
+            return acc;
+        }
+        case "literal":
+            try {
+                return JSON.parse(payload);
+            }
+            catch (e) {
+                throw new AgentBindingError(`literal source has invalid JSON: ${e.message}`);
+            }
+        default:
+            throw new AgentBindingError(`unknown rubric input source scheme: '${scheme}'`);
+    }
+}
+export class AgentBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentBindingError";
+    }
+}
+/** OTel attribute keys are typically flat strings with literal dots
+ *  (e.g. `gen_ai.user.message`), but some traces nest objects under a
+ *  parent attribute. Try direct lookup first; fall back to nested walk. */
+function getDottedPath(obj, path) {
+    if (obj === null || obj === undefined || typeof obj !== "object")
+        return undefined;
+    const flat = obj[path];
+    if (flat !== undefined)
+        return flat;
+    let cur = obj;
+    for (const part of path.split(".")) {
+        if (cur === null || cur === undefined)
+            return undefined;
+        if (typeof cur !== "object")
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function buildPromptVars(rule, tree, resolvedInputs, lang) {
+    // Surface enough context that builtin:rubric-judge-v1 can be a generic
+    // template without per-rule knowledge: judge question + inputs blob +
+    // rule metadata. `language_instruction` localizes prose fields only;
+    // schema-fixed values (enums, span IDs) stay English regardless.
+    return {
+        rule_id: rule.id,
+        judge_question: rule.rubric?.judgeQuestion ?? "",
+        output_schema: rule.rubric?.outputSchemaRaw ?? {},
+        inputs: resolvedInputs,
+        trace_id: tree.traceId,
+        language_instruction: languageInstructionFor(lang),
+    };
+}
+async function evaluateOne(rule, tree, provider, promptRegistry, timeoutMs, lang = "en", artifacts, userQuery = null, queryId = null) {
+    const rubric = rule.rubric; // caller guarantees
+    // Resolve inputs.
+    const resolvedInputs = {};
+    for (const inp of rubric.inputs) {
+        resolvedInputs[inp.kind] = resolveRubricInput(inp, tree);
+    }
+    // Render prompt.
+    const tpl = promptRegistry.get(rubric.agentBinding.promptTemplateRef);
+    const prompt = renderPrompt(tpl, buildPromptVars(rule, tree, resolvedInputs, lang));
+    if (artifacts) {
+        await artifacts.writeStageTwoPrompt(rule.id, 0, prompt); // chunk-000 — single-trace mode K=1
+    }
+    // Invoke.
+    const resp = await provider.invoke({
+        prompt,
+        outputSchema: rubric.outputZodSchema,
+        timeoutMs,
+        correlationId: `${tree.traceId}/${rule.id}`,
+    });
+    if (artifacts) {
+        await artifacts.writeStageTwoResponse(rule.id, 0, resp.output);
+    }
+    const out = resp.output;
+    const firstSpan = out.first_violating_step_id;
+    const otherSpans = Array.isArray(out.evidence_span_ids) ? out.evidence_span_ids : [];
+    // Convergence: ensure first_violating_step_id is in evidence.spans.
+    const spans = otherSpans.includes(firstSpan) ? otherSpans : [firstSpan, ...otherSpans];
+    return {
+        ruleId: rule.id,
+        judgmentKind: "rubric",
+        severity: out.severity ?? rule.severity, // agent may upgrade/downgrade
+        symptom: rule.symptom,
+        likelyCause: out.category ?? out.reasoning ?? rule.symptom,
+        evidence: {
+            spans,
+            excerpt: out.reasoning ?? "",
+        },
+        suggestedFix: {
+            target: rule.suggestedFix.target,
+            // Render changeTemplate with rubric output as bindings (best-effort:
+            // string-keyed values; complex shapes pass through unchanged).
+            change: renderChangeTemplate(rule.suggestedFix.changeTemplate, out),
+        },
+        confidence: out.confidence ?? "medium", // rubric default > symbolic
+        verifyWith: {
+            suggestedEvalCase: {
+                queryId,
+                query: userQuery,
+                assertions: rule.verifyWith.assertionTemplates.map((t) => renderChangeTemplate(t, out)),
+            },
+        },
+    };
+}
+export function renderChangeTemplate(tpl, bindings) {
+    return tpl.replace(/{{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*}}/g, (_, key) => {
+        const v = bindings[key];
+        if (v === undefined || v === null)
+            return `{{${key}}}`;
+        return typeof v === "string" ? v : JSON.stringify(v);
+    });
+}
+/**
+ * Evaluate every rubric rule in `rules` and return findings + skip records.
+ *
+ * A rule is *skipped* (not failed) when:
+ *   - `--no-llm` is set → reason: 'no-llm-flag-set'
+ *   - rule's named provider isn't registered or `isAvailable()` is false
+ *     → reason: `provider-not-available:<name>`
+ *   - rule's prompt template isn't registered
+ *     → reason: `prompt-template-missing:<ref>`
+ *
+ * Schema violations / transport errors from the provider are surfaced
+ * as `AgentBindingError` (let the CLI decide whether to fail the whole
+ * run or skip the single rule). Default callsite (`index.ts`) catches
+ * these and records them in `rules_skipped` rather than aborting.
+ */
+export async function evaluateRubricRules(opts) {
+    const findings = [];
+    const skipped = [];
+    for (const rule of opts.rules) {
+        if (!rule.rubric)
+            continue;
+        if (opts.noLlm) {
+            skipped.push({ ruleId: rule.id, reason: "no-llm-flag-set" });
+            continue;
+        }
+        // Resolve provider for this rule.
+        let provider;
+        try {
+            provider = opts.registry.resolve({
+                preferred: rule.rubric.agentBinding.provider,
+                requiredCapabilities: ["structured_output"],
+            });
+        }
+        catch (e) {
+            if (e instanceof AgentProviderError && e.kind === "not_available") {
+                skipped.push({
+                    ruleId: rule.id,
+                    reason: `provider-not-available:${rule.rubric.agentBinding.provider}`,
+                });
+                continue;
+            }
+            throw e;
+        }
+        if (!provider) {
+            skipped.push({
+                ruleId: rule.id,
+                reason: `provider-not-available:${rule.rubric.agentBinding.provider}`,
+            });
+            continue;
+        }
+        if (!(await provider.isAvailable())) {
+            skipped.push({
+                ruleId: rule.id,
+                reason: `provider-not-available:${rule.rubric.agentBinding.provider}`,
+            });
+            continue;
+        }
+        if (!opts.promptRegistry.has(rule.rubric.agentBinding.promptTemplateRef)) {
+            skipped.push({
+                ruleId: rule.id,
+                reason: `prompt-template-missing:${rule.rubric.agentBinding.promptTemplateRef}`,
+            });
+            continue;
+        }
+        try {
+            // Write work-queue once per rule before invoking (single-trace: 1 entry).
+            await opts.artifacts?.writeStageTwoWorkQueue(rule.id, [opts.tree.traceId]);
+            const finding = await evaluateOne(rule, opts.tree, provider, opts.promptRegistry, opts.timeoutMs, opts.lang ?? "en", opts.artifacts, opts.userQuery ?? null, opts.queryId ?? null);
+            findings.push(finding);
+        }
+        catch (e) {
+            if (e instanceof AgentProviderError) {
+                // Provider-level failures (timeout / transport / schema_violation) downgrade
+                // to a skip; the rest of the run still produces a usable report.
+                skipped.push({
+                    ruleId: rule.id,
+                    reason: `agent-error:${e.kind}`,
+                });
+                continue;
+            }
+            throw e;
+        }
+    }
+    return { findings, skipped };
+}

package/dist/trace-ai/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-ai/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-ai/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-ai/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-ai/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-ai/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-ai/diagnose/builtin-rules/register.d.ts

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

package/dist/trace-ai/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-ai/diagnose/builtin-rules/retrieval-empty-no-fallback.d.ts

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

package/dist/trace-ai/diagnose/builtin-rules/retrieval-empty-no-fallback.js

@@ -0,0 +1,29 @@
+function resultCount(s) {
+    const v = s.attributes["gen_ai.retrieval.result_count"];
+    return typeof v === "number" ? v : null;
+}
+export const predicate = (trace) => {
+    const ordered = trace.spans
+        .slice()
+        .sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    for (let i = 0; i < ordered.length; i++) {
+        const s = ordered[i];
+        if (s.kind !== "retrieval")
+            continue;
+        if (resultCount(s) !== 0)
+            continue;
+        const next = ordered[i + 1];
+        if (!next)
+            continue;
+        if (next.kind === "llm") {
+            hits.push({
+                evidenceSpans: [s.spanId, next.spanId],
+                excerpt: `retrieval returned 0 results; next step was LLM generation with no fallback path`,
+                bindings: {},
+            });
+        }
+        // retrieval (retry/rewrite) or tool (alt source) → no hit
+    }
+    return hits;
+};

package/dist/trace-ai/diagnose/builtin-rules/retrieval-empty-no-fallback.yaml

@@ -0,0 +1,15 @@
+schema_version: diagnosis-rule/v1
+id: retrieval_empty_no_fallback
+severity: medium
+symptom: empty_retrieval_result_no_fallback_path
+taxonomy:
+  signals_axis: execution
+  ms_class: cascading_error
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "when retrieval returns 0 results, branch to query rewrite, alternate source, or explicit 'no answer' before generating"
+verify_with:
+  assertion_templates:
+    - "if(retrieval.result_count == 0): next_step in [retry, rewrite, alt_source, no_answer]"
+predicate: builtin:retrieval_empty_no_fallback
+params: {}

package/dist/trace-ai/diagnose/builtin-rules/tool-error-swallowed.d.ts

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