@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.4

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

@@ -3,9 +3,12 @@ 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 { PatchApplier } from "./patch/index.js";
 import { computeScores } from "./scoring.js";
 import { writeBundles } from "./bundle-writer.js";
+import { analyzeFailures, roundRetrievedAnyData } from "./context/failure-analyzer.js";
+import { diagnoseMechanism } from "./context/retrieval-health.js";
+import { runPreflight } from "./run-preflight.js";
 export class ExperimentCoordinator {
     opts;
     store;
@@ -16,8 +19,9 @@ export class ExperimentCoordinator {
     }
     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.`);
+        if (replayed.isTerminal) {
+            throw new Error(`Experiment is in terminal state ${replayed.currentState}. ` +
+                `Use --new-run to start a fresh experiment in this directory.`);
         }
         const mission = await this.store.readMission();
         const expId = this.opts.experimentId ?? `exp_${Date.now()}`;
@@ -26,14 +30,34 @@ export class ExperimentCoordinator {
         }
         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
+        const uninstallSignals = this.installSignalHandlers();
+        // Layer 2 auto-recovery: prior holder died mid-round without writing step_failed
+        // (typically SIGKILL/OOM/power — signal handlers can't help with these). FSM is
+        // stuck in an executing-side phase with no lastFailure. Synthesize step_failed so
+        // the startRound calc below rewinds to redo the round.
+        const stuckMidRound = !replayed.lastFailure
+            && replayed.currentRound > 0
+            && replayed.currentState !== "Init"
+            && replayed.currentState !== "Deciding"
+            && !replayed.isTerminal;
+        if (stuckMidRound) {
+            await this.store.appendEvent({
+                type: "step_failed",
+                state: replayed.currentState,
+                error: `auto-recovered: prior holder died mid-${replayed.currentState} at round ${replayed.currentRound}`,
+                retryable: true,
+            });
+            process.stderr.write(`Recovered stale ${replayed.currentState} at round ${replayed.currentRound}; redoing round.\n`);
+        }
+        // If previous run failed mid-round (real failure OR auto-recovered above), retry that round.
+        const startRound = (replayed.lastFailure || stuckMidRound) && replayed.currentRound > 0
             ? replayed.currentRound - 1
             : replayed.currentRound;
         try {
             await this.runLoop(mission, startRound, expId);
         }
         finally {
+            uninstallSignals();
             clearInterval(this.heartbeatTimer);
             await this.store.releaseLock();
         }
@@ -45,16 +69,88 @@ export class ExperimentCoordinator {
         }
         await this.store.acquireLock();
         this.heartbeatTimer = setInterval(() => { void this.store.updateHeartbeat(); }, 10_000);
+        const uninstallSignals = this.installSignalHandlers();
         try {
             const mission = await this.store.readMission();
             const expId = `exp_${replayed.currentRound}`;
             await this.runLoop(mission, replayed.currentRound, expId);
         }
         finally {
+            uninstallSignals();
             clearInterval(this.heartbeatTimer);
             await this.store.releaseLock();
         }
     }
+    /**
+     * 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.
+     */
+    installSignalHandlers() {
+        let firing = false;
+        const handler = (signal) => {
+            if (firing)
+                return;
+            firing = true;
+            // Process exits in the IIFE — Node won't await the handler itself, so we
+            // must drive the async flow and then `process.exit` ourselves.
+            void (async () => {
+                try {
+                    const replayed = await this.store.replayState();
+                    if (signal === "SIGINT") {
+                        await this.store.appendEvent({
+                            type: "aborted",
+                            round: replayed.currentRound,
+                            reason: `interrupted by ${signal}`,
+                        });
+                    }
+                    else {
+                        // For non-terminal states only — if FSM was already Deciding/Init/terminal,
+                        // a step_failed would be a lie. Skip the event but still release the lock.
+                        const recoverable = !replayed.isTerminal
+                            && replayed.currentState !== "Init"
+                            && replayed.currentState !== "Deciding";
+                        if (recoverable) {
+                            await this.store.appendEvent({
+                                type: "step_failed",
+                                state: replayed.currentState,
+                                error: `process interrupted by ${signal}`,
+                                retryable: true,
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`signal handler: failed to append event: ${String(err)}\n`);
+                }
+                if (this.heartbeatTimer)
+                    clearInterval(this.heartbeatTimer);
+                try {
+                    await this.store.releaseLock();
+                }
+                catch { /* best-effort */ }
+                // Exit codes per shell convention (128 + signal number).
+                const code = signal === "SIGINT" ? 130 : signal === "SIGHUP" ? 129 : 143;
+                process.exit(code);
+            })();
+        };
+        process.on("SIGINT", handler);
+        process.on("SIGHUP", handler);
+        process.on("SIGTERM", handler);
+        return () => {
+            process.off("SIGINT", handler);
+            process.off("SIGHUP", handler);
+            process.off("SIGTERM", handler);
+        };
+    }
     async runLoop(mission, startRound, expId) {
         const round = startRound + 1;
         const maxRounds = mission.max_rounds ?? Infinity;
@@ -64,12 +160,35 @@ export class ExperimentCoordinator {
         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");
+            throw new Error("mission.md has no next_change — add one or let the planner suggest");
+        if (!mission.enabled_targets.includes(nextChange.target)) {
+            throw new Error(`next_change.target=${nextChange.target} is not in mission.enabled_targets=[${mission.enabled_targets.join(", ")}]. ` +
+                `Either add the target to enabled_targets in mission.md, or change next_change to use an enabled target.`);
+        }
         const prevRounds = await this.store.readAllRounds();
-        // Load current candidate and apply patch
+        // Load current candidate and apply patch via PatchApplier (handles agent.*/kn.*/skill.content).
+        // PatchApplier may call external APIs (KN/skill) that throw on stubs or transient failures;
+        // surface those as Generating-phase step_failed so the FSM stays observable and lineage
+        // doesn't get stuck in "running". No auto-retry: patch side-effects (KN writes, skill version
+        // publish) are not safe to blindly retry — user inspects step_failed and resumes manually.
         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);
+        const patchApplier = new PatchApplier(this.opts.expDir, this.opts.knClient, this.opts.skillClient);
+        let patched;
+        try {
+            const result = await patchApplier.apply(currentCandidate, nextChange);
+            patched = result.candidate;
+        }
+        catch (err) {
+            await this.store.appendEvent({
+                type: "step_failed",
+                state: "Generating",
+                error: String(err),
+                retryable: false,
+            });
+            process.stderr.write(`\nGenerating failed for target ${nextChange.target}: ${String(err)}\n`);
+            return;
+        }
         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 }));
@@ -84,6 +203,43 @@ export class ExperimentCoordinator {
         // === 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));
+        // Preflight: reconcile the live agent against expectation before any eval
+        // chat is sent. A mismatch (wrong KN binding) fails the round fast —
+        // non-retryable, since it will not fix itself.
+        if (this.opts.fetchAgentConfig) {
+            const agentId = patched["agent_id"];
+            if (typeof agentId !== "string" || !agentId) {
+                // fetchAgentConfig is wired but the agent can't be identified — fail
+                // loudly rather than silently skipping the guard.
+                await this.store.appendEvent({
+                    type: "step_failed",
+                    state: "Executing",
+                    error: "preflight: candidate has no agent_id — cannot verify the agent under test",
+                    retryable: false,
+                });
+                process.stderr.write("\nPreflight check failed — candidate has no agent_id.\n");
+                return;
+            }
+            try {
+                await runPreflight({
+                    expDir: this.opts.expDir,
+                    agentId,
+                    fetchConfig: this.opts.fetchAgentConfig,
+                    evalSetPaths,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                await this.store.appendEvent({
+                    type: "step_failed",
+                    state: "Executing",
+                    error: `preflight: ${message}`,
+                    retryable: false,
+                });
+                process.stderr.write(`\nPreflight check failed — eval not run:\n${message}\n`);
+                return;
+            }
+        }
         let queryResults;
         try {
             const result = await this.withRetry(() => this.opts.runEval({ evalSetPaths, candidatePath: newCandidatePath, expDir: this.opts.expDir, round }), "Executing");
@@ -109,10 +265,58 @@ export class ExperimentCoordinator {
         await this.store.writeRound(round, { round, trial_version: round, scores, per_query_results: queryResults });
         if (await this.checkAbort(round))
             return;
-        // === Triaging ===
+        // === Triaging (merged: diagnose + propose in one LLM call) ===
         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;
+        const failureAnalysis = await analyzeFailures(currentRoundData.per_query_results ?? [], this.opts.fetchTrace);
+        // Fail-fast on a mechanism failure: if the trace shows the agent retrieved
+        // no KN data across the failing queries, this round measured a wiring
+        // failure, not the prompt. Running triage would only burn an LLM call
+        // proposing prompt patches that cannot fix it — stop and report the root
+        // cause instead.
+        //
+        // diagnoseMechanism only sees failing queries, so confirm against the whole
+        // round: if any query (passing or failing) did retrieve KN data, the no-data
+        // failures are localized, not a global break — let triage handle them.
+        let mechanism = diagnoseMechanism(failureAnalysis);
+        if (mechanism.broken
+            && await roundRetrievedAnyData(currentRoundData.per_query_results ?? [], this.opts.fetchTrace)) {
+            mechanism = { broken: false, reason: "" };
+        }
+        if (mechanism.broken) {
+            await this.store.appendEvent({
+                type: "step_failed",
+                state: "Triaging",
+                error: `mechanism: ${mechanism.reason}`,
+                retryable: false,
+            });
+            process.stderr.write(`\nMechanism failure — triage skipped, round halted:\n${mechanism.reason}\n`);
+            return;
+        }
+        // Pre-fetch all available context so the merged planner LLM can see KN schema
+        // + bound skill content + data probes before deciding both verdict AND next_change.
+        // We call assemble() twice (kn target + skill target) since each path fetches
+        // distinct artifacts; total cost dominated by the LLM call that follows.
+        const knId = patched["kn"]?.["id"];
+        const boundSkills = patched["agent"]?.["skills"] ?? [];
+        let kn_context;
+        let skill_context;
+        if (this.opts.contextAssembler) {
+            const assembler = this.opts.contextAssembler;
+            const empty = {};
+            const [knRes, skillRes] = await Promise.all([
+                knId
+                    ? assembler.assemble("kn.object_type", knId, boundSkills, failureAnalysis)
+                    : Promise.resolve(empty),
+                boundSkills.length > 0
+                    ? assembler.assemble("skill.content", knId, boundSkills, failureAnalysis)
+                    : Promise.resolve(empty),
+            ]);
+            kn_context = knRes.kn_context;
+            skill_context = skillRes.skill_context;
+        }
+        const updatedMission = await this.store.readMission();
         let triageResult;
         try {
             triageResult = await this.withRetry(() => this.opts.triage.triage({
@@ -120,36 +324,54 @@ export class ExperimentCoordinator {
                 prevRounds,
                 candidateConfig: patched,
                 crossRoundMemoryRef: prevMemory,
+                failureAnalysis,
+                mission: updatedMission,
+                kn_context,
+                skill_context,
             }), "Triaging");
         }
         catch {
             return;
         }
+        // Persist triage_conclusion. Only "continue"/"publish" are valid in the typed schema;
+        // "abort" is a runtime verdict mapped to "publish" for storage but routed to Aborted below.
+        const storedVerdict = triageResult.verdict === "continue" ? "continue" : "publish";
         await this.store.writeRound(round, {
             triage_conclusion: {
                 diagnoses: triageResult.diagnoses,
                 hints: triageResult.hints,
-                verdict: triageResult.verdict,
+                verdict: storedVerdict,
                 cross_round_memory_ref: triageResult.new_memory_token,
             },
         });
-        await this.store.appendEvent({ type: "round_completed", round, verdict: triageResult.verdict });
-        // Generate next suggestion if continuing
+        await this.store.appendEvent({ type: "round_completed", round, verdict: storedVerdict });
+        // Persist failure_attribution in a TriageComplete event for downstream consumers (exp show, etc.)
+        await this.store.appendEvent({
+            type: "TriageComplete",
+            round,
+            verdict: triageResult.verdict,
+            summary: triageResult.summary,
+            failure_attribution: triageResult.failure_attribution,
+        });
+        // Abort: terminal state — no suggestion, no Deciding pause.
+        if (triageResult.verdict === "abort") {
+            await this.store.appendEvent({ type: "aborted", round, reason: `triage_abort: ${triageResult.summary ?? "no summary"}` });
+            process.stdout.write(`\nExperiment aborted by triage: ${triageResult.summary ?? "(no reason)"}\n`);
+            return;
+        }
+        // Continue: triageResult.next_change was produced in the same LLM call; write it as suggestion.
         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 {
+            if (!triageResult.next_change) {
+                // Parser already enforces presence when verdict=continue, but guard belt-and-braces.
+                await this.store.appendEvent({
+                    type: "step_failed",
+                    state: "Triaging",
+                    error: "verdict=continue but next_change missing in triage output",
+                    retryable: true,
+                });
                 return;
             }
+            await this.store.writeSuggestedChange(triageResult.next_change);
         }
         // === Deciding ===
         await this.store.appendEvent({ type: "state_transition", from: "Triaging", to: "Deciding", round });

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

@@ -6,7 +6,9 @@ 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"];
+    // candidate_version ("v1", "v2", …) is the experiment's own round numbering,
+    // NOT a platform agent version. The eval always measures the current live
+    // agent, which fetchAgent resolves at "latest" — never conflate the two.
     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 = [];
@@ -17,7 +19,6 @@ export async function runEval(opts) {
         await evalSetRun({
             evalSetDir,
             candidateAgentId: agentId,
-            candidateAgentVersion: agentVersion,
             outDir,
             maxParallel: opts.maxParallel ?? 4,
             deps: opts.deps,
@@ -40,6 +41,7 @@ export async function runEval(opts) {
                     error_codes: [],
                 },
                 raw_trace_id: c.trace_id ?? undefined,
+                conversation_id: c.conversation_id ?? undefined,
             });
         }
     }

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

@@ -2,6 +2,7 @@ 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 readAllEvents(expDir: string): Promise<Record<string, unknown>[]>;
 export declare function appendEvent(expDir: string, event: EventInput): Promise<void>;
 export interface ReplayedState {
     currentState: ExpFsmState;

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

@@ -1,5 +1,23 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+export async function readAllEvents(expDir) {
+    const filePath = path.join(expDir, ".trace-state", "events.jsonl");
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    return raw.split("\n").filter(Boolean).map(line => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+    }).filter((e) => e !== null);
+}
 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";

package/dist/trace-ai/exp/exp-store/expected-fingerprint.d.ts

@@ -0,0 +1,3 @@
+import type { AgentFingerprint } from "../preflight.js";
+export declare function writeExpectedFingerprint(expDir: string, fingerprint: AgentFingerprint): Promise<void>;
+export declare function readExpectedFingerprint(expDir: string): Promise<AgentFingerprint | undefined>;

package/dist/trace-ai/exp/exp-store/expected-fingerprint.js

@@ -0,0 +1,31 @@
+// src/trace-ai/exp/exp-store/expected-fingerprint.ts
+//
+// The loop-owned record of the agent configuration last seen under test.
+// Re-captured by the preflight step every round (never hand-edited) — it is the
+// per-round provenance fingerprint of exactly what config the round measured.
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+function fingerprintPath(expDir) {
+    return path.join(expDir, ".trace-state", "expected-fingerprint.yaml");
+}
+export async function writeExpectedFingerprint(expDir, fingerprint) {
+    const p = fingerprintPath(expDir);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, yaml.dump(fingerprint, { lineWidth: -1 }), "utf8");
+}
+export async function readExpectedFingerprint(expDir) {
+    try {
+        const raw = await fs.readFile(fingerprintPath(expDir), "utf8");
+        const parsed = yaml.load(raw);
+        // Fingerprints written before non_fixed_kn_bindings existed lack the field;
+        // normalize so consumers can rely on it always being an array.
+        if (parsed && !Array.isArray(parsed.non_fixed_kn_bindings)) {
+            parsed.non_fixed_kn_bindings = [];
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -16,12 +16,72 @@ export declare class ExpStore {
         current_candidate: {
             path: string;
         };
+        enabled_targets: ("agent.system_prompt" | "agent.skills" | "kn.object_type" | "kn.relation_type" | "skill.content")[];
         max_rounds?: number | undefined;
         provider?: string | undefined;
         next_change?: {
-            target: string;
+            target: "agent.system_prompt";
+            patch: string | Record<string, unknown>;
+            hypothesis?: string | undefined;
+        } | {
+            target: "agent.skills";
+            patch: {
+                unbind: string[];
+                bind: {
+                    id: string;
+                    version: string;
+                }[];
+            };
+            hypothesis?: string | undefined;
+        } | {
+            target: "kn.object_type";
             hypothesis: string;
-            patch: string;
+            patch: {
+                kn_id: string;
+                add_object_types: {
+                    concept_name: string;
+                    dataview_id: string;
+                    primary_keys: string[];
+                    data_properties: {
+                        name: string;
+                        type: string;
+                    }[];
+                }[];
+                add_relation_types: {
+                    concept_name: string;
+                    source_object_type: string;
+                    target_object_type: string;
+                    join_key: string;
+                }[];
+            };
+        } | {
+            target: "kn.relation_type";
+            hypothesis: string;
+            patch: {
+                kn_id: string;
+                add_object_types: {
+                    concept_name: string;
+                    dataview_id: string;
+                    primary_keys: string[];
+                    data_properties: {
+                        name: string;
+                        type: string;
+                    }[];
+                }[];
+                add_relation_types: {
+                    concept_name: string;
+                    source_object_type: string;
+                    target_object_type: string;
+                    join_key: string;
+                }[];
+            };
+        } | {
+            target: "skill.content";
+            hypothesis: string;
+            patch: {
+                skill_id: string;
+                append_section: string;
+            };
         } | undefined;
         guardrails?: {
             name: string;
@@ -31,6 +91,7 @@ export declare class ExpStore {
     }>;
     writeSuggestedChange: (c: NextChange) => Promise<void>;
     appendEvent: (e: EventInput) => Promise<void>;
+    readAllEvents: () => Promise<Record<string, unknown>[]>;
     replayState: () => Promise<ReplayedState>;
     acquireLock: () => Promise<void>;
     releaseLock: () => Promise<void>;

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

@@ -3,7 +3,7 @@ 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 { appendEvent, replayState, readAllEvents } 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";
@@ -44,6 +44,7 @@ export class ExpStore {
     readMission = () => readMission(this.expDir);
     writeSuggestedChange = (c) => writeSuggestedChange(this.expDir, c);
     appendEvent = (e) => appendEvent(this.expDir, e);
+    readAllEvents = () => readAllEvents(this.expDir);
     replayState = () => replayState(this.expDir);
     acquireLock = () => acquireLock(this.expDir);
     releaseLock = () => releaseLock(this.expDir);

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

@@ -0,0 +1,12 @@
+export interface RollbackStep {
+    op: "remove_object_type" | "remove_relation_type";
+    kn_id: string;
+    concept_name: string;
+    applied_at: string;
+}
+export declare class RollbackYaml {
+    private filePath;
+    constructor(workDir: string);
+    appendStep(step: Omit<RollbackStep, "applied_at">): Promise<void>;
+    readSteps(): Promise<RollbackStep[]>;
+}

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

@@ -0,0 +1,29 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+export class RollbackYaml {
+    filePath;
+    constructor(workDir) {
+        this.filePath = path.join(workDir, "rollback.yaml");
+    }
+    async appendStep(step) {
+        const existing = await this.readSteps();
+        const doc = {
+            schema_version: "exp-rollback/v1",
+            steps: [...existing, { ...step, applied_at: new Date().toISOString() }],
+        };
+        await fs.writeFile(this.filePath, yaml.dump(doc), "utf-8");
+    }
+    async readSteps() {
+        try {
+            const content = await fs.readFile(this.filePath, "utf-8");
+            const parsed = yaml.load(content);
+            return parsed?.steps ?? [];
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+    }
+}

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

@@ -1,3 +1,5 @@
+import type { FailureAttribution } from "./schemas.js";
+export declare function formatFailureAttribution(attribution: FailureAttribution[]): string;
 export interface ParsedExpArgs {
     subcommand: "run" | "resume" | "show" | "status" | "abort" | "doctor" | "list" | "info";
     expDir: string;