@gr8ful/spf 0.1.0

package/dist/core/runner.js

@@ -0,0 +1,168 @@
+/**
+ * The Run object: config + adw_id + agent_map + tracer + console, bound once.
+ *
+ * `run.phase(params, fn)` is the ONE phase primitive — an async scope for all
+ * three kinds (engineer, agent, code), replacing Python's `with run.phase(...)
+ * as ph:` context manager (JS has no direct equivalent, so the callback form
+ * is the idiomatic stand-in). Success must be earned: every phase defaults to
+ * fail; only a clean exit flips it (agent phases additionally require a
+ * parsed envelope + green gates, enforced inside ph.call).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import * as agents from "./agents.js";
+import { makeGit } from "./git_helper.js";
+import { Console } from "./console.js";
+import { Tracer } from "./tracer.js";
+import { makeEventRecord } from "./data_types.js";
+import { ensureDir, nowIso } from "./utils.js";
+class PhaseHandleImpl {
+    run;
+    phase;
+    constructor(run, phase) {
+        this.run = run;
+        this.phase = phase;
+    }
+    log(payload) {
+        this.run.tracer.event(makeEventRecord({
+            adw_id: this.run.adw_id,
+            phase_id: this.phase.phase_id,
+            type: "log",
+            name: this.phase.params.name,
+            payload,
+        }));
+        this.run.console.note(Object.entries(payload).map(([k, v]) => `${k}: ${v}`).join(", "));
+        if (this.phase.params.kind === "engineer" && "input" in payload) {
+            this.run.tracer.sessionRequest(this.run.adw_id, String(payload.input));
+        }
+    }
+    async call(call) {
+        if (this.phase.params.kind !== "agent") {
+            throw new Error("ph.call() is only valid inside an agent phase");
+        }
+        return (await agents.execute(this.run, this.phase, call));
+    }
+}
+export class Run {
+    cfg;
+    adw_id;
+    tracer;
+    console;
+    engineer;
+    phases = [];
+    tokens = 0;
+    cost = 0;
+    repo_root; // where every agent is spawned to work — always absolute
+    /** Every git operation for this run, bound to repo_root. Never call git_helper directly. */
+    git;
+    /** From the same anchor as repo_root — null if no .spf/ dir exists. */
+    spf_dir;
+    /** Absolute. Sibling of it: flue.db (Flue's own conversation store), sessions/. */
+    data_dir;
+    session_dir;
+    context_handoff_dir;
+    agent_map;
+    seq; // a joined run continues the sequence
+    agentMapPath;
+    constructor(init) {
+        this.cfg = init.cfg;
+        this.adw_id = init.adwId;
+        this.tracer = init.tracer;
+        this.console = new Console(init.tracer, init.adwId);
+        this.engineer = init.engineer;
+        this.seq = init.tracer.maxPhaseSeq(init.adwId);
+        this.repo_root = init.repoRoot;
+        this.spf_dir = init.sfDir;
+        this.git = makeGit(init.repoRoot);
+        this.data_dir = init.dataDir;
+        this.session_dir = ensureDir(path.join(init.dataDir, "sessions", init.adwId));
+        this.context_handoff_dir = ensureDir(path.join(this.session_dir, "context_handoff"));
+        this.agentMapPath = path.join(this.session_dir, "agent_map.json");
+        this.agent_map = existsSync(this.agentMapPath) ? JSON.parse(readFileSync(this.agentMapPath, "utf-8")) : {};
+    }
+    // ── agent map (adw_id -> per-agent coding-agent session ids) ────────────
+    saveAgentMap(agent, entry) {
+        this.agent_map[agent] = entry;
+        writeFileSync(this.agentMapPath, JSON.stringify(this.agent_map, null, 2));
+    }
+    // ── usage (run totals mirror what the tracer accumulates in sqlite) ─────
+    addUsage(tokens, cost) {
+        this.tokens += tokens;
+        this.cost += cost;
+        this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
+    }
+    // ── the phase primitive ─────────────────────────────────────────────────
+    async phase(params, fn) {
+        this.seq += 1;
+        const phase = {
+            phase_id: `${this.adw_id}_${String(this.seq).padStart(2, "0")}_${params.name}`,
+            adw_id: this.adw_id,
+            seq: this.seq,
+            params,
+            status: "running",
+            attempt: 0,
+            error: null,
+            started_at: nowIso(),
+            ended_at: null,
+        };
+        this.phases.push(phase);
+        this.tracer.phaseUpsert(phase);
+        this.tracer.event(makeEventRecord({
+            adw_id: this.adw_id,
+            phase_id: phase.phase_id,
+            type: "phase_start",
+            name: params.name,
+            payload: { kind: params.kind, owner: params.owner, description: params.description },
+        }));
+        this.console.phaseStarted(phase);
+        const clock = performance.now();
+        try {
+            const result = await fn(new PhaseHandleImpl(this, phase));
+            phase.status = "success";
+            phase.ended_at = nowIso();
+            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "success" } }));
+            this.tracer.phaseUpsert(phase);
+            this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
+            return result;
+        }
+        catch (error) {
+            phase.status = "fail"; // success must be earned
+            phase.error = String(error?.message ?? error).slice(0, 1000);
+            phase.ended_at = nowIso();
+            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "error", name: params.name, payload: { error: phase.error } }));
+            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "fail" } }));
+            this.tracer.phaseUpsert(phase);
+            this.tracer.sessionFinish(this.adw_id, false);
+            this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
+            this.console.sessionFinished(false, this.tokens, this.cost, this.cfg.observability.db);
+            throw error;
+        }
+    }
+    /**
+     * Finalize the run and return its exit code. Call this exactly once.
+     *
+     * Two criteria, not one. Every phase must have passed, AND the ADW's own
+     * acceptance test must hold. They are different questions on purpose: a
+     * test phase that ran a red suite succeeded at its job. Pass `accepted=`
+     * so the exit code, the session status, and the banner are decided
+     * together and cannot disagree.
+     */
+    finish(accepted = true, reason = "") {
+        const phasesOk = this.phases.length > 0 && this.phases.every((p) => p.status === "success");
+        const ok = phasesOk && accepted;
+        if (phasesOk && !accepted) {
+            const note = reason || "the run's acceptance criterion was not met";
+            this.tracer.event(makeEventRecord({
+                adw_id: this.adw_id,
+                phase_id: this.phases.length > 0 ? this.phases[this.phases.length - 1].phase_id : "",
+                type: "error",
+                name: "not_accepted",
+                payload: { reason: note },
+            }));
+            this.console.note(`not accepted: ${note}`);
+        }
+        this.tracer.sessionFinish(this.adw_id, ok);
+        this.console.sessionFinished(ok, this.tokens, this.cost, this.cfg.observability.db);
+        return ok ? 0 : 1;
+    }
+}

package/dist/core/session.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Session lifecycle: pin-or-create an adw_id, build the Run object.
+ *
+ * `ensure(cfg, adwId)` joins the session if it exists or creates it under
+ * exactly that id (pinned ids for repeatable runs); omitted, a fresh id is
+ * minted and printed so the next ADW can pick it up.
+ */
+import { Run } from "./runner.ts";
+import type { SFConfig } from "./data_types.ts";
+/**
+ * `cwd` anchors this run's repo_root and data_dir — it is NOT where the
+ * process happened to start; it is an explicit decision, threaded down from
+ * the CLI/chain context. Defaults to `process.cwd()` only for direct callers
+ * (tests, scratch scripts) that have no anchor of their own to pass.
+ */
+export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string): Run;

package/dist/core/session.js

@@ -0,0 +1,60 @@
+/**
+ * Session lifecycle: pin-or-create an adw_id, build the Run object.
+ *
+ * `ensure(cfg, adwId)` joins the session if it exists or creates it under
+ * exactly that id (pinned ids for repeatable runs); omitted, a fresh id is
+ * minted and printed so the next ADW can pick it up.
+ */
+import path from "node:path";
+import * as paths from "./paths.js";
+import { Run } from "./runner.js";
+import { Tracer } from "./tracer.js";
+import { engineerName, newId } from "./utils.js";
+/**
+ * A killed run still closes its own trace.
+ *
+ * Node's default SIGTERM/SIGINT handling exits without unwinding, so `just
+ * kill` (or any `kill <pid>`) would leave the session reading `running`
+ * forever and its process rows open — the trace would claim work is in
+ * flight that is already dead. Handling the signal both finalizes here and
+ * lets the phase's try/catch record the phase as failed on the way out
+ * (best-effort: a signal can still land mid-write).
+ */
+function finalizeWhenKilled(run) {
+    const handler = (signal) => {
+        run.tracer.sessionFinish(run.adw_id, false); // also closes process rows
+        process.exit(128 + (signal === "SIGINT" ? 2 : 15));
+    };
+    process.on("SIGTERM", handler);
+    process.on("SIGINT", handler);
+}
+/**
+ * `cwd` anchors this run's repo_root and data_dir — it is NOT where the
+ * process happened to start; it is an explicit decision, threaded down from
+ * the CLI/chain context. Defaults to `process.cwd()` only for direct callers
+ * (tests, scratch scripts) that have no anchor of their own to pass.
+ */
+export function ensure(cfg, adwId, cwd) {
+    const id = adwId || newId(8);
+    const anchor = paths.resolveAnchor(cwd);
+    const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
+    const tracer = new Tracer(dataPaths.db_path, path.join(dataPaths.sessions_dir, id, "events.jsonl"));
+    const run = new Run({
+        cfg,
+        adwId: id,
+        tracer,
+        engineer: engineerName(),
+        repoRoot: anchor.repo_root,
+        sfDir: anchor.spf_dir,
+        dataDir: dataPaths.data_dir,
+    });
+    const scriptPath = process.argv[1] || "adw";
+    const adwName = path.basename(scriptPath, path.extname(scriptPath));
+    tracer.sessionStart(id, run.engineer, adwName);
+    // This process is the run. Record it before any phase opens, so a run that
+    // hangs in its first agent call is still killable by adw_id.
+    tracer.processStart(id, "adw", "", process.pid ?? -1, [path.basename(scriptPath), ...process.argv.slice(2)].join(" "));
+    finalizeWhenKilled(run);
+    run.console.sessionStarted(id, run.engineer);
+    return run;
+}

package/dist/core/sqlite.d.ts

@@ -0,0 +1,55 @@
+/**
+ * bun:sqlite's surface, backed by node:sqlite, so tracer.ts and the visualizer's
+ * db.ts change only their import line.
+ *
+ * This is deliberately NOT a full bun:sqlite polyfill — it's the ~10-behavior
+ * subset SPF actually calls (query/exec/get/all/run, readonly, PRAGMAs, WAL).
+ * Every mapping below was verified live against node:sqlite, not assumed:
+ *
+ *  - bun:sqlite's `{ readonly: true }` maps to node:sqlite's `{ readOnly: true }`
+ *    (capital O). Passing the lowercase bun spelling to node:sqlite is NOT an
+ *    error — it is silently ignored and the connection opens read-write. That
+ *    would quietly void every "this connection never writes" guarantee in the
+ *    codebase, so the translation below is deliberate, not cosmetic.
+ *  - PRAGMAs (journal_mode, table_info) return rows through the normal
+ *    prepare()/get()/all() path on both drivers, and multi-statement `exec()`
+ *    works on both — so the tracer's schema creation and additive ALTER
+ *    migrations need no changes at all.
+ *  - `.query()` on bun:sqlite is a MEMOIZED prepare — the same SQL text
+ *    returns the same cached statement. node:sqlite's `prepare()` is not
+ *    memoized, and db.ts rebuilds its SQL per-request through an
+ *    `optionalColumn()` probe, so this shim caches by exact SQL text. That is
+ *    also *correct*: when a tracer ALTER lands mid-serve and the probed SQL
+ *    text changes, a fresh statement is prepared automatically.
+ *  - node:sqlite's `get()` returns `undefined` for no-row, not `null`; rows
+ *    come back with a null prototype. Both are normalized below so existing
+ *    `?? null` / `Object.assign(row, ...)` call sites stay honest.
+ *  - node:sqlite defaults `enableForeignKeyConstraints: true` — unlike plain
+ *    SQLite and bun:sqlite, which both default FK enforcement OFF. The
+ *    tracer's schema uses `REFERENCES` purely as documentation (rows are not
+ *    always inserted parent-before-child — e.g. the very first `events` row
+ *    for a session lands before that session's own `sessions` row commits),
+ *    so this is disabled explicitly to restore the behavior the rest of the
+ *    codebase was written against. Confirmed by reproduction: enabling it
+ *    throws `FOREIGN KEY constraint failed` on session start.
+ */
+export interface DatabaseOptions {
+    readonly?: boolean;
+}
+export interface Statement<Row, Params extends unknown[]> {
+    get(...params: Params): Row | null;
+    all(...params: Params): Row[];
+    run(...params: Params): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+}
+export declare class Database {
+    private readonly db;
+    private readonly statementCache;
+    constructor(path: string, options?: DatabaseOptions);
+    /** Cached prepare, keyed by exact SQL text — see the module doc comment. */
+    query<Row = unknown, Params extends unknown[] = unknown[]>(sql: string): Statement<Row, Params>;
+    exec(sql: string): void;
+    close(): void;
+}

package/dist/core/sqlite.js

@@ -0,0 +1,106 @@
+/**
+ * bun:sqlite's surface, backed by node:sqlite, so tracer.ts and the visualizer's
+ * db.ts change only their import line.
+ *
+ * This is deliberately NOT a full bun:sqlite polyfill — it's the ~10-behavior
+ * subset SPF actually calls (query/exec/get/all/run, readonly, PRAGMAs, WAL).
+ * Every mapping below was verified live against node:sqlite, not assumed:
+ *
+ *  - bun:sqlite's `{ readonly: true }` maps to node:sqlite's `{ readOnly: true }`
+ *    (capital O). Passing the lowercase bun spelling to node:sqlite is NOT an
+ *    error — it is silently ignored and the connection opens read-write. That
+ *    would quietly void every "this connection never writes" guarantee in the
+ *    codebase, so the translation below is deliberate, not cosmetic.
+ *  - PRAGMAs (journal_mode, table_info) return rows through the normal
+ *    prepare()/get()/all() path on both drivers, and multi-statement `exec()`
+ *    works on both — so the tracer's schema creation and additive ALTER
+ *    migrations need no changes at all.
+ *  - `.query()` on bun:sqlite is a MEMOIZED prepare — the same SQL text
+ *    returns the same cached statement. node:sqlite's `prepare()` is not
+ *    memoized, and db.ts rebuilds its SQL per-request through an
+ *    `optionalColumn()` probe, so this shim caches by exact SQL text. That is
+ *    also *correct*: when a tracer ALTER lands mid-serve and the probed SQL
+ *    text changes, a fresh statement is prepared automatically.
+ *  - node:sqlite's `get()` returns `undefined` for no-row, not `null`; rows
+ *    come back with a null prototype. Both are normalized below so existing
+ *    `?? null` / `Object.assign(row, ...)` call sites stay honest.
+ *  - node:sqlite defaults `enableForeignKeyConstraints: true` — unlike plain
+ *    SQLite and bun:sqlite, which both default FK enforcement OFF. The
+ *    tracer's schema uses `REFERENCES` purely as documentation (rows are not
+ *    always inserted parent-before-child — e.g. the very first `events` row
+ *    for a session lands before that session's own `sessions` row commits),
+ *    so this is disabled explicitly to restore the behavior the rest of the
+ *    codebase was written against. Confirmed by reproduction: enabling it
+ *    throws `FOREIGN KEY constraint failed` on session start.
+ */
+import { DatabaseSync } from "node:sqlite";
+/**
+ * bun:sqlite accepts any JS value as a bind param; node:sqlite is typed to
+ * null/number/bigint/string/ArrayBufferView. Every current call site only
+ * ever passes strings/numbers/null, so this cast documents the narrowing
+ * this adapter is responsible for rather than widening node:sqlite's types.
+ */
+function asSqlParams(params) {
+    return params;
+}
+const STATEMENT_CACHE_LIMIT = 200;
+export class Database {
+    db;
+    statementCache = new Map();
+    constructor(path, options) {
+        this.db = new DatabaseSync(path, {
+            readOnly: options?.readonly ?? false,
+            timeout: 5000,
+            enableForeignKeyConstraints: false,
+        });
+    }
+    /** Cached prepare, keyed by exact SQL text — see the module doc comment. */
+    query(sql) {
+        let stmt = this.statementCache.get(sql);
+        if (!stmt) {
+            stmt = this.db.prepare(sql);
+            if (this.statementCache.size >= STATEMENT_CACHE_LIMIT) {
+                const oldest = this.statementCache.keys().next().value;
+                if (oldest !== undefined)
+                    this.statementCache.delete(oldest);
+            }
+            this.statementCache.set(sql, stmt);
+        }
+        return {
+            get: (...params) => {
+                guardNamedParams(params, sql);
+                const row = stmt.get(...asSqlParams(params));
+                return row === undefined ? null : { ...row };
+            },
+            all: (...params) => {
+                guardNamedParams(params, sql);
+                return stmt.all(...asSqlParams(params)).map((row) => ({ ...row }));
+            },
+            run: (...params) => {
+                guardNamedParams(params, sql);
+                const result = stmt.run(...asSqlParams(params));
+                return { changes: Number(result.changes), lastInsertRowid: result.lastInsertRowid };
+            },
+        };
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+}
+/**
+ * Every current call site passes only strings/numbers, positionally. If a
+ * future call ever passes a bare object as the first param against SQL with
+ * no named-parameter markers, node:sqlite's `allowBareNamedParameters`
+ * default would silently reinterpret it — fail loudly instead.
+ */
+function guardNamedParams(params, sql) {
+    const first = params[0];
+    const looksNamed = first !== null && typeof first === "object";
+    const sqlHasNamedMarkers = /[:$@][A-Za-z_]/.test(sql);
+    if (looksNamed && !sqlHasNamedMarkers) {
+        throw new Error(`sqlite: unexpected object parameter for a positional query: ${sql}`);
+    }
+}

package/dist/core/tracer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Tracer: every event lands in JSONL and SQLite AS IT HAPPENS.
+ *
+ * Files are the raw record; spf.db is the queryable mirror the UI polls.
+ * No push transport — the flow is always: agents -> sqlite -> web ui.
+ * WAL mode so the UI can read while ADW processes write.
+ */
+import { Database } from "./sqlite.ts";
+import type { AgentConfig, EventRecord, GateReport, Phase } from "./data_types.ts";
+export declare class Tracer {
+    db: Database;
+    dbPath: string;
+    eventsJsonl: string;
+    constructor(dbPath: string, eventsJsonl: string);
+    /** Additive column migrations, so a db from an older SPF still opens. */
+    private migrate;
+    event(record: EventRecord): string;
+    sessionStart(adwId: string, engineer: string, adwName?: string | null): void;
+    sessionRequest(adwId: string, request: string): void;
+    sessionFinish(adwId: string, ok: boolean): void;
+    sessionAddUsage(adwId: string, tokens: number, cost: number): void;
+    /**
+     * Record a live process for this run.
+     *
+     * A coding agent that hangs produces no events at all, which is exactly
+     * when you need its pid — and `ps` cannot tell you which adw_id it
+     * belongs to. Writing it here makes the trace the answer to "what is this
+     * run running, and how do I stop it".
+     */
+    processStart(adwId: string, kind: string, name: string, pid: number, command: string): void;
+    /** Mark the newest live row for this pid as finished. */
+    processEnd(adwId: string, pid: number): void;
+    /** Close out every live row for a run — called when the session ends. */
+    processesEndAll(adwId: string): void;
+    /**
+     * Highest seq already recorded for this session; 0 when it is new.
+     *
+     * A joined run continues the sequence instead of restarting at 1 — which
+     * would collide with the first run's phases on both `seq` (breaking
+     * ordering) and `phase_id` (silently overwriting a row through the
+     * phase_upsert conflict clause).
+     */
+    maxPhaseSeq(adwId: string): number;
+    phaseUpsert(phase: Phase): void;
+    envelopeRow(phase: Phase, agent: string, outputType: string, payloadJson: string, valid: boolean, attempt: number): void;
+    /** The report carries both the verdict and the evidence behind it. */
+    gateRow(phase: Phase, gate: string, report: GateReport, attempt: number): void;
+    /**
+     * The agent's config row is the source of truth for its label and color.
+     *
+     * Context is carried here rather than derived from events because the lane
+     * wants one number per agent — the latest — and a session that runs the
+     * same agent twice overwrites it, exactly like model and session_id.
+     */
+    agentSessionRow(adwId: string, agent: AgentConfig, sessionId: string, contextTokens?: number, contextWindow?: number): void;
+}