@gr8ful/spf 0.1.0

package/dist/core/agents.js

@@ -0,0 +1,456 @@
+/**
+ * Config loading/validation and agent execution.
+ *
+ * Every ADW validates its agents before running (fail fast, nothing spawns
+ * against a half-valid config). Every agent call parses against a concrete
+ * output type; parse failures and gate violations re-prompt the SAME session
+ * with a correction — context intact, bounded retries. Agent proposes, code
+ * disposes.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import * as v from "valibot";
+import * as agentCc from "./agent_cc.js";
+import * as agentFlue from "./agent_flue.js";
+import * as paths from "./paths.js";
+import * as permissions from "./permissions.js";
+import * as prompts from "./prompts.js";
+import { GateReport, UsageBreakdown, makeEventRecord, SFConfigSchema, } from "./data_types.js";
+import { newId } from "./utils.js";
+const JSON_FIX_ATTEMPTS = 2; // continue-with-correction attempts for malformed JSON
+export class GateFailure extends Error {
+}
+/**
+ * A ValiError's own `.message` is only its FIRST issue — fine for a quick
+ * console line, not for something a human has to act on or a model has to
+ * repair. `v.flatten()` gives every issue, keyed by field path; this renders
+ * that as one line per field. Any other error (e.g. JSON.parse's
+ * SyntaxError) falls back to its plain message, unchanged.
+ */
+function describeParseError(error) {
+    if (!(error instanceof v.ValiError)) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    const flat = v.flatten(error.issues);
+    const lines = [];
+    if (flat.root)
+        lines.push(...flat.root);
+    if (flat.nested) {
+        for (const [field, messages] of Object.entries(flat.nested)) {
+            for (const message of messages ?? [])
+                lines.push(`${field}: ${message}`);
+        }
+    }
+    return lines.length > 0 ? lines.join("; ") : error.message;
+}
+// ── config ───────────────────────────────────────────────────────────────────
+/** Same-name agents patch (shallow field overwrite); new names append. */
+function mergeAgentLists(base, override) {
+    const merged = base.map((agent) => ({ ...agent }));
+    for (const overrideAgent of override) {
+        const i = merged.findIndex((a) => a.name === overrideAgent.name);
+        if (i === -1)
+            merged.push({ ...overrideAgent });
+        else
+            merged[i] = { ...merged[i], ...overrideAgent };
+    }
+    return merged;
+}
+/** `defaults`/`observability`/`quality` merge key-by-key; `agents` merges by name. */
+function mergeRawConfig(base, override) {
+    return {
+        defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
+        observability: { ...(base.observability || {}), ...(override.observability || {}) },
+        quality: { ...(base.quality || {}), ...(override.quality || {}) },
+        watch: { ...(base.watch || {}), ...(override.watch || {}) },
+        agents: mergeAgentLists(base.agents || [], override.agents || []),
+    };
+}
+/**
+ * Load and merge every existing path in `configPaths`, in order — later
+ * paths override earlier ones. Built-in defaults first, an optional `.spf/`
+ * override second is the normal case; a single explicit `--config` path
+ * (the caller passes just that one path, no built-in) is used standalone.
+ * A path that doesn't exist is silently skipped, EXCEPT that if none of them
+ * exist the result is an all-defaults config — every field has a schema
+ * default, so this degrades to "zero agents defined" rather than a crash,
+ * and agents.validate() reports that plainly.
+ */
+export function loadConfig(configPaths) {
+    let raw = {};
+    for (const configPath of configPaths) {
+        if (!existsSync(configPath))
+            continue;
+        const parsed = parseYaml(readFileSync(configPath, "utf-8")) || {};
+        raw = mergeRawConfig(raw, parsed);
+    }
+    const defaults = raw.defaults || {};
+    for (const agent of raw.agents || []) {
+        for (const key of ["coding_agent", "model", "thinking", "color", "tools", "writes"]) {
+            if (key in defaults && !(key in agent))
+                agent[key] = defaults[key];
+        }
+        if (!("harness_engineering" in agent))
+            agent.harness_engineering = defaults.harness_engineering || [];
+    }
+    try {
+        return v.parse(SFConfigSchema, raw);
+    }
+    catch (error) {
+        throw new Error(`invalid config (${configPaths.join(", ")}): ${describeParseError(error)}`);
+    }
+}
+export function resolve(cfg, name) {
+    const agent = cfg.agents.find((a) => a.name === name);
+    if (!agent) {
+        throw new Error(`agent ${JSON.stringify(name)} is not defined in the config — available: ${JSON.stringify(cfg.agents.map((a) => a.name))}`);
+    }
+    return agent;
+}
+/** Fail fast: every required name must resolve to a usable agent. */
+export function validate(cfg, required, requiredSuites = [], cwd) {
+    const anchor = paths.resolveAnchor(cwd);
+    const problems = [];
+    for (const suiteName of requiredSuites) {
+        const names = cfg.quality.suites[suiteName];
+        if (!names || names.length === 0) {
+            problems.push(`quality.suites.${JSON.stringify(suiteName)} is not configured — add it to spf.config.yaml before running a chain that needs it`);
+            continue;
+        }
+        const missing = names.filter((n) => !cfg.quality.checks.some((c) => c.name === n));
+        if (missing.length > 0) {
+            problems.push(`quality.suites.${suiteName} names check(s) not in quality.checks: ${missing.join(", ")}`);
+        }
+    }
+    for (const name of required) {
+        let agent;
+        try {
+            agent = resolve(cfg, name);
+        }
+        catch (error) {
+            problems.push(error.message);
+            continue;
+        }
+        for (const [label, ref] of [
+            ["system", agent.prompt_engineering.system],
+            ["user", agent.prompt_engineering.user],
+        ]) {
+            try {
+                paths.resolvePromptRef(anchor, ref);
+            }
+            catch (error) {
+                problems.push(`agent ${JSON.stringify(name)}: ${label} ${error.message}`);
+            }
+        }
+        // Model shape depends on the backend: Flue needs provider/model-id (no
+        // catalog to check against, only the static shape); claude_code takes
+        // its own bare alias/full-name vocabulary (see agent_cc.ts), so only a
+        // non-empty check applies.
+        if (agent.coding_agent === "flue") {
+            try {
+                agentFlue.resolveModel(agent.model);
+            }
+            catch (error) {
+                problems.push(`agent ${JSON.stringify(name)}: ${error.message}`);
+            }
+        }
+        else if (!agent.model.trim()) {
+            problems.push(`agent ${JSON.stringify(name)}: model is empty`);
+        }
+        // harness_engineering (pi -e extensions) has no analogue on any current
+        // backend — a subagent/skill built the same way is
+        // useSubagent()/defineSkill() (Flue) or an MCP server/plugin (Claude
+        // Code) inside a custom tool, not a config path. Fail loudly rather
+        // than silently loading nothing.
+        if (agent.harness_engineering.length > 0) {
+            problems.push(`agent ${JSON.stringify(name)}: harness_engineering is not supported (${JSON.stringify(agent.harness_engineering)}) — ` +
+                `use useSubagent()/defineSkill() (flue) or an MCP server/plugin (claude_code) in a custom tool instead`);
+        }
+        const isKnownToolName = agent.coding_agent === "claude_code" ? agentCc.isKnownToolName : agentFlue.isKnownToolName;
+        for (const toolName of agent.tools ?? []) {
+            if (!isKnownToolName(toolName)) {
+                problems.push(`agent ${JSON.stringify(name)}: unknown tool ${JSON.stringify(toolName)} — known: read, write, edit, bash, grep, glob, find (alias for glob), ls (dropped, covered by bash/glob)`);
+            }
+        }
+    }
+    if (problems.length > 0) {
+        throw new Error("config validation failed:\n- " + problems.join("\n- "));
+    }
+}
+/** One agent call: render prompts -> pi run -> typed parse -> gates -> envelope. */
+export async function execute(run, phase, call) {
+    const agent = resolve(run.cfg, phase.params.owner);
+    const agentDir = path.join(run.session_dir, agent.name);
+    mkdirSync(agentDir, { recursive: true });
+    const variables = {
+        prompt: call.prompt,
+        previous_envelope: call.previous ? JSON.stringify(call.previous, null, 2) : "(none)",
+        context_handoff_dir: run.context_handoff_dir,
+    };
+    const systemText = prompts.render(paths.resolvePromptRef(run, agent.prompt_engineering.system), variables);
+    const userText = prompts.render(paths.resolvePromptRef(run, agent.prompt_engineering.user), variables);
+    prompts.save(path.join(agentDir, "prompts"), "system.md", systemText);
+    prompts.save(path.join(agentDir, "prompts"), "user.md", userText);
+    const { session_id: sessionId, is_new: isNewSession } = agentSessionId(run, agent);
+    run.tracer.event(makeEventRecord({
+        adw_id: run.adw_id,
+        phase_id: phase.phase_id,
+        type: "agent_start",
+        name: agent.name,
+        payload: {
+            model: agent.model,
+            thinking: agent.thinking,
+            color: agent.color,
+            session_id: sessionId,
+            coding_agent: agent.coding_agent,
+            purpose: agent.purpose,
+            tools: agent.tools ?? null, // null = all tools
+            harness_engineering: agent.harness_engineering,
+        },
+    }));
+    run.console.agentStarted(agent.name, agent.model, sessionId);
+    // Parse retries and gate corrections re-enter the SAME Flue conversation,
+    // so the last send is the one whose context occupancy is current — while
+    // spend is the opposite: every send costs, so usage accumulates across all.
+    let latest = null;
+    const spent = new UsageBreakdown();
+    async function send(promptText) {
+        const request = {
+            prompt: promptText,
+            system_prompt: systemText,
+            model: agent.model,
+            thinking: agent.thinking,
+            session_id: sessionId,
+            resume: !isNewSession,
+            tools: agent.tools ?? undefined,
+            output_schema: call.output_type.schema,
+            output_type_name: call.output_type.name,
+            cwd: run.repo_root,
+            flue_db_path: path.join(run.data_dir, "flue.db"),
+        };
+        const forward = eventForwarder(run, phase, agent.name, agent.coding_agent);
+        const onSpawn = (pid) => run.tracer.processStart(run.adw_id, "agent", agent.name, pid, `${agent.coding_agent} ${agent.name} ${agent.model}`);
+        const onExit = (pid) => run.tracer.processEnd(run.adw_id, pid);
+        const result = agent.coding_agent === "claude_code"
+            ? await agentCc.run(request, forward, onSpawn, onExit)
+            : await agentFlue.run(request, forward, onSpawn, onExit);
+        run.addUsage(result.tokens, result.cost);
+        spent.merge(result.usage);
+        latest = result;
+        return result;
+    }
+    // What the tree looked like before this agent got its hands on it. Every
+    // send in this phase — first prompt, JSON retries, gate corrections — is
+    // measured against this one baseline.
+    const treeBefore = permissions.snapshot(run);
+    let result = await send(userText);
+    let parsed = await parseWithRetries(run, phase, call, result, send);
+    let envelope = parsed.envelope;
+    // claim gates — violations flow back into the SAME session as corrections
+    for (let gateAttempt = 1; gateAttempt <= Math.max(1, phase.params.retries + 1); gateAttempt++) {
+        const violations = [];
+        for (const gate of call.gates || []) {
+            const report = asReport(gate(envelope, run));
+            const found = report.violations;
+            run.tracer.gateRow(phase, gate.name, report, gateAttempt);
+            run.tracer.event(makeEventRecord({
+                adw_id: run.adw_id,
+                phase_id: phase.phase_id,
+                type: found.length > 0 ? "gate_fail" : "gate_pass",
+                name: gate.name,
+                payload: { attempt: gateAttempt, violations: found, checks: report.checks },
+            }));
+            run.console.gateResult(gate.name, report);
+            violations.push(...found);
+        }
+        if (violations.length === 0)
+            break;
+        if (gateAttempt > phase.params.retries) {
+            throw new GateFailure(`${agent.name} failed gates after ${gateAttempt} attempt(s):\n- ` + violations.join("\n- "));
+        }
+        phase.attempt = gateAttempt;
+        run.console.retry(agent.name, gateAttempt, phase.params.retries, `${violations.length} gate violation(s)`);
+        const correction = "Your previous response failed validation:\n- " +
+            violations.join("\n- ") +
+            "\n\nFix these problems, then re-emit ONLY your Report JSON.";
+        result = await send(correction);
+        parsed = await parseWithRetries(run, phase, call, result, send);
+        envelope = parsed.envelope;
+    }
+    // Permission is checked after every send is done, and before the envelope is
+    // accepted: an agent does not get to report success on a phase in which it
+    // wrote somewhere it was not allowed to.
+    let touched;
+    try {
+        touched = permissions.enforce(run, phase, agent, treeBefore);
+    }
+    catch (breach) {
+        run.tracer.event(makeEventRecord({
+            adw_id: run.adw_id,
+            phase_id: phase.phase_id,
+            type: "error",
+            name: "permission_breach",
+            payload: {
+                agent: agent.name,
+                error: breach.message,
+                writes: agent.writes ?? null,
+                protected_files: run.cfg.defaults.protected_files,
+            },
+        }));
+        throw breach;
+    }
+    if (touched.length > 0) {
+        run.tracer.event(makeEventRecord({
+            adw_id: run.adw_id,
+            phase_id: phase.phase_id,
+            type: "log",
+            name: "paths_touched",
+            payload: { agent: agent.name, paths: touched },
+        }));
+    }
+    persistEnvelope(run, phase, agent.name, call, envelope, parsed.attempt, true);
+    run.console.envelopeSummary(envelope, call.output_type.name);
+    const context = latest ?? result;
+    run.tracer.agentSessionRow(run.adw_id, agent, sessionId, context.context_tokens, context.context_window);
+    run.saveAgentMap(agent.name, { session_id: sessionId, model: agent.model, coding_agent: agent.coding_agent });
+    run.tracer.event(makeEventRecord({
+        adw_id: run.adw_id,
+        phase_id: phase.phase_id,
+        type: "handoff",
+        name: agent.name,
+        payload: { artifacts: envelope.artifacts, summary: envelope.summary },
+    }));
+    run.tracer.event(makeEventRecord({
+        adw_id: run.adw_id,
+        phase_id: phase.phase_id,
+        type: "agent_end",
+        name: agent.name,
+        // Phase totals, not the last send's: a retried phase paid for every attempt.
+        tokens: spent.total_tokens,
+        payload: {
+            cost: spent.total_cost,
+            usage: spent.toJSON(),
+            context_tokens: context.context_tokens,
+            context_window: context.context_window,
+        },
+    }));
+    run.console.agentFinished(agent.name, spent.total_tokens, spent.total_cost);
+    if (envelope.status !== "success") {
+        throw new Error(`${agent.name} reported status=${JSON.stringify(envelope.status)}: ${envelope.summary}`);
+    }
+    return envelope;
+}
+/** Accept a GateReport, or a legacy gate that returned a violations list. */
+function asReport(result) {
+    if (result instanceof GateReport)
+        return result;
+    const report = new GateReport();
+    for (const v of result || [])
+        report.check(String(v), false);
+    return report;
+}
+/**
+ * `is_new` is Flue's own affair to ignore (its `init(agent, {id})` is
+ * unconditionally create-or-continue) but `claude_code` needs it explicitly
+ * — its CLI has no single create-or-continue flag, only `--session-id`
+ * (first contact) vs `--resume` (rejoin), so `send()` threads this through
+ * as `AgentRequest.resume`.
+ */
+function agentSessionId(run, agent) {
+    const entry = run.agent_map[agent.name];
+    if (entry && entry.model === agent.model)
+        return { session_id: entry.session_id, is_new: false }; // rejoin the existing context window
+    const session_id = agent.coding_agent === "claude_code" ? agentCc.newSessionId() : `spf-${run.adw_id}-${agent.name}-${newId(4)}`;
+    return { session_id, is_new: true };
+}
+/**
+ * One tool_call event per real tool call, with its exact args and result.
+ * Picks the tracker for whichever backend this agent runs on — each
+ * backend's own module owns the ONE fold point for its raw event shape, so
+ * this stays a plain pass-through regardless of which one it's given.
+ */
+function eventForwarder(run, phase, agentName, codingAgent) {
+    const tracker = codingAgent === "claude_code" ? new agentCc.CcToolCallTracker() : new agentFlue.ToolCallTracker();
+    return (chunk) => {
+        const record = tracker.observe(chunk);
+        if (record === null)
+            return;
+        // The call's span rides the columns; duration_ms stays in the payload as
+        // Flue's own authoritative number.
+        const { label, started_at, ended_at, ...rest } = record;
+        run.tracer.event(makeEventRecord({
+            adw_id: run.adw_id,
+            phase_id: phase.phase_id,
+            type: "tool_call",
+            name: label,
+            started_at: started_at ?? null,
+            ended_at: ended_at ?? null,
+            payload: { ...rest, agent: agentName },
+        }));
+    };
+}
+function extractJson(text) {
+    let candidate = text;
+    if (text.includes("```")) {
+        const parts = text.split("```");
+        for (let i = 1; i < parts.length; i += 2) {
+            let block = parts[i];
+            if (block.startsWith("json"))
+                block = block.slice(4);
+            block = block.trim();
+            if (block.startsWith("{")) {
+                candidate = block;
+                break;
+            }
+        }
+    }
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        throw new Error("no JSON object found in the response");
+    return JSON.parse(candidate.slice(start, end + 1));
+}
+/**
+ * Parse the final response against the declared output type; on failure,
+ * continue the SAME session with a correction (bounded).
+ */
+async function parseWithRetries(run, phase, call, result, send) {
+    let current = result;
+    for (let attempt = 1; attempt <= JSON_FIX_ATTEMPTS + 1; attempt++) {
+        try {
+            // The model may never call sf_report at all (plain text + stop) — fall
+            // back to extracting JSON from the text in that case, same as before.
+            const payload = current.report ?? extractJson(current.text);
+            const envelope = v.parse(call.output_type.schema, payload);
+            return { envelope, attempt };
+        }
+        catch (error) {
+            const message = describeParseError(error);
+            persistEnvelope(run, phase, phase.params.owner, call, null, attempt, false, current.text);
+            if (attempt > JSON_FIX_ATTEMPTS) {
+                throw new Error(`${phase.params.owner} never produced valid ${call.output_type.name} JSON: ${message}`);
+            }
+            run.console.retry(phase.params.owner, attempt, JSON_FIX_ATTEMPTS, `invalid ${call.output_type.name} JSON: ${message}`);
+            const fields = call.output_type.fields.join(", ");
+            current = await send(`Your response was not valid JSON for the required structure ` +
+                `(${message}). Respond again with ONLY a JSON object with these ` +
+                `fields: ${fields}. No prose, no code fences.`);
+        }
+    }
+    throw new Error("unreachable");
+}
+function persistEnvelope(run, phase, agentName, call, envelope, attempt, valid, raw = "") {
+    const payloadJson = envelope ? JSON.stringify(envelope, null, 2) : JSON.stringify({ raw: raw.slice(-2000) });
+    run.tracer.envelopeRow(phase, agentName, call.output_type.name, payloadJson, valid, attempt);
+    if (envelope) {
+        const record = {
+            agent_name: agentName,
+            purpose: resolve(run.cfg, agentName).purpose,
+            output_type: call.output_type.name,
+            attempt,
+            ...envelope,
+        };
+        writeFileSync(path.join(run.session_dir, agentName, "envelope.json"), JSON.stringify(record, null, 2));
+    }
+}

package/dist/core/changes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Deterministic change capture: what was built, straight from git.
+ *
+ * "What changed since main" is not a judgement call — it is two git commands and
+ * a subtraction. So it is code, and an agent is only handed the result. The
+ * capture writes the full diff into `context_handoff/` and returns a ChangeSet;
+ * `asEnvelope` adapts that into the one door every agent handoff uses.
+ *
+ * The base is resolved, not assumed. Off the base branch the diff covers the
+ * whole branch plus the working tree; on it, the uncommitted tree; and on a clean
+ * tree, the last commit — because "document the work that was just done" still
+ * has an answer right after a chain committed. Whichever it picked rides along in
+ * `BaseRef.reason`, so the trace never leaves you guessing what a diff was
+ * measured against.
+ */
+import { type GitHandle } from "./git_helper.ts";
+import { BaseRef, ChangeSet, type ChangeCapture, type ChangesOutputT } from "./data_types.ts";
+interface RunLike {
+    context_handoff_dir: string;
+    repo_root: string;
+    git: GitHandle;
+}
+/** Pick the commit the work is measured from, and record why that one. */
+export declare function resolveBase(run: RunLike, ref: string): BaseRef;
+/** Diff the working tree against the resolved base and persist the evidence. */
+export declare function capture(run: RunLike, params: ChangeCapture): ChangeSet;
+/**
+ * Wrap a captured change so an agent can be handed it directly.
+ *
+ * Pure formatting over an already-captured ChangeSet — no `run`, no git
+ * call. `commit` is always a full sha here, so it's shortened the same way
+ * `BaseRef.label` shortens a pinned ref: a slice, not another subprocess.
+ */
+export declare function asEnvelope(changes: ChangeSet, notes?: string): ChangesOutputT;
+export {};

package/dist/core/changes.js

@@ -0,0 +1,98 @@
+/**
+ * Deterministic change capture: what was built, straight from git.
+ *
+ * "What changed since main" is not a judgement call — it is two git commands and
+ * a subtraction. So it is code, and an agent is only handed the result. The
+ * capture writes the full diff into `context_handoff/` and returns a ChangeSet;
+ * `asEnvelope` adapts that into the one door every agent handoff uses.
+ *
+ * The base is resolved, not assumed. Off the base branch the diff covers the
+ * whole branch plus the working tree; on it, the uncommitted tree; and on a clean
+ * tree, the last commit — because "document the work that was just done" still
+ * has an answer right after a chain committed. Whichever it picked rides along in
+ * `BaseRef.reason`, so the trace never leaves you guessing what a diff was
+ * measured against.
+ */
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import * as v from "valibot";
+import { isRepoAt } from "./git_helper.js";
+import { BaseRef, ChangeSet, ChangesOutput } from "./data_types.js";
+const DIFF_FILENAME = "changes.diff";
+/** Pick the commit the work is measured from, and record why that one. */
+export function resolveBase(run, ref) {
+    if (!isRepoAt(run.repo_root)) {
+        throw new Error("not a git repository — change capture needs one. Run `git init` in " +
+            "the repo root before running an ADW that documents a change.");
+    }
+    if (!run.git.refExists(ref)) {
+        throw new Error(`base ref ${JSON.stringify(ref)} does not exist in this repository — pass --base ` +
+            `with a ref that does (e.g. --base master, --base HEAD~1).`);
+    }
+    // Built first, then given its reason: BaseRef.label knows how to print a
+    // pinned sha, and the reason is the line a human reads in the trace.
+    const base = new BaseRef(ref, run.git.mergeBase(ref, "HEAD"));
+    if (run.git.shortSha(base.commit) !== run.git.shortSha("HEAD")) {
+        base.reason = `HEAD is ahead of ${base.label} — diffing every commit since, plus the working tree`;
+    }
+    else if (run.git.isDirty()) {
+        base.reason = `HEAD is on ${base.label} — diffing the uncommitted working tree`;
+    }
+    else if (run.git.refExists("HEAD~1")) {
+        base.commit = run.git.rev("HEAD~1");
+        base.reason = `HEAD is on ${base.label} with a clean tree — falling back to the last commit`;
+    }
+    else {
+        base.reason = `HEAD is on ${base.label} with a clean tree and no parent commit`;
+    }
+    return base;
+}
+/** Diff the working tree against the resolved base and persist the evidence. */
+export function capture(run, params) {
+    const base = resolveBase(run, params.base);
+    const files = run.git.diffFiles(base.commit);
+    const untracked = params.include_untracked ? run.git.untrackedFiles() : [];
+    const [insertions, deletions] = run.git.diffCounts(base.commit);
+    const stat = run.git.diffStat(base.commit);
+    let text = run.git.diffText(base.commit);
+    const lines = text.split("\n");
+    const truncated = lines.length > params.max_diff_lines;
+    if (truncated) {
+        text = lines.slice(0, params.max_diff_lines).join("\n");
+        text += `\n\n[truncated at ${params.max_diff_lines} lines of ${lines.length} — run \`git diff ${base.commit}\` for the rest]`;
+    }
+    // Untracked files are absent from `git diff` by construction, so they are
+    // named here rather than silently missing from the record. The reader has
+    // `read` and can open any of them.
+    const untrackedBlock = untracked.length > 0 ? untracked.map((f) => `  ${f}`).join("\n") : "  (none)";
+    const diffPath = path.join(run.context_handoff_dir, DIFF_FILENAME);
+    writeFileSync(diffPath, `# changes since ${base.label} @ ${run.git.shortSha(base.commit)}\n` +
+        `# ${base.reason}\n` +
+        `# +${insertions} -${deletions} across ${files.length} tracked file(s)\n\n` +
+        `## stat\n${stat || "  (no tracked changes)"}\n\n` +
+        `## untracked files\n${untrackedBlock}\n\n` +
+        `## diff\n${text}\n`);
+    return new ChangeSet(base, files, untracked, insertions, deletions, stat, diffPath, truncated);
+}
+/**
+ * Wrap a captured change so an agent can be handed it directly.
+ *
+ * Pure formatting over an already-captured ChangeSet — no `run`, no git
+ * call. `commit` is always a full sha here, so it's shortened the same way
+ * `BaseRef.label` shortens a pinned ref: a slice, not another subprocess.
+ */
+export function asEnvelope(changes, notes = "") {
+    const total = changes.files.length + changes.untracked.length;
+    return v.parse(ChangesOutput.schema, {
+        status: "success",
+        summary: `${total} file(s) changed since ${changes.base.label} (+${changes.insertions} -${changes.deletions})`,
+        artifacts: [changes.diff_path],
+        notes_for_next_agent: notes,
+        base: `${changes.base.label} @ ${changes.base.commit.slice(0, 7)} — ${changes.base.reason}`,
+        changed_files: [...changes.files, ...changes.untracked],
+        insertions: changes.insertions,
+        deletions: changes.deletions,
+        stat: changes.stat,
+        diff_path: changes.diff_path,
+    });
+}

package/dist/core/console.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Console reporter: one narrative, two destinations.
+ *
+ * Every line an ADW prints ALSO lands in the db as a `log` event, so the swim-lane
+ * UI reads the same story the terminal does. Both go through `emit` — print and
+ * trace cannot drift. Plain sequential lines only: no spinners, no live displays,
+ * so a CI log reads exactly like a terminal.
+ */
+import type { EnvelopeBase, EventRecord, GateReport, Phase } from "./data_types.ts";
+interface Tracer {
+    event(record: EventRecord): string;
+}
+/** Bound to one run's tracer. Reachable as `run.console` everywhere. */
+export declare class Console {
+    private tracer;
+    private adwId;
+    private phaseId;
+    private phaseName;
+    private results;
+    private finished;
+    constructor(tracer: Tracer, adwId: string);
+    private emit;
+    sessionStarted(adwId: string, engineer: string): void;
+    sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): void;
+    phaseStarted(phase: Phase): void;
+    phaseEnded(phase: Phase, seconds: number): void;
+    /** Free-form detail inside the current phase — what `ph.log()` recorded. */
+    note(message: string): void;
+    agentStarted(name: string, model: string, sessionId: string): void;
+    agentFinished(name: string, tokens: number, cost: number): void;
+    retry(name: string, attempt: number, limit: number, reason: string): void;
+    /** A gate reports WHAT it checked, not just whether it passed. */
+    gateResult(name: string, report: GateReport): void;
+    envelopeSummary(envelope: EnvelopeBase, typeName: string): void;
+}
+export {};