@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

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

@@ -0,0 +1,45 @@
+function getPrompt(s) {
+    const v = s.attributes["gen_ai.prompt"] ?? s.attributes["llm.prompt"];
+    return typeof v === "string" ? v : "";
+}
+function getErrorMessage(s) {
+    const v = s.attributes["error.message"];
+    return typeof v === "string" ? v : "";
+}
+function getToolName(s) {
+    const v = s.attributes["gen_ai.tool.name"];
+    return typeof v === "string" ? v : s.name;
+}
+export const predicate = (trace) => {
+    const allSpans = trace.spans
+        .slice()
+        .sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    for (let i = 0; i < allSpans.length; i++) {
+        const s = allSpans[i];
+        if (s.kind !== "tool" || s.status !== "error")
+            continue;
+        const errMsg = getErrorMessage(s);
+        const toolName = getToolName(s);
+        // find next LLM span
+        let next;
+        for (let j = i + 1; j < allSpans.length; j++) {
+            if (allSpans[j].kind === "llm") {
+                next = allSpans[j];
+                break;
+            }
+        }
+        if (!next)
+            continue;
+        const prompt = getPrompt(next).toLowerCase();
+        const errInPrompt = errMsg.length > 0 && prompt.includes(errMsg.toLowerCase());
+        if (!errInPrompt) {
+            hits.push({
+                evidenceSpans: [s.spanId, next.spanId],
+                excerpt: `tool '${toolName}' errored ('${errMsg}') but next LLM prompt did not propagate the error`,
+                bindings: { tool_name: toolName, error_message: errMsg },
+            });
+        }
+    }
+    return hits;
+};

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

@@ -0,0 +1,15 @@
+schema_version: diagnosis-rule/v1
+id: tool_error_swallowed
+severity: high
+symptom: tool_error_not_propagated_to_next_prompt
+taxonomy:
+  signals_axis: execution
+  ms_class: cascading_error
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "after tool '{{tool_name}}' errors, include error.message in the next LLM prompt or take a recovery branch"
+verify_with:
+  assertion_templates:
+    - "next_llm_prompt_after({{tool_name}}_error).contains(error.message)"
+predicate: builtin:tool_error_swallowed
+params: {}

package/dist/trace-ai/diagnose/builtin-rules/tool-loop-no-state-change.d.ts

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

package/dist/trace-ai/diagnose/builtin-rules/tool-loop-no-state-change.js

@@ -0,0 +1,38 @@
+const STATE_KEY = "gen_ai.conversation.state";
+function toolName(s) {
+    const v = s.attributes["gen_ai.tool.name"];
+    return typeof v === "string" ? v : s.name;
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b); // PR-A: simple JSON compare; sufficient for tool args
+}
+export const predicate = (trace, params) => {
+    const minConsecutive = params.min_consecutive ?? 3;
+    const tools = (trace.byKind.get("tool") ?? []).slice().sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    let i = 0;
+    while (i < tools.length) {
+        const start = tools[i];
+        const startName = toolName(start);
+        const startArgs = start.attributes["gen_ai.tool.args"];
+        const startState = start.attributes[STATE_KEY];
+        let j = i + 1;
+        while (j < tools.length &&
+            toolName(tools[j]) === startName &&
+            deepEqual(tools[j].attributes["gen_ai.tool.args"], startArgs) &&
+            // state unchanged across the run (or both undefined)
+            (tools[j].attributes[STATE_KEY] === startState || (startState === undefined && tools[j].attributes[STATE_KEY] === undefined)))
+            j++;
+        const runLen = j - i;
+        if (runLen >= minConsecutive) {
+            const evidenceSpans = tools.slice(i, j).map((s) => s.spanId);
+            hits.push({
+                evidenceSpans,
+                excerpt: `tool '${startName}' called ${runLen} times consecutively with identical args; conversation state unchanged`,
+                bindings: { tool_name: startName, loop_count: runLen, max_count: minConsecutive - 1 },
+            });
+        }
+        i = j;
+    }
+    return hits;
+};

package/dist/trace-ai/diagnose/builtin-rules/tool-loop-no-state-change.yaml

@@ -0,0 +1,16 @@
+schema_version: diagnosis-rule/v1
+id: tool_loop_no_state_change
+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: "add stop condition after {{loop_count}} equivalent failed retrievals of '{{tool_name}}'"
+verify_with:
+  assertion_templates:
+    - "tool_call_count({{tool_name}}) <= {{max_count}}"
+predicate: builtin:tool_loop_no_state_change
+params:
+  min_consecutive: 3

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;

package/dist/trace-ai/diagnose/output-schema-converter.js

@@ -0,0 +1,81 @@
+/**
+ * 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";
+export class OutputSchemaConversionError extends Error {
+    path;
+    constructor(message, path) {
+        super(`${message} (at ${path})`);
+        this.path = path;
+        this.name = "OutputSchemaConversionError";
+    }
+}
+function convertProp(spec, path) {
+    const t = spec.type;
+    if (typeof t !== "string") {
+        throw new OutputSchemaConversionError(`property is missing 'type' string`, path);
+    }
+    switch (t) {
+        case "string": {
+            if (Array.isArray(spec.enum)) {
+                if (spec.enum.length === 0) {
+                    throw new OutputSchemaConversionError(`empty enum`, path);
+                }
+                for (const v of spec.enum) {
+                    if (typeof v !== "string") {
+                        throw new OutputSchemaConversionError(`enum supports string values only`, path);
+                    }
+                }
+                return z.enum(spec.enum);
+            }
+            return z.string();
+        }
+        case "number": return z.number();
+        case "boolean": return z.boolean();
+        case "array": {
+            const items = spec.items;
+            if (!items) {
+                throw new OutputSchemaConversionError(`array property requires 'items'`, path);
+            }
+            return z.array(convertProp(items, `${path}.items`));
+        }
+        case "object": {
+            const subProps = spec.properties ?? {};
+            const subRequired = spec.required ?? [];
+            return buildObject(subProps, subRequired, path);
+        }
+        default:
+            throw new OutputSchemaConversionError(`unsupported type '${t}'`, path);
+    }
+}
+function buildObject(properties, required, path) {
+    const shape = {};
+    const requiredSet = new Set(required);
+    for (const [key, spec] of Object.entries(properties)) {
+        const sub = convertProp(spec, `${path}.${key}`);
+        shape[key] = requiredSet.has(key) ? sub : sub.optional();
+    }
+    for (const req of required) {
+        if (!(req in properties)) {
+            throw new OutputSchemaConversionError(`required key '${req}' is not present in properties`, path);
+        }
+    }
+    return z.object(shape);
+}
+export function rubricOutputToZod(rubric) {
+    return buildObject(rubric.output_schema.properties, rubric.output_schema.required, "output_schema");
+}

package/dist/trace-ai/diagnose/predicate-registry.d.ts

@@ -0,0 +1,7 @@
+import type { Predicate } from "./types.js";
+export declare class PredicateNotFoundError extends Error {
+    constructor(name: string);
+}
+export declare function registerPredicate(name: string, fn: Predicate): void;
+export declare function resolvePredicate(ref: string): Predicate;
+export declare function clearRegistry(): void;

package/dist/trace-ai/diagnose/predicate-registry.js

@@ -0,0 +1,30 @@
+export class PredicateNotFoundError extends Error {
+    constructor(name) {
+        super(`predicate not registered: ${name}`);
+        this.name = "PredicateNotFoundError";
+    }
+}
+const REGISTRY = new Map();
+export function registerPredicate(name, fn) {
+    if (REGISTRY.has(name)) {
+        throw new Error(`predicate already registered: ${name}`);
+    }
+    REGISTRY.set(name, fn);
+}
+export function resolvePredicate(ref) {
+    const m = ref.match(/^([a-z-]+):(.+)$/);
+    if (!m)
+        throw new Error(`malformed predicate ref: ${ref}`);
+    const [, scheme, name] = m;
+    if (scheme !== "builtin") {
+        throw new Error(`unsupported predicate scheme: ${scheme} (only 'builtin:' is allowed in PR-A)`);
+    }
+    const fn = REGISTRY.get(name);
+    if (!fn)
+        throw new PredicateNotFoundError(name);
+    return fn;
+}
+// Test-only escape hatch.
+export function clearRegistry() {
+    REGISTRY.clear();
+}

package/dist/trace-ai/diagnose/query-extractor.d.ts

@@ -0,0 +1,14 @@
+import type { TraceTree } from "./types.js";
+/**
+ * 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 declare function extractUserQueryFromTrace(tree: TraceTree): string | null;