@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

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

@@ -0,0 +1,203 @@
+// src/trace-ai/exp/coordinator.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 { applyPatch } from "./patch/index.js";
+import { computeScores } from "./scoring.js";
+import { writeBundles } from "./bundle-writer.js";
+export class ExperimentCoordinator {
+    opts;
+    store;
+    heartbeatTimer;
+    constructor(opts) {
+        this.opts = opts;
+        this.store = new ExpStore(opts.expDir);
+    }
+    async run() {
+        const replayed = await this.store.replayState();
+        if (replayed.isTerminal && !replayed.currentState.includes("Aborted")) {
+            throw new Error(`Experiment is in terminal state ${replayed.currentState}. Use --new-run to start fresh.`);
+        }
+        const mission = await this.store.readMission();
+        const expId = this.opts.experimentId ?? `exp_${Date.now()}`;
+        if (replayed.currentRound === 0) {
+            await this.store.initDir(mission);
+        }
+        await this.store.acquireLock();
+        this.heartbeatTimer = setInterval(() => { void this.store.updateHeartbeat(); }, 10_000);
+        // If previous run failed mid-round, retry that round (startRound = currentRound - 1)
+        const startRound = replayed.lastFailure && replayed.currentRound > 0
+            ? replayed.currentRound - 1
+            : replayed.currentRound;
+        try {
+            await this.runLoop(mission, startRound, expId);
+        }
+        finally {
+            clearInterval(this.heartbeatTimer);
+            await this.store.releaseLock();
+        }
+    }
+    async resume() {
+        const replayed = await this.store.replayState();
+        if (replayed.currentState !== "Deciding") {
+            throw new Error(`Cannot resume: experiment is in state ${replayed.currentState}, not Deciding. Only Deciding state supports resume.`);
+        }
+        await this.store.acquireLock();
+        this.heartbeatTimer = setInterval(() => { void this.store.updateHeartbeat(); }, 10_000);
+        try {
+            const mission = await this.store.readMission();
+            const expId = `exp_${replayed.currentRound}`;
+            await this.runLoop(mission, replayed.currentRound, expId);
+        }
+        finally {
+            clearInterval(this.heartbeatTimer);
+            await this.store.releaseLock();
+        }
+    }
+    async runLoop(mission, startRound, expId) {
+        const round = startRound + 1;
+        const maxRounds = mission.max_rounds ?? Infinity;
+        if (await this.checkAbort(round))
+            return;
+        // === Generating (Apply Phase) ===
+        await this.store.appendEvent({ type: "state_transition", from: "Deciding", to: "Generating", round });
+        const nextChange = mission.next_change;
+        if (!nextChange)
+            throw new Error("mission.md has no next_change — add one or let Synthesizer suggest");
+        const prevRounds = await this.store.readAllRounds();
+        // Load current candidate and apply patch
+        const currentCandidatePath = path.join(this.opts.expDir, mission.current_candidate.path);
+        const currentCandidate = yaml.load(await fs.readFile(currentCandidatePath, "utf8"));
+        const patched = applyPatch(currentCandidate, nextChange);
+        patched["candidate_version"] = `v${round}`;
+        const newCandidatePath = path.join(this.opts.expDir, "candidates", `candidate-v${round}.yaml`);
+        await fs.writeFile(newCandidatePath, yaml.dump(patched, { lineWidth: -1 }));
+        await this.store.appendLineage({
+            version: round,
+            candidate_path: `candidates/candidate-v${round}.yaml`,
+            next_change: nextChange,
+            status: "running",
+        });
+        if (await this.checkAbort(round))
+            return;
+        // === Executing ===
+        await this.store.appendEvent({ type: "state_transition", from: "Generating", to: "Executing", round });
+        const evalSetPaths = mission.eval_sets.map(e => path.join(this.opts.expDir, e.path));
+        let queryResults;
+        try {
+            const result = await this.withRetry(() => this.opts.runEval({ evalSetPaths, candidatePath: newCandidatePath, expDir: this.opts.expDir, round }), "Executing");
+            queryResults = result.queryResults;
+        }
+        catch {
+            return; // step_failed already written by withRetry
+        }
+        if (await this.checkAbort(round))
+            return;
+        // === Scoring ===
+        await this.store.appendEvent({ type: "state_transition", from: "Executing", to: "Scoring", round });
+        const guardrails = mission.guardrails ?? [];
+        const scores = computeScores(queryResults, guardrails);
+        if (scores.guardrail_hard_fail) {
+            await this.store.updateLineage(round, { status: "guardrail_failed" });
+            await this.store.writeRound(round, { round, trial_version: round, guardrail_failed: true, scores });
+            await this.store.appendEvent({ type: "state_transition", from: "Scoring", to: "Deciding", round });
+            process.stdout.write(`\nRound ${round}: Guardrail hard gate violated. Fix the candidate and run exp resume.\n`);
+            return;
+        }
+        await this.store.updateLineage(round, { status: "scored" });
+        await this.store.writeRound(round, { round, trial_version: round, scores, per_query_results: queryResults });
+        if (await this.checkAbort(round))
+            return;
+        // === Triaging ===
+        await this.store.appendEvent({ type: "state_transition", from: "Scoring", to: "Triaging", round });
+        const currentRoundData = (await this.store.readAllRounds()).find(r => r.round === round) ?? { round, trial_version: round };
+        const prevMemory = prevRounds.at(-1)?.triage_conclusion?.cross_round_memory_ref;
+        let triageResult;
+        try {
+            triageResult = await this.withRetry(() => this.opts.triage.triage({
+                currentRound: currentRoundData,
+                prevRounds,
+                candidateConfig: patched,
+                crossRoundMemoryRef: prevMemory,
+            }), "Triaging");
+        }
+        catch {
+            return;
+        }
+        await this.store.writeRound(round, {
+            triage_conclusion: {
+                diagnoses: triageResult.diagnoses,
+                hints: triageResult.hints,
+                verdict: triageResult.verdict,
+                cross_round_memory_ref: triageResult.new_memory_token,
+            },
+        });
+        await this.store.appendEvent({ type: "round_completed", round, verdict: triageResult.verdict });
+        // Generate next suggestion if continuing
+        if (triageResult.verdict === "continue" && round < maxRounds) {
+            const updatedMission = await this.store.readMission();
+            try {
+                const suggestion = await this.withRetry(() => this.opts.synthesizer.generate({
+                    mission: updatedMission,
+                    candidateConfig: patched,
+                    prevRound: currentRoundData,
+                    prevRounds,
+                    crossRoundMemoryRef: triageResult.new_memory_token,
+                }), "Triaging");
+                await this.store.writeSuggestedChange(suggestion);
+            }
+            catch {
+                return;
+            }
+        }
+        // === Deciding ===
+        await this.store.appendEvent({ type: "state_transition", from: "Triaging", to: "Deciding", round });
+        if (triageResult.verdict === "publish" || round >= maxRounds) {
+            // Publish immediately
+            await this.store.appendEvent({ type: "state_transition", from: "Deciding", to: "Publishing", round });
+            const allRounds = await this.store.readAllRounds();
+            const allLineage = await this.store.readLineage();
+            await writeBundles({ expDir: this.opts.expDir, experimentId: expId, lineage: allLineage, rounds: allRounds, createdBy: process.env["USER"] ?? "unknown" });
+            await this.store.appendEvent({ type: "state_transition", from: "Publishing", to: "Published", round });
+            process.stdout.write(`\nExperiment complete. Outputs written to ${path.join(this.opts.expDir, "outputs")}\n`);
+        }
+        else {
+            // Pause at Deciding — lock released by run()/resume() finally block
+            process.stdout.write(`\nRound ${round} complete.\n`);
+            process.stdout.write(`Scores: outcome=${scores.outcome.toFixed(2)}, trajectory=${scores.trajectory.toFixed(2)}\n`);
+            process.stdout.write(`Triage: ${triageResult.diagnoses.join("; ")}\n`);
+            process.stdout.write(`Next suggestion written to mission.md. Review and run exp resume to continue.\n`);
+        }
+    }
+    async checkAbort(round) {
+        if (await this.store.isAborted()) {
+            clearInterval(this.heartbeatTimer);
+            await this.store.appendEvent({ type: "aborted", round, reason: "user_abort" });
+            await this.store.releaseLock();
+            return true;
+        }
+        return false;
+    }
+    async withRetry(fn, state) {
+        let lastErr;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt < 2) {
+                    await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
+                }
+            }
+        }
+        await this.store.appendEvent({
+            type: "step_failed",
+            state: state,
+            error: String(lastErr),
+            retryable: true,
+        });
+        throw lastErr;
+    }
+}

package/dist/trace-ai/exp/eval-runner.d.ts

@@ -0,0 +1,14 @@
+import type { QueryResult } from "./schemas.js";
+import type { RunnerDeps } from "../eval-set/test-runner.js";
+export interface EvalRunnerOpts {
+    evalSetPaths: string[];
+    candidatePath: string;
+    expDir: string;
+    round: number;
+    deps: RunnerDeps;
+    maxParallel?: number;
+}
+export interface EvalRunResult {
+    queryResults: QueryResult[];
+}
+export declare function runEval(opts: EvalRunnerOpts): Promise<EvalRunResult>;

package/dist/trace-ai/exp/eval-runner.js

@@ -0,0 +1,47 @@
+// src/trace-ai/exp/eval-runner.ts
+import path from "node:path";
+import yaml from "js-yaml";
+import fs from "node:fs/promises";
+import { run as evalSetRun } from "../eval-set/test-runner.js";
+export async function runEval(opts) {
+    const candidateRaw = yaml.load(await fs.readFile(opts.candidatePath, "utf8"));
+    const agentId = candidateRaw["agent_id"] ?? "candidate";
+    const agentVersion = candidateRaw["candidate_version"];
+    const roundEvalBase = path.join(opts.expDir, ".trace-state", "rounds", `round-${opts.round}-eval`);
+    // Run eval for each eval-set (sequentially for MVP-C single-path)
+    const allResults = [];
+    for (const evalSetDir of opts.evalSetPaths) {
+        // Each eval-set gets its own subdir so outputs from multiple sets don't overwrite each other
+        const outDir = path.join(roundEvalBase, path.basename(evalSetDir));
+        await fs.mkdir(outDir, { recursive: true });
+        await evalSetRun({
+            evalSetDir,
+            candidateAgentId: agentId,
+            candidateAgentVersion: agentVersion,
+            outDir,
+            maxParallel: opts.maxParallel ?? 4,
+            deps: opts.deps,
+        });
+        // Read report and convert to QueryResult[]
+        const reportPath = path.join(outDir, "report.yaml");
+        const report = yaml.load(await fs.readFile(reportPath, "utf8"));
+        for (const c of report.cases) {
+            allResults.push({
+                query_id: c.query_id,
+                assertion_results: c.assertion_results.map(ar => ({
+                    type: ar.assertion.type,
+                    verdict: ar.verdict,
+                    reason: typeof ar.actual === "string" ? ar.actual : undefined,
+                })),
+                trajectory_summary: {
+                    tool_call_sequence: [], // populated from trace if available
+                    retry_count: 0,
+                    latency_ms: c.duration_ms ?? 0,
+                    error_codes: [],
+                },
+                raw_trace_id: c.trace_id ?? undefined,
+            });
+        }
+    }
+    return { queryResults: allResults };
+}

package/dist/trace-ai/exp/exp-store/abort-signal.d.ts

@@ -0,0 +1,3 @@
+export declare function isAborted(expDir: string): Promise<boolean>;
+export declare function writeAbortSignal(expDir: string): Promise<void>;
+export declare function clearAbortSignal(expDir: string): Promise<void>;

package/dist/trace-ai/exp/exp-store/abort-signal.js

@@ -0,0 +1,27 @@
+// src/trace-ai/exp/exp-store/abort-signal.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+function signalPath(expDir) {
+    return path.join(expDir, ".trace-state", "abort.signal");
+}
+export async function isAborted(expDir) {
+    try {
+        await fs.access(signalPath(expDir));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function writeAbortSignal(expDir) {
+    await fs.writeFile(signalPath(expDir), new Date().toISOString(), "utf8");
+}
+export async function clearAbortSignal(expDir) {
+    try {
+        await fs.unlink(signalPath(expDir));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { LineageEntry } from "../schemas.js";
+export declare function appendLineage(expDir: string, entry: Omit<LineageEntry, "appended_at">): Promise<void>;
+export declare function updateLineage(expDir: string, version: number, patch: Partial<LineageEntry>): Promise<void>;
+export declare function readLineage(expDir: string): Promise<LineageEntry[]>;

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