@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

package/dist/trace-ai/exp/exp-store/mission-md.js

@@ -0,0 +1,37 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { MissionSchema } from "../schemas.js";
+export async function readMission(expDir) {
+    const filePath = path.join(expDir, "mission.md");
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        throw new Error(`mission.md not found in ${expDir}`);
+    }
+    // Extract YAML frontmatter between --- delimiters
+    const match = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        throw new Error(`mission.md in ${expDir} has no YAML frontmatter`);
+    const parsed = yaml.load(match[1]);
+    const result = MissionSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map(i => `${i.path.join(".")}: ${i.message}`).join("; ");
+        throw new Error(`mission.md schema invalid: ${issues}`);
+    }
+    return result.data;
+}
+export async function writeSuggestedChange(expDir, change) {
+    const filePath = path.join(expDir, "mission.md");
+    const raw = await fs.readFile(filePath, "utf8");
+    const match = raw.match(/^---\n([\s\S]*?)\n---(\n[\s\S]*)?$/);
+    if (!match)
+        throw new Error(`mission.md in ${expDir} has no YAML frontmatter`);
+    const frontmatter = yaml.load(match[1]);
+    frontmatter["next_change"] = change;
+    const body = match[2] ?? "";
+    const newContent = `---\n${yaml.dump(frontmatter, { lineWidth: -1 })}---${body}`;
+    await fs.writeFile(filePath, newContent, "utf8");
+}

package/dist/trace-ai/exp/exp-store/readme-template.d.ts

@@ -0,0 +1,5 @@
+export declare function renderReadme(opts: {
+    experimentId: string;
+    timestamp: string;
+    goal: string;
+}): string;

package/dist/trace-ai/exp/exp-store/readme-template.js

@@ -0,0 +1,25 @@
+// src/trace-ai/exp/exp-store/readme-template.ts
+export function renderReadme(opts) {
+    return `# Experiment: ${opts.experimentId}
+
+Created: ${opts.timestamp}
+Goal: ${opts.goal}
+
+## 目录说明
+- mission.md        — 实验意图（你来编辑）
+- eval-sets/        — 评测集（来自 MVP-B 或手动预置）
+- candidates/       — Agent 候选快照
+- outputs/          — 最终产物（bundle / manifest / provenance）
+- .trace-state/     — 运行态，勿手动编辑
+
+## 常用命令
+\`\`\`
+kweaver trace exp run .           — 启动 / 新开一轮
+kweaver trace exp resume .        — 从 Deciding 状态继续
+kweaver trace exp show .          — 查看当前状态和建议
+kweaver trace exp status .        — 一行摘要（适合脚本）
+kweaver trace exp abort .         — 优雅中止
+kweaver trace exp doctor .        — 环境自检
+\`\`\`
+`;
+}

package/dist/trace-ai/exp/exp-store/round-yaml.d.ts

@@ -0,0 +1,3 @@
+import type { RoundData } from "../schemas.js";
+export declare function writeRound(expDir: string, n: number, data: Partial<RoundData>): Promise<void>;
+export declare function readAllRounds(expDir: string): Promise<RoundData[]>;

package/dist/trace-ai/exp/exp-store/round-yaml.js

@@ -0,0 +1,33 @@
+// src/trace-ai/exp/exp-store/round-yaml.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+function roundPath(expDir, n) {
+    return path.join(expDir, ".trace-state", "rounds", `round-${n}.yaml`);
+}
+export async function writeRound(expDir, n, data) {
+    const p = roundPath(expDir, n);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    let existing = {};
+    try {
+        existing = yaml.load(await fs.readFile(p, "utf8"));
+    }
+    catch { }
+    const merged = { ...existing, round: n, ...data };
+    await fs.writeFile(p, yaml.dump(merged, { lineWidth: -1 }), "utf8");
+}
+export async function readAllRounds(expDir) {
+    const roundsDir = path.join(expDir, ".trace-state", "rounds");
+    try {
+        const files = await fs.readdir(roundsDir);
+        const rounds = [];
+        for (const f of files.filter(f => f.endsWith(".yaml")).sort()) {
+            const raw = await fs.readFile(path.join(roundsDir, f), "utf8");
+            rounds.push(yaml.load(raw));
+        }
+        return rounds;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,8 @@
+export interface ParsedExpArgs {
+    subcommand: "run" | "resume" | "show" | "status" | "abort" | "doctor" | "list" | "info";
+    expDir: string;
+    newRun?: boolean;
+    json?: boolean;
+}
+export declare function parseExpArgs(argv: string[]): ParsedExpArgs;
+export declare function runExpCommand(argv: string[]): Promise<number>;

package/dist/trace-ai/exp/index.js

@@ -0,0 +1,238 @@
+// src/trace-ai/exp/index.ts
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { ExpStore } from "./exp-store/index.js";
+import { ExperimentCoordinator } from "./coordinator.js";
+import { ClaudeCodeSynthesizer } from "./providers/synthesizer-client.js";
+import { ClaudeCodeTriageClient } from "./providers/triage-client.js";
+import { runEval } from "./eval-runner.js";
+import { defaultRegistry } from "../../agent-providers/registry.js";
+import { ClaudeCodeSubprocessProvider } from "../../agent-providers/providers/claude-code-subprocess.js";
+import { PromptTemplateRegistry } from "../../agent-providers/prompt-template.js";
+import { createBuiltinSemanticMatchProvider } from "../eval-set/semantic-match-provider.js";
+import { ensureValidToken } from "../../auth/oauth.js";
+import { fetchAgentInfo, sendChatRequest } from "../../api/agent-chat.js";
+import { getTracesByConversation } from "../../api/conversations.js";
+import { upsertRegistry, listRegistry } from "./exp-store/exp-registry.js";
+import { runInfo, runList, getHealthChecks } from "./info.js";
+import { resolveClaudeBinary } from "./claude-binary.js";
+const __expIndexDir = path.dirname(fileURLToPath(import.meta.url));
+const EVAL_SET_RUBRIC_DIR = path.join(__expIndexDir, "..", "eval-set", "rubric-templates");
+function ensureProvider() {
+    if (!defaultRegistry.has("claude-code")) {
+        defaultRegistry.register(new ClaudeCodeSubprocessProvider({
+            binary: resolveClaudeBinary(),
+            defaultTimeoutMs: 120_000,
+        }), { setAsDefault: true });
+    }
+}
+export function parseExpArgs(argv) {
+    const [sub, dir, ...flags] = argv;
+    const validSubs = ["run", "resume", "show", "status", "abort", "doctor", "list", "info"];
+    if (!validSubs.includes(sub)) {
+        throw new Error(`Unknown exp subcommand: ${sub}. Use: ${validSubs.join(", ")}`);
+    }
+    const isDiscoveryCmd = sub === "list" || sub === "info";
+    const expDir = isDiscoveryCmd
+        ? (dir ? path.resolve(dir) : "")
+        : path.resolve(dir ?? ".");
+    return {
+        subcommand: sub,
+        expDir,
+        newRun: flags.includes("--new-run"),
+        json: flags.includes("--json"),
+    };
+}
+export async function runExpCommand(argv) {
+    const args = parseExpArgs(argv);
+    switch (args.subcommand) {
+        case "list": {
+            if (args.expDir) {
+                await runList([{ path: args.expDir, last_active_ts: new Date().toISOString() }]);
+            }
+            else {
+                const entries = await listRegistry();
+                await runList(entries);
+            }
+            return 0;
+        }
+        case "info": {
+            let expDir = args.expDir;
+            if (!expDir) {
+                const entries = await listRegistry();
+                if (entries.length === 0) {
+                    process.stderr.write("Error: no experiments in registry. Run 'trace exp run <dir>' first, or provide a path: trace exp info <dir>\n");
+                    return 1;
+                }
+                expDir = entries[0].path;
+                process.stderr.write(`Using most recent: ${expDir}\n`);
+            }
+            await runInfo(expDir, { json: args.json });
+            return 0;
+        }
+        case "run": {
+            ensureProvider();
+            const store = new ExpStore(args.expDir);
+            const replayed = await store.replayState();
+            if (!replayed.isTerminal && replayed.currentRound > 0 && !replayed.lastFailure) {
+                process.stderr.write(`Error: experiment in progress (state: ${replayed.currentState}). Use exp resume.\n`);
+                return 2;
+            }
+            if (replayed.isTerminal && !args.newRun) {
+                process.stderr.write(`Error: experiment already in terminal state ${replayed.currentState}. Use --new-run to start fresh.\n`);
+                return 2;
+            }
+            if (replayed.isTerminal && args.newRun) {
+                await store.archiveState();
+            }
+            await upsertRegistry(args.expDir, new Date().toISOString());
+            const coord = await makeCoordinator(args.expDir);
+            await coord.run();
+            return 0;
+        }
+        case "resume": {
+            ensureProvider();
+            const store = new ExpStore(args.expDir);
+            const replayed = await store.replayState();
+            if (replayed.currentState !== "Deciding") {
+                process.stderr.write(`Error: cannot resume — experiment is in state ${replayed.currentState}. Only Deciding state supports resume.\n`);
+                return 2;
+            }
+            await upsertRegistry(args.expDir, new Date().toISOString());
+            const coord = await makeCoordinator(args.expDir);
+            await coord.resume();
+            return 0;
+        }
+        case "show": {
+            const store = new ExpStore(args.expDir);
+            const replayed = await store.replayState();
+            const rounds = await store.readAllRounds();
+            const lineage = await store.readLineage();
+            const mission = await store.readMission().catch(() => null);
+            process.stdout.write(`State: ${replayed.currentState}  Round: ${replayed.currentRound}\n`);
+            if (mission?.next_change) {
+                process.stdout.write(`Suggested next change:\n  target: ${mission.next_change.target}\n  hypothesis: ${mission.next_change.hypothesis}\n`);
+            }
+            if (rounds.length > 0) {
+                const last = rounds[rounds.length - 1];
+                process.stdout.write(`Last round scores: outcome=${last.scores?.outcome.toFixed(2) ?? "?"}, trajectory=${last.scores?.trajectory.toFixed(2) ?? "?"}\n`);
+                if (last.triage_conclusion) {
+                    process.stdout.write(`Triage: ${last.triage_conclusion.diagnoses.join("; ")}\n`);
+                }
+            }
+            process.stdout.write(`Lineage: ${lineage.length} versions\n`);
+            return 0;
+        }
+        case "status": {
+            const store = new ExpStore(args.expDir);
+            const replayed = await store.replayState();
+            process.stdout.write(`${args.expDir}: ${replayed.currentState} (round ${replayed.currentRound})\n`);
+            return 0;
+        }
+        case "abort": {
+            const store = new ExpStore(args.expDir);
+            await store.writeAbortSignal();
+            process.stdout.write(`Abort signal written. Running process will stop at next checkpoint.\n`);
+            return 0;
+        }
+        case "doctor": {
+            const store = new ExpStore(args.expDir);
+            return runDoctor(args.expDir, store);
+        }
+    }
+}
+async function runDoctor(expDir, store) {
+    let ok = true;
+    const check = (label, pass, msg) => {
+        process.stdout.write(`${pass ? "✓" : "✗"} ${label}${pass ? "" : `: ${msg}`}\n`);
+        if (!pass)
+            ok = false;
+    };
+    try {
+        const mission = await store.readMission();
+        check("mission.md valid", true, "");
+        for (const es of mission.eval_sets) {
+            const esPath = path.join(expDir, es.path);
+            try {
+                await fs.access(esPath);
+                check(`eval_set ${es.path}`, true, "");
+            }
+            catch {
+                check(`eval_set ${es.path}`, false, `not found: ${esPath}`);
+            }
+        }
+        const candPath = path.join(expDir, mission.current_candidate.path);
+        try {
+            await fs.access(candPath);
+            check("current_candidate readable", true, "");
+        }
+        catch {
+            check("current_candidate readable", false, `not found: ${candPath}`);
+        }
+    }
+    catch (e) {
+        check("mission.md valid", false, String(e));
+    }
+    const health = await getHealthChecks(expDir);
+    check("claude-code provider available", health.provider_available, "run: npx @anthropic-ai/claude-code --version");
+    check("no step_failed in events", health.no_step_failed, "step_failed found in events.jsonl");
+    return ok ? 0 : 1;
+}
+async function makeCoordinator(expDir) {
+    let baseUrl = process.env["KWEAVER_BASE_URL"] ?? "";
+    let token = process.env["KWEAVER_TOKEN"] ?? "";
+    const bd = process.env["KWEAVER_BUSINESS_DOMAIN"] ?? "bd_public";
+    if (!baseUrl || !token) {
+        const t = await ensureValidToken();
+        if (!baseUrl)
+            baseUrl = t.baseUrl;
+        if (!token)
+            token = t.accessToken;
+    }
+    let semanticMatchProvider;
+    try {
+        const provider = defaultRegistry.resolve({ requiredCapabilities: ["structured_output"] });
+        if (provider && (await provider.isAvailable())) {
+            const promptRegistry = new PromptTemplateRegistry();
+            await promptRegistry.loadBuiltinDir(EVAL_SET_RUBRIC_DIR);
+            semanticMatchProvider = createBuiltinSemanticMatchProvider({ provider, promptRegistry, lang: "zh" });
+        }
+    }
+    catch {
+        process.stderr.write("warn: could not create semantic-match provider — semantic_match assertions will be skipped\n");
+    }
+    return new ExperimentCoordinator({
+        expDir,
+        synthesizer: new ClaudeCodeSynthesizer(),
+        triage: new ClaudeCodeTriageClient(),
+        runEval: ({ evalSetPaths, candidatePath, round }) => runEval({
+            evalSetPaths,
+            candidatePath,
+            expDir,
+            round,
+            maxParallel: 2,
+            deps: {
+                fetchAgent: async (agentId) => fetchAgentInfo({ baseUrl, accessToken: token, agentId, version: "latest", businessDomain: bd }),
+                sendChat: async ({ agentInfo, query }) => {
+                    const result = await sendChatRequest({
+                        baseUrl,
+                        accessToken: token,
+                        agentId: agentInfo.id,
+                        agentKey: agentInfo.key,
+                        agentVersion: agentInfo.version,
+                        query,
+                        stream: true,
+                        businessDomain: bd,
+                    });
+                    return { text: result.text, conversationId: result.conversationId };
+                },
+                fetchTrace: async (conversationId) => {
+                    const r = await getTracesByConversation({ baseUrl, accessToken: token, conversationId, businessDomain: bd });
+                    return { spans: r.spans };
+                },
+                semanticMatchProvider,
+            },
+        }),
+    });
+}

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

@@ -0,0 +1,35 @@
+import type { ThreeAxisScores } from "./schemas.js";
+export interface HealthChecks {
+    mission_valid: boolean;
+    eval_set_valid: boolean;
+    candidate_readable: boolean;
+    provider_available: boolean;
+    no_step_failed: boolean;
+}
+export interface ExpSnapshot {
+    workspace: string;
+    state: string;
+    round: number;
+    scores: ThreeAxisScores | null;
+    triage_summary: string | null;
+    suggested_next: {
+        target: string;
+        hypothesis: string;
+    } | null;
+    lineage_versions: number;
+    health: HealthChecks;
+}
+export declare function getHealthChecks(expDir: string): Promise<HealthChecks>;
+export declare function buildExpSnapshot(expDir: string): Promise<ExpSnapshot>;
+export declare function formatSnapshotYaml(snap: ExpSnapshot): string;
+export declare function formatSnapshotTableRow(entry: {
+    path: string;
+    last_active_ts: string;
+}, snap: ExpSnapshot | null): string;
+export declare function runInfo(expDir: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function runList(registryEntries: Array<{
+    path: string;
+    last_active_ts: string;
+}>): Promise<void>;

package/dist/trace-ai/exp/info.js

@@ -0,0 +1,120 @@
+// src/trace-ai/exp/info.ts
+import path from "node:path";
+import fs from "node:fs/promises";
+import yaml from "js-yaml";
+import { ExpStore } from "./exp-store/index.js";
+import { defaultRegistry } from "../../agent-providers/registry.js";
+export async function getHealthChecks(expDir) {
+    const store = new ExpStore(expDir);
+    let mission_valid = false;
+    let eval_set_valid = false;
+    let candidate_readable = false;
+    try {
+        const mission = await store.readMission();
+        mission_valid = true;
+        let allEvalSetsOk = true;
+        for (const es of mission.eval_sets) {
+            try {
+                await fs.access(path.join(expDir, es.path));
+            }
+            catch {
+                allEvalSetsOk = false;
+            }
+        }
+        eval_set_valid = allEvalSetsOk;
+        try {
+            await fs.access(path.join(expDir, mission.current_candidate.path));
+            candidate_readable = true;
+        }
+        catch {
+            candidate_readable = false;
+        }
+    }
+    catch { /* mission_valid stays false */ }
+    let provider_available = false;
+    try {
+        provider_available = defaultRegistry.resolve({ preferred: "claude-code" }) !== null;
+    }
+    catch {
+        provider_available = false;
+    }
+    const replayed = await store.replayState();
+    const no_step_failed = replayed.lastFailure === null;
+    return { mission_valid, eval_set_valid, candidate_readable, provider_available, no_step_failed };
+}
+export async function buildExpSnapshot(expDir) {
+    // Throw early if the experiment directory doesn't exist, so callers (e.g.
+    // runList) can catch and render a "(missing)" row instead of returning a
+    // phantom "Init" snapshot for a non-existent path.
+    await fs.access(expDir);
+    const store = new ExpStore(expDir);
+    const replayed = await store.replayState();
+    const rounds = await store.readAllRounds();
+    const lineage = await store.readLineage();
+    const mission = await store.readMission().catch(() => null);
+    const health = await getHealthChecks(expDir);
+    const lastRound = rounds.length > 0 ? rounds[rounds.length - 1] : null;
+    const scores = lastRound?.scores ?? null;
+    const triage_summary = lastRound?.triage_conclusion?.diagnoses.join("; ") ?? null;
+    const suggested_next = mission?.next_change
+        ? { target: mission.next_change.target, hypothesis: mission.next_change.hypothesis }
+        : null;
+    return {
+        workspace: expDir,
+        state: replayed.currentState,
+        round: replayed.currentRound,
+        scores: scores ?? null,
+        triage_summary,
+        suggested_next,
+        lineage_versions: lineage.length,
+        health,
+    };
+}
+export function formatSnapshotYaml(snap) {
+    return yaml.dump(snap, { lineWidth: -1 });
+}
+export function formatSnapshotTableRow(entry, snap) {
+    if (snap === null) {
+        return [entry.path.padEnd(50), "(missing)"].join("  ");
+    }
+    const outcome = snap.scores?.outcome.toFixed(2) ?? "-";
+    const trajectory = snap.scores?.trajectory.toFixed(2) ?? "-";
+    const lastActive = entry.last_active_ts.replace("T", " ").slice(0, 19);
+    return [
+        entry.path.padEnd(50),
+        snap.state.padEnd(12),
+        String(snap.round).padEnd(6),
+        outcome.padEnd(8),
+        trajectory.padEnd(10),
+        lastActive,
+    ].join("  ");
+}
+export async function runInfo(expDir, opts = {}) {
+    const snap = await buildExpSnapshot(expDir);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(snap, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(formatSnapshotYaml(snap));
+    }
+}
+export async function runList(registryEntries) {
+    const header = [
+        "PATH".padEnd(50),
+        "STATE".padEnd(12),
+        "ROUND".padEnd(6),
+        "OUTCOME".padEnd(8),
+        "TRAJECTORY".padEnd(10),
+        "LAST_ACTIVE",
+    ].join("  ");
+    process.stdout.write(header + "\n");
+    process.stdout.write("-".repeat(header.length) + "\n");
+    for (const entry of registryEntries) {
+        let snap = null;
+        try {
+            snap = await buildExpSnapshot(entry.path);
+        }
+        catch { /* missing path */ }
+        process.stdout.write(formatSnapshotTableRow(entry, snap) + "\n");
+    }
+}

package/dist/trace-ai/exp/patch/agent-config.d.ts

@@ -0,0 +1 @@
+export declare function applyAgentConfigPatch(candidate: Record<string, unknown>, patchJson: string): Record<string, unknown>;

package/dist/trace-ai/exp/patch/agent-config.js

@@ -0,0 +1,26 @@
+// src/trace-ai/exp/patch/agent-config.ts
+export function applyAgentConfigPatch(candidate, patchJson) {
+    const patch = JSON.parse(patchJson);
+    if (!patch.agent)
+        throw new Error("agent.* patch must have an 'agent' key");
+    // Only the agent sub-tree is patched; extra top-level keys in patchJson are intentionally ignored.
+    // Callers should scope patch JSON to { agent: { ... } } only.
+    const result = structuredClone(candidate);
+    result["agent"] = mergePatch(result["agent"], patch["agent"]);
+    return result;
+}
+function mergePatch(target, patch) {
+    const result = { ...target };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null) {
+            delete result[k];
+        }
+        else if (typeof v === "object" && !Array.isArray(v)) {
+            result[k] = mergePatch(result[k] ?? {}, v);
+        }
+        else {
+            result[k] = v;
+        }
+    }
+    return result;
+}

package/dist/trace-ai/exp/patch/index.d.ts

@@ -0,0 +1,2 @@
+import type { NextChange } from "../schemas.js";
+export declare function applyPatch(candidate: Record<string, unknown>, change: NextChange): Record<string, unknown>;

package/dist/trace-ai/exp/patch/index.js

@@ -0,0 +1,13 @@
+import { applyAgentConfigPatch } from "./agent-config.js";
+import { applySkillPatch } from "./skill.js";
+export function applyPatch(candidate, change) {
+    const prefix = change.target.split(".")[0];
+    switch (prefix) {
+        case "agent":
+            return applyAgentConfigPatch(candidate, change.patch);
+        case "skill":
+            return applySkillPatch(candidate, change.patch);
+        default:
+            throw new Error(`Unsupported target prefix "${prefix}" — only agent.* and skill.* are supported in MVP-C`);
+    }
+}

package/dist/trace-ai/exp/patch/skill.d.ts

@@ -0,0 +1 @@
+export declare function applySkillPatch(candidate: Record<string, unknown>, patchJson: string): Record<string, unknown>;

package/dist/trace-ai/exp/patch/skill.js

@@ -0,0 +1,24 @@
+export function applySkillPatch(candidate, patchJson) {
+    const patch = JSON.parse(patchJson);
+    if (!patch.skills)
+        throw new Error("skill.* patch must have a 'skills' key");
+    const result = structuredClone(candidate);
+    let skills = result["skills"] ?? [];
+    // Order is significant: remove → add → swap
+    if (patch.skills.remove) {
+        const toRemove = new Set(patch.skills.remove);
+        skills = skills.filter(s => !toRemove.has(s.name));
+    }
+    if (patch.skills.add) {
+        skills = [...skills, ...patch.skills.add];
+    }
+    if (patch.skills.swap) {
+        const { from, to } = patch.skills.swap;
+        const matched = skills.some(s => s.name === from);
+        if (!matched)
+            throw new Error(`skill.swap: skill "${from}" not found in candidate`);
+        skills = skills.map(s => s.name === from ? to : s);
+    }
+    result["skills"] = skills;
+    return result;
+}

package/dist/trace-ai/exp/providers/synthesizer-client.d.ts

@@ -0,0 +1,14 @@
+import type { Mission, NextChange, RoundData } from "../schemas.js";
+export interface SynthesizerInput {
+    mission: Mission;
+    candidateConfig: Record<string, unknown>;
+    prevRound?: RoundData;
+    prevRounds: RoundData[];
+    crossRoundMemoryRef?: string;
+}
+export interface SynthesizerClient {
+    generate(input: SynthesizerInput): Promise<NextChange>;
+}
+export declare class ClaudeCodeSynthesizer implements SynthesizerClient {
+    generate(input: SynthesizerInput): Promise<NextChange>;
+}

package/dist/trace-ai/exp/providers/synthesizer-client.js

@@ -0,0 +1,39 @@
+// src/trace-ai/exp/providers/synthesizer-client.ts
+import yaml from "js-yaml";
+import { defaultRegistry } from "../../../agent-providers/registry.js";
+import { NextChangeSchema } from "../schemas.js";
+export class ClaudeCodeSynthesizer {
+    async generate(input) {
+        const provider = defaultRegistry.resolve({ preferred: "claude-code" });
+        if (!provider)
+            throw new Error("claude-code provider not available");
+        const prevSummary = input.prevRounds.map(r => `Round ${r.round}: outcome=${r.scores?.outcome.toFixed(2) ?? "?"}, hints=${r.triage_conclusion?.hints.join("; ") ?? "none"}`).join("\n");
+        const prompt = `You are an agent optimization assistant. Given an experiment goal and round results, suggest the next change to try.
+
+GOAL: ${input.mission.goal}
+
+CURRENT CANDIDATE CONFIG:
+${yaml.dump(input.candidateConfig, { lineWidth: 80 })}
+
+PREVIOUS ROUNDS:
+${prevSummary || "None (first round)"}
+
+${input.prevRound?.triage_conclusion ? `TRIAGE HINTS FROM LAST ROUND:\n${input.prevRound.triage_conclusion.hints.join("\n")}` : ""}
+
+${input.crossRoundMemoryRef ? `CROSS-ROUND CONTEXT: ${input.crossRoundMemoryRef}` : ""}
+
+Respond with a JSON object with exactly these fields:
+- "target": one of "agent.system_prompt", "agent.temperature", "agent.model", "skill.add", "skill.remove", "skill.swap"
+- "hypothesis": brief explanation of why this change might help
+- "patch": a JSON Merge Patch string to apply to the candidate config
+
+Example for changing system_prompt:
+{"target": "agent.system_prompt", "hypothesis": "Add explicit stop condition", "patch": "{\"agent\":{\"system_prompt\":\"New prompt here\"}}"}`;
+        const response = await provider.invoke({
+            prompt,
+            outputSchema: NextChangeSchema,
+            correlationId: `synthesizer-${Date.now()}`,
+        });
+        return response.output;
+    }
+}

package/dist/trace-ai/exp/providers/triage-client.d.ts

@@ -0,0 +1,19 @@
+import type { RoundData } from "../schemas.js";
+export interface TriageInput {
+    currentRound: RoundData;
+    prevRounds: RoundData[];
+    candidateConfig: Record<string, unknown>;
+    crossRoundMemoryRef?: string;
+}
+export interface TriageResult {
+    diagnoses: string[];
+    hints: string[];
+    verdict: "continue" | "publish";
+    new_memory_token: string;
+}
+export interface TriageClient {
+    triage(input: TriageInput): Promise<TriageResult>;
+}
+export declare class ClaudeCodeTriageClient implements TriageClient {
+    triage(input: TriageInput): Promise<TriageResult>;
+}