@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/trace-ai/scan/scan-summary-markdown.js

@@ -0,0 +1,71 @@
+function rel(p) { return p; }
+export function renderScanSummaryMarkdown(s) {
+    const lines = [];
+    const scan = s.scan;
+    lines.push(`# Trace Diagnose Batch Summary — agent \`${scan.agent_id}\``);
+    lines.push("");
+    const resumeBanner = scan.resumed_from_partial
+        ? ` · resumed — ${scan.traces_reused} reused, ${scan.traces_freshly_diagnosed} freshly diagnosed`
+        : "";
+    lines.push(`> ${scan.trace_count} traces · ${scan.traces_with_findings} with findings · diagnosed ${scan.diagnosed_at} · cli \`${scan.cli_version}\`${resumeBanner}`);
+    lines.push("");
+    // ── Summary ────────────────────────────────────────────────────────────
+    lines.push("## Summary");
+    lines.push("");
+    if (s.summary === null) {
+        lines.push("_Stage-4 synthesizer did not complete; aggregates and per-trace reports are still emitted below._");
+        lines.push("");
+    }
+    else {
+        lines.push(`**${s.summary.headline}**`);
+        lines.push("");
+        if (s.summary.primary_root_cause) {
+            const rc = s.summary.primary_root_cause;
+            lines.push(`Primary root cause — rules ${rc.rule_ids.map((id) => `\`${id}\``).join(", ")}; target for fix: \`${rc.target_for_fix}\`.`);
+            lines.push("");
+            lines.push(`> ${rc.description.replace(/\r?\n+/g, " ")}`);
+            lines.push("");
+        }
+    }
+    // ── Fix priority ───────────────────────────────────────────────────────
+    if (s.summary && s.summary.fix_priority.length > 0) {
+        lines.push("## Fix priority");
+        lines.push("");
+        lines.push("| Order | Rule | Affected | Reason |");
+        lines.push("|---|---|---|---|");
+        s.summary.fix_priority.forEach((p, idx) => {
+            lines.push(`| ${idx + 1} | \`${p.rule_id}\` | ${p.affected_trace_count} | ${p.reason.replace(/\|/g, "\\|").replace(/\r?\n/g, " ")} |`);
+        });
+        lines.push("");
+    }
+    // ── Cross-rule links ───────────────────────────────────────────────────
+    if (s.summary && s.summary.cross_rule_links.length > 0) {
+        lines.push("## Cross-rule links");
+        lines.push("");
+        for (const link of s.summary.cross_rule_links) {
+            const ids = link.rule_ids.map((r) => `\`${r}\``).join(" ↔ ");
+            lines.push(`- ${ids} — ${link.relation}`);
+        }
+        lines.push("");
+    }
+    // ── Aggregates ─────────────────────────────────────────────────────────
+    lines.push("## Aggregates");
+    lines.push("");
+    lines.push("| Rule | Count | high | medium | low |");
+    lines.push("|---|---|---|---|---|");
+    for (const item of s.aggregates.rule_frequency) {
+        lines.push(`| \`${item.rule_id}\` | ${item.count} | ${item.severity_breakdown.high} | ${item.severity_breakdown.medium} | ${item.severity_breakdown.low} |`);
+    }
+    lines.push("");
+    // ── Per-trace index ────────────────────────────────────────────────────
+    lines.push("## Per-Trace Reports");
+    lines.push("");
+    lines.push("| conv_id | trace_id | findings | report |");
+    lines.push("|---|---|---|---|");
+    for (const item of s.per_trace_index) {
+        const mdPath = item.report_path.replace(/\.yaml$/, ".md");
+        lines.push(`| \`${item.conversation_id}\` | \`${item.trace_id.slice(0, 16)}…\` | ${item.finding_count} | [yaml](${item.report_path}) / [md](${mdPath}) |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/trace-ai/scan/scan-summary-schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * The `summary` block shape — used both as the embedded field of the full
+ * scan-summary report AND as the output schema the Stage-4 cross-trace
+ * synthesizer LLM must satisfy.
+ */
+export declare const ScanSummaryShape: z.ZodObject<{
+    headline: z.ZodString;
+    primary_root_cause: z.ZodNullable<z.ZodObject<{
+        rule_ids: z.ZodArray<z.ZodString>;
+        description: z.ZodString;
+        target_for_fix: z.ZodString;
+    }, z.core.$strip>>;
+    fix_priority: z.ZodArray<z.ZodObject<{
+        rule_id: z.ZodString;
+        affected_trace_count: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    cross_rule_links: z.ZodArray<z.ZodObject<{
+        rule_ids: z.ZodArray<z.ZodString>;
+        relation: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScanSummaryShape = z.infer<typeof ScanSummaryShape>;
+export declare const ScanSummarySchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"scan-summary/v1">;
+    scan: z.ZodObject<{
+        agent_id: z.ZodString;
+        trace_count: z.ZodNumber;
+        traces_with_findings: z.ZodNumber;
+        traces_reused: z.ZodNumber;
+        traces_freshly_diagnosed: z.ZodNumber;
+        resumed_from_partial: z.ZodBoolean;
+        diagnosed_at: z.ZodString;
+        cli_version: z.ZodString;
+        synthesizer_mode: z.ZodLiteral<"agent">;
+    }, z.core.$strip>;
+    summary: z.ZodNullable<z.ZodObject<{
+        headline: z.ZodString;
+        primary_root_cause: z.ZodNullable<z.ZodObject<{
+            rule_ids: z.ZodArray<z.ZodString>;
+            description: z.ZodString;
+            target_for_fix: z.ZodString;
+        }, z.core.$strip>>;
+        fix_priority: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            affected_trace_count: z.ZodNumber;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        cross_rule_links: z.ZodArray<z.ZodObject<{
+            rule_ids: z.ZodArray<z.ZodString>;
+            relation: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    aggregates: z.ZodObject<{
+        rule_frequency: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            count: z.ZodNumber;
+            severity_breakdown: z.ZodObject<{
+                high: z.ZodNumber;
+                medium: z.ZodNumber;
+                low: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    per_trace_index: z.ZodArray<z.ZodObject<{
+        trace_id: z.ZodString;
+        conversation_id: z.ZodString;
+        report_path: z.ZodString;
+        finding_count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScanSummary = z.infer<typeof ScanSummarySchema>;

package/dist/trace-ai/scan/scan-summary-schema.js

@@ -0,0 +1,61 @@
+// packages/typescript/src/trace-ai/scan/scan-summary-schema.ts
+import { z } from "zod";
+const PrimaryRootCauseShape = z.object({
+    rule_ids: z.array(z.string()).min(1),
+    description: z.string(),
+    target_for_fix: z.string(),
+});
+const FixPriorityItemShape = z.object({
+    rule_id: z.string(),
+    affected_trace_count: z.number().int().nonnegative(),
+    reason: z.string(),
+});
+const CrossRuleLinkShape = z.object({
+    rule_ids: z.array(z.string()).min(2),
+    relation: z.string(),
+});
+/**
+ * The `summary` block shape — used both as the embedded field of the full
+ * scan-summary report AND as the output schema the Stage-4 cross-trace
+ * synthesizer LLM must satisfy.
+ */
+export const ScanSummaryShape = z.object({
+    headline: z.string().max(160),
+    primary_root_cause: PrimaryRootCauseShape.nullable(),
+    fix_priority: z.array(FixPriorityItemShape),
+    cross_rule_links: z.array(CrossRuleLinkShape),
+});
+const RuleFrequencyItemShape = z.object({
+    rule_id: z.string(),
+    count: z.number().int().nonnegative(),
+    severity_breakdown: z.object({
+        high: z.number().int().nonnegative(),
+        medium: z.number().int().nonnegative(),
+        low: z.number().int().nonnegative(),
+    }),
+});
+const PerTraceIndexItemShape = z.object({
+    trace_id: z.string(),
+    conversation_id: z.string(),
+    report_path: z.string(),
+    finding_count: z.number().int().nonnegative(),
+});
+export const ScanSummarySchema = z.object({
+    schema_version: z.literal("scan-summary/v1"),
+    scan: z.object({
+        agent_id: z.string().min(1),
+        trace_count: z.number().int().nonnegative(),
+        traces_with_findings: z.number().int().nonnegative(),
+        traces_reused: z.number().int().nonnegative(),
+        traces_freshly_diagnosed: z.number().int().nonnegative(),
+        resumed_from_partial: z.boolean(),
+        diagnosed_at: z.string(),
+        cli_version: z.string(),
+        synthesizer_mode: z.literal("agent"),
+    }),
+    summary: ScanSummaryShape.nullable(),
+    aggregates: z.object({
+        rule_frequency: z.array(RuleFrequencyItemShape),
+    }),
+    per_trace_index: z.array(PerTraceIndexItemShape),
+});

package/dist/trace-ai/scan/single-agent-validator.d.ts

@@ -0,0 +1,23 @@
+export type SingleAgentValidationErrorCode = "empty" | "no-spans" | "mixed";
+export declare class SingleAgentValidationError extends Error {
+    readonly code: SingleAgentValidationErrorCode;
+    readonly byConvId: ReadonlyMap<string, string | undefined>;
+    constructor(code: SingleAgentValidationErrorCode, message: string, byConvId?: ReadonlyMap<string, string | undefined>);
+}
+export interface SingleAgentValidationResult {
+    agentId: string;
+    checkedConvIds: number;
+}
+export interface FetchSpansResult {
+    spans: Array<{
+        attributes: Record<string, unknown>;
+    }>;
+    conversation_id: string;
+}
+export type FetchSpansByConvId = (convId: string) => Promise<FetchSpansResult>;
+/**
+ * Verify every conv_id in the batch resolves to spans owned by the same
+ * agent_id. Throws SingleAgentValidationError on mismatch with a discrepancy
+ * map for the CLI to print.
+ */
+export declare function validateSingleAgent(convIds: string[], fetchSpansById: FetchSpansByConvId): Promise<SingleAgentValidationResult>;

package/dist/trace-ai/scan/single-agent-validator.js

@@ -0,0 +1,42 @@
+export class SingleAgentValidationError extends Error {
+    code;
+    byConvId;
+    constructor(code, message, byConvId = new Map()) {
+        super(message);
+        this.code = code;
+        this.byConvId = byConvId;
+        this.name = "SingleAgentValidationError";
+    }
+}
+function extractAgentId(spans) {
+    for (const s of spans) {
+        const v = s.attributes["gen_ai.agent.id"];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Verify every conv_id in the batch resolves to spans owned by the same
+ * agent_id. Throws SingleAgentValidationError on mismatch with a discrepancy
+ * map for the CLI to print.
+ */
+export async function validateSingleAgent(convIds, fetchSpansById) {
+    if (convIds.length === 0) {
+        throw new SingleAgentValidationError("empty", "no conversation_ids supplied");
+    }
+    const byConvId = new Map();
+    for (const convId of convIds) {
+        const fetched = await fetchSpansById(convId);
+        if (fetched.spans.length === 0) {
+            throw new SingleAgentValidationError("no-spans", `conversation_id has no spans: ${convId}`);
+        }
+        byConvId.set(convId, extractAgentId(fetched.spans));
+    }
+    const agentIds = new Set(byConvId.values());
+    if (agentIds.size > 1 || (agentIds.size === 1 && agentIds.has(undefined))) {
+        const lines = [...byConvId.entries()].map(([c, a]) => `  ${c} → ${a ?? "(no agent.id)"}`).join("\n");
+        throw new SingleAgentValidationError("mixed", `--traces conversation_ids span multiple agents:\n${lines}`, byConvId);
+    }
+    return { agentId: [...agentIds][0], checkedConvIds: convIds.length };
+}

package/dist/trace-ai/scan/traces-list-parser.d.ts

@@ -0,0 +1,15 @@
+export type TracesListErrorCode = "empty" | "file-not-found";
+export declare class TracesListError extends Error {
+    readonly code: TracesListErrorCode;
+    constructor(code: TracesListErrorCode, message: string);
+}
+/**
+ * Parse the `--traces` argument value into an array of conversation_ids.
+ * Two forms:
+ *   - comma-separated:  "conv1,conv2,conv3"
+ *   - @file path:       "@/path/to/ids.txt" (one id per line; # comments and blanks ignored)
+ *
+ * Throws TracesListError with code='empty' for empty result, 'file-not-found'
+ * when @file path does not exist.
+ */
+export declare function parseTracesList(arg: string): Promise<string[]>;

package/dist/trace-ai/scan/traces-list-parser.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+export class TracesListError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "TracesListError";
+    }
+}
+/**
+ * Parse the `--traces` argument value into an array of conversation_ids.
+ * Two forms:
+ *   - comma-separated:  "conv1,conv2,conv3"
+ *   - @file path:       "@/path/to/ids.txt" (one id per line; # comments and blanks ignored)
+ *
+ * Throws TracesListError with code='empty' for empty result, 'file-not-found'
+ * when @file path does not exist.
+ */
+export async function parseTracesList(arg) {
+    if (arg.startsWith("@")) {
+        const filePath = arg.slice(1);
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, "utf8");
+        }
+        catch {
+            throw new TracesListError("file-not-found", `--traces file not found: ${filePath}`);
+        }
+        const ids = raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith("#"));
+        if (ids.length === 0) {
+            throw new TracesListError("empty", `no conversation_ids found in ${filePath}`);
+        }
+        return ids;
+    }
+    const ids = arg
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (ids.length === 0) {
+        throw new TracesListError("empty", "empty --traces value");
+    }
+    return ids;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "dev": "tsx watch src/cli.ts",
-    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json && rm -rf dist/templates && cp -R src/templates dist/templates && cp src/trace-core/diagnose/builtin-rules/*.yaml dist/trace-core/diagnose/builtin-rules/",
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json && rm -rf dist/templates && cp -R src/templates dist/templates && cp src/trace-ai/diagnose/builtin-rules/*.yaml dist/trace-ai/diagnose/builtin-rules/ && mkdir -p dist/agent-providers/prompts && cp src/agent-providers/prompts/*.prompt.md dist/agent-providers/prompts/ && cp src/trace-ai/diagnose/builtin-rules/*.prompt.md dist/trace-ai/diagnose/builtin-rules/ 2>/dev/null || true && mkdir -p dist/trace-ai/scan/prompts/builtin && cp src/trace-ai/scan/prompts/builtin/*.prompt.md dist/trace-ai/scan/prompts/builtin/ && mkdir -p dist/trace-ai/eval-set/rubric-templates && cp src/trace-ai/eval-set/rubric-templates/*.prompt.md dist/trace-ai/eval-set/rubric-templates/",
     "start": "node ./dist/cli.js",
     "lint": "node node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
     "test": "node --import tsx --test test/*.test.ts",

package/dist/api/dataviews.d.ts

@@ -1,117 +0,0 @@
-/** Field metadata returned by the data-views API. */
-export interface ViewField {
-    name: string;
-    type: string;
-    display_name?: string;
-    comment?: string;
-}
-/** Normalized data view model (mdl-data-model). */
-export interface DataView {
-    id: string;
-    name: string;
-    query_type: string;
-    datasource_id: string;
-    /** View type, e.g. "atomic" or "custom". */
-    type?: string;
-    /** Underlying data source engine, e.g. "mysql", "postgresql". */
-    data_source_type?: string;
-    /** Human-readable data source name. */
-    data_source_name?: string;
-    /** Full SQL expression stored in the view definition (Trino catalog.schema.table). */
-    sql_str?: string;
-    /** Fully-qualified table reference (catalog."schema"."table"). */
-    meta_table_name?: string;
-    /** Field metadata. Populated by `get`; absent (`undefined`) in `list` results. */
-    fields?: ViewField[];
-}
-export declare function parseDataView(raw: Record<string, unknown>): DataView;
-export interface CreateDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    name: string;
-    datasourceId: string;
-    table: string;
-    fields?: Array<{
-        name: string;
-        type: string;
-    }>;
-    businessDomain?: string;
-}
-export declare function createDataView(options: CreateDataViewOptions): Promise<string>;
-export interface ListDataViewsOptions {
-    baseUrl: string;
-    accessToken: string;
-    businessDomain?: string;
-    /** Filter by data source id. */
-    datasourceId?: string;
-    /** Server-side keyword filter (fuzzy). */
-    name?: string;
-    /** View type filter (e.g. atomic, custom). */
-    type?: string;
-    /** Max items; default -1 (all). */
-    limit?: number;
-}
-export declare function listDataViews(options: ListDataViewsOptions): Promise<DataView[]>;
-export interface DeleteDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    businessDomain?: string;
-}
-export declare function deleteDataView(options: DeleteDataViewOptions): Promise<void>;
-export interface GetDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    businessDomain?: string;
-}
-export declare function getDataView(options: GetDataViewOptions): Promise<DataView>;
-export interface FindDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    businessDomain?: string;
-    /** View name to search for (sent as keyword to server). */
-    name: string;
-    /** Filter by data source id. */
-    datasourceId?: string;
-    /** When true, apply client-side exact name match after keyword search (default false). */
-    exact?: boolean;
-    /** When true, poll until a result appears or timeout (default false). */
-    wait?: boolean;
-    /** Total wait budget in ms (default 30000). Only used when wait is true. */
-    timeoutMs?: number;
-}
-/**
- * Find data views by name. Uses server-side keyword filtering; when `exact` is true,
- * applies client-side `name ===` filter. Optional polling with exponential backoff.
- */
-export declare function findDataView(options: FindDataViewOptions): Promise<DataView[]>;
-/** Options for querying data view rows via mdl-uniquery (SQL / view definition). */
-export interface QueryDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    sql?: string;
-    offset?: number;
-    limit?: number;
-    needTotal?: boolean;
-    outputFields?: string[];
-    filters?: Record<string, unknown>;
-    sort?: Array<Record<string, unknown>>;
-    businessDomain?: string;
-}
-/** Query result from mdl-uniquery data-views POST (shape varies by backend). */
-export interface DataViewQueryResult {
-    columns?: Array<{
-        name: string;
-        type?: string;
-        vega_type?: string;
-    }>;
-    entries?: unknown;
-    total_count?: number;
-}
-/**
- * Execute a query against a data view (POST /api/mdl-uniquery/v1/data-views/:id).
- * When `sql` is omitted, the server uses the view's stored SQL definition.
- */
-export declare function queryDataView(options: QueryDataViewOptions): Promise<DataViewQueryResult>;