@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

package/dist/trace-ai/diagnose/query-extractor.js

@@ -0,0 +1,45 @@
+/**
+ * Extract the most recent user-role message from a trace's input.messages.
+ *
+ * Scans spans for `gen_ai.input.messages` (a JSON-stringified array of
+ * {role, content}), checking two locations in order:
+ *   1. span.events[*].attributes  — emitted by dolphin otel_listener as the
+ *      "gen_ai.client.inference.operation.details" event (primary path)
+ *   2. span.attributes             — fallback for runtimes that promote the
+ *      field directly onto the span
+ *
+ * Returns the last `role === "user"` message content, or null if not found.
+ */
+export function extractUserQueryFromTrace(tree) {
+    for (const span of tree.spans) {
+        const candidates = [];
+        // Primary: event attributes (dolphin otel_listener path)
+        for (const ev of span.events ?? []) {
+            const v = ev.attributes?.["gen_ai.input.messages"];
+            if (typeof v === "string")
+                candidates.push(v);
+        }
+        // Fallback: span attributes
+        const spanAttr = span.attributes?.["gen_ai.input.messages"];
+        if (typeof spanAttr === "string")
+            candidates.push(spanAttr);
+        for (const raw of candidates) {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (!Array.isArray(parsed))
+                continue;
+            for (let i = parsed.length - 1; i >= 0; i--) {
+                const m = parsed[i];
+                if (m?.role === "user" && typeof m.content === "string" && m.content.length > 0) {
+                    return m.content;
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/trace-ai/diagnose/report-assembler.d.ts

@@ -0,0 +1,31 @@
+import type { Finding, Hit, Report, Rule, Summary } from "./types.js";
+export interface AssembleReportOpts {
+    traceId: string;
+    agentId: string | null;
+    tenant: string | null;
+    cliVersion: string;
+    rules: Rule[];
+    hits: Map<string, Hit[]>;
+    /** Additional pre-built findings (rubric judgments come from agent-binding). */
+    extraFindings?: Finding[];
+    summary: Summary;
+    /** Run mode. Default `symbolic-only` for backward compat. */
+    mode?: 'symbolic-only' | 'rubric-only' | 'hybrid';
+    /** Rubric rules skipped due to --no-llm / unavailable provider / etc. */
+    rulesSkipped?: {
+        ruleId: string;
+        reason: string;
+    }[];
+    /** Stage-3 synthesizer that produced `summary`. */
+    synthesizerMode?: 'template' | 'agent';
+    /** 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;
+}
+/** Build symbolic-pillar findings from rule+hit pairs.
+ *  Exported so callers (e.g. tests, index.ts) can compose findings from
+ *  multiple sources before handing them to a custom summary path. */
+export declare function symbolicHitsToFindings(rules: Rule[], hits: Map<string, Hit[]>, userQuery?: string | null, queryId?: string | null): Finding[];
+export declare function assembleReport(opts: AssembleReportOpts): Report;
+export declare function reportToYamlObject(r: Report): unknown;

package/dist/trace-ai/diagnose/report-assembler.js

@@ -0,0 +1,100 @@
+function renderTemplate(tpl, bindings) {
+    return tpl.replace(/{{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*}}/g, (_, key) => {
+        const v = bindings[key];
+        return v === undefined ? `{{${key}}}` : String(v);
+    });
+}
+/** Build symbolic-pillar findings from rule+hit pairs.
+ *  Exported so callers (e.g. tests, index.ts) can compose findings from
+ *  multiple sources before handing them to a custom summary path. */
+export function symbolicHitsToFindings(rules, hits, userQuery = null, queryId = null) {
+    const findings = [];
+    for (const rule of rules) {
+        if (rule.predicateRef === null)
+            continue;
+        const ruleHits = hits.get(rule.id) ?? [];
+        for (const hit of ruleHits) {
+            findings.push({
+                ruleId: rule.id,
+                judgmentKind: "symbolic",
+                severity: rule.severity,
+                symptom: rule.symptom,
+                likelyCause: rule.symptom, // symbolic: no LLM, so mirror symptom; rubric agent overrides
+                evidence: { spans: hit.evidenceSpans, excerpt: hit.excerpt },
+                suggestedFix: {
+                    target: rule.suggestedFix.target,
+                    change: renderTemplate(rule.suggestedFix.changeTemplate, hit.bindings),
+                },
+                confidence: "low",
+                verifyWith: {
+                    suggestedEvalCase: {
+                        queryId,
+                        query: userQuery,
+                        assertions: rule.verifyWith.assertionTemplates.map((t) => renderTemplate(t, hit.bindings)),
+                    },
+                },
+            });
+        }
+    }
+    return findings;
+}
+export function assembleReport(opts) {
+    const symbolicFindings = symbolicHitsToFindings(opts.rules, opts.hits, opts.userQuery ?? null, opts.queryId ?? null);
+    const findings = [...symbolicFindings, ...(opts.extraFindings ?? [])];
+    return {
+        schemaVersion: "trace-diagnose-report/v1",
+        trace: { traceId: opts.traceId, agentId: opts.agentId, tenant: opts.tenant },
+        run: {
+            diagnosedAt: new Date().toISOString(),
+            cliVersion: opts.cliVersion,
+            mode: opts.mode ?? "symbolic-only",
+            rulesApplied: opts.rules.map((r) => r.id),
+            rulesSkipped: opts.rulesSkipped ?? [],
+            synthesizerMode: opts.synthesizerMode ?? "template",
+        },
+        summary: opts.summary,
+        findings,
+    };
+}
+// Convert internal camelCase Report to the snake_case shape used by ReportSchema (and by yaml output).
+export function reportToYamlObject(r) {
+    return {
+        schema_version: r.schemaVersion,
+        trace: { trace_id: r.trace.traceId, agent_id: r.trace.agentId, tenant: r.trace.tenant },
+        run: {
+            diagnosed_at: r.run.diagnosedAt,
+            cli_version: r.run.cliVersion,
+            mode: r.run.mode,
+            rules_applied: r.run.rulesApplied,
+            rules_skipped: r.run.rulesSkipped.map((s) => ({ rule_id: s.ruleId, reason: s.reason })),
+            synthesizer_mode: r.run.synthesizerMode,
+        },
+        summary: {
+            headline: r.summary.headline,
+            primary_root_cause: r.summary.primaryRootCause === null ? null : {
+                finding_ids: r.summary.primaryRootCause.findingIds,
+                description: r.summary.primaryRootCause.description,
+                target_for_fix: r.summary.primaryRootCause.targetForFix,
+            },
+            fix_priority: r.summary.fixPriority.map((p) => ({ finding_id: p.findingId, reason: p.reason })),
+            cross_finding_links: r.summary.crossFindingLinks.map((l) => ({ finding_ids: l.findingIds, relation: l.relation })),
+        },
+        findings: r.findings.map((f) => ({
+            rule_id: f.ruleId,
+            judgment_kind: f.judgmentKind,
+            severity: f.severity,
+            symptom: f.symptom,
+            likely_cause: f.likelyCause,
+            evidence: { spans: f.evidence.spans, excerpt: f.evidence.excerpt },
+            suggested_fix: { target: f.suggestedFix.target, change: f.suggestedFix.change },
+            confidence: f.confidence,
+            verify_with: {
+                suggested_eval_case: {
+                    query_id: f.verifyWith.suggestedEvalCase.queryId,
+                    query: f.verifyWith.suggestedEvalCase.query,
+                    assertions: f.verifyWith.suggestedEvalCase.assertions,
+                },
+            },
+        })),
+    };
+}

package/dist/trace-ai/diagnose/report-markdown.d.ts

@@ -0,0 +1,18 @@
+import type { Report } from "./types.js";
+/**
+ * Optional context the md renderer uses to build runnable verification
+ * commands. None of these are in the yaml schema (which stays v1-locked and
+ * CLI-agnostic) — they live only in the markdown view so users who paste the
+ * md into a ticket / PR have copy-pasteable shell commands without needing to
+ * remember the trace's conversation context.
+ */
+export interface MarkdownRenderOpts {
+    /** The conversation_id passed to `kweaver trace diagnose`. Used to render
+     *  the "re-run diagnosis" command. When undefined, that command is rendered
+     *  with a `<conversation_id>` placeholder. */
+    conversationId?: string;
+    /** Business domain (`-bd` flag). When undefined, commands omit the flag and
+     *  inherit kweaver's default (`bd_public`). */
+    businessDomain?: string;
+}
+export declare function renderReportMarkdown(r: Report, opts?: MarkdownRenderOpts): string;

package/dist/trace-ai/diagnose/report-markdown.js

@@ -0,0 +1,192 @@
+// Human-readable markdown view of a trace-diagnose report.
+//
+// The YAML report (see `report-assembler.reportToYamlObject`) is the source of
+// truth; this file is a pure projection. Persisted alongside the yaml when
+// `--format=both`. Markdown was chosen over a stdout pretty-print because
+// reports are commonly pasted into tickets / PRs / wikis where ephemeral
+// terminal output would be lost.
+//
+// Structure (inverted-pyramid: most actionable first):
+//   1. Title + one-line meta
+//   2. Summary  — headline (+ primary root cause if any)
+//   3. Fix priority table   (omitted when empty)
+//   4. Findings — one section per finding, excerpt as a blockquote
+//   5. Cross-finding links  (omitted when empty)
+//   6. How to verify — kweaver CLI commands the reader can paste to
+//      independently re-confirm the report's claims against the live trace.
+//      Sourced from Report fields + the caller-supplied conversation_id /
+//      business_domain (which are not part of the yaml schema — yaml stays
+//      CLI-agnostic, markdown is the CLI-aware view).
+//   7. Run    — mode / synthesizer / rules applied & skipped (reference)
+export function renderReportMarkdown(r, opts = {}) {
+    const lines = [];
+    const shortId = r.trace.traceId.length > 16 ? `${r.trace.traceId.slice(0, 16)}…` : r.trace.traceId;
+    lines.push(`# Trace Diagnose Report — \`${shortId}\``);
+    lines.push("");
+    lines.push(`> trace \`${r.trace.traceId}\` · agent \`${r.trace.agentId ?? "—"}\` · tenant \`${r.trace.tenant ?? "—"}\` · diagnosed ${r.run.diagnosedAt} · cli \`${r.run.cliVersion}\``);
+    lines.push("");
+    // ── Summary ──────────────────────────────────────────────────────────────
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`**${r.summary.headline}**`);
+    lines.push("");
+    if (r.summary.primaryRootCause !== null) {
+        const rc = r.summary.primaryRootCause;
+        const fids = rc.findingIds.map((i) => `#${i}`).join(", ");
+        lines.push(`Primary root cause spans findings ${fids} — target for fix: \`${rc.targetForFix}\`.`);
+        lines.push("");
+        lines.push(`> ${escapeBlockquote(rc.description)}`);
+        lines.push("");
+    }
+    // ── Fix priority ─────────────────────────────────────────────────────────
+    if (r.summary.fixPriority.length > 0) {
+        lines.push("## Fix priority");
+        lines.push("");
+        lines.push("| Order | Finding | Rule | Reason |");
+        lines.push("|---|---|---|---|");
+        r.summary.fixPriority.forEach((p, idx) => {
+            const f = r.findings[p.findingId];
+            const ruleCell = f ? `\`${f.ruleId}\` [${f.severity}/${f.judgmentKind}]` : `(unknown #${p.findingId})`;
+            lines.push(`| ${idx + 1} | #${p.findingId} | ${ruleCell} | ${escapeTableCell(p.reason)} |`);
+        });
+        lines.push("");
+    }
+    // ── Findings ─────────────────────────────────────────────────────────────
+    lines.push(`## Findings (${r.findings.length})`);
+    lines.push("");
+    if (r.findings.length === 0) {
+        lines.push(`_No findings were emitted by any of the ${r.run.rulesApplied.length} applied rules._`);
+        lines.push("");
+    }
+    else {
+        r.findings.forEach((f, idx) => renderFinding(lines, f, idx));
+    }
+    // ── Cross-finding links ──────────────────────────────────────────────────
+    if (r.summary.crossFindingLinks.length > 0) {
+        lines.push("## Cross-finding links");
+        lines.push("");
+        for (const link of r.summary.crossFindingLinks) {
+            const ids = link.findingIds.map((i) => `#${i}`).join(" ↔ ");
+            lines.push(`- ${ids} — ${link.relation}`);
+        }
+        lines.push("");
+    }
+    // ── How to verify ────────────────────────────────────────────────────────
+    renderVerificationSection(lines, r, opts);
+    // ── Run reference ────────────────────────────────────────────────────────
+    lines.push("## Run");
+    lines.push("");
+    lines.push(`- **mode**: \`${r.run.mode}\` · **synthesizer**: \`${r.run.synthesizerMode}\` · **rules**: ${r.run.rulesApplied.length} applied, ${r.run.rulesSkipped.length} skipped`);
+    lines.push(`- **applied**: ${r.run.rulesApplied.map((id) => `\`${id}\``).join(", ")}`);
+    if (r.run.rulesSkipped.length > 0) {
+        lines.push("- **skipped**:");
+        for (const s of r.run.rulesSkipped) {
+            lines.push(`    - \`${s.ruleId}\` — ${s.reason}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderFinding(lines, f, idx) {
+    lines.push(`### #${idx} \`${f.ruleId}\` — [${f.severity}/${f.judgmentKind}]`);
+    lines.push("");
+    if (f.evidence.excerpt.trim().length > 0) {
+        for (const ln of f.evidence.excerpt.trim().split(/\r?\n/)) {
+            lines.push(`> ${ln}`);
+        }
+        lines.push("");
+    }
+    const meta = [];
+    meta.push(`- **symptom**: ${f.symptom}`);
+    meta.push(`- **likely cause**: ${f.likelyCause}`);
+    meta.push(`- **confidence**: ${f.confidence}`);
+    if (f.evidence.spans.length > 0) {
+        meta.push(`- **evidence spans**: ${f.evidence.spans.map((s) => `\`${s}\``).join(", ")}`);
+    }
+    meta.push(`- **suggested fix** → \`${f.suggestedFix.target}\`: ${f.suggestedFix.change}`);
+    if (f.verifyWith.suggestedEvalCase.assertions.length > 0) {
+        meta.push(`- **verify with**:`);
+        for (const a of f.verifyWith.suggestedEvalCase.assertions) {
+            meta.push(`    - ${a}`);
+        }
+    }
+    for (const m of meta)
+        lines.push(m);
+    lines.push("");
+}
+/**
+ * Render kweaver CLI verification commands so a reader can independently
+ * re-confirm the diagnosis against the live trace. Sections:
+ *   1. Re-fetch the raw spans (proves the trace data the report was built
+ *      from still matches what observability returns)
+ *   2. Re-diagnose with --no-llm (reproducibility check — same symbolic
+ *      findings should fire deterministically; rules out claude-side flake)
+ *   3. Inspect suspect spans per finding (only when findings.length > 0)
+ *   4. Check recurrence across the agent's other conversations
+ *
+ * The commands intentionally omit auth flags (--token / --base-url) — the
+ * reader is expected to have `kweaver auth` already configured or to be
+ * working in the same shell session that produced this report.
+ */
+function renderVerificationSection(lines, r, opts) {
+    const bdFlag = opts.businessDomain ? ` -bd ${opts.businessDomain}` : "";
+    const convId = opts.conversationId ?? "<conversation_id>";
+    lines.push("## How to verify");
+    lines.push("");
+    lines.push("Paste these into a shell to independently re-confirm the report against the live trace.");
+    lines.push("");
+    // 1. Re-fetch raw spans for the trace.
+    lines.push("### 1. Re-fetch the raw trace");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`kweaver call -X POST '/api/agent-observability/v1/traces/_search' \\`);
+    lines.push(`  -d '{"query":{"term":{"traceId":"${r.trace.traceId}"}}}'${bdFlag} \\`);
+    lines.push(`  | jq '.hits.hits[]._source | {spanId, name, kind: .attributes."gen_ai.operation.name", status: .status.code}'`);
+    lines.push("```");
+    lines.push("");
+    // 2. Re-run diagnosis deterministically.
+    lines.push("### 2. Re-run diagnosis (reproducibility check)");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`kweaver trace diagnose ${convId} --no-llm --out /tmp/verify.yaml${bdFlag}`);
+    lines.push("# then diff against this report's yaml — symbolic findings should match exactly");
+    lines.push("```");
+    lines.push("");
+    // 3. Inspect suspect spans per finding.
+    if (r.findings.length > 0) {
+        lines.push("### 3. Inspect the suspect spans");
+        lines.push("");
+        r.findings.forEach((f, idx) => {
+            if (f.evidence.spans.length === 0)
+                return;
+            const spanList = f.evidence.spans.map((s) => `"${s}"`).join(", ");
+            lines.push(`Finding #${idx} (\`${f.ruleId}\`):`);
+            lines.push("");
+            lines.push("```bash");
+            lines.push(`kweaver call -X POST '/api/agent-observability/v1/traces/_search' \\`);
+            lines.push(`  -d '{"query":{"terms":{"spanId":[${spanList}]}}}'${bdFlag} \\`);
+            lines.push(`  | jq '.hits.hits[]._source.attributes'`);
+            lines.push("```");
+            lines.push("");
+        });
+    }
+    // 4. Recurrence check.
+    if (r.trace.agentId !== null) {
+        const sectionNum = r.findings.length > 0 ? 4 : 3;
+        lines.push(`### ${sectionNum}. Check whether this pattern recurs for the agent`);
+        lines.push("");
+        lines.push("```bash");
+        lines.push(`kweaver agent sessions ${r.trace.agentId} --limit 20${bdFlag}`);
+        lines.push("# sample a few conversation_ids from the list, re-diagnose each, count rule hits");
+        lines.push("```");
+        lines.push("");
+    }
+}
+function escapeTableCell(s) {
+    // Pipes and newlines break GFM tables; collapse newlines and escape `|`.
+    return s.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+}
+function escapeBlockquote(s) {
+    // Blockquote-safe; just collapse newlines so the whole description sits in one line.
+    return s.replace(/\r?\n+/g, " ").trim();
+}

package/dist/trace-ai/diagnose/rule-loader.d.ts

@@ -0,0 +1,11 @@
+import type { Rule } from "./types.js";
+export declare class RuleLoadError extends Error {
+    constructor(message: string);
+}
+export interface LoadRulesOpts {
+    builtinDir: string | null;
+    cwdRulesDir: string | null;
+    extraRulesDir: string | null;
+    noBuiltin: boolean;
+}
+export declare function loadRules(opts: LoadRulesOpts): Promise<Rule[]>;

package/dist/trace-ai/diagnose/rule-loader.js

@@ -0,0 +1,120 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { RuleSchema } from "./schemas.js";
+import { resolvePredicate } from "./predicate-registry.js";
+import { rubricOutputToZod, OutputSchemaConversionError } from "./output-schema-converter.js";
+export class RuleLoadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RuleLoadError";
+    }
+}
+async function listYamls(dir) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml")))
+            .map((e) => path.join(dir, e.name));
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+async function parseOne(filePath) {
+    const raw = await fs.readFile(filePath, "utf8");
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (e) {
+        throw new RuleLoadError(`yaml parse error in ${filePath}: ${e.message}`);
+    }
+    const result = RuleSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new RuleLoadError(`schema validation failed for ${filePath}: ${result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+    }
+    const r = result.data;
+    let predicateRef = null;
+    let rubric = null;
+    if (r.predicate) {
+        // resolvePredicate throws PredicateNotFoundError; rewrap for uniform caller experience.
+        try {
+            resolvePredicate(r.predicate);
+        }
+        catch (e) {
+            throw new RuleLoadError(`${filePath}: ${e.message}`);
+        }
+        predicateRef = r.predicate;
+    }
+    else if (r.rubric) {
+        // Compile output_schema → zod at load time so authors see schema errors
+        // up-front via `trace diagnose rules validate <path>`, not at LLM call time.
+        let outputZodSchema;
+        try {
+            outputZodSchema = rubricOutputToZod(r.rubric);
+        }
+        catch (e) {
+            if (e instanceof OutputSchemaConversionError) {
+                throw new RuleLoadError(`${filePath}: rubric.output_schema: ${e.message}`);
+            }
+            throw e;
+        }
+        rubric = {
+            judgeQuestion: r.rubric.judge_question,
+            inputs: r.rubric.inputs.map((i) => ({ kind: i.kind, source: i.source })),
+            outputSchemaRaw: r.rubric.output_schema,
+            outputZodSchema,
+            agentBinding: {
+                provider: r.rubric.agent_binding.provider,
+                promptTemplateRef: r.rubric.agent_binding.prompt_template_ref,
+            },
+            gatesOn: r.rubric.gates_on,
+        };
+    }
+    else {
+        // RuleSchema's XOR refinement should have already caught this; keep an
+        // explicit branch so the failure mode is obvious if schemas drift.
+        throw new RuleLoadError(`${filePath}: rule has neither predicate nor rubric`);
+    }
+    return {
+        schemaVersion: r.schema_version,
+        id: r.id,
+        severity: r.severity,
+        symptom: r.symptom,
+        taxonomy: { signalsAxis: r.taxonomy.signals_axis, msClass: r.taxonomy.ms_class },
+        suggestedFix: { target: r.suggested_fix.target, changeTemplate: r.suggested_fix.change_template },
+        verifyWith: { assertionTemplates: r.verify_with.assertion_templates },
+        predicateRef,
+        rubric,
+        params: r.params,
+        sourcePath: filePath,
+    };
+}
+export async function loadRules(opts) {
+    const dirs = [];
+    if (opts.builtinDir && !opts.noBuiltin)
+        dirs.push(opts.builtinDir);
+    if (opts.cwdRulesDir)
+        dirs.push(opts.cwdRulesDir);
+    if (opts.extraRulesDir)
+        dirs.push(opts.extraRulesDir);
+    const seenIds = new Map(); // id → first path
+    const rules = [];
+    for (const dir of dirs) {
+        const yamls = await listYamls(dir);
+        for (const f of yamls) {
+            const r = await parseOne(f);
+            const prev = seenIds.get(r.id);
+            if (prev) {
+                throw new RuleLoadError(`rule id conflict for '${r.id}': defined in both ${prev} and ${f}`);
+            }
+            seenIds.set(r.id, f);
+            rules.push(r);
+        }
+    }
+    return rules;
+}