@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.2

package/dist/resources/skills.d.ts

@@ -1,5 +1,5 @@
 import type { ClientContext } from "../client.js";
-import { type SkillListResult, type SkillStatus } from "../api/skills.js";
+import { type SkillCategory, type SkillListResult, type SkillStatus } from "../api/skills.js";
 export declare class SkillsResource {
     private readonly ctx;
     constructor(ctx: ClientContext);
@@ -24,6 +24,7 @@ export declare class SkillsResource {
         source?: string;
     }): Promise<SkillListResult>;
     get(skillId: string): Promise<import("../api/skills.js").SkillInfo>;
+    getMarket(skillId: string): Promise<import("../api/skills.js").SkillInfo>;
     registerContent(content: string, opts?: {
         source?: string;
         extendInfo?: Record<string, unknown>;
@@ -34,6 +35,18 @@ export declare class SkillsResource {
     }): Promise<import("../api/skills.js").RegisterSkillResult>;
     delete(skillId: string): Promise<import("../api/skills.js").DeleteSkillResult>;
     updateStatus(skillId: string, status: SkillStatus): Promise<import("../api/skills.js").UpdateSkillStatusResult>;
+    updateMetadata(skillId: string, metadata: {
+        name: string;
+        description: string;
+        category: SkillCategory;
+        source?: string;
+        extendInfo?: Record<string, unknown>;
+    }): Promise<import("../api/skills.js").UpdateSkillMetadataResult>;
+    updatePackageContent(skillId: string, content: string): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
+    updatePackageZip(skillId: string, filename: string, bytes: Uint8Array): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
+    history(skillId: string): Promise<import("../api/skills.js").SkillReleaseHistoryInfo[]>;
+    republishHistory(skillId: string, version: string): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
+    publishHistory(skillId: string, version: string): Promise<import("../api/skills.js").UpdateSkillPackageResult>;
     content(skillId: string): Promise<import("../api/skills.js").SkillContentIndex>;
     fetchContent(skillId: string): Promise<string>;
     readFile(skillId: string, relPath: string): Promise<import("../api/skills.js").SkillFileReadResult>;
@@ -44,4 +57,7 @@ export declare class SkillsResource {
     }): Promise<{
         directory: string;
     }>;
+    getManagementContent(skillId: string, responseMode?: "url" | "content"): Promise<import("../api/skills.js").SkillManagementContentData>;
+    readManagementFile(skillId: string, relPath: string): Promise<import("../api/skills.js").SkillFileReadResult>;
+    downloadManagementArchive(skillId: string, responseMode?: "url" | "content"): Promise<import("../api/skills.js").DownloadedSkillArchive>;
 }

package/dist/resources/skills.js

@@ -1,4 +1,4 @@
-import { deleteSkill, downloadSkill, fetchSkillContent, fetchSkillFile, getSkill, getSkillContentIndex, installSkillArchive, listSkillMarket, listSkills, readSkillFile, registerSkillContent, registerSkillZip, updateSkillStatus, } from "../api/skills.js";
+import { deleteSkill, downloadSkill, downloadSkillManagementArchive, fetchSkillContent, fetchSkillFile, getSkill, getSkillMarketDetail, getSkillContentIndex, getSkillManagementContent, installSkillArchive, listSkillMarket, listSkillHistory, listSkills, publishSkillHistory, readSkillFile, readSkillManagementFile, republishSkillHistory, registerSkillContent, registerSkillZip, updateSkillMetadata, updateSkillPackageContent, updateSkillPackageZip, updateSkillStatus, } from "../api/skills.js";
 export class SkillsResource {
     ctx;
     constructor(ctx) {
@@ -13,6 +13,9 @@ export class SkillsResource {
     async get(skillId) {
         return getSkill({ ...this.ctx.base(), skillId });
     }
+    async getMarket(skillId) {
+        return getSkillMarketDetail({ ...this.ctx.base(), skillId });
+    }
     async registerContent(content, opts = {}) {
         return registerSkillContent({ ...this.ctx.base(), content, ...opts });
     }
@@ -25,6 +28,24 @@ export class SkillsResource {
     async updateStatus(skillId, status) {
         return updateSkillStatus({ ...this.ctx.base(), skillId, status });
     }
+    async updateMetadata(skillId, metadata) {
+        return updateSkillMetadata({ ...this.ctx.base(), skillId, ...metadata });
+    }
+    async updatePackageContent(skillId, content) {
+        return updateSkillPackageContent({ ...this.ctx.base(), skillId, content });
+    }
+    async updatePackageZip(skillId, filename, bytes) {
+        return updateSkillPackageZip({ ...this.ctx.base(), skillId, filename, bytes });
+    }
+    async history(skillId) {
+        return listSkillHistory({ ...this.ctx.base(), skillId });
+    }
+    async republishHistory(skillId, version) {
+        return republishSkillHistory({ ...this.ctx.base(), skillId, version });
+    }
+    async publishHistory(skillId, version) {
+        return publishSkillHistory({ ...this.ctx.base(), skillId, version });
+    }
     async content(skillId) {
         return getSkillContentIndex({ ...this.ctx.base(), skillId });
     }
@@ -44,4 +65,14 @@ export class SkillsResource {
         const archive = await this.download(skillId);
         return installSkillArchive({ bytes: archive.bytes, directory, force: opts.force });
     }
+    // ── Management Content ───────────────────────────────────────────────────────
+    async getManagementContent(skillId, responseMode) {
+        return getSkillManagementContent({ ...this.ctx.base(), skillId, responseMode });
+    }
+    async readManagementFile(skillId, relPath) {
+        return readSkillManagementFile({ ...this.ctx.base(), skillId, relPath });
+    }
+    async downloadManagementArchive(skillId, responseMode) {
+        return downloadSkillManagementArchive({ ...this.ctx.base(), skillId, responseMode });
+    }
 }

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

@@ -0,0 +1,67 @@
+/**
+ * Stage-2 — rubric judgments: resolve rubric.inputs against a TraceTree,
+ * render the prompt template, invoke the agent provider, and map the
+ * schema-validated output to a `Finding`.
+ *
+ * Why this layer exists separate from `signal-probe`:
+ *   - Async / I/O-bound (subprocess or HTTP) vs. sync predicates
+ *   - Per-rule provider lookup + skip-on-unavailable
+ *   - Error semantics differ (skip + record vs. throw RuleProbeError)
+ *
+ * Convergence invariant (enforced upstream in schemas.ts): every rubric
+ * `output_schema.required` includes `first_violating_step_id`, so each
+ * rubric finding always points at a concrete span and can be correlated
+ * with symbolic findings on the same span by the synthesizer.
+ */
+import type { Finding, Rule, RubricInputSpec, TraceTree } from "./types.js";
+import type { AgentRegistry } from "../../agent-providers/registry.js";
+import { PromptTemplateRegistry, type AgentOutputLang } from "../../agent-providers/prompt-template.js";
+import type { ArtifactWriter } from "../scan/artifacts/writer.js";
+export interface RubricEvaluateOpts {
+    rules: Rule[];
+    tree: TraceTree;
+    registry: AgentRegistry;
+    promptRegistry: PromptTemplateRegistry;
+    /** If true, all rubric rules are skipped with reason='no-llm-flag-set'. */
+    noLlm?: boolean;
+    /** Per-invocation timeout in ms; provider may apply its own ceiling. */
+    timeoutMs?: number;
+    /** Output locale for natural-language fields in the agent reply. Default 'en'. */
+    lang?: AgentOutputLang;
+    /** When provided, writes Stage-2 prompt/response artifacts per rule invocation. */
+    artifacts?: ArtifactWriter;
+    /** User query extracted from trace input.messages (2026-05-13). */
+    userQuery?: string | null;
+    /** Conversation/query ID for suggested_eval_case correlation (2026-05-13). */
+    queryId?: string | null;
+}
+export interface RubricEvaluateResult {
+    findings: Finding[];
+    skipped: {
+        ruleId: string;
+        reason: string;
+    }[];
+}
+/** Resolve one rubric input spec against the trace and return a value
+ *  suitable for prompt interpolation. Pure for testability. */
+export declare function resolveRubricInput(spec: RubricInputSpec, tree: TraceTree): unknown;
+export declare class AgentBindingError extends Error {
+    constructor(message: string);
+}
+export declare function renderChangeTemplate(tpl: string, bindings: Record<string, unknown>): string;
+/**
+ * Evaluate every rubric rule in `rules` and return findings + skip records.
+ *
+ * A rule is *skipped* (not failed) when:
+ *   - `--no-llm` is set → reason: 'no-llm-flag-set'
+ *   - rule's named provider isn't registered or `isAvailable()` is false
+ *     → reason: `provider-not-available:<name>`
+ *   - rule's prompt template isn't registered
+ *     → reason: `prompt-template-missing:<ref>`
+ *
+ * Schema violations / transport errors from the provider are surfaced
+ * as `AgentBindingError` (let the CLI decide whether to fail the whole
+ * run or skip the single rule). Default callsite (`index.ts`) catches
+ * these and records them in `rules_skipped` rather than aborting.
+ */
+export declare function evaluateRubricRules(opts: RubricEvaluateOpts): Promise<RubricEvaluateResult>;

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

@@ -0,0 +1,257 @@
+/**
+ * Stage-2 — rubric judgments: resolve rubric.inputs against a TraceTree,
+ * render the prompt template, invoke the agent provider, and map the
+ * schema-validated output to a `Finding`.
+ *
+ * Why this layer exists separate from `signal-probe`:
+ *   - Async / I/O-bound (subprocess or HTTP) vs. sync predicates
+ *   - Per-rule provider lookup + skip-on-unavailable
+ *   - Error semantics differ (skip + record vs. throw RuleProbeError)
+ *
+ * Convergence invariant (enforced upstream in schemas.ts): every rubric
+ * `output_schema.required` includes `first_violating_step_id`, so each
+ * rubric finding always points at a concrete span and can be correlated
+ * with symbolic findings on the same span by the synthesizer.
+ */
+import { AgentProviderError } from "../../agent-providers/types.js";
+import { render as renderPrompt, languageInstructionFor, } from "../../agent-providers/prompt-template.js";
+/** Resolve one rubric input spec against the trace and return a value
+ *  suitable for prompt interpolation. Pure for testability. */
+export function resolveRubricInput(spec, tree) {
+    const colon = spec.source.indexOf(":");
+    if (colon === -1) {
+        throw new AgentBindingError(`rubric input source missing prefix (expected '<scheme>:...'): '${spec.source}'`);
+    }
+    const scheme = spec.source.slice(0, colon);
+    const payload = spec.source.slice(colon + 1);
+    switch (scheme) {
+        case "extract_from_root_attr": {
+            // dotted path against root.attributes (nested attr lookups are common).
+            const root = tree.root;
+            if (!root)
+                return null;
+            return getDottedPath(root.attributes, payload);
+        }
+        case "filter_by_kind": {
+            // payload form: '[kind1,kind2,...]' or 'kind1,kind2,...'
+            const inner = payload.replace(/^\[|\]$/g, "");
+            const kinds = inner.split(",").map((s) => s.trim()).filter(Boolean);
+            const acc = [];
+            for (const k of kinds) {
+                const spans = tree.byKind.get(k) ?? [];
+                for (const s of spans) {
+                    acc.push({
+                        spanId: s.spanId,
+                        name: s.name,
+                        kind: s.kind,
+                        attributes: s.attributes,
+                        durationMs: s.durationMs,
+                        status: s.status,
+                    });
+                }
+            }
+            // Order chronologically so the agent reads a coherent timeline.
+            acc.sort((a, b) => {
+                const sa = tree.byId.get(a.spanId)?.startTimeUnixNano ?? "0";
+                const sb = tree.byId.get(b.spanId)?.startTimeUnixNano ?? "0";
+                return Number(BigInt(sa) - BigInt(sb));
+            });
+            return acc;
+        }
+        case "literal":
+            try {
+                return JSON.parse(payload);
+            }
+            catch (e) {
+                throw new AgentBindingError(`literal source has invalid JSON: ${e.message}`);
+            }
+        default:
+            throw new AgentBindingError(`unknown rubric input source scheme: '${scheme}'`);
+    }
+}
+export class AgentBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentBindingError";
+    }
+}
+/** OTel attribute keys are typically flat strings with literal dots
+ *  (e.g. `gen_ai.user.message`), but some traces nest objects under a
+ *  parent attribute. Try direct lookup first; fall back to nested walk. */
+function getDottedPath(obj, path) {
+    if (obj === null || obj === undefined || typeof obj !== "object")
+        return undefined;
+    const flat = obj[path];
+    if (flat !== undefined)
+        return flat;
+    let cur = obj;
+    for (const part of path.split(".")) {
+        if (cur === null || cur === undefined)
+            return undefined;
+        if (typeof cur !== "object")
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function buildPromptVars(rule, tree, resolvedInputs, lang) {
+    // Surface enough context that builtin:rubric-judge-v1 can be a generic
+    // template without per-rule knowledge: judge question + inputs blob +
+    // rule metadata. `language_instruction` localizes prose fields only;
+    // schema-fixed values (enums, span IDs) stay English regardless.
+    return {
+        rule_id: rule.id,
+        judge_question: rule.rubric?.judgeQuestion ?? "",
+        output_schema: rule.rubric?.outputSchemaRaw ?? {},
+        inputs: resolvedInputs,
+        trace_id: tree.traceId,
+        language_instruction: languageInstructionFor(lang),
+    };
+}
+async function evaluateOne(rule, tree, provider, promptRegistry, timeoutMs, lang = "en", artifacts, userQuery = null, queryId = null) {
+    const rubric = rule.rubric; // caller guarantees
+    // Resolve inputs.
+    const resolvedInputs = {};
+    for (const inp of rubric.inputs) {
+        resolvedInputs[inp.kind] = resolveRubricInput(inp, tree);
+    }
+    // Render prompt.
+    const tpl = promptRegistry.get(rubric.agentBinding.promptTemplateRef);
+    const prompt = renderPrompt(tpl, buildPromptVars(rule, tree, resolvedInputs, lang));
+    if (artifacts) {
+        await artifacts.writeStageTwoPrompt(rule.id, 0, prompt); // chunk-000 — single-trace mode K=1
+    }
+    // Invoke.
+    const resp = await provider.invoke({
+        prompt,
+        outputSchema: rubric.outputZodSchema,
+        timeoutMs,
+        correlationId: `${tree.traceId}/${rule.id}`,
+    });
+    if (artifacts) {
+        await artifacts.writeStageTwoResponse(rule.id, 0, resp.output);
+    }
+    const out = resp.output;
+    const firstSpan = out.first_violating_step_id;
+    const otherSpans = Array.isArray(out.evidence_span_ids) ? out.evidence_span_ids : [];
+    // Convergence: ensure first_violating_step_id is in evidence.spans.
+    const spans = otherSpans.includes(firstSpan) ? otherSpans : [firstSpan, ...otherSpans];
+    return {
+        ruleId: rule.id,
+        judgmentKind: "rubric",
+        severity: out.severity ?? rule.severity, // agent may upgrade/downgrade
+        symptom: rule.symptom,
+        likelyCause: out.category ?? out.reasoning ?? rule.symptom,
+        evidence: {
+            spans,
+            excerpt: out.reasoning ?? "",
+        },
+        suggestedFix: {
+            target: rule.suggestedFix.target,
+            // Render changeTemplate with rubric output as bindings (best-effort:
+            // string-keyed values; complex shapes pass through unchanged).
+            change: renderChangeTemplate(rule.suggestedFix.changeTemplate, out),
+        },
+        confidence: out.confidence ?? "medium", // rubric default > symbolic
+        verifyWith: {
+            suggestedEvalCase: {
+                queryId,
+                query: userQuery,
+                assertions: rule.verifyWith.assertionTemplates.map((t) => renderChangeTemplate(t, out)),
+            },
+        },
+    };
+}
+export function renderChangeTemplate(tpl, bindings) {
+    return tpl.replace(/{{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*}}/g, (_, key) => {
+        const v = bindings[key];
+        if (v === undefined || v === null)
+            return `{{${key}}}`;
+        return typeof v === "string" ? v : JSON.stringify(v);
+    });
+}
+/**
+ * Evaluate every rubric rule in `rules` and return findings + skip records.
+ *
+ * A rule is *skipped* (not failed) when:
+ *   - `--no-llm` is set → reason: 'no-llm-flag-set'
+ *   - rule's named provider isn't registered or `isAvailable()` is false
+ *     → reason: `provider-not-available:<name>`
+ *   - rule's prompt template isn't registered
+ *     → reason: `prompt-template-missing:<ref>`
+ *
+ * Schema violations / transport errors from the provider are surfaced
+ * as `AgentBindingError` (let the CLI decide whether to fail the whole
+ * run or skip the single rule). Default callsite (`index.ts`) catches
+ * these and records them in `rules_skipped` rather than aborting.
+ */
+export async function evaluateRubricRules(opts) {
+    const findings = [];
+    const skipped = [];
+    for (const rule of opts.rules) {
+        if (!rule.rubric)
+            continue;
+        if (opts.noLlm) {
+            skipped.push({ ruleId: rule.id, reason: "no-llm-flag-set" });
+            continue;
+        }
+        // Resolve provider for this rule.
+        let provider;
+        try {
+            provider = opts.registry.resolve({
+                preferred: rule.rubric.agentBinding.provider,
+                requiredCapabilities: ["structured_output"],
+            });
+        }
+        catch (e) {
+            if (e instanceof AgentProviderError && e.kind === "not_available") {
+                skipped.push({
+                    ruleId: rule.id,
+                    reason: `provider-not-available:${rule.rubric.agentBinding.provider}`,
+                });
+                continue;
+            }
+            throw e;
+        }
+        if (!provider) {
+            skipped.push({
+                ruleId: rule.id,
+                reason: `provider-not-available:${rule.rubric.agentBinding.provider}`,
+            });
+            continue;
+        }
+        if (!(await provider.isAvailable())) {
+            skipped.push({
+                ruleId: rule.id,
+                reason: `provider-not-available:${rule.rubric.agentBinding.provider}`,
+            });
+            continue;
+        }
+        if (!opts.promptRegistry.has(rule.rubric.agentBinding.promptTemplateRef)) {
+            skipped.push({
+                ruleId: rule.id,
+                reason: `prompt-template-missing:${rule.rubric.agentBinding.promptTemplateRef}`,
+            });
+            continue;
+        }
+        try {
+            // Write work-queue once per rule before invoking (single-trace: 1 entry).
+            await opts.artifacts?.writeStageTwoWorkQueue(rule.id, [opts.tree.traceId]);
+            const finding = await evaluateOne(rule, opts.tree, provider, opts.promptRegistry, opts.timeoutMs, opts.lang ?? "en", opts.artifacts, opts.userQuery ?? null, opts.queryId ?? null);
+            findings.push(finding);
+        }
+        catch (e) {
+            if (e instanceof AgentProviderError) {
+                // Provider-level failures (timeout / transport / schema_violation) downgrade
+                // to a skip; the rest of the run still produces a usable report.
+                skipped.push({
+                    ruleId: rule.id,
+                    reason: `agent-error:${e.kind}`,
+                });
+                continue;
+            }
+            throw e;
+        }
+    }
+    return { findings, skipped };
+}

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 };