@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

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

@@ -0,0 +1,184 @@
+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;
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    symptom: z.ZodString;
+    taxonomy: z.ZodObject<{
+        signals_axis: z.ZodEnum<{
+            interaction: "interaction";
+            execution: "execution";
+            environment: "environment";
+        }>;
+        ms_class: z.ZodEnum<{
+            retry_loop: "retry_loop";
+            tool_misuse: "tool_misuse";
+            context_loss: "context_loss";
+            goal_drift: "goal_drift";
+            cascading_error: "cascading_error";
+            silent_quality_degradation: "silent_quality_degradation";
+        }>;
+    }, z.core.$strip>;
+    suggested_fix: z.ZodObject<{
+        target: z.ZodString;
+        change_template: z.ZodString;
+    }, z.core.$strip>;
+    verify_with: z.ZodObject<{
+        assertion_templates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    predicate: z.ZodOptional<z.ZodString>;
+    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>;
+export declare const ReportSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"trace-diagnose-report/v1">;
+    trace: z.ZodObject<{
+        trace_id: z.ZodString;
+        agent_id: z.ZodNullable<z.ZodString>;
+        tenant: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    run: z.ZodObject<{
+        diagnosed_at: z.ZodString;
+        cli_version: z.ZodString;
+        mode: z.ZodEnum<{
+            "symbolic-only": "symbolic-only";
+            "rubric-only": "rubric-only";
+            hybrid: "hybrid";
+        }>;
+        rules_applied: z.ZodArray<z.ZodString>;
+        rules_skipped: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        synthesizer_mode: z.ZodEnum<{
+            agent: "agent";
+            template: "template";
+        }>;
+    }, z.core.$strip>;
+    summary: 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>;
+    findings: z.ZodArray<z.ZodObject<{
+        rule_id: z.ZodString;
+        judgment_kind: z.ZodEnum<{
+            symbolic: "symbolic";
+            rubric: "rubric";
+        }>;
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        symptom: z.ZodString;
+        likely_cause: z.ZodString;
+        evidence: z.ZodObject<{
+            spans: z.ZodArray<z.ZodString>;
+            excerpt: z.ZodString;
+        }, z.core.$strip>;
+        suggested_fix: z.ZodObject<{
+            target: z.ZodString;
+            change: z.ZodString;
+        }, z.core.$strip>;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        verify_with: z.ZodObject<{
+            suggested_eval_case: z.ZodObject<{
+                query_id: z.ZodNullable<z.ZodString>;
+                query: z.ZodNullable<z.ZodString>;
+                assertions: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, 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>;

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

@@ -0,0 +1,158 @@
+/**
+ * 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 { AgentProviderError } from "../../agent-providers/types.js";
+import { render as renderPrompt, languageInstructionFor, } from "../../agent-providers/prompt-template.js";
+import { SummaryOutputSchema } from "./schemas.js";
+import { templateSynthesize } from "./synthesizer-template.js";
+/** Map zod-validated agent output (snake_case Summary) → internal camelCase Summary. */
+function toInternalSummary(out) {
+    return {
+        headline: out.headline,
+        primaryRootCause: out.primary_root_cause === null
+            ? null
+            : {
+                findingIds: out.primary_root_cause.finding_ids,
+                description: out.primary_root_cause.description,
+                targetForFix: out.primary_root_cause.target_for_fix,
+            },
+        fixPriority: out.fix_priority.map((p) => ({ findingId: p.finding_id, reason: p.reason })),
+        crossFindingLinks: out.cross_finding_links.map((l) => ({
+            findingIds: l.finding_ids,
+            relation: l.relation,
+        })),
+    };
+}
+/** Snake-case projection of Finding for the prompt — matches the YAML
+ *  representation users already see, so the model doesn't have to translate. */
+function findingForPrompt(f, idx) {
+    return {
+        index: idx,
+        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,
+        suggested_fix_change: f.suggestedFix.change,
+        confidence: f.confidence,
+    };
+}
+/**
+ * The output_schema rendered into the prompt is a JSON-Schema-ish
+ * description of the Summary contract. Authored inline rather than
+ * derived from the zod schema to keep the prompt human-readable.
+ */
+const SUMMARY_OUTPUT_SCHEMA_DESCRIPTION = {
+    type: "object",
+    required: ["headline", "primary_root_cause", "fix_priority", "cross_finding_links"],
+    properties: {
+        headline: { type: "string", maxLength: 160 },
+        primary_root_cause: {
+            type: "object_or_null",
+            required: ["finding_ids", "description", "target_for_fix"],
+            properties: {
+                finding_ids: { type: "array", items: { type: "integer" } },
+                description: { type: "string" },
+                target_for_fix: { type: "string" },
+            },
+        },
+        fix_priority: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["finding_id", "reason"],
+                properties: { finding_id: { type: "integer" }, reason: { type: "string" } },
+            },
+        },
+        cross_finding_links: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["finding_ids", "relation"],
+                properties: {
+                    finding_ids: { type: "array", items: { type: "integer" }, minItems: 2 },
+                    relation: { type: "string" },
+                },
+            },
+        },
+    },
+};
+export async function agentSynthesize(opts) {
+    // Empty findings: no narrative to compose. Both modes produce the same
+    // summary here, so default to `template` so reports don't claim the
+    // agent ran when it didn't.
+    if (opts.findings.length === 0) {
+        return { summary: templateSynthesize([]), mode: "template" };
+    }
+    if (!opts.provider) {
+        return {
+            summary: templateSynthesize(opts.findings),
+            mode: "template",
+            fallbackReason: "no-provider-registered",
+        };
+    }
+    const ref = opts.promptRef ?? "builtin:within-trace-synthesizer-v1";
+    if (!opts.promptRegistry.has(ref)) {
+        return {
+            summary: templateSynthesize(opts.findings),
+            mode: "template",
+            fallbackReason: `prompt-template-missing:${ref}`,
+        };
+    }
+    const tpl = opts.promptRegistry.get(ref);
+    const prompt = renderPrompt(tpl, {
+        trace_id: opts.traceId,
+        agent_id: opts.agentId ?? "<unknown>",
+        findings: opts.findings.map((f, i) => findingForPrompt(f, i)),
+        output_schema: SUMMARY_OUTPUT_SCHEMA_DESCRIPTION,
+        language_instruction: languageInstructionFor(opts.lang ?? "en"),
+    });
+    try {
+        if (!(await opts.provider.isAvailable())) {
+            return {
+                summary: templateSynthesize(opts.findings),
+                mode: "template",
+                fallbackReason: `provider-not-available:${opts.provider.name}`,
+            };
+        }
+        if (opts.artifacts) {
+            await opts.artifacts.writeStageThreeSynthPrompt(prompt);
+        }
+        const resp = await opts.provider.invoke({
+            prompt,
+            outputSchema: SummaryOutputSchema,
+            timeoutMs: opts.timeoutMs,
+            correlationId: `synthesize:${opts.traceId}`,
+        });
+        if (opts.artifacts) {
+            await opts.artifacts.writeStageThreeSynthResponse(resp.output);
+        }
+        return { summary: toInternalSummary(resp.output), mode: "agent" };
+    }
+    catch (e) {
+        if (e instanceof AgentProviderError) {
+            return {
+                summary: templateSynthesize(opts.findings),
+                mode: "template",
+                fallbackReason: `agent-error:${e.kind}`,
+            };
+        }
+        throw e;
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { Finding, Summary } from "./types.js";
+export declare function templateSynthesize(findings: Finding[]): Summary;

package/dist/trace-ai/diagnose/synthesizer-template.js

@@ -0,0 +1,49 @@
+const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+function overlapRatio(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    const intersect = b.filter((x) => setA.has(x)).length;
+    const smaller = Math.min(a.length, b.length);
+    return intersect / smaller;
+}
+export function templateSynthesize(findings) {
+    if (findings.length === 0) {
+        return {
+            headline: "No findings",
+            primaryRootCause: null,
+            fixPriority: [],
+            crossFindingLinks: [],
+        };
+    }
+    // Sort indices by severity desc, stable on original index (so same input → same output).
+    const indices = findings.map((_, i) => i);
+    indices.sort((i, j) => {
+        const r = SEVERITY_RANK[findings[j].severity] - SEVERITY_RANK[findings[i].severity];
+        return r !== 0 ? r : i - j;
+    });
+    const topIdx = indices[0];
+    const top = findings[topIdx];
+    const headline = `see findings[${topIdx}]: ${top.symptom}`;
+    const primaryRootCause = {
+        findingIds: [topIdx],
+        description: `Top-severity finding from rule '${top.ruleId}': ${top.symptom}`,
+        targetForFix: top.suggestedFix.target,
+    };
+    const fixPriority = indices.map((i) => ({
+        findingId: i,
+        reason: `severity=${findings[i].severity}`,
+    }));
+    const crossFindingLinks = [];
+    for (let i = 0; i < findings.length; i++) {
+        for (let j = i + 1; j < findings.length; j++) {
+            if (overlapRatio(findings[i].evidence.spans, findings[j].evidence.spans) >= 0.5) {
+                crossFindingLinks.push({
+                    findingIds: [i, j],
+                    relation: "overlapping_evidence_spans",
+                });
+            }
+        }
+    }
+    return { headline, primaryRootCause, fixPriority, crossFindingLinks };
+}

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

@@ -0,0 +1,3 @@
+import type { TraceTree } from "./types.js";
+import type { RawSpan } from "../../api/trace.js";
+export declare function assembleTraceTree(traceId: string, raw: RawSpan[]): TraceTree;