taskflow-core 0.1.6 → 0.1.8

package/dist/trace.js

@@ -0,0 +1,191 @@
+/**
+ * Deterministic-replay trace — the foundation.
+ *
+ * Every run may emit an **append-only event trace** (`runs/<flow>/<runId>.trace.jsonl`)
+ * recording what each subagent call received and produced, plus the runtime's
+ * own decisions (gate verdicts, when-guard results, budget hits, cache hits,
+ * "this phase cannot be replayed" markers). A future `replay` action consumes
+ * this trace to re-evaluate a recorded run against changed decision knobs
+ * (thresholds, budget, model route) **without calling the model** — zero tokens.
+ *
+ * This module is deliberately **host-agnostic and side-effect-light**: it owns
+ * only the data shape, a JSONL reader/writer with partial-line tolerance, and a
+ * fail-open file-backed sink. The runtime emits events via `RuntimeDeps.trace`;
+ * if no sink is injected, nothing happens (the host-agnostic invariant is
+ * preserved — runs with no trace sink behave identically to today).
+ *
+ * **0.1.7 scope**: trace *emission* + read-only `trace` inspection only. The
+ * `replay` action (which consumes these events) lands in 0.2.0 — but the schema
+ * here is already complete enough that a 0.2.0 replay won't need a breaking
+ * migration. See `replay.ts` for the `ReplayDecision` type stub.
+ */
+import { openSync, readFileSync, renameSync, unlinkSync, writeFileSync, closeSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** A sink that drops everything. The default when no sink is injected. */
+export const NoopTraceSink = {
+    emit() { },
+    flush() { },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// File-backed sink (buffered per phase, flushed at phase-end)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Append-only JSONL trace, buffered per phase. Events for a phase accumulate in
+ * memory (lock-free) and are written in one locked append at `flush(phaseId)`,
+ * so a 30-item `map` fan-out never serialises 30 completions through the file
+ * lock. Crash-safety is therefore at the phase boundary, not the sub-call —
+ * sufficient for replay, which only needs completed phases.
+ *
+ * Each flush appends one line per event (`JSON.stringify` + `\n`) to a temp
+ * file then renames atomically onto the trace path's *appended* content. To
+ * keep appends atomic without read-modify-write races, flush holds an
+ * exclusive lock file (`<runId>.trace.lock`) via `O_CREAT|O_EXCL` (the same
+ * discipline as `store.ts`'s `withLock`).
+ */
+export class FileTraceSink {
+    buffer = new Map();
+    tracePath;
+    lockPath;
+    dirOk;
+    constructor(tracePath) {
+        this.tracePath = tracePath;
+        this.lockPath = `${tracePath}.lock`;
+        // Probe writability of the parent dir once; if unwritable, degrade to
+        // no-op silently (fail-open — trace is best-effort, never run-breaking).
+        try {
+            const dir = join(tracePath, "..");
+            this.dirOk = existsSync(dir);
+        }
+        catch {
+            this.dirOk = false;
+        }
+    }
+    emit(event) {
+        try {
+            const arr = this.buffer.get(event.phaseId) ?? [];
+            arr.push(event);
+            this.buffer.set(event.phaseId, arr);
+        }
+        catch {
+            /* fail-open */
+        }
+    }
+    flush(phaseId) {
+        const events = this.buffer.get(phaseId);
+        this.buffer.delete(phaseId);
+        if (!events || events.length === 0 || !this.dirOk)
+            return;
+        // Serialize + append under an exclusive lock. Best-effort: any error is
+        // swallowed (trace is never run-breaking).
+        try {
+            withExclusiveLock(this.lockPath, () => {
+                const chunk = events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+                appendAtomic(this.tracePath, chunk);
+            });
+        }
+        catch {
+            /* fail-open */
+        }
+    }
+}
+/** Atomic append: read current (if any) + write combined to temp + rename. */
+function appendAtomic(path, chunk) {
+    let existing = "";
+    try {
+        existing = readFileSync(path, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, existing + chunk, "utf8");
+    renameSync(tmp, path);
+}
+/** Hold an exclusive lock for the duration of `fn` via `O_CREAT|O_EXCL`. */
+function withExclusiveLock(lockPath, fn) {
+    let fd;
+    const staleMs = 60_000; // steal a lock older than 60s (a crashed writer)
+    for (let i = 0; i < 200; i++) {
+        try {
+            fd = openSync(lockPath, "wx");
+            break;
+        }
+        catch (e) {
+            // Lock exists — steal if stale.
+            try {
+                const st = statSync(lockPath);
+                if (Date.now() - st.mtimeMs > staleMs) {
+                    const stolen = `${lockPath}.steal-${process.pid}-${Date.now()}`;
+                    renameSync(lockPath, stolen);
+                    try {
+                        unlinkSync(stolen);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    continue;
+                }
+            }
+            catch {
+                /* ignore stat failure */
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+        }
+    }
+    if (fd === undefined) {
+        // Could not acquire — run unlocked (fail-open; worst case a partial
+        // interleaving that JSONL-line-parsing tolerates on read).
+        fn();
+        return;
+    }
+    try {
+        fn();
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Reader (partial-line tolerant)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Read + parse a trace JSONL. Skips blank lines and any trailing partial line
+ * (a crash mid-flush can leave a truncated final record). Returns events in
+ * file (append) order. Best-effort: a missing file → empty array.
+ */
+export function readTrace(tracePath) {
+    let text;
+    try {
+        text = readFileSync(tracePath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const lines = text.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Partial / corrupt line — skip (fail-open). A truncated final record
+            // from a crashed flush is the expected case.
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,4CAA6C,CAAC;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,IAAI,aAAa,CAEhF;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACzB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,aAAa,GAAG,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,IAAI,IAAI,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AA2DD,UAAU,SAAS;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAuEjF"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,YAAI,MAAM,EAAE,WAAW,EAAE,UAAU,CAAU,CAAC;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,IAAI,aAAa,CAEhF;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACzB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,aAAa,GAAG,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,IAAI,IAAI,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AA2DD,UAAU,SAAS;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAuEjF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskflow-core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Host-neutral engine for declarative, verifiable task-DAG orchestration — the runtime, DSL, cache, and verification shared by pi-taskflow, codex-taskflow, claude-taskflow, and opencode-taskflow.",
   "keywords": [
     "taskflow",