@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.2

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-core → trace-ai}/diagnose/rule-loader.js

@@ -3,6 +3,7 @@ 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);
@@ -37,15 +38,47 @@ async function parseOne(filePath) {
         throw new RuleLoadError(`schema validation failed for ${filePath}: ${result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
     }
     const r = result.data;
-    if (!r.predicate) {
-        throw new RuleLoadError(`PR-A only supports symbolic rules; ${filePath} has no predicate`);
+    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;
     }
-    // resolvePredicate throws PredicateNotFoundError; rewrap for uniform caller experience.
-    try {
-        resolvePredicate(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,
+        };
     }
-    catch (e) {
-        throw new RuleLoadError(`${filePath}: ${e.message}`);
+    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,
@@ -55,7 +88,8 @@ async function parseOne(filePath) {
         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: r.predicate,
+        predicateRef,
+        rubric,
         params: r.params,
         sourcePath: filePath,
     };

package/dist/{trace-core → trace-ai}/diagnose/schemas.d.ts

@@ -1,4 +1,38 @@
 import { z } from "zod";
+/**
+ * Rubric input source descriptor. The supported source prefixes are
+ * resolved by `diagnose/agent-binding.ts` against the in-memory TraceTree:
+ *
+ *   - `extract_from_root_attr:<dot.path>`   → root span attribute by name
+ *   - `filter_by_kind:[kind1,kind2,...]`    → ordered span subset by kind
+ *   - `literal:<json>`                      → constant blob (debug / fixtures)
+ *
+ * Authors describe **which slice of the trace** the agent needs as context;
+ * the binding does the actual extraction so rule YAML stays declarative.
+ */
+declare const RubricInputSchema: z.ZodObject<{
+    kind: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strip>;
+declare const RubricSchema: z.ZodObject<{
+    judge_question: z.ZodString;
+    inputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        source: z.ZodString;
+    }, z.core.$strip>>>;
+    output_schema: z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+        required: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        properties: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    agent_binding: z.ZodObject<{
+        provider: z.ZodString;
+        prompt_template_ref: z.ZodString;
+    }, z.core.$strip>;
+    gates_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type RubricYaml = z.infer<typeof RubricSchema>;
+export type RubricInputYaml = z.infer<typeof RubricInputSchema>;
 export declare const RuleSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"diagnosis-rule/v1">;
     id: z.ZodString;
@@ -31,7 +65,23 @@ export declare const RuleSchema: z.ZodObject<{
         assertion_templates: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
     predicate: z.ZodOptional<z.ZodString>;
-    rubric: z.ZodOptional<z.ZodUnknown>;
+    rubric: z.ZodOptional<z.ZodObject<{
+        judge_question: z.ZodString;
+        inputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            source: z.ZodString;
+        }, z.core.$strip>>>;
+        output_schema: z.ZodObject<{
+            type: z.ZodLiteral<"object">;
+            required: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            properties: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>;
+        agent_binding: z.ZodObject<{
+            provider: z.ZodString;
+            prompt_template_ref: z.ZodString;
+        }, z.core.$strip>;
+        gates_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type RuleYaml = z.infer<typeof RuleSchema>;
@@ -80,6 +130,7 @@ export declare const ReportSchema: z.ZodObject<{
         rule_id: z.ZodString;
         judgment_kind: z.ZodEnum<{
             symbolic: "symbolic";
+            rubric: "rubric";
         }>;
         severity: z.ZodEnum<{
             low: "low";
@@ -96,7 +147,11 @@ export declare const ReportSchema: z.ZodObject<{
             target: z.ZodString;
             change: z.ZodString;
         }, z.core.$strip>;
-        confidence: z.ZodLiteral<"low">;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
         verify_with: z.ZodObject<{
             suggested_eval_case: z.ZodObject<{
                 query_id: z.ZodNullable<z.ZodString>;
@@ -107,3 +162,23 @@ export declare const ReportSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ReportYaml = z.infer<typeof ReportSchema>;
+/** The Summary section in isolation — exported so the agent synthesizer
+ *  can validate its LLM output against the same shape the report uses. */
+export declare const SummaryOutputSchema: z.ZodObject<{
+    headline: z.ZodString;
+    primary_root_cause: z.ZodNullable<z.ZodObject<{
+        finding_ids: z.ZodArray<z.ZodNumber>;
+        description: z.ZodString;
+        target_for_fix: z.ZodString;
+    }, z.core.$strip>>;
+    fix_priority: z.ZodArray<z.ZodObject<{
+        finding_id: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    cross_finding_links: z.ZodArray<z.ZodObject<{
+        finding_ids: z.ZodArray<z.ZodNumber>;
+        relation: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SummaryOutput = z.infer<typeof SummaryOutputSchema>;
+export {};

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

@@ -0,0 +1,154 @@
+import { z } from "zod";
+const TaxonomySchema = z.object({
+    signals_axis: z.enum(["interaction", "execution", "environment"]),
+    ms_class: z.enum([
+        "retry_loop",
+        "tool_misuse",
+        "context_loss",
+        "goal_drift",
+        "cascading_error",
+        "silent_quality_degradation",
+    ]),
+});
+const SuggestedFixSchema = z.object({
+    target: z.string().min(1),
+    change_template: z.string().min(1),
+});
+const VerifyWithSchema = z.object({
+    assertion_templates: z.array(z.string()).default([]),
+});
+/**
+ * Rubric input source descriptor. The supported source prefixes are
+ * resolved by `diagnose/agent-binding.ts` against the in-memory TraceTree:
+ *
+ *   - `extract_from_root_attr:<dot.path>`   → root span attribute by name
+ *   - `filter_by_kind:[kind1,kind2,...]`    → ordered span subset by kind
+ *   - `literal:<json>`                      → constant blob (debug / fixtures)
+ *
+ * Authors describe **which slice of the trace** the agent needs as context;
+ * the binding does the actual extraction so rule YAML stays declarative.
+ */
+const RubricInputSchema = z.object({
+    kind: z.string().min(1),
+    source: z.string().min(1),
+});
+/**
+ * Minimal JSON-Schema-ish shape we accept for rubric output_schema. We
+ * convert to a zod schema at load time (see `output-schema-converter.ts`);
+ * keeping this loose here lets authors paste literal JSON Schema without
+ * us re-implementing the whole spec — just the subset we need (object
+ * with required[] + properties{type,enum,items}).
+ */
+const RubricOutputSchemaSchema = z.object({
+    type: z.literal("object"),
+    required: z.array(z.string()).default([]),
+    properties: z.record(z.string(), z.record(z.string(), z.unknown())),
+});
+const AgentBindingSchema = z.object({
+    provider: z.string().min(1),
+    prompt_template_ref: z.string().regex(/^builtin:[a-zA-Z0-9_-]+$/),
+});
+const RubricSchema = z.object({
+    judge_question: z.string().min(1),
+    inputs: z.array(RubricInputSchema).default([]),
+    output_schema: RubricOutputSchemaSchema,
+    agent_binding: AgentBindingSchema,
+    /**
+     * Optional symbolic rule_ids that act as gate for this rubric in batch mode.
+     * Empty/missing → rubric runs on all traces (PR-B fallback). In single-trace
+     * mode this field is ignored; rubric always runs.
+     */
+    gates_on: z.array(z.string()).optional(),
+});
+/**
+ * The convergence contract between Stage-1 (symbolic) and Stage-2 (rubric):
+ * every rubric verdict MUST emit `first_violating_step_id` so cross-finding
+ * links can correlate rubric findings with the spans symbolic rules cite.
+ *
+ * Enforced as a YAML-load-time check rather than at runtime so authors
+ * see the violation in `trace diagnose rules validate <path>`.
+ */
+const FIRST_VIOLATING_STEP_ID = "first_violating_step_id";
+export const RuleSchema = z
+    .object({
+    schema_version: z.literal("diagnosis-rule/v1"),
+    id: z.string().regex(/^[a-z][a-z0-9_]*$/),
+    severity: z.enum(["low", "medium", "high"]),
+    symptom: z.string().min(1),
+    taxonomy: TaxonomySchema,
+    suggested_fix: SuggestedFixSchema,
+    verify_with: VerifyWithSchema,
+    predicate: z.string().regex(/^builtin:[a-z][a-z0-9_]*$/).optional(),
+    rubric: RubricSchema.optional(),
+    params: z.record(z.string(), z.unknown()).default({}),
+})
+    .refine((r) => Boolean(r.predicate) !== Boolean(r.rubric), { message: "exactly one of `predicate` or `rubric` must be present" })
+    .refine((r) => !r.rubric || r.rubric.output_schema.required.includes(FIRST_VIOLATING_STEP_ID), {
+    message: `rubric.output_schema.required must include '${FIRST_VIOLATING_STEP_ID}' (Stage-1↔Stage-2 convergence contract)`,
+    path: ["rubric", "output_schema", "required"],
+});
+const FindingSchema = z.object({
+    rule_id: z.string(),
+    judgment_kind: z.enum(["symbolic", "rubric"]),
+    severity: z.enum(["low", "medium", "high"]),
+    symptom: z.string(),
+    likely_cause: z.string(),
+    evidence: z.object({
+        spans: z.array(z.string()),
+        excerpt: z.string(),
+    }),
+    suggested_fix: z.object({
+        target: z.string(),
+        change: z.string(),
+    }),
+    // Symbolic findings always emit `low` (no semantic basis for higher).
+    // Rubric agent supplies its own confidence; rule-loader propagates the
+    // value the agent returned in the rubric output. Accept the union.
+    confidence: z.enum(["low", "medium", "high"]),
+    verify_with: z.object({
+        suggested_eval_case: z.object({
+            query_id: z.string().nullable(),
+            query: z.string().nullable(),
+            assertions: z.array(z.string()),
+        }),
+    }),
+});
+const SummarySchema = z.object({
+    headline: z.string().max(160),
+    primary_root_cause: z
+        .object({
+        finding_ids: z.array(z.number().int().nonnegative()).min(1),
+        description: z.string(),
+        target_for_fix: z.string(),
+    })
+        .nullable(),
+    fix_priority: z.array(z.object({
+        finding_id: z.number().int().nonnegative(),
+        reason: z.string(),
+    })),
+    cross_finding_links: z.array(z.object({
+        finding_ids: z.array(z.number().int().nonnegative()).min(2),
+        relation: z.string(),
+    })),
+});
+export const ReportSchema = z.object({
+    schema_version: z.literal("trace-diagnose-report/v1"),
+    trace: z.object({
+        trace_id: z.string(),
+        agent_id: z.string().nullable(),
+        tenant: z.string().nullable(),
+    }),
+    run: z.object({
+        diagnosed_at: z.string(),
+        cli_version: z.string(),
+        mode: z.enum(["symbolic-only", "rubric-only", "hybrid"]),
+        rules_applied: z.array(z.string()),
+        rules_skipped: z.array(z.object({ rule_id: z.string(), reason: z.string() })),
+        synthesizer_mode: z.enum(["template", "agent"]),
+    }),
+    summary: SummarySchema,
+    findings: z.array(FindingSchema),
+});
+/** The Summary section in isolation — exported so the agent synthesizer
+ *  can validate its LLM output against the same shape the report uses. */
+export const SummaryOutputSchema = SummarySchema;

package/dist/trace-ai/diagnose/signal-probe.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stage-1 (symbolic) runner. Rubric rules are handled separately in
+ * `agent-binding.ts` and merged into the findings list by `index.ts`.
+ *
+ * Rationale for keeping the split here: symbolic predicates are cheap,
+ * deterministic, sync; rubric judgments are slow, non-deterministic,
+ * async. Running them in one loop would entangle backpressure,
+ * timeout, and retry concerns that only apply to one of the two paths.
+ */
+import type { Hit, Rule, TraceTree } from "./types.js";
+export declare class RuleProbeError extends Error {
+    constructor(ruleId: string, cause: Error);
+}
+export declare function runRules(rules: Rule[], tree: TraceTree): Promise<Map<string, Hit[]>>;
+/** Helpers that split a rule list by which stage owns them. */
+export declare function symbolicRules(rules: Rule[]): Rule[];
+export declare function rubricRules(rules: Rule[]): Rule[];

package/dist/trace-ai/diagnose/signal-probe.js

@@ -0,0 +1,39 @@
+/**
+ * Stage-1 (symbolic) runner. Rubric rules are handled separately in
+ * `agent-binding.ts` and merged into the findings list by `index.ts`.
+ *
+ * Rationale for keeping the split here: symbolic predicates are cheap,
+ * deterministic, sync; rubric judgments are slow, non-deterministic,
+ * async. Running them in one loop would entangle backpressure,
+ * timeout, and retry concerns that only apply to one of the two paths.
+ */
+import { resolvePredicate } from "./predicate-registry.js";
+export class RuleProbeError extends Error {
+    constructor(ruleId, cause) {
+        super(`predicate failed for rule '${ruleId}': ${cause.message}`);
+        this.name = "RuleProbeError";
+    }
+}
+export async function runRules(rules, tree) {
+    const out = new Map();
+    for (const rule of rules) {
+        if (!rule.predicateRef)
+            continue; // rubric rule — handled by agent-binding
+        const fn = resolvePredicate(rule.predicateRef);
+        try {
+            const hits = fn(tree, rule.params);
+            out.set(rule.id, hits);
+        }
+        catch (e) {
+            throw new RuleProbeError(rule.id, e);
+        }
+    }
+    return out;
+}
+/** Helpers that split a rule list by which stage owns them. */
+export function symbolicRules(rules) {
+    return rules.filter((r) => r.predicateRef !== null);
+}
+export function rubricRules(rules) {
+    return rules.filter((r) => r.rubric !== null);
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Stage-3 — agent-driven within-trace synthesizer.
+ *
+ * Takes the N findings produced by Stages 1+2 and asks the LLM to compose
+ * a `Summary` (headline + root cause + ordered fix priority + cross-finding
+ * links). Falls back to the deterministic `templateSynthesize` if:
+ *   - findings.length === 0 (no narrative needed)
+ *   - no provider registered / provider unavailable
+ *   - the agent invocation fails for any reason (we still want a usable
+ *     report even when the LLM judge times out)
+ *
+ * The agent path remains a *narrative* layer — symbolic and rubric findings
+ * are already in hand; the synthesizer doesn't fabricate new findings, only
+ * organizes the ones it was given. This keeps the contract small and the
+ * failure modes containable.
+ */
+import type { Finding, Summary } from "./types.js";
+import type { AgentProvider } from "../../agent-providers/types.js";
+import { PromptTemplateRegistry, type AgentOutputLang } from "../../agent-providers/prompt-template.js";
+import type { ArtifactWriter } from "../scan/artifacts/writer.js";
+export interface AgentSynthesizeOpts {
+    findings: Finding[];
+    traceId: string;
+    agentId: string | null;
+    provider: AgentProvider | null;
+    promptRegistry: PromptTemplateRegistry;
+    promptRef?: string;
+    timeoutMs?: number;
+    /** Output locale for synthesizer prose. Default 'en'. */
+    lang?: AgentOutputLang;
+    /** When provided, writes Stage-3 prompt/response artifacts. */
+    artifacts?: ArtifactWriter;
+}
+export interface AgentSynthesizeResult {
+    summary: Summary;
+    mode: "agent" | "template";
+    /** Reason set when mode === 'template' under a non-default branch. */
+    fallbackReason?: string;
+}
+export declare function agentSynthesize(opts: AgentSynthesizeOpts): Promise<AgentSynthesizeResult>;