@lchase/kiln 0.8.0 → 0.10.0

package/dist/fix-commit.js

@@ -0,0 +1,73 @@
+import { spawnSync } from "node:child_process";
+export function fixTrailerLines(input) {
+    return [`Kiln-Job: ${input.jobId}`, `Kiln-Round: ${input.round}`, `Kiln-Prompts-Hash: ${input.promptsHash}`];
+}
+/**
+ * The fix workflow `land` step. `workflows/fix.yaml` keeps the same command.
+ * Launch sets `KILN_JOB`, `KILN_ROUND`, and `KILN_PROMPTS_HASH`.
+ */
+export const FIX_LAND_COMMAND = 'git add -A && git diff --cached --quiet || git commit -m "kiln: $KILN_TASK_TITLE" --trailer "Kiln-Job: $KILN_JOB" --trailer "Kiln-Round: $KILN_ROUND" --trailer "Kiln-Prompts-Hash: $KILN_PROMPTS_HASH"';
+/**
+ * Make the tip of `dir` carry the fix-round trailers.
+ * A dirty tree is committed. A tip that already moved and lacks the trailers
+ * is amended. A clean tree still on `baseSha` is left alone.
+ */
+export function ensureFixTrailers(dir, input, baseSha) {
+    if (!hasTrailers(dir, input)) {
+        if (isDirty(dir)) {
+            commit(dir, input, false);
+            return "committed";
+        }
+        const head = revParse(dir, "HEAD");
+        if (!head || (baseSha && head === baseSha))
+            return "clean";
+        commit(dir, input, true);
+        return "amended";
+    }
+    return "present";
+}
+export function commitMessageHasTrailers(message, input) {
+    return fixTrailerLines(input).every((line) => message.split("\n").some((entry) => entry.trim() === line));
+}
+function hasTrailers(dir, input) {
+    const message = git(dir, ["log", "-1", "--format=%B"]);
+    if (message.status !== 0)
+        return false;
+    return commitMessageHasTrailers(message.stdout, input);
+}
+function isDirty(dir) {
+    const status = git(dir, ["status", "--porcelain"]);
+    if (status.status !== 0)
+        return false;
+    return status.stdout.trim().length > 0;
+}
+function revParse(dir, ref) {
+    const result = git(dir, ["rev-parse", ref]);
+    if (result.status !== 0)
+        return undefined;
+    const sha = result.stdout.trim();
+    return sha || undefined;
+}
+function commit(dir, input, amend) {
+    if (!amend) {
+        const added = git(dir, ["add", "-A"]);
+        if (added.status !== 0)
+            return;
+    }
+    const args = ["commit"];
+    if (amend)
+        args.push("--amend", "--no-edit");
+    else
+        args.push("-m", `kiln: ${input.title}`);
+    for (const line of fixTrailerLines(input))
+        args.push("--trailer", line);
+    git(dir, args);
+}
+function git(cwd, args) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}

package/dist/jobs.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join } from "node:path";
+import { appendEvent } from "./events.js";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { jobBasename } from "./paths.js";
 import { JobSchema, parseIssueKey } from "./schemas.js";
@@ -88,6 +89,17 @@ export function writeJob(config, input) {
     mkdirSync(config.jobsDir, { recursive: true });
     const jsonPath = jobFilePath(config.jobsDir, job.id);
     writeFileSync(jsonPath, `${JSON.stringify(job, null, 2)}\n`);
+    appendEvent(config.kilnDir, {
+        job_id: job.id,
+        event: "job.added",
+        properties: {
+            repo: job.repo,
+            workflow: job.workflow,
+            title: job.title,
+            ...(job.source ? { source_kind: job.source.kind } : {}),
+            once: "job.added",
+        },
+    });
     return { job, jsonPath };
 }
 export function renderAddedJob(job, jsonPath) {

package/dist/ledger.js

@@ -0,0 +1,152 @@
+import { readEvents } from "./events.js";
+import { redact } from "./redact.js";
+import { formatSpend, spendSnapshot } from "./rails.js";
+/**
+ * Interventions are derived from the event log. Nothing is stored beside it.
+ * A human had to act when a gate was rejected, a job was retried by hand,
+ * a gate carried a manual edit note, or the job stopped as needs-human.
+ */
+const SINCE = /^(\d+)([dhms])$/;
+const REASON_RANK = ["gate rejected", "manual edit", "re-queued or retried by hand"];
+/** `7d`, `12h`, `30m`, `45s`, or an ISO-8601 time. */
+export function parseSince(raw, now = new Date()) {
+    const match = SINCE.exec(raw.trim());
+    if (match?.[1] && match[2]) {
+        const count = Number(match[1]);
+        const unit = match[2];
+        const ms = unit === "d" ? 86_400_000 : unit === "h" ? 3_600_000 : unit === "m" ? 60_000 : 1_000;
+        return new Date(now.getTime() - count * ms);
+    }
+    const parsed = Date.parse(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`--since ${JSON.stringify(raw)} is not a duration like 7d or an ISO-8601 time.`);
+    }
+    return new Date(parsed);
+}
+export function ledgerRows(events, options = {}) {
+    const repos = repoByJob(events);
+    const counts = new Map();
+    for (const event of events) {
+        if (!event.job_id)
+            continue;
+        if (options.since && Date.parse(event.ts) < options.since.getTime())
+            continue;
+        const repo = repos.get(event.job_id) ?? "(no repo)";
+        if (options.repo !== undefined && repo !== options.repo)
+            continue;
+        for (const reason of reasonsFor(event)) {
+            const jobs = counts.get(repo) ?? new Map();
+            const key = `${event.job_id}\0${reason}`;
+            jobs.set(key, (jobs.get(key) ?? 0) + 1);
+            counts.set(repo, jobs);
+        }
+    }
+    const rows = [];
+    for (const repo of [...counts.keys()].sort()) {
+        const jobs = counts.get(repo);
+        if (!jobs)
+            continue;
+        const byJob = new Map();
+        for (const [key, count] of jobs) {
+            const split = key.indexOf("\0");
+            const jobId = key.slice(0, split);
+            const reason = key.slice(split + 1);
+            const list = byJob.get(jobId) ?? [];
+            list.push({ reason, count });
+            byJob.set(jobId, list);
+        }
+        for (const jobId of [...byJob.keys()].sort()) {
+            const reasons = byJob.get(jobId) ?? [];
+            reasons.sort((left, right) => rank(left.reason) - rank(right.reason) || left.reason.localeCompare(right.reason));
+            const total = reasons.reduce((sum, item) => sum + item.count, 0);
+            rows.push({ repo, jobId, reasons, total });
+        }
+    }
+    return rows;
+}
+export function renderLedger(events, options = {}) {
+    const spend = options.spend ??
+        (options.dailyDollarCap !== undefined || options.now
+            ? spendSnapshot(events, options.dailyDollarCap, options.now ?? new Date())
+            : undefined);
+    const head = spend ? `${formatSpend(spend)}\n` : "";
+    const rows = ledgerRows(events, options);
+    if (rows.length === 0)
+        return redact(`${head}0 interventions\n`);
+    const lines = [];
+    let grand = 0;
+    let index = 0;
+    while (index < rows.length) {
+        const repo = rows[index]?.repo ?? "";
+        const group = [];
+        while (index < rows.length && rows[index]?.repo === repo) {
+            const row = rows[index];
+            if (row)
+                group.push(row);
+            index += 1;
+        }
+        const repoTotal = group.reduce((sum, row) => sum + row.total, 0);
+        lines.push(`${repo}  ${repoTotal}`);
+        for (const row of group) {
+            lines.push(`  ${row.jobId}  ${row.total}`);
+            for (const reason of row.reasons)
+                lines.push(`    ${reason.reason}  ${reason.count}`);
+        }
+        grand += repoTotal;
+    }
+    lines.push("");
+    lines.push(`${grand} ${grand === 1 ? "intervention" : "interventions"}`);
+    return redact(`${head}${lines.join("\n")}\n`);
+}
+export function renderLedgerFile(kilnDir, options = {}) {
+    const events = readEvents(kilnDir);
+    const spend = spendSnapshot(events, options.dailyDollarCap, options.now ?? new Date());
+    return renderLedger(events, { ...options, spend });
+}
+function reasonsFor(event) {
+    const reasons = [];
+    if (event.event === "gate.resolved" && event.properties.decision === "reject")
+        reasons.push("gate rejected");
+    if ((event.event === "gate.resolved" || event.event === "gate.opened") && hasEdit(event.properties)) {
+        reasons.push("manual edit");
+    }
+    if (event.event === "job.retried")
+        reasons.push("re-queued or retried by hand");
+    if (event.event === "needs-human")
+        reasons.push(`needs-human (${event.properties.reason})`);
+    return reasons;
+}
+function hasEdit(properties) {
+    return Boolean(properties.note?.trim() || properties.edit?.trim());
+}
+function repoByJob(events) {
+    const repos = new Map();
+    for (const event of events) {
+        if (event.event === "job.added" && event.job_id)
+            repos.set(event.job_id, event.properties.repo);
+    }
+    for (const event of events) {
+        if (!event.job_id || repos.has(event.job_id))
+            continue;
+        const repo = repoOf(event);
+        if (repo)
+            repos.set(event.job_id, repo);
+    }
+    return repos;
+}
+function repoOf(event) {
+    if (event.event === "job.added" || event.event === "job.retried" || event.event === "run.started") {
+        return event.properties.repo;
+    }
+    if (event.event === "gate.resolved")
+        return event.properties.repo;
+    return undefined;
+}
+function rank(reason) {
+    const index = REASON_RANK.indexOf(reason);
+    if (index >= 0)
+        return index;
+    if (reason.startsWith("needs-human"))
+        return REASON_RANK.length;
+    return REASON_RANK.length + 1;
+}

package/dist/project.js

@@ -0,0 +1,394 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, join, relative, sep } from "node:path";
+import { appendEvent } from "./events.js";
+import { costFromJournal, decideFailure } from "./failure.js";
+import { jobBasename, packageRoot } from "./paths.js";
+/**
+ * Project a yak journal into the kiln event log. Called when a run is
+ * observed. `properties.once` makes a second observation of the same journal
+ * line a no-op.
+ *
+ * `run.started` carries the kiln version, the yak version, the workflow
+ * name, and a hash of the prompts and skills that workflow is using.
+ */
+const REVIEW_STEPS = new Set(["security", "ux", "ui", "code"]);
+const CLIP = 240;
+export function projectRunJournal(input) {
+    try {
+        project(input);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`kiln: event log: ${message}`);
+    }
+}
+export function kilnVersion() {
+    return packageVersion(join(packageRoot(), "package.json"));
+}
+export function yakVersion() {
+    const require = createRequire(import.meta.url);
+    return packageVersion(require.resolve("@lchase/yak/package.json"));
+}
+/**
+ * SHA-256 of the prompt files this workflow launches with, then any files
+ * under the package `skills/` directory. The rendered prompt (preamble plus
+ * factory body) is what the run uses when it is already on disk. Otherwise
+ * the packaged prompt, combined the same way, is hashed. Labels are basenames
+ * for prompts and package-relative paths for skills, so the hash does not
+ * depend on the machine path.
+ */
+export function promptsHash(workflow, kilnDir, jobId) {
+    const hash = createHash("sha256");
+    hash.update("prompts\0");
+    for (const file of promptFiles(workflow, kilnDir, jobId)) {
+        hash.update(file.label);
+        hash.update("\0");
+        hash.update(file.body);
+        hash.update("\0");
+    }
+    hash.update("skills\0");
+    for (const file of skillFiles()) {
+        hash.update(file.label);
+        hash.update("\0");
+        hash.update(file.body);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function project(input) {
+    const workflow = workflowName(input);
+    for (let index = 0; index < input.events.length; index += 1) {
+        const event = asRecord(input.events[index]);
+        if (!event || typeof event.t !== "string")
+            continue;
+        if (event.t === "run.started")
+            recordRunStarted(input, workflow);
+        else if (event.t === "step.started")
+            recordPhaseStarted(input, event, index);
+        else if (event.t === "step.completed" || event.t === "step.failed")
+            recordPhaseFinished(input, event, index);
+        else if (event.t === "gate.opened")
+            recordGateOpened(input, event, index);
+        else if (event.t === "gate.answered")
+            recordGateResolved(input, event);
+        else if (event.t === "run.finished")
+            recordRunFinished(input, event);
+    }
+}
+function recordRunStarted(input, workflow) {
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "run.started",
+        properties: {
+            kiln_version: kilnVersion(),
+            yak_version: yakVersion(),
+            workflow,
+            prompts_hash: promptsHash(workflow, input.kilnDir, input.jobId),
+            repo: input.repo || "unknown",
+            once: "run.started",
+        },
+    });
+}
+function recordPhaseStarted(input, event, index) {
+    const step = typeof event.stepId === "string" ? event.stepId : "";
+    if (!step)
+        return;
+    const iteration = iterationOf(event);
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "phase.started",
+        step,
+        properties: {
+            ...(iteration !== undefined ? { iteration } : {}),
+            once: `phase.started:${index}`,
+        },
+    });
+}
+function recordPhaseFinished(input, event, index) {
+    const step = typeof event.stepId === "string" ? event.stepId : "";
+    if (!step)
+        return;
+    const failed = event.t === "step.failed";
+    const iteration = iterationOf(event);
+    const artifactName = typeof event.artifact === "string" ? event.artifact : step;
+    const artifact = failed ? undefined : readArtifact(input.runDir, artifactName, iteration);
+    const failure = failed ? asRecord(event.failure) : undefined;
+    const reason = typeof failure?.reason === "string" ? clip(failure.reason) : undefined;
+    const detail = typeof failure?.detail === "string" ? clip(failure.detail) : undefined;
+    const verdict = artifact && typeof artifact.verdict === "string" ? clip(artifact.verdict) : undefined;
+    const exitCode = step === "verify" && artifact && typeof artifact.exitCode === "number" && Number.isInteger(artifact.exitCode)
+        ? artifact.exitCode
+        : undefined;
+    const testCommand = step === "verify" && input.testCommand?.trim() ? clip(input.testCommand.trim()) : undefined;
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "phase.finished",
+        step,
+        properties: {
+            outcome: failed ? "failed" : "completed",
+            ...(iteration !== undefined ? { iteration } : {}),
+            ...(typeof event.cached === "boolean" ? { cached: event.cached } : {}),
+            ...(event.skipped === true ? { skipped: true } : {}),
+            ...(reason ? { reason } : {}),
+            ...(detail ? { detail } : {}),
+            ...(verdict && REVIEW_STEPS.has(step) ? { verdict } : {}),
+            ...(testCommand ? { test_command: testCommand } : {}),
+            ...(exitCode !== undefined ? { exit_code: exitCode } : {}),
+            once: `phase.finished:${index}`,
+        },
+    });
+}
+function recordGateOpened(input, event, index) {
+    const step = typeof event.stepId === "string" ? event.stepId : "";
+    if (!step)
+        return;
+    const request = readJson(join(input.runDir, "pending", `${step}.request.json`));
+    const rendered = request && typeof request.rendered === "string" ? clip(request.rendered.split("\n")[0] ?? "") : "";
+    const noted = noteFrom(request);
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "gate.opened",
+        step,
+        properties: {
+            ...(rendered ? { prompt: rendered } : {}),
+            ...(noted ?? {}),
+            once: `gate.opened:${index}`,
+        },
+    });
+}
+function recordGateResolved(input, event) {
+    const step = typeof event.stepId === "string" ? event.stepId : "";
+    if (!step || event.skipped === true)
+        return;
+    const answer = readJson(join(input.runDir, "pending", `${step}.answer.json`)) ??
+        readJson(join(input.runDir, "artifacts", "approval.json"));
+    const decision = answer && typeof answer.decision === "string" ? answer.decision : "";
+    if (!decision)
+        return;
+    const noted = noteFrom(answer);
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "gate.resolved",
+        step,
+        properties: {
+            decision,
+            by: "human",
+            ...(input.repo ? { repo: input.repo } : {}),
+            ...(noted ?? {}),
+            once: `gate.resolved:${step}`,
+        },
+    });
+}
+function recordRunFinished(input, event) {
+    const cost = costFromJournal(input.events);
+    if (event.status === "ok") {
+        appendEvent(input.kilnDir, {
+            job_id: input.jobId,
+            run_id: input.runId,
+            event: "run.finished",
+            properties: { status: "ok", tokens: cost.tokens, usd: cost.usd, once: "run.finished" },
+        });
+        return;
+    }
+    // A normal failure is classified in recoverRuns, which owns the retry decision.
+    // A cancelled run is not recovered, so the class is recorded here.
+    if (event.status !== "failed" || event.reason !== "cancelled")
+        return;
+    const decision = decideFailure({
+        text: "cancelled",
+        operational: false,
+        blocked: true,
+        attempt: 1,
+        maxAttempts: Number.MAX_SAFE_INTEGER,
+        sameFingerprint: 1,
+        maxSameFingerprint: Number.MAX_SAFE_INTEGER,
+    });
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "run.failed",
+        properties: {
+            status: "failed",
+            reason: "cancelled",
+            class: decision.class,
+            fingerprint: decision.fingerprint,
+            tokens: cost.tokens,
+            usd: cost.usd,
+            once: `run.failed:${input.runId}`,
+        },
+    });
+}
+function workflowName(input) {
+    const started = input.events.map(asRecord).find((event) => event?.t === "run.started");
+    const journal = started && typeof started.workflow === "string" ? started.workflow : "";
+    if (journal === "kiln-fix")
+        return "fix";
+    if (journal === "kiln-feature")
+        return "feature";
+    if (journal === "kiln-investigation")
+        return "investigation";
+    if (journal.startsWith("kiln-") && journal.length > "kiln-".length)
+        return journal.slice("kiln-".length);
+    return input.workflow || journal || "unknown";
+}
+function iterationOf(event) {
+    return typeof event.iteration === "number" && Number.isInteger(event.iteration) && event.iteration >= 0
+        ? event.iteration
+        : undefined;
+}
+function noteFrom(value) {
+    if (!value)
+        return undefined;
+    const note = typeof value.note === "string" ? clip(value.note) : "";
+    const edit = typeof value.edit === "string" ? clip(value.edit) : "";
+    if (!note && !edit)
+        return undefined;
+    return {
+        ...(note ? { note } : {}),
+        ...(edit ? { edit } : {}),
+    };
+}
+function readArtifact(runDir, name, iteration) {
+    if (!/^[A-Za-z0-9._-]+$/.test(name))
+        return undefined;
+    const file = iteration === undefined ? `${name}.json` : `${name}.${iteration}.json`;
+    return readJson(join(runDir, "artifacts", file));
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return asRecord(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function clip(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return "";
+    return trimmed.length <= CLIP ? trimmed : `${trimmed.slice(0, CLIP - 1)}…`;
+}
+function promptFiles(workflow, kilnDir, jobId) {
+    const rendered = renderedWorkflow(kilnDir, jobId, workflow);
+    const packaged = join(packageRoot(), "workflows", `${workflow}.yaml`);
+    const yamlPath = rendered ?? (existsSync(packaged) ? packaged : undefined);
+    if (!yamlPath)
+        return [];
+    let yaml = "";
+    try {
+        yaml = readFileSync(yamlPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const paths = new Set();
+    for (const match of yaml.matchAll(/file:\s*(?:"([^"]+\.md)"|'([^']+\.md)'|(\S+\.md))/g)) {
+        const found = match[1] ?? match[2] ?? match[3];
+        if (found)
+            paths.add(found);
+    }
+    const files = [];
+    for (const file of [...paths].sort()) {
+        const body = promptBody(file, Boolean(rendered));
+        if (body === undefined)
+            continue;
+        files.push({ label: basename(file), body });
+    }
+    files.sort((left, right) => (left.label < right.label ? -1 : left.label > right.label ? 1 : 0));
+    return files;
+}
+function renderedWorkflow(kilnDir, jobId, workflow) {
+    let safe;
+    try {
+        safe = jobBasename(jobId);
+    }
+    catch {
+        return undefined;
+    }
+    const path = join(kilnDir, "rendered", safe, `${workflow}.yaml`);
+    return existsSync(path) ? path : undefined;
+}
+/** A rendered prompt is already the combined text. A packaged path is combined here. */
+function promptBody(file, rendered) {
+    const path = file.startsWith("/") || /^[A-Za-z]:/.test(file) ? file : join(packageRoot(), file);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    if (rendered)
+        return text;
+    const directive = text.match(/^<!--\s*factory:\s*(prompts\/factory\/[a-z0-9-]+\.md)\s*-->/m);
+    if (!directive?.[1])
+        return text;
+    const factoryPath = join(packageRoot(), directive[1]);
+    const factoryRoot = join(packageRoot(), "prompts", "factory") + sep;
+    if (!factoryPath.startsWith(factoryRoot))
+        return text;
+    try {
+        const factory = readFileSync(factoryPath, "utf8");
+        return `${text.trimEnd()}\n\n${factory.trimStart()}`;
+    }
+    catch {
+        return text;
+    }
+}
+function skillFiles() {
+    const root = packageRoot();
+    const dir = join(root, "skills");
+    if (!existsSync(dir))
+        return [];
+    const found = [];
+    const walk = (current) => {
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile()) {
+                try {
+                    found.push({ label: relative(root, path), body: readFileSync(path, "utf8") });
+                }
+                catch {
+                    // A skill that cannot be read is left out of this hash.
+                }
+            }
+        }
+    };
+    walk(dir);
+    found.sort((left, right) => (left.label < right.label ? -1 : left.label > right.label ? 1 : 0));
+    return found;
+}
+function packageVersion(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed.version === "string" && parsed.version ? parsed.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}