@kweaver-ai/kweaver-sdk 0.8.3 → 0.8.4

package/dist/trace-ai/eval-set/schemas.d.ts

@@ -26,6 +26,7 @@ export declare const EvalSetIndexSchema: z.ZodObject<{
             holdout: "holdout";
         }>>;
     }, z.core.$strip>>;
+    target_kn: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const EvalSetShardSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"trace-eval-set/v1">;

package/dist/trace-ai/eval-set/schemas.js

@@ -46,6 +46,10 @@ export const EvalSetIndexSchema = z.object({
     schema_version: z.literal("trace-eval-set-index/v1"),
     eval_set_id: z.string().min(1),
     shards: z.array(ShardRefSchema).min(1),
+    // KN id the reference answers were authored against. Optional for backward
+    // compatibility; when present, the exp loop's preflight check verifies the
+    // agent under test is bound to exactly this KN before running the round.
+    target_kn: z.string().min(1).optional(),
 });
 // ── trace-eval-set/v1 ────────────────────────────────────────────────────
 const refineCase = (data, ctx) => {

package/dist/trace-ai/eval-set/types.d.ts

@@ -31,6 +31,8 @@ export interface EvalSetIndex {
     schema_version: "trace-eval-set-index/v1";
     eval_set_id: string;
     shards: EvalSetIndexShard[];
+    /** KN id the reference answers were authored against (see EvalSetIndexSchema). */
+    target_kn?: string;
 }
 export interface BuildResult {
     cases_written: number;

package/dist/trace-ai/exp/capture-fingerprint.d.ts

@@ -0,0 +1,10 @@
+import type { AgentFingerprint } from "./preflight.js";
+/** Fetches the full raw config object of an agent at a given version. */
+export type AgentConfigFetcher = (agentId: string, version: string) => Promise<Record<string, unknown>>;
+/**
+ * Capture the live agent's material configuration as an AgentFingerprint.
+ * The version is resolved from the returned config body (so a "latest" request
+ * records the concrete version actually fetched), falling back to the requested
+ * version when the body omits it.
+ */
+export declare function captureAgentFingerprint(fetchConfig: AgentConfigFetcher, agentId: string, version: string): Promise<AgentFingerprint>;

package/dist/trace-ai/exp/capture-fingerprint.js

@@ -0,0 +1,12 @@
+import { fingerprintFromAgentConfig } from "./preflight.js";
+/**
+ * Capture the live agent's material configuration as an AgentFingerprint.
+ * The version is resolved from the returned config body (so a "latest" request
+ * records the concrete version actually fetched), falling back to the requested
+ * version when the body omits it.
+ */
+export async function captureAgentFingerprint(fetchConfig, agentId, version) {
+    const config = await fetchConfig(agentId, version);
+    const resolvedVersion = typeof config["version"] === "string" ? config["version"] : version;
+    return fingerprintFromAgentConfig(agentId, resolvedVersion, config);
+}

package/dist/trace-ai/exp/context/context-assembler.d.ts

@@ -0,0 +1,18 @@
+import type { PatchTarget, KnContext, SkillContext, SkillBinding, QueryFailureAnalysis, KnSchemaSnapshot } from "../schemas.js";
+import type { VegaCatalogClient } from "./vega-catalog-client.js";
+import type { KnSchemaClient } from "./kn-schema-client.js";
+import type { SkillApiClient } from "../patch/skill-api-client.js";
+import type { DataProbe } from "./kn-data-prober.js";
+type ProbeFn = (schema: KnSchemaSnapshot, failures: QueryFailureAnalysis[]) => Promise<DataProbe[]>;
+export declare class ContextAssembler {
+    private knSchemaClient;
+    private vegaCatalogClient;
+    private skillApiClient;
+    private probeFn?;
+    constructor(knSchemaClient: KnSchemaClient, vegaCatalogClient: VegaCatalogClient, skillApiClient: SkillApiClient, probeFn?: ProbeFn | undefined);
+    assemble(suggestedTarget: PatchTarget, knId: string | undefined, boundSkills: SkillBinding[], failureAnalysis?: QueryFailureAnalysis[]): Promise<{
+        kn_context?: KnContext;
+        skill_context?: SkillContext;
+    }>;
+}
+export {};

package/dist/trace-ai/exp/context/context-assembler.js

@@ -0,0 +1,42 @@
+export class ContextAssembler {
+    knSchemaClient;
+    vegaCatalogClient;
+    skillApiClient;
+    probeFn;
+    constructor(knSchemaClient, vegaCatalogClient, skillApiClient, probeFn) {
+        this.knSchemaClient = knSchemaClient;
+        this.vegaCatalogClient = vegaCatalogClient;
+        this.skillApiClient = skillApiClient;
+        this.probeFn = probeFn;
+    }
+    async assemble(suggestedTarget, knId, boundSkills, failureAnalysis) {
+        if (suggestedTarget === "kn.object_type" || suggestedTarget === "kn.relation_type") {
+            if (!knId)
+                throw new Error("kn_id is required for kn.* patch target but was not found in candidate.yaml");
+            const [existing_schema, available_dataviews] = await Promise.all([
+                this.knSchemaClient.getSchema(knId),
+                this.vegaCatalogClient.listDataviews({ knId }),
+            ]);
+            let data_probes;
+            if (this.probeFn && failureAnalysis && failureAnalysis.length > 0) {
+                try {
+                    data_probes = await this.probeFn(existing_schema, failureAnalysis);
+                }
+                catch {
+                    // probe is best-effort
+                }
+            }
+            return { kn_context: { kn_id: knId, existing_schema, available_dataviews, data_probes } };
+        }
+        if (suggestedTarget === "skill.content") {
+            const bound_skills = await Promise.all(boundSkills.map(async (s) => ({
+                id: s.id,
+                version: s.version,
+                content: await this.skillApiClient.getSkillContent(s.id),
+            })));
+            return { skill_context: { bound_skills } };
+        }
+        // agent.system_prompt / agent.skills: no platform data needed
+        return {};
+    }
+}

package/dist/trace-ai/exp/context/failure-analyzer.d.ts

@@ -0,0 +1,22 @@
+import type { QueryResult, QueryFailureAnalysis } from "../schemas.js";
+import type { TraceSpan } from "../../../api/conversations.js";
+type FetchTraceFn = (conversationId: string) => Promise<{
+    spans: TraceSpan[];
+}>;
+/**
+ * Per failing query, pair the assertion failure with what the trace says the
+ * agent actually did — the tool calls it made and, crucially, whether it
+ * retrieved any KN data (`retrieval_health`). The retrieval-health signal lets
+ * triage tell a mechanism failure (agent never retrieved data) apart from a
+ * reasoning failure (retrieved data, answered wrong).
+ */
+export declare function analyzeFailures(results: QueryResult[], fetchTrace?: FetchTraceFn): Promise<QueryFailureAnalysis[]>;
+/**
+ * Did ANY query in the round show the agent retrieving KN data? Used to veto a
+ * mechanism-failure verdict: diagnoseMechanism only sees failing queries, so a
+ * mostly-healthy round (passing queries retrieved fine) that happens to have a
+ * few failing no-data queries must not be mistaken for a global wiring failure.
+ * Short-circuits on the first retrieval, so a healthy round costs ~one fetch.
+ */
+export declare function roundRetrievedAnyData(results: QueryResult[], fetchTrace?: FetchTraceFn): Promise<boolean>;
+export {};

package/dist/trace-ai/exp/context/failure-analyzer.js

@@ -0,0 +1,59 @@
+import { extractToolCalls, healthFromToolCalls, summarizeToolCalls, } from "./retrieval-health.js";
+const MAX_REASON_LEN = 200;
+/**
+ * Per failing query, pair the assertion failure with what the trace says the
+ * agent actually did — the tool calls it made and, crucially, whether it
+ * retrieved any KN data (`retrieval_health`). The retrieval-health signal lets
+ * triage tell a mechanism failure (agent never retrieved data) apart from a
+ * reasoning failure (retrieved data, answered wrong).
+ */
+export async function analyzeFailures(results, fetchTrace) {
+    const failing = results.filter(r => r.assertion_results.some(a => a.verdict === "fail" || a.verdict === "skip"));
+    return Promise.all(failing.map(async (r) => {
+        const worstAssertion = r.assertion_results.find(a => a.verdict === "fail")
+            ?? r.assertion_results.find(a => a.verdict === "skip");
+        const verdict = worstAssertion?.verdict === "fail" ? "fail" : "skip";
+        const rawReason = worstAssertion?.reason ?? "";
+        const assertion_reason = rawReason.slice(0, MAX_REASON_LEN);
+        // "no_trace" until a trace is fetched and parsed — covers both an absent
+        // fetcher/conversation_id and a fetch that throws.
+        let tool_call_summary = [];
+        let retrieval_health = "no_trace";
+        if (fetchTrace && r.conversation_id) {
+            try {
+                const { spans } = await fetchTrace(r.conversation_id);
+                const calls = extractToolCalls(spans);
+                tool_call_summary = summarizeToolCalls(calls);
+                retrieval_health = healthFromToolCalls(calls);
+            }
+            catch {
+                // trace fetch is best-effort; retrieval_health stays "no_trace"
+            }
+        }
+        return { query_id: r.query_id, verdict, assertion_reason, tool_call_summary, retrieval_health };
+    }));
+}
+/**
+ * Did ANY query in the round show the agent retrieving KN data? Used to veto a
+ * mechanism-failure verdict: diagnoseMechanism only sees failing queries, so a
+ * mostly-healthy round (passing queries retrieved fine) that happens to have a
+ * few failing no-data queries must not be mistaken for a global wiring failure.
+ * Short-circuits on the first retrieval, so a healthy round costs ~one fetch.
+ */
+export async function roundRetrievedAnyData(results, fetchTrace) {
+    if (!fetchTrace)
+        return false;
+    for (const r of results) {
+        if (!r.conversation_id)
+            continue;
+        try {
+            const { spans } = await fetchTrace(r.conversation_id);
+            if (healthFromToolCalls(extractToolCalls(spans)) === "retrieved")
+                return true;
+        }
+        catch {
+            // trace fetch is best-effort
+        }
+    }
+    return false;
+}

package/dist/trace-ai/exp/context/kn-data-prober.d.ts

@@ -0,0 +1,13 @@
+import type { KnSchemaSnapshot, QueryFailureAnalysis } from "../schemas.js";
+import type { QueryResourceOptions, ResourceQueryResult } from "../../../api/resources.js";
+type QueryResourceFn = (opts: Pick<QueryResourceOptions, "baseUrl" | "accessToken" | "id" | "needTotal" | "limit">) => Promise<ResourceQueryResult>;
+export interface DataProbe {
+    concept_name: string;
+    data_view_id: string;
+    total_records: number;
+}
+export declare function probeObjectTypes(schema: KnSchemaSnapshot, failures: QueryFailureAnalysis[], queryResource: QueryResourceFn, opts?: {
+    baseUrl?: string;
+    accessToken?: string;
+}): Promise<DataProbe[]>;
+export {};

package/dist/trace-ai/exp/context/kn-data-prober.js

@@ -0,0 +1,38 @@
+function extractConceptNames(failures) {
+    const names = new Set();
+    for (const f of failures) {
+        for (const call of f.tool_call_summary) {
+            const match = call.match(/kn_search\(([^)]+)\)/);
+            if (match)
+                names.add(match[1].trim());
+        }
+    }
+    return names;
+}
+export async function probeObjectTypes(schema, failures, queryResource, opts = {}) {
+    const mentionedConcepts = extractConceptNames(failures);
+    const toProbe = schema.object_types.filter(ot => ot.data_view_id && mentionedConcepts.has(ot.concept_name));
+    const seen = new Set();
+    const unique = toProbe.filter(ot => {
+        if (seen.has(ot.data_view_id))
+            return false;
+        seen.add(ot.data_view_id);
+        return true;
+    });
+    const results = await Promise.all(unique.map(async (ot) => {
+        try {
+            const result = await queryResource({
+                baseUrl: opts.baseUrl ?? "",
+                accessToken: opts.accessToken ?? "",
+                id: ot.data_view_id,
+                needTotal: true,
+                limit: 1,
+            });
+            return { concept_name: ot.concept_name, data_view_id: ot.data_view_id, total_records: result.total_count ?? 0 };
+        }
+        catch {
+            return null;
+        }
+    }));
+    return results.filter((r) => r !== null);
+}

package/dist/trace-ai/exp/context/kn-schema-client.d.ts

@@ -0,0 +1,14 @@
+import type { KnSchemaSnapshot } from "../schemas.js";
+import type { ContextLoaderCallOptions, SearchSchemaArgs, SearchSchemaResult } from "../../../api/context-loader.js";
+export interface KnSchemaClient {
+    getSchema(knId: string): Promise<KnSchemaSnapshot>;
+}
+type SearchSchemaFn = (opts: ContextLoaderCallOptions, args: SearchSchemaArgs) => Promise<SearchSchemaResult>;
+export declare class KweaverKnSchemaClient implements KnSchemaClient {
+    private mcpUrl;
+    private token;
+    private searchSchemaFn;
+    constructor(mcpUrl: string, token: string, searchSchemaFn?: SearchSchemaFn);
+    getSchema(knId: string): Promise<KnSchemaSnapshot>;
+}
+export {};

package/dist/trace-ai/exp/context/kn-schema-client.js

@@ -0,0 +1,41 @@
+import { searchSchema } from "../../../api/context-loader.js";
+export class KweaverKnSchemaClient {
+    mcpUrl;
+    token;
+    searchSchemaFn;
+    constructor(mcpUrl, token, searchSchemaFn = searchSchema) {
+        this.mcpUrl = mcpUrl;
+        this.token = token;
+        this.searchSchemaFn = searchSchemaFn;
+    }
+    async getSchema(knId) {
+        const opts = {
+            mcpUrl: this.mcpUrl,
+            accessToken: this.token,
+            knId,
+        };
+        const result = await this.searchSchemaFn(opts, {
+            query: "*",
+            response_format: "json",
+            schema_brief: true,
+        });
+        const rawObjectTypes = (result.object_types ?? []);
+        const object_types = rawObjectTypes.map(ot => {
+            const ds = ot["data_source"];
+            const props = ot["properties"] ?? [];
+            return {
+                concept_name: String(ot["concept_name"] ?? ""),
+                data_view_id: typeof ds?.["id"] === "string" ? ds["id"] : undefined,
+                fields: props.map(p => ({ name: String(p["name"] ?? ""), type: String(p["type"] ?? "string") })),
+            };
+        });
+        const rawRelTypes = (result.relation_types ?? []);
+        const relation_types = rawRelTypes.map(rt => ({
+            concept_name: String(rt["concept_name"] ?? rt["name"] ?? ""),
+            source: String(rt["source"] ?? ""),
+            target: String(rt["target"] ?? ""),
+            join_key: String(rt["join_key"] ?? ""),
+        }));
+        return { object_types, relation_types };
+    }
+}

package/dist/trace-ai/exp/context/retrieval-health.d.ts

@@ -0,0 +1,32 @@
+import type { TraceSpan } from "../../../api/conversations.js";
+import type { QueryFailureAnalysis } from "../schemas.js";
+export type ToolCallOutcome = "data" | "empty" | "error";
+export interface ToolCallRecord {
+    tool_name: string;
+    /** Raw gen_ai.tool.call.arguments JSON string (may be ""). */
+    arguments: string;
+    outcome: ToolCallOutcome;
+}
+export type RetrievalHealth = "retrieved" | "empty" | "errored" | "no_kn_calls" | "no_trace";
+export interface MechanismDiagnosis {
+    broken: boolean;
+    /** Root-cause message, populated only when broken. */
+    reason: string;
+}
+/** Extract every `execute_tool` call from a conversation's trace spans. */
+export declare function extractToolCalls(spans: TraceSpan[]): ToolCallRecord[];
+/** Render tool calls as `tool_name→outcome` strings for the triage prompt, capped. */
+export declare function summarizeToolCalls(calls: ToolCallRecord[], max?: number): string[];
+/**
+ * Reduce a query's tool calls to one retrieval-health verdict. "retrieved" wins
+ * as soon as any KN call returned data — one good retrieval proves the mechanism
+ * works. Otherwise "errored" outranks "empty" (an error is the stronger signal).
+ */
+export declare function healthFromToolCalls(calls: ToolCallRecord[]): RetrievalHealth;
+/**
+ * Roll per-query retrieval health up to a round-level verdict. The mechanism is
+ * "broken" when enough failing queries exercised the KN yet none retrieved any
+ * data — a fail-fast signal that the round measured a wiring failure, not the
+ * prompt. no_kn_calls / no_trace queries carry no evidence and are ignored.
+ */
+export declare function diagnoseMechanism(analyses: QueryFailureAnalysis[]): MechanismDiagnosis;

package/dist/trace-ai/exp/context/retrieval-health.js

@@ -0,0 +1,138 @@
+/** KN retrieval/navigation tools — calls to these are what "retrieved KN data" means. */
+const KN_RETRIEVAL_TOOLS = new Set([
+    "query_object_instance",
+    "kn_search",
+    "semantic_search",
+    "search_schema",
+    "get_logic_properties_values",
+    "dv_query",
+    // SQL aggregation over the KN's Vega resources — the agent's main data path
+    // for COUNT/SUM/GROUP BY/TOP-N. Omitting it makes the mechanism check blind to
+    // a SQL-capable agent and false-flag a healthy round as "retrieved no data".
+    "vega_sql_query",
+]);
+const TOOL_SPAN_PREFIX = "execute_tool ";
+/**
+ * Minimum no-data failing queries before the mechanism may be blamed. A handful
+ * of no-data failures can be legitimate (a genuinely hard question, or the agent
+ * building a bad query) — the guard needs enough of them to be confident. An
+ * eval set smaller than this can never trip the guard on count alone; that is
+ * acceptable because the round-level retrieval veto (roundRetrievedAnyData in
+ * failure-analyzer) is the real safety net against a false positive.
+ */
+const MIN_MECHANISM_EVIDENCE = 3;
+/**
+ * Classify a tool's result `answer` payload. Biased toward "data" on ambiguous
+ * objects: a false "data" only means a mechanism failure goes undetected (the
+ * loop behaves as before), whereas a false "empty"/"error" could wrongly fail a
+ * healthy round.
+ */
+function classifyAnswer(answer) {
+    if (answer === null || answer === undefined)
+        return "empty";
+    // The error payload comes back as an SSE string carrying error_code.
+    if (typeof answer === "string")
+        return /error_code/.test(answer) ? "error" : "empty";
+    if (Array.isArray(answer))
+        return answer.length > 0 ? "data" : "empty";
+    if (typeof answer === "object") {
+        const obj = answer;
+        if (obj["error_code"])
+            return "error";
+        // Any non-empty array property counts as data — deliberately permissive per
+        // the bias-toward-"data" rationale above. A metadata array (e.g. warnings)
+        // could trip this; that is the acceptable direction to err.
+        for (const v of Object.values(obj)) {
+            if (Array.isArray(v) && v.length > 0)
+                return "data";
+        }
+        return "empty";
+    }
+    return "empty";
+}
+/** Classify a `gen_ai.tool.call.result` payload string. Defensive — never throws. */
+function classifyResult(resultStr) {
+    if (typeof resultStr !== "string" || resultStr.trim() === "")
+        return "empty";
+    let parsed;
+    try {
+        parsed = JSON.parse(resultStr);
+    }
+    catch {
+        // The error payload is itself valid JSON, so a parse failure means an
+        // opaque payload — flag it as an error only if it carries an error marker.
+        return /error_code/.test(resultStr) ? "error" : "empty";
+    }
+    return classifyAnswer(parsed?.answer);
+}
+/** Extract every `execute_tool` call from a conversation's trace spans. */
+export function extractToolCalls(spans) {
+    const calls = [];
+    for (const span of spans) {
+        const attrs = span.attributes ?? {};
+        const byAttr = attrs["gen_ai.operation.name"] === "execute_tool";
+        const byName = typeof span.name === "string" && span.name.startsWith(TOOL_SPAN_PREFIX);
+        if (!byAttr && !byName)
+            continue;
+        const toolName = typeof attrs["gen_ai.tool.name"] === "string" && attrs["gen_ai.tool.name"]
+            ? attrs["gen_ai.tool.name"]
+            : byName
+                ? span.name.slice(TOOL_SPAN_PREFIX.length)
+                : "";
+        if (!toolName)
+            continue;
+        const args = typeof attrs["gen_ai.tool.call.arguments"] === "string" ? attrs["gen_ai.tool.call.arguments"] : "";
+        const result = typeof attrs["gen_ai.tool.call.result"] === "string" ? attrs["gen_ai.tool.call.result"] : "";
+        calls.push({ tool_name: toolName, arguments: args, outcome: classifyResult(result) });
+    }
+    return calls;
+}
+/** Render tool calls as `tool_name→outcome` strings for the triage prompt, capped. */
+export function summarizeToolCalls(calls, max = 8) {
+    return calls.slice(0, max).map(c => `${c.tool_name}→${c.outcome}`);
+}
+/**
+ * Reduce a query's tool calls to one retrieval-health verdict. "retrieved" wins
+ * as soon as any KN call returned data — one good retrieval proves the mechanism
+ * works. Otherwise "errored" outranks "empty" (an error is the stronger signal).
+ */
+export function healthFromToolCalls(calls) {
+    const knCalls = calls.filter(c => KN_RETRIEVAL_TOOLS.has(c.tool_name));
+    if (knCalls.length === 0)
+        return "no_kn_calls";
+    if (knCalls.some(c => c.outcome === "data"))
+        return "retrieved";
+    if (knCalls.some(c => c.outcome === "error"))
+        return "errored";
+    return "empty";
+}
+/**
+ * Roll per-query retrieval health up to a round-level verdict. The mechanism is
+ * "broken" when enough failing queries exercised the KN yet none retrieved any
+ * data — a fail-fast signal that the round measured a wiring failure, not the
+ * prompt. no_kn_calls / no_trace queries carry no evidence and are ignored.
+ */
+export function diagnoseMechanism(analyses) {
+    let retrieved = 0;
+    let errored = 0;
+    let empty = 0;
+    for (const a of analyses) {
+        if (a.retrieval_health === "retrieved")
+            retrieved++;
+        else if (a.retrieval_health === "errored")
+            errored++;
+        else if (a.retrieval_health === "empty")
+            empty++;
+    }
+    const noData = errored + empty;
+    if (retrieved > 0 || noData < MIN_MECHANISM_EVIDENCE) {
+        return { broken: false, reason: "" };
+    }
+    return {
+        broken: true,
+        reason: `Mechanism failure: ${noData} failing queries exercised the KN but none retrieved data ` +
+            `(${errored} errored, ${empty} empty), and no failing query retrieved any KN data. ` +
+            `The agent is not retrieving from the knowledge network — this is not a prompt problem. ` +
+            `Check the agent's KN binding (kn_id map_type must be "fixedValue") and that the bound KN holds data.`,
+    };
+}

package/dist/trace-ai/exp/context/vega-catalog-client.d.ts

@@ -0,0 +1,14 @@
+import type { VegaCatalogEntry } from "../schemas.js";
+export interface VegaCatalogClient {
+    listDataviews(filter?: {
+        knId?: string;
+    }): Promise<VegaCatalogEntry[]>;
+}
+export declare class KweaverVegaCatalogClient implements VegaCatalogClient {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    listDataviews(_filter?: {
+        knId?: string;
+    }): Promise<VegaCatalogEntry[]>;
+}

package/dist/trace-ai/exp/context/vega-catalog-client.js

@@ -0,0 +1,15 @@
+// Stub: replace body with real Vega API calls when endpoint is confirmed
+export class KweaverVegaCatalogClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    async listDataviews(_filter) {
+        // TODO: GET {baseUrl}/api/vega/v1/dataviews?kn_id={filter.knId}
+        // Response shape: [{ id, name, columns: [{ name, type }] }]
+        // Intentionally returns empty — data_probes from KnDataProber is the primary enrichment path
+        return [];
+    }
+}

package/dist/trace-ai/exp/coordinator.d.ts

@@ -1,26 +1,13 @@
-import type { Mission, NextChange, QueryResult, RoundData } from "./schemas.js";
-export interface SynthesizerClient {
-    generate(input: {
-        mission: Mission;
-        candidateConfig: Record<string, unknown>;
-        prevRound?: RoundData;
-        prevRounds: RoundData[];
-        crossRoundMemoryRef?: string;
-    }): Promise<NextChange>;
-}
-export interface TriageClient {
-    triage(input: {
-        currentRound: RoundData;
-        prevRounds: RoundData[];
-        candidateConfig: Record<string, unknown>;
-        crossRoundMemoryRef?: string;
-    }): Promise<RoundData["triage_conclusion"] & {
-        new_memory_token: string;
-    }>;
-}
+import type { KnApiClient } from "./patch/kn-api-client.js";
+import type { SkillApiClient } from "./patch/skill-api-client.js";
+import { ContextAssembler } from "./context/context-assembler.js";
+import type { TriageClient, TriageResult } from "./providers/triage-client.js";
+import type { AgentConfigFetcher } from "./capture-fingerprint.js";
+import type { QueryResult } from "./schemas.js";
+import type { TraceSpan } from "../../api/conversations.js";
+export type { TriageClient, TriageResult };
 export interface CoordinatorOpts {
     expDir: string;
-    synthesizer: SynthesizerClient;
     triage: TriageClient;
     runEval: (opts: {
         evalSetPaths: string[];
@@ -31,6 +18,18 @@ export interface CoordinatorOpts {
         queryResults: QueryResult[];
     }>;
     experimentId?: string;
+    contextAssembler?: ContextAssembler;
+    fetchTrace?: (conversationId: string) => Promise<{
+        spans: TraceSpan[];
+    }>;
+    knClient?: KnApiClient;
+    skillClient?: SkillApiClient;
+    /**
+     * When provided, a preflight reconciliation runs before each eval round —
+     * verifying the live agent matches expectation and is bound to the eval set's
+     * target KN. A mismatch fails the round fast, before any eval chat is sent.
+     */
+    fetchAgentConfig?: AgentConfigFetcher;
 }
 export declare class ExperimentCoordinator {
     private opts;
@@ -39,6 +38,20 @@ export declare class ExperimentCoordinator {
     constructor(opts: CoordinatorOpts);
     run(): Promise<void>;
     resume(): Promise<void>;
+    /**
+     * Install SIGINT/SIGHUP/SIGTERM handlers that flush a final event and release
+     * the lock before exit. Returns an uninstaller that MUST be called in the
+     * caller's finally block (otherwise normal exit would still fire the handler).
+     *
+     * Semantics:
+     *   SIGINT  → user-intent abort       → emit `aborted` event (terminal)
+     *   SIGHUP  → terminal closed         → emit `step_failed` retryable
+     *   SIGTERM → external kill (ambig.)  → emit `step_failed` retryable
+     *
+     * SIGKILL / OOM / power loss can't be caught here — Layer 2 auto-recovery in
+     * run() handles that case on the next start.
+     */
+    private installSignalHandlers;
     private runLoop;
     private checkAbort;
     private withRetry;