@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/trace-ai/exp/exp-store/candidate-lineage-yaml.js

@@ -0,0 +1,37 @@
+// src/trace-ai/exp/exp-store/candidate-lineage-yaml.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+function lineagePath(expDir) {
+    return path.join(expDir, ".trace-state", "candidate-lineage.yaml");
+}
+export async function appendLineage(expDir, entry) {
+    const p = lineagePath(expDir);
+    let entries = [];
+    try {
+        entries = yaml.load(await fs.readFile(p, "utf8")) ?? [];
+    }
+    catch { }
+    entries.push({ ...entry, appended_at: new Date().toISOString() });
+    await fs.writeFile(p, yaml.dump(entries, { lineWidth: -1 }), "utf8");
+}
+export async function updateLineage(expDir, version, patch) {
+    const p = lineagePath(expDir);
+    let entries = [];
+    try {
+        entries = yaml.load(await fs.readFile(p, "utf8")) ?? [];
+    }
+    catch { }
+    const idx = entries.findIndex(e => e.version === version);
+    if (idx >= 0)
+        Object.assign(entries[idx], patch);
+    await fs.writeFile(p, yaml.dump(entries, { lineWidth: -1 }), "utf8");
+}
+export async function readLineage(expDir) {
+    try {
+        return yaml.load(await fs.readFile(lineagePath(expDir), "utf8")) ?? [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/trace-ai/exp/exp-store/events-jsonl.d.ts

@@ -0,0 +1,17 @@
+import type { ExpEvent, ExpFsmState } from "../schemas.js";
+export type EventInput = ExpEvent extends infer T ? T extends {
+    ts: string;
+} ? Omit<T, "ts"> : never : never;
+export declare function appendEvent(expDir: string, event: EventInput): Promise<void>;
+export interface ReplayedState {
+    currentState: ExpFsmState;
+    currentRound: number;
+    lastEvent: ExpEvent | null;
+    lastFailure: {
+        state: ExpFsmState;
+        error: string;
+        retryable: boolean;
+    } | null;
+    isTerminal: boolean;
+}
+export declare function replayState(expDir: string): Promise<ReplayedState>;

package/dist/trace-ai/exp/exp-store/events-jsonl.js

@@ -0,0 +1,60 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function appendEvent(expDir, event) {
+    const filePath = path.join(expDir, ".trace-state", "events.jsonl");
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) + "\n";
+    await fs.appendFile(filePath, line, "utf8");
+}
+const TERMINAL = new Set(["Published", "Aborted"]);
+export async function replayState(expDir) {
+    const filePath = path.join(expDir, ".trace-state", "events.jsonl");
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return { currentState: "Init", currentRound: 0, lastEvent: null, lastFailure: null, isTerminal: false };
+    }
+    const lines = raw.split("\n").filter(Boolean);
+    if (lines.length === 0) {
+        return { currentState: "Init", currentRound: 0, lastEvent: null, lastFailure: null, isTerminal: false };
+    }
+    let currentState = "Init";
+    let currentRound = 0;
+    let lastEvent = null;
+    let lastFailure = null;
+    for (const line of lines) {
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            // Skip malformed lines (e.g. from a crash mid-write) rather than bricking replay.
+            process.stderr.write(`[warn] events.jsonl: skipping malformed line: ${line.slice(0, 120)}\n`);
+            continue;
+        }
+        lastEvent = ev;
+        if (ev.type === "state_transition") {
+            currentState = ev.to;
+            currentRound = ev.round;
+            lastFailure = null;
+        }
+        else if (ev.type === "step_failed") {
+            currentState = ev.state;
+            lastFailure = { state: ev.state, error: ev.error, retryable: ev.retryable };
+        }
+        else if (ev.type === "aborted") {
+            currentState = "Aborted";
+        }
+        else if (ev.type === "round_completed") {
+            currentRound = ev.round;
+        }
+    }
+    return {
+        currentState,
+        currentRound,
+        lastEvent,
+        lastFailure,
+        isTerminal: TERMINAL.has(currentState),
+    };
+}

package/dist/trace-ai/exp/exp-store/exp-registry.d.ts

@@ -0,0 +1,6 @@
+export interface RegistryEntry {
+    path: string;
+    last_active_ts: string;
+}
+export declare function upsertRegistry(absPath: string, ts: string): Promise<void>;
+export declare function listRegistry(): Promise<RegistryEntry[]>;

package/dist/trace-ai/exp/exp-store/exp-registry.js

@@ -0,0 +1,41 @@
+// src/trace-ai/exp/exp-store/exp-registry.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getConfigDir } from "../../../config/store.js";
+function registryFilePath() {
+    return path.join(getConfigDir(), "exp-registry.json");
+}
+async function readRegistry() {
+    try {
+        const raw = await fs.readFile(registryFilePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.entries))
+            return { schema_version: "exp-registry/v1", entries: [] };
+        return parsed;
+    }
+    catch {
+        return { schema_version: "exp-registry/v1", entries: [] };
+    }
+}
+export async function upsertRegistry(absPath, ts) {
+    try {
+        const reg = await readRegistry();
+        const idx = reg.entries.findIndex((e) => e.path === absPath);
+        if (idx >= 0) {
+            reg.entries[idx].last_active_ts = ts;
+        }
+        else {
+            reg.entries.push({ path: absPath, last_active_ts: ts });
+        }
+        const filePath = registryFilePath();
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(reg, null, 2) + "\n", "utf8");
+    }
+    catch (e) {
+        process.stderr.write(`warn: exp-registry write failed: ${e instanceof Error ? e.message : String(e)}\n`);
+    }
+}
+export async function listRegistry() {
+    const reg = await readRegistry();
+    return [...reg.entries].sort((a, b) => b.last_active_ts.localeCompare(a.last_active_ts));
+}

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

@@ -0,0 +1,46 @@
+import type { LineageEntry, Mission, NextChange, RoundData } from "../schemas.js";
+import { type ReplayedState, type EventInput } from "./events-jsonl.js";
+export { type ReplayedState };
+export declare class ExpStore {
+    readonly expDir: string;
+    constructor(expDir: string);
+    initDir(mission: Mission): Promise<string>;
+    archiveState(): Promise<void>;
+    readMission: () => Promise<{
+        schema_version: "trace-mission/v1";
+        goal: string;
+        eval_sets: {
+            path: string;
+            role: "seed" | "regression" | "holdout";
+        }[];
+        current_candidate: {
+            path: string;
+        };
+        max_rounds?: number | undefined;
+        provider?: string | undefined;
+        next_change?: {
+            target: string;
+            hypothesis: string;
+            patch: string;
+        } | undefined;
+        guardrails?: {
+            name: string;
+            kind: "hard" | "soft";
+            rule: string;
+        }[] | undefined;
+    }>;
+    writeSuggestedChange: (c: NextChange) => Promise<void>;
+    appendEvent: (e: EventInput) => Promise<void>;
+    replayState: () => Promise<ReplayedState>;
+    acquireLock: () => Promise<void>;
+    releaseLock: () => Promise<void>;
+    updateHeartbeat: () => Promise<void>;
+    isAborted: () => Promise<boolean>;
+    writeAbortSignal: () => Promise<void>;
+    clearAbortSignal: () => Promise<void>;
+    writeRound: (n: number, data: Partial<RoundData>) => Promise<void>;
+    readAllRounds: () => Promise<RoundData[]>;
+    appendLineage: (e: Omit<LineageEntry, "appended_at">) => Promise<void>;
+    updateLineage: (v: number, p: Partial<LineageEntry>) => Promise<void>;
+    readLineage: () => Promise<LineageEntry[]>;
+}

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

@@ -0,0 +1,59 @@
+// src/trace-ai/exp/exp-store/index.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { readMission, writeSuggestedChange } from "./mission-md.js";
+import { appendEvent, replayState } from "./events-jsonl.js";
+import { acquireLock, releaseLock, updateHeartbeat } from "./lock.js";
+import { isAborted, writeAbortSignal, clearAbortSignal } from "./abort-signal.js";
+import { writeRound, readAllRounds } from "./round-yaml.js";
+import { appendLineage, updateLineage, readLineage } from "./candidate-lineage-yaml.js";
+import { renderReadme } from "./readme-template.js";
+export class ExpStore {
+    expDir;
+    constructor(expDir) {
+        this.expDir = expDir;
+    }
+    async initDir(mission) {
+        const experimentId = `exp_${crypto.randomBytes(4).toString("hex")}`;
+        await fs.mkdir(path.join(this.expDir, ".trace-state", "rounds"), { recursive: true });
+        await fs.mkdir(path.join(this.expDir, "candidates"), { recursive: true });
+        await fs.mkdir(path.join(this.expDir, "eval-sets"), { recursive: true });
+        await fs.mkdir(path.join(this.expDir, "outputs"), { recursive: true });
+        await fs.writeFile(path.join(this.expDir, ".trace-state", "events.jsonl"), "", { flag: "wx" }).catch(() => { }); // already exists ok
+        const readmePath = path.join(this.expDir, "README.md");
+        try {
+            await fs.access(readmePath);
+        }
+        catch {
+            await fs.writeFile(readmePath, renderReadme({
+                experimentId,
+                timestamp: new Date().toISOString(),
+                goal: mission.goal,
+            }));
+        }
+        return experimentId;
+    }
+    async archiveState() {
+        const src = path.join(this.expDir, ".trace-state");
+        const dst = path.join(this.expDir, `.trace-state-archived-${Date.now()}`);
+        await fs.rename(src, dst);
+        await fs.mkdir(path.join(this.expDir, ".trace-state", "rounds"), { recursive: true });
+        await fs.writeFile(path.join(this.expDir, ".trace-state", "events.jsonl"), "");
+    }
+    readMission = () => readMission(this.expDir);
+    writeSuggestedChange = (c) => writeSuggestedChange(this.expDir, c);
+    appendEvent = (e) => appendEvent(this.expDir, e);
+    replayState = () => replayState(this.expDir);
+    acquireLock = () => acquireLock(this.expDir);
+    releaseLock = () => releaseLock(this.expDir);
+    updateHeartbeat = () => updateHeartbeat(this.expDir);
+    isAborted = () => isAborted(this.expDir);
+    writeAbortSignal = () => writeAbortSignal(this.expDir);
+    clearAbortSignal = () => clearAbortSignal(this.expDir);
+    writeRound = (n, data) => writeRound(this.expDir, n, data);
+    readAllRounds = () => readAllRounds(this.expDir);
+    appendLineage = (e) => appendLineage(this.expDir, e);
+    updateLineage = (v, p) => updateLineage(this.expDir, v, p);
+    readLineage = () => readLineage(this.expDir);
+}

package/dist/trace-ai/exp/exp-store/lock.d.ts

@@ -0,0 +1,3 @@
+export declare function acquireLock(expDir: string): Promise<void>;
+export declare function releaseLock(expDir: string): Promise<void>;
+export declare function updateHeartbeat(expDir: string): Promise<void>;

package/dist/trace-ai/exp/exp-store/lock.js

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const STALE_THRESHOLD_MS = 30_000;
+function lockPath(expDir) {
+    return path.join(expDir, ".trace-state", "lock.json");
+}
+export async function acquireLock(expDir) {
+    const p = lockPath(expDir);
+    const lock = {
+        hostname: os.hostname(),
+        pid: process.pid,
+        started_at: new Date().toISOString(),
+        last_heartbeat_ts: new Date().toISOString(),
+    };
+    const data = JSON.stringify(lock, null, 2);
+    // O_EXCL: atomic create — fails with EEXIST if a lock file already exists.
+    try {
+        await fs.writeFile(p, data, { encoding: "utf8", flag: "wx" });
+        return;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    // Lock file exists — check freshness.
+    let existing;
+    try {
+        existing = JSON.parse(await fs.readFile(p, "utf8"));
+    }
+    catch {
+        // Unreadable lock (e.g. partial write) — treat as stale.
+        existing = { hostname: "", pid: 0, started_at: "", last_heartbeat_ts: new Date(0).toISOString() };
+    }
+    const age = Date.now() - new Date(existing.last_heartbeat_ts).getTime();
+    if (age < STALE_THRESHOLD_MS) {
+        throw new Error(`Experiment is locked by pid ${existing.pid} on ${existing.hostname} (heartbeat ${Math.floor(age / 1000)}s ago). Use exp resume or wait.`);
+    }
+    // Stale — unlink then retry O_EXCL. If another process beats us here, we'll
+    // get EEXIST again and throw a clear error rather than silently overwriting.
+    await fs.unlink(p).catch(() => { });
+    try {
+        await fs.writeFile(p, data, { encoding: "utf8", flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            throw new Error("Lock acquired by another process during stale recovery. Try again.");
+        }
+        throw err;
+    }
+}
+export async function releaseLock(expDir) {
+    try {
+        await fs.unlink(lockPath(expDir));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+export async function updateHeartbeat(expDir) {
+    const p = lockPath(expDir);
+    try {
+        const raw = await fs.readFile(p, "utf8");
+        const lock = JSON.parse(raw);
+        lock.last_heartbeat_ts = new Date().toISOString();
+        await fs.writeFile(p, JSON.stringify(lock, null, 2), "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}

package/dist/trace-ai/exp/exp-store/mission-md.d.ts

@@ -0,0 +1,3 @@
+import { type Mission, type NextChange } from "../schemas.js";
+export declare function readMission(expDir: string): Promise<Mission>;
+export declare function writeSuggestedChange(expDir: string, change: NextChange): Promise<void>;

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