@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/help/format.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Help text formatter for the kweaver CLI.
+ *
+ * All `--help` output must go through `renderHelp()` to keep a consistent
+ * gh-style layout. See `docs/cli_conventions.md` §8 for the spec.
+ */
+export interface HelpItem {
+    name: string;
+    desc: string;
+}
+export interface HelpSection {
+    title: string;
+    items: HelpItem[];
+}
+export interface HelpFlag {
+    name: string;
+    desc: string;
+}
+export interface HelpFlagGroup {
+    title: string;
+    flags: HelpFlag[];
+}
+export interface RenderHelpOptions {
+    /** Optional one-line tagline shown at the very top. */
+    tagline?: string;
+    /** One or more USAGE lines (without the "USAGE" header). */
+    usage: string | string[];
+    /**
+     * Command / subcommand groupings (rendered as separate sections with
+     * two-column name:desc layout).
+     */
+    sections?: HelpSection[];
+    /**
+     * Flags. Either a flat list (rendered under "FLAGS") or grouped sub-blocks
+     * (each rendered under its own title, e.g. "Login options").
+     */
+    flags?: HelpFlag[] | HelpFlagGroup[];
+    /** One-line "INHERITED FLAGS" summary. Omitted if undefined. */
+    inheritedFlags?: string;
+    /** Environment variable docs. */
+    environment?: HelpFlag[];
+    /** Example invocations (prefix `$ ` added automatically if missing). */
+    examples?: string[];
+    /** Free-form "LEARN MORE" trailing lines. */
+    learnMore?: string[];
+    /** Override the wrap width (default 80). */
+    width?: number;
+}
+/**
+ * Render full help text per the §8 spec.
+ */
+export declare function renderHelp(opts: RenderHelpOptions): string;
+/**
+ * Render a two-column name:desc list.
+ *
+ * Width policy: left column = max(name length) + 2 (capped at half the wrap
+ * width). Description wraps onto continuation lines aligned to the right
+ * column. `indent` controls the leading whitespace (default: 2 spaces).
+ */
+export declare function formatTwoColumn(items: HelpItem[], width?: number, indent?: string): string[];
+/**
+ * Word-wrap a string at the given column. Preserves single newlines as
+ * explicit line breaks.
+ */
+export declare function wrap(text: string, width: number): string[];

package/dist/help/format.js

@@ -0,0 +1,141 @@
+/**
+ * Help text formatter for the kweaver CLI.
+ *
+ * All `--help` output must go through `renderHelp()` to keep a consistent
+ * gh-style layout. See `docs/cli_conventions.md` §8 for the spec.
+ */
+const DEFAULT_WIDTH = 80;
+const INDENT = "  ";
+/**
+ * Render full help text per the §8 spec.
+ */
+export function renderHelp(opts) {
+    const width = opts.width ?? DEFAULT_WIDTH;
+    const out = [];
+    if (opts.tagline) {
+        out.push(opts.tagline);
+        out.push("");
+    }
+    const usageLines = Array.isArray(opts.usage) ? opts.usage : [opts.usage];
+    out.push("USAGE");
+    for (const line of usageLines) {
+        out.push(INDENT + line);
+    }
+    out.push("");
+    if (opts.sections && opts.sections.length > 0) {
+        for (const section of opts.sections) {
+            out.push(section.title.toUpperCase());
+            out.push(...formatTwoColumn(section.items, width));
+            out.push("");
+        }
+    }
+    if (opts.flags) {
+        if (isFlagGroupArray(opts.flags)) {
+            out.push("FLAGS");
+            for (const group of opts.flags) {
+                out.push(INDENT + group.title);
+                out.push(...formatTwoColumn(group.flags.map((f) => ({ name: f.name, desc: f.desc })), width, INDENT.repeat(2)));
+                out.push("");
+            }
+        }
+        else {
+            out.push("FLAGS");
+            out.push(...formatTwoColumn(opts.flags.map((f) => ({ name: f.name, desc: f.desc })), width));
+            out.push("");
+        }
+    }
+    if (opts.inheritedFlags) {
+        out.push("INHERITED FLAGS");
+        out.push(INDENT + opts.inheritedFlags);
+        out.push("");
+    }
+    if (opts.environment && opts.environment.length > 0) {
+        out.push("ENVIRONMENT");
+        out.push(...formatTwoColumn(opts.environment.map((e) => ({ name: e.name, desc: e.desc })), width));
+        out.push("");
+    }
+    if (opts.examples && opts.examples.length > 0) {
+        out.push("EXAMPLES");
+        for (const ex of opts.examples) {
+            const trimmed = ex.trimStart();
+            const line = trimmed.startsWith("$") ? trimmed : `$ ${trimmed}`;
+            out.push(INDENT + line);
+        }
+        out.push("");
+    }
+    if (opts.learnMore && opts.learnMore.length > 0) {
+        out.push("LEARN MORE");
+        for (const line of opts.learnMore) {
+            out.push(INDENT + line);
+        }
+        out.push("");
+    }
+    while (out.length > 0 && out[out.length - 1] === "")
+        out.pop();
+    return out.join("\n");
+}
+/**
+ * Render a two-column name:desc list.
+ *
+ * Width policy: left column = max(name length) + 2 (capped at half the wrap
+ * width). Description wraps onto continuation lines aligned to the right
+ * column. `indent` controls the leading whitespace (default: 2 spaces).
+ */
+export function formatTwoColumn(items, width = DEFAULT_WIDTH, indent = INDENT) {
+    if (items.length === 0)
+        return [];
+    const maxName = items.reduce((m, i) => Math.max(m, i.name.length), 0);
+    const halfWidth = Math.floor(width / 2);
+    const colGap = Math.min(maxName + 2, halfWidth);
+    const descCol = indent.length + colGap;
+    const descWidth = Math.max(20, width - descCol);
+    const out = [];
+    for (const item of items) {
+        const namePadded = item.name.padEnd(colGap, " ");
+        const descLines = wrap(item.desc, descWidth);
+        if (descLines.length === 0) {
+            out.push(indent + item.name);
+            continue;
+        }
+        out.push(indent + namePadded + descLines[0]);
+        for (let i = 1; i < descLines.length; i++) {
+            out.push(" ".repeat(descCol) + descLines[i]);
+        }
+    }
+    return out;
+}
+/**
+ * Word-wrap a string at the given column. Preserves single newlines as
+ * explicit line breaks.
+ */
+export function wrap(text, width) {
+    if (!text)
+        return [];
+    const result = [];
+    for (const para of text.split("\n")) {
+        if (para.length <= width) {
+            result.push(para);
+            continue;
+        }
+        const words = para.split(/\s+/);
+        let line = "";
+        for (const word of words) {
+            if (line.length === 0) {
+                line = word;
+            }
+            else if (line.length + 1 + word.length <= width) {
+                line += " " + word;
+            }
+            else {
+                result.push(line);
+                line = word;
+            }
+        }
+        if (line.length > 0)
+            result.push(line);
+    }
+    return result;
+}
+function isFlagGroupArray(v) {
+    return v.length > 0 && "flags" in v[0];
+}

package/dist/index.d.ts

@@ -57,11 +57,11 @@ export { SkillsResource } from "./resources/skills.js";
 export { ToolboxesResource } from "./resources/toolboxes.js";
 export type { InvokeToolArgs } from "./resources/toolboxes.js";
 export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
-export type { SkillStatus, SkillSummary, SkillInfo, SkillFileSummary, SkillContentIndex, SkillFileReadResult, RegisterSkillResult, DeleteSkillResult, UpdateSkillStatusResult, SkillListResult, ListSkillsOptions, ListSkillMarketOptions, GetSkillOptions, RegisterSkillContentOptions, RegisterSkillZipOptions, UpdateSkillStatusOptions, ReadSkillFileOptions, DownloadSkillOptions, DownloadedSkillArchive, } from "./api/skills.js";
-export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
-export type { ViewField, DataView, CreateDataViewOptions, GetDataViewOptions, ListDataViewsOptions, DeleteDataViewOptions, FindDataViewOptions, QueryDataViewOptions, DataViewQueryResult, } from "./api/dataviews.js";
-export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
-export { DataViewsResource } from "./resources/dataviews.js";
+export type { SkillCategory, SkillEditableStatus, SkillStatus, SkillSummary, SkillInfo, SkillFileSummary, SkillContentIndex, SkillFileReadResult, RegisterSkillResult, DeleteSkillResult, UpdateSkillStatusResult, SkillListResult, ListSkillsOptions, ListSkillMarketOptions, GetSkillOptions, RegisterSkillContentOptions, RegisterSkillZipOptions, UpdateSkillMetadataOptions, UpdateSkillMetadataResult, UpdateSkillPackageContentOptions, UpdateSkillPackageZipOptions, UpdateSkillPackageResult, UpdateSkillStatusOptions, ReadSkillFileOptions, DownloadSkillOptions, DownloadedSkillArchive, SkillReleaseHistoryInfo, SkillHistoryVersionOptions, SkillManagementContentData, GetSkillManagementContentOptions, ReadSkillManagementFileOptions, DownloadSkillManagementOptions, } from "./api/skills.js";
+export { listSkills, listSkillMarket, getSkill, getSkillMarketDetail, deleteSkill, updateSkillStatus, updateSkillMetadata, registerSkillContent, registerSkillZip, updateSkillPackageContent, updateSkillPackageZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, listSkillHistory, republishSkillHistory, publishSkillHistory, installSkillArchive, getSkillManagementContent, readSkillManagementFile, downloadSkillManagementArchive, } from "./api/skills.js";
+export type { ViewField, Resource, CreateResourceOptions, GetResourceOptions, ListResourcesOptions, DeleteResourceOptions, FindResourceOptions, QueryResourceOptions, ResourceQueryResult, } from "./api/resources.js";
+export { parseResource, createResource, getResource, listResources, deleteResource, findResource, queryResource, } from "./api/resources.js";
+export { ResourcesResource } from "./resources/resources.js";
 export type { MfManagerBaseOptions, ListLlmModelsOptions, GetLlmModelOptions, AddLlmModelOptions, EditLlmModelOptions, DeleteLlmModelsOptions, TestLlmModelOptions, ListSmallModelsOptions, GetSmallModelOptions, AddSmallModelOptions, EditSmallModelOptions, DeleteSmallModelsOptions, TestSmallModelOptions, } from "./api/models.js";
 export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";
 export type { MfApiBaseOptions, ChatMessage, ModelChatCompletionsOptions, ModelChatResult, ModelEmbeddingOptions, ModelRerankOptions, } from "./api/model-invocation.js";

package/dist/index.js

@@ -44,9 +44,9 @@ export { ContextLoaderResource } from "./resources/context-loader.js";
 export { SkillsResource } from "./resources/skills.js";
 export { ToolboxesResource } from "./resources/toolboxes.js";
 export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
-export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
-export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
-export { DataViewsResource } from "./resources/dataviews.js";
+export { listSkills, listSkillMarket, getSkill, getSkillMarketDetail, deleteSkill, updateSkillStatus, updateSkillMetadata, registerSkillContent, registerSkillZip, updateSkillPackageContent, updateSkillPackageZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, listSkillHistory, republishSkillHistory, publishSkillHistory, installSkillArchive, getSkillManagementContent, readSkillManagementFile, downloadSkillManagementArchive, } from "./api/skills.js";
+export { parseResource, createResource, getResource, listResources, deleteResource, findResource, queryResource, } from "./api/resources.js";
+export { ResourcesResource } from "./resources/resources.js";
 export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";
 export { MF_MODEL_API_PATH_PREFIX, consumeOpenAiSseText, modelChatCompletions, modelEmbedding, modelEmbeddings, modelRerank, } from "./api/model-invocation.js";
 export { listBusinessDomains } from "./api/business-domains.js";

package/dist/resources/bkn.d.ts

@@ -49,6 +49,11 @@ export declare class BknResource {
     /**
      * Search KN schema — finds matching object types, relation types, and action types.
      * Uses the public agent-retrieval HTTP compatibility endpoint.
+     *
+     * @deprecated Use `client.contextLoader(...).searchSchema(...)` for new
+     * schema discovery integrations. `knSearch` is kept only for compatibility
+     * with the legacy HTTP `kn_search` endpoint and may not receive new
+     * `search_schema` capabilities.
      */
     knSearch(knId: string, query: string, opts?: {
         onlySchema?: boolean;

package/dist/resources/bkn.js

@@ -90,6 +90,11 @@ export class BknResource {
     /**
      * Search KN schema — finds matching object types, relation types, and action types.
      * Uses the public agent-retrieval HTTP compatibility endpoint.
+     *
+     * @deprecated Use `client.contextLoader(...).searchSchema(...)` for new
+     * schema discovery integrations. `knSearch` is kept only for compatibility
+     * with the legacy HTTP `kn_search` endpoint and may not receive new
+     * `search_schema` capabilities.
      */
     async knSearch(knId, query, opts = {}) {
         const raw = await knSearchHttp({

package/dist/resources/{dataviews.d.ts → resources.d.ts}

@@ -1,6 +1,6 @@
-import type { DataView, DataViewQueryResult } from "../api/dataviews.js";
+import type { Resource, ResourceQueryResult } from "../api/resources.js";
 import type { ClientContext } from "../client.js";
-export declare class DataViewsResource {
+export declare class ResourcesResource {
     private readonly ctx;
     constructor(ctx: ClientContext);
     create(opts: {
@@ -12,26 +12,25 @@ export declare class DataViewsResource {
             type: string;
         }>;
     }): Promise<string>;
-    get(id: string): Promise<DataView>;
+    get(id: string): Promise<Resource>;
     list(opts?: {
         datasourceId?: string;
-        type?: string;
+        category?: string;
         limit?: number;
-    }): Promise<DataView[]>;
+    }): Promise<Resource[]>;
     find(name: string, opts?: {
         datasourceId?: string;
         exact?: boolean;
         wait?: boolean;
         timeoutMs?: number;
-    }): Promise<DataView[]>;
+    }): Promise<Resource[]>;
     delete(id: string): Promise<void>;
     query(id: string, opts?: {
-        sql?: string;
         offset?: number;
         limit?: number;
         needTotal?: boolean;
-        outputFields?: string[];
-        filters?: Record<string, unknown>;
-        sort?: Array<Record<string, unknown>>;
-    }): Promise<DataViewQueryResult>;
+        filterCondition?: unknown;
+        sort?: string;
+        direction?: "asc" | "desc";
+    }): Promise<ResourceQueryResult>;
 }

package/dist/resources/{dataviews.js → resources.js}

@@ -1,25 +1,25 @@
-import { createDataView, deleteDataView, findDataView, getDataView, listDataViews, queryDataView, } from "../api/dataviews.js";
-export class DataViewsResource {
+import { RESOURCE_LIST_DEFAULT_LIMIT, createResource, deleteResource, findResource, getResource, listResources, queryResource, } from "../api/resources.js";
+export class ResourcesResource {
     ctx;
     constructor(ctx) {
         this.ctx = ctx;
     }
     async create(opts) {
-        return createDataView({ ...this.ctx.base(), ...opts });
+        return createResource({ ...this.ctx.base(), ...opts });
     }
     async get(id) {
-        return getDataView({ ...this.ctx.base(), id });
+        return getResource({ ...this.ctx.base(), id });
     }
     async list(opts = {}) {
-        return listDataViews({
+        return listResources({
             ...this.ctx.base(),
             datasourceId: opts.datasourceId,
-            type: opts.type,
-            limit: opts.limit,
+            category: opts.category,
+            limit: opts.limit ?? RESOURCE_LIST_DEFAULT_LIMIT,
         });
     }
     async find(name, opts) {
-        return findDataView({
+        return findResource({
             ...this.ctx.base(),
             name,
             datasourceId: opts?.datasourceId,
@@ -29,19 +29,18 @@ export class DataViewsResource {
         });
     }
     async delete(id) {
-        await deleteDataView({ ...this.ctx.base(), id });
+        await deleteResource({ ...this.ctx.base(), id });
     }
     async query(id, opts) {
-        return queryDataView({
+        return queryResource({
             ...this.ctx.base(),
             id,
-            sql: opts?.sql,
             offset: opts?.offset,
             limit: opts?.limit,
             needTotal: opts?.needTotal,
-            outputFields: opts?.outputFields,
-            filters: opts?.filters,
+            filterCondition: opts?.filterCondition,
             sort: opts?.sort,
+            direction: opts?.direction,
         });
     }
 }

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