@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

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/tool-retry-intent-mismatch.yaml

@@ -0,0 +1,68 @@
+schema_version: diagnosis-rule/v1
+id: tool_retry_intent_mismatch
+
+# Paired with the symbolic rule `tool_loop_no_state_change`:
+#   - symbolic rule:  "the same tool ran N times with identical args"
+#   - this rubric:    "given the user's intent and the retry context,
+#                      WHY did the agent keep retrying?"
+#
+# The two findings will share span sequences (Stage-1↔Stage-2 convergence
+# is enforced because output_schema.required includes
+# first_violating_step_id), so the within-trace synthesizer can collapse
+# them into one cross_finding_link with relation="same span sequence;
+# symbolic detects mechanical pattern, rubric judges semantic intent".
+
+severity: high
+symptom: repeated_tool_call_without_state_change
+
+taxonomy:
+  signals_axis: execution
+  ms_class: retry_loop
+
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "agent retried because of '{{category}}'; address that intent (e.g. add staleness detection, broaden query, escalate to human)"
+
+verify_with:
+  assertion_templates:
+    - "for the same conversation, the agent reaches a non-retry next step"
+
+rubric:
+  gates_on:
+    - tool_loop_no_state_change
+  judge_question: >-
+    Given the user's intent and the tool retry pattern in this trace,
+    classify why the agent kept calling the same tool: a legitimate
+    retry strategy (expecting changed state), a stale-results handling
+    failure (results were identical and the agent didn't recognize that),
+    prompt confusion (the agent misinterpreted its own instructions),
+    or other.
+  inputs:
+    - kind: user_intent
+      source: extract_from_root_attr:gen_ai.user.message
+    - kind: span_sequence
+      source: filter_by_kind:[tool,llm]
+  output_schema:
+    type: object
+    required: [category, reasoning, severity, first_violating_step_id]
+    properties:
+      category:
+        type: string
+        enum: [legitimate_retry, stale_results, prompt_confusion, other]
+      reasoning:
+        type: string
+      severity:
+        type: string
+        enum: [low, medium, high]
+      confidence:
+        type: string
+        enum: [low, medium, high]
+      first_violating_step_id:
+        type: string
+      evidence_span_ids:
+        type: array
+        items:
+          type: string
+  agent_binding:
+    provider: claude-code
+    prompt_template_ref: builtin:rubric-judge-v1

package/dist/trace-ai/diagnose/index.d.ts

@@ -0,0 +1,32 @@
+import { RuleLoadError } from "./rule-loader.js";
+import { RuleProbeError } from "./signal-probe.js";
+import type { DiagnoseOpts, Report } from "./types.js";
+import type { AgentRegistry } from "../../agent-providers/registry.js";
+import { PromptTemplateRegistry } from "../../agent-providers/prompt-template.js";
+import "./builtin-rules/register.js";
+export declare class TraceNotFoundError extends Error {
+    constructor(conversationId: string);
+}
+/**
+ * Allow callers (CLI, tests, future scan-mode) to inject a custom registry
+ * + prompt registry without globals. The CLI in `commands/trace.ts` calls
+ * `diagnose()` and registers the default ClaudeCodeSubprocessProvider into
+ * `defaultRegistry` ahead of time; tests pass their own registry containing
+ * a StubAgentProvider.
+ */
+export interface DiagnoseInternalOpts {
+    /** Override the AgentRegistry used for rubric rules + synthesizer. */
+    registry?: AgentRegistry;
+    /** Override the PromptTemplateRegistry. */
+    promptRegistry?: PromptTemplateRegistry;
+}
+export declare function diagnose(conversationId: string, opts: DiagnoseOpts, internal?: DiagnoseInternalOpts): Promise<Report>;
+/** Resolve which file paths to write given the user-supplied --out and format.
+ *  Both: derive the missing extension from the given one; if --out had no
+ *  recognized extension, append .yaml / .md. Single-format: write to --out
+ *  verbatim (caller's extension is honored as-is). */
+export declare function derivePaths(out: string, format: 'yaml' | 'markdown' | 'both'): {
+    yamlPath: string | null;
+    mdPath: string | null;
+};
+export { TraceNotFoundError as DiagnoseTraceNotFound, RuleLoadError, RuleProbeError };

package/dist/trace-ai/diagnose/index.js

@@ -0,0 +1,246 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { fileURLToPath } from "node:url";
+import { getSpansByConversationId } from "../../api/trace.js";
+import { assembleTraceTree } from "./trace-shaper.js";
+import { loadRules, RuleLoadError } from "./rule-loader.js";
+import { runRules, RuleProbeError, rubricRules } from "./signal-probe.js";
+import { agentSynthesize } from "./synthesizer-agent.js";
+import { evaluateRubricRules } from "./agent-binding.js";
+import { assembleReport, reportToYamlObject, symbolicHitsToFindings } from "./report-assembler.js";
+import { renderReportMarkdown } from "./report-markdown.js";
+import { defaultRegistry } from "../../agent-providers/registry.js";
+import { defaultPromptRegistry, } from "../../agent-providers/prompt-template.js";
+import { ArtifactWriter } from "../scan/artifacts/writer.js";
+import { resolveArtifactsBase } from "../scan/artifacts/paths.js";
+import { extractUserQueryFromTrace } from "./query-extractor.js";
+import "./builtin-rules/register.js"; // side effect: registers all builtin predicates
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUILTIN_DIR = path.join(__dirname, "builtin-rules");
+// Prompts moved to top-level agent-providers/ when the trace-core/ container
+// was split (refactor 2026-05-12). diagnose/ now sits two levels under src/,
+// so we go up two and across.
+const SHARED_PROMPT_DIR = path.join(__dirname, "..", "..", "agent-providers", "prompts");
+export class TraceNotFoundError extends Error {
+    constructor(conversationId) {
+        super(`no spans found for conversation: ${conversationId}`);
+        this.name = "TraceNotFoundError";
+    }
+}
+let sharedPromptsLoaded = false;
+async function ensureBuiltinPromptsLoaded(reg) {
+    if (reg !== defaultPromptRegistry) {
+        // Caller-provided registry: load on every call so test-specific
+        // overrides see their content (cheap; ENOENT is no-op).
+        await reg.loadBuiltinDir(SHARED_PROMPT_DIR);
+        return;
+    }
+    if (sharedPromptsLoaded)
+        return;
+    await reg.loadBuiltinDir(SHARED_PROMPT_DIR);
+    sharedPromptsLoaded = true;
+}
+export async function diagnose(conversationId, opts, internal = {}) {
+    const t_start = Date.now();
+    const cwdRulesDir = opts.rulesDir ?? path.join(process.cwd(), "diagnosis-rules");
+    const registry = internal.registry ?? defaultRegistry;
+    const promptRegistry = internal.promptRegistry ?? defaultPromptRegistry;
+    await ensureBuiltinPromptsLoaded(promptRegistry);
+    // ── Artifact writer setup ────────────────────────────────────────────────
+    const artifactsEnabled = !(opts.noArtifacts ?? false) && opts.out !== null;
+    const artifactsBase = artifactsEnabled
+        ? resolveArtifactsBase({ mode: "single", out: opts.out })
+        : "";
+    const artifacts = new ArtifactWriter({ base: artifactsBase, enabled: artifactsEnabled });
+    // ── 1. Fetch + shape spans ──────────────────────────────────────────────
+    const fetched = await getSpansByConversationId({
+        baseUrl: opts.baseUrl,
+        token: opts.token,
+        businessDomain: opts.businessDomain,
+        conversationId,
+    });
+    const rawSpans = fetched.spans;
+    if (rawSpans.length === 0)
+        throw new TraceNotFoundError(conversationId);
+    const observedTraceIds = fetched.traceIds.length > 0
+        ? fetched.traceIds
+        : [...new Set(rawSpans.map((s) => s.traceId).filter((t) => Boolean(t)))];
+    const primaryTraceId = observedTraceIds[0] ?? conversationId;
+    if (observedTraceIds.length > 1) {
+        process.stderr.write(`warning: conversation ${conversationId} has ${observedTraceIds.length} traces; diagnosing the first (${primaryTraceId})\n`);
+    }
+    const spansForPrimary = observedTraceIds.length > 0
+        ? rawSpans.filter((s) => !s.traceId || s.traceId === primaryTraceId)
+        : rawSpans;
+    const tree = assembleTraceTree(primaryTraceId, spansForPrimary);
+    // ── 1b. Extract user query for suggested_eval_case population ───────────
+    const userQuery = extractUserQueryFromTrace(tree);
+    const queryId = conversationId;
+    // ── 2. Load rules + run Stage-1 (symbolic) ──────────────────────────────
+    const rules = await loadRules({
+        builtinDir: BUILTIN_DIR,
+        cwdRulesDir,
+        extraRulesDir: null,
+        noBuiltin: opts.noBuiltin,
+    });
+    const hits = await runRules(rules, tree);
+    const symbolicFindings = symbolicHitsToFindings(rules, hits, userQuery, queryId);
+    // ── 3. Stage-2 (rubric) — skip everything when --no-llm ─────────────────
+    const haveRubric = rubricRules(rules).length > 0;
+    let rubricFindings = [];
+    let rulesSkipped = [];
+    if (haveRubric) {
+        const r = await evaluateRubricRules({
+            rules,
+            tree,
+            registry,
+            promptRegistry,
+            noLlm: opts.noLlm,
+            timeoutMs: opts.timeoutMs,
+            lang: opts.lang,
+            artifacts,
+            userQuery,
+            queryId,
+        });
+        rubricFindings = r.findings;
+        rulesSkipped = r.skipped;
+    }
+    const allFindings = [...symbolicFindings, ...rubricFindings];
+    // ── 4. Stage-3 — agent synthesizer (template fallback) ──────────────────
+    const synthProvider = opts.noLlm
+        ? null
+        : registry.resolve({ preferred: opts.agentProvider ?? undefined });
+    const synth = await agentSynthesize({
+        findings: allFindings,
+        traceId: primaryTraceId,
+        agentId: extractAgentId(tree),
+        provider: synthProvider,
+        promptRegistry,
+        timeoutMs: opts.timeoutMs,
+        lang: opts.lang,
+        artifacts,
+    });
+    // ── 5. Assemble report ──────────────────────────────────────────────────
+    const haveSymbolic = rules.some((r) => r.predicateRef !== null);
+    const ranRubric = haveRubric && !opts.noLlm;
+    const mode = haveSymbolic && ranRubric
+        ? "hybrid"
+        : ranRubric
+            ? "rubric-only"
+            : "symbolic-only";
+    const version = await cliVersion();
+    const report = assembleReport({
+        traceId: primaryTraceId,
+        agentId: extractAgentId(tree),
+        tenant: extractTenant(tree),
+        cliVersion: version,
+        rules,
+        hits,
+        extraFindings: rubricFindings,
+        summary: synth.summary,
+        mode,
+        rulesSkipped,
+        synthesizerMode: synth.mode,
+        userQuery,
+        queryId,
+    });
+    // ── 6. Write run-metadata artifact ─────────────────────────────────────
+    const t_total = Date.now() - t_start;
+    await artifacts.writeRunMetadata({
+        cli_args: { conv_id: conversationId, out: opts.out, lang: opts.lang ?? "en" },
+        agent_id: extractAgentId(tree) ?? "",
+        rule_load_summary: {
+            rules_applied: rules.map((r) => r.id),
+            rules_skipped_at_load: [],
+            rules_dir: opts.rulesDir ?? "builtin",
+        },
+        single_agent_validation: { checked_conv_ids: 1, agent_id_resolved: extractAgentId(tree) ?? "" },
+        timing: { stage_1_ms: 0, stage_2_ms: 0, stage_3_ms: 0, stage_4_ms: 0, total_ms: t_total },
+        llm_calls: {
+            stage_2_chunks: rubricFindings.length > 0 ? 1 : 0,
+            stage_3: synth.mode === "agent" ? 1 : 0,
+            stage_4: 0,
+            total: (rubricFindings.length > 0 ? 1 : 0) + (synth.mode === "agent" ? 1 : 0),
+        },
+        cost_estimate_usd: { stage_2: 0, stage_4: 0, total: 0, model_price_table_version: "2026-05" },
+    });
+    // ── 7. Emit ──────────────────────────────────────────────────────────────
+    const yamlText = yaml.dump(reportToYamlObject(report));
+    // Markdown renderer also receives the conversation_id + business_domain so
+    // the "How to verify" section can emit runnable CLI commands. These two
+    // values are NOT in the yaml schema (yaml stays CLI-agnostic) — they live
+    // only in the md projection.
+    const mdOpts = { conversationId, businessDomain: opts.businessDomain };
+    const format = opts.format ?? (opts.out !== null ? "both" : "yaml");
+    if (opts.out !== null) {
+        await fs.mkdir(path.dirname(opts.out), { recursive: true });
+        const { yamlPath, mdPath } = derivePaths(opts.out, format);
+        if (yamlPath !== null)
+            await fs.writeFile(yamlPath, yamlText, "utf8");
+        if (mdPath !== null)
+            await fs.writeFile(mdPath, renderReportMarkdown(report, mdOpts), "utf8");
+    }
+    else {
+        // stdout — markdown to stdout would corrupt downstream `yq` / yaml consumers, so
+        // 'both' degrades to yaml-only. Users who want md on stdout pass --format=markdown.
+        if (format === "markdown") {
+            process.stdout.write(renderReportMarkdown(report, mdOpts));
+        }
+        else {
+            process.stdout.write(yamlText);
+        }
+    }
+    if (report.findings.length === 0) {
+        process.stderr.write("no findings\n");
+    }
+    return report;
+}
+/** Resolve which file paths to write given the user-supplied --out and format.
+ *  Both: derive the missing extension from the given one; if --out had no
+ *  recognized extension, append .yaml / .md. Single-format: write to --out
+ *  verbatim (caller's extension is honored as-is). */
+export function derivePaths(out, format) {
+    if (format === "yaml")
+        return { yamlPath: out, mdPath: null };
+    if (format === "markdown")
+        return { yamlPath: null, mdPath: out };
+    // both
+    const lower = out.toLowerCase();
+    if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
+        const stem = out.slice(0, out.lastIndexOf("."));
+        return { yamlPath: out, mdPath: `${stem}.md` };
+    }
+    if (lower.endsWith(".md") || lower.endsWith(".markdown")) {
+        const stem = out.slice(0, out.lastIndexOf("."));
+        return { yamlPath: `${stem}.yaml`, mdPath: out };
+    }
+    return { yamlPath: `${out}.yaml`, mdPath: `${out}.md` };
+}
+function extractAgentId(tree) {
+    for (const s of tree.spans) {
+        const v = s.attributes["gen_ai.agent.id"];
+        if (typeof v === "string")
+            return v;
+    }
+    return null;
+}
+function extractTenant(tree) {
+    for (const s of tree.spans) {
+        const v = s.attributes["tenant"];
+        if (typeof v === "string")
+            return v;
+    }
+    return null;
+}
+async function cliVersion() {
+    try {
+        const pkgPath = path.join(__dirname, "..", "..", "..", "package.json");
+        const txt = await fs.readFile(pkgPath, "utf8");
+        return JSON.parse(txt).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export { TraceNotFoundError as DiagnoseTraceNotFound, RuleLoadError, RuleProbeError };

package/dist/trace-ai/diagnose/output-schema-converter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Convert a rubric YAML's `output_schema` (a JSON-Schema-ish blob) into a
+ * zod schema the agent provider validates LLM responses against.
+ *
+ * We don't pull in a full JSON-Schema-to-Zod converter — rubric YAMLs use
+ * a deliberately narrow subset: `type: object` with `required[]` and
+ * `properties{type, enum, items}`. Anything richer is rejected at load
+ * time so authors don't accidentally rely on full JSON Schema semantics
+ * we haven't implemented.
+ *
+ * Supported per-property `type` values: `string`, `number`, `boolean`,
+ * `array` (homogeneous items by `items.type`), `object` (recursive).
+ * `enum` (string-only) is supported on `string` properties.
+ *
+ * Unsupported / rejected at conversion time: `type: integer` (use number),
+ * `anyOf`/`oneOf`, `$ref`, `additionalProperties: false`, `format`.
+ */
+import { z } from "zod";
+import type { RubricYaml } from "./schemas.js";
+export declare class OutputSchemaConversionError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+export declare function rubricOutputToZod(rubric: RubricYaml): z.ZodTypeAny;