Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
import { mkdtempSync, readdirSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { Binding } from "../binding";
import { hostedScreenshotPath, screenshotsDir } from "../layout";
import { readLedger } from "../ledger";
import { sq } from "./shell";
import type { Shell, TaskStatus } from "./types";
/** Screenshot files the behavior gate captured for this loop, if any. */
function screenshots(dir: string): string[] {
try {
return readdirSync(dir)
.filter((f) => /\.(png|jpe?g|gif)$/i.test(f))
.map((f) => join(dir, f))
.sort();
} catch {
return [];
}
}
const ARTIFACTS_BRANCH = "loop-artifacts";
/**
* Host the loop's screenshots so they render inline in the PR. Loop artifacts
* must not pollute the product tree (the conductor guardrail), so they live on
* ONE shared, non-merging `loop-artifacts` branch (gh-pages style) under
* `.ai/runs/<id>/screenshots/` — appended via a temp index on the branch tip so
* earlier loops' artifacts survive. All git plumbing, no checkout / working-tree
* change. Returns raw URLs GitHub renders, or null on any failure so the caller
* falls back to listing paths rather than failing the PR.
*/
function hostScreenshots(
id: string,
shots: string[],
shell: Shell,
cwd: string
): { name: string; url: string }[] | null {
const repo = shell("gh repo view --json nameWithOwner -q .nameWithOwner", {
cwd
});
if (!repo.ok || !repo.output.trim()) return null;
const slug = repo.output.trim(); // owner/repo
// Resolve the shared branch's current tip (absent on the first loop ever).
const fetched = shell(`git fetch origin ${ARTIFACTS_BRANCH}`, { cwd });
const tip = fetched.ok
? shell("git rev-parse FETCH_HEAD", { cwd }).output.trim()
: "";
// Build a temp index on top of the tip and add each screenshot.
const idx = join(mkdtempSync(join(tmpdir(), "loop-idx-")), "index");
const withIdx = (cmd: string) =>
shell(`GIT_INDEX_FILE=${sq(idx)} ${cmd}`, { cwd });
if (tip && !withIdx(`git read-tree ${tip}`).ok) return null;
const hosted: { name: string; url: string }[] = [];
for (const path of shots) {
const h = shell(`git hash-object -w ${sq(path)}`, { cwd });
if (!h.ok || !h.output.trim()) return null;
const name = path.split("/").pop() ?? "shot.png";
const repoPath = hostedScreenshotPath(id, name);
const add = withIdx(
`git update-index --add --cacheinfo 100644,${h.output.trim()},${repoPath}`
);
if (!add.ok) return null;
hosted.push({
name,
url: `https://raw.githubusercontent.com/${slug}/${ARTIFACTS_BRANCH}/${repoPath}`
});
}
const tree = withIdx("git write-tree");
if (!tree.ok || !tree.output.trim()) return null;
const commit = shell(
`git commit-tree ${tree.output.trim()} ${tip ? `-p ${tip}` : ""} -m ${sq(`chore(loops): screenshots for ${id}`)}`,
{ cwd }
);
if (!commit.ok || !commit.output.trim()) return null;
// Non-force append; a stale tip (a concurrent loop pushed) just fails → paths.
const push = shell(
`git push origin ${commit.output.trim()}:refs/heads/${ARTIFACTS_BRANCH}`,
{ cwd }
);
if (!push.ok) return null;
return hosted;
}
/** Sort key + label so before/after captures read in the right order. */
function shotRank(name: string): number {
if (/before/i.test(name)) return 0;
if (/after/i.test(name)) return 1;
return 2;
}
function shotLabel(name: string): string | null {
if (/before/i.test(name)) return "**Before**";
if (/after/i.test(name)) return "**After**";
return null;
}
/** The "Behavior verification" section: embedded images if hosted, else paths. */
function behaviorSection(
hosted: { name: string; url: string }[] | null,
shots: string[]
): string[] {
if (hosted && hosted.length > 0) {
const ordered = [...hosted].sort(
(a, b) => shotRank(a.name) - shotRank(b.name)
);
const out = ["### Behavior verification"];
for (const h of ordered) {
const label = shotLabel(h.name);
if (label) out.push(label, "");
out.push(``, "");
}
return out;
}
if (shots.length > 0) {
return [
"### Behavior verification",
"_captured locally (hosting unavailable):_",
...shots.map((s) => `- \`${s}\``),
""
];
}
return [];
}
/** Label a reviewer can filter on when a PR ships without full proof. */
const NEEDS_VERIFICATION_LABEL = "agent:needs-verification";
export type PrFlags = {
/** PR base branch. Defaults to the repo default (main); pass the loop's base
* branch to show only the loop's commit when it wasn't branched off main. */
base?: string;
/** Proof gaps on kept work — renders a "Needs human verification" section,
* opens the PR as a draft, and applies the needs-verification label. */
unverified?: string[];
/** Product questions for the reviewer (disputed criteria, doer assumptions). */
questions?: string[];
/** The task plan and per-task outcome — rendered as a checklist. */
plan?: { title: string; status: TaskStatus }[];
/** Set when the loop ended WITHOUT meeting all criteria (plateau/blocked) but
* committed work exists — salvage it as a draft PR rather than losing the
* work with the worktree. */
partial?: { state: string; reason: string };
};
const TASK_MARK: Record<TaskStatus, string> = {
done: "- [x]",
flagged: "- [x] ⚠️",
failed: "- [ ] ✗",
pending: "- [ ]"
};
/**
* Push the loop branch and open a **gated** PR (never merged). The body carries
* the design rationale surface: acceptance checklist, embedded behavior-gate
* screenshots, and the full ledger, so a human reviewer sees every kept/reverted
* iteration and why. Unproven or partial work ships as a DRAFT with an explicit
* warning section — flagged, never silently dropped. Returns the PR URL.
*/
export function openPr(
binding: Binding,
ledgerPath: string,
shell: Shell,
cwd: string,
flags: PrFlags = {}
): string {
const ledger = readLedger(ledgerPath);
const kept = ledger.filter((e) => e.decision === "keep").length;
const shots = screenshots(screenshotsDir(cwd, binding.id));
const hosted =
shots.length > 0 ? hostScreenshots(binding.id, shots, shell, cwd) : null;
const unverified = flags.unverified ?? [];
const questions = flags.questions ?? [];
const needsReview = unverified.length > 0 || Boolean(flags.partial);
const body = [
`## ${binding.title}`,
"",
`**Kind:** ${binding.kind} · **Risk:** ${binding.risk}`,
"",
// A partial PR must not auto-close its issue on merge — the criteria are
// not all met. Reference it without the `Closes` keyword instead.
...(binding.issue
? [
flags.partial
? `Related to #${binding.issue}`
: `Closes #${binding.issue}`,
""
]
: []),
...(flags.partial
? [
`> [!WARNING]`,
`> **Partial work — the loop ended \`${flags.partial.state}\`:** ${flags.partial.reason}`,
`> The ledger below records which commits passed gates and review. Remaining criteria are unfinished, not failing.`,
""
]
: []),
...(unverified.length > 0
? [
`> [!WARNING]`,
`> **Needs human verification.** The behavior gate could not prove the change either way — absence of proof, not disproof. A human must verify before merge:`,
...unverified.map((u) => `> - ${u}`),
""
]
: []),
"### Acceptance",
...binding.acceptance.map((c) => `- [${flags.partial ? " " : "x"}] ${c}`),
"",
...(flags.plan && flags.plan.length > 0
? [
"### Tasks",
...flags.plan.map(
(t) =>
`${TASK_MARK[t.status]} ${t.title}${t.status === "flagged" ? " _(kept without judge review)_" : t.status === "failed" ? " _(attempts on rescue branch)_" : ""}`
),
""
]
: []),
...(questions.length > 0
? ["### Open questions", ...questions.map((q) => `- ${q}`), ""]
: []),
...behaviorSection(hosted, shots),
"### Ledger",
...ledger.map(
(e) => `- ${e.iteration}. **${e.decision}** — ${e.change} _(${e.reason})_`
),
"",
`_Conducted headless: ${kept} kept / ${ledger.length} iterations. ` +
`Gated PR — requires human review, do not auto-merge._`
].join("\n");
const bodyFile = join(mkdtempSync(join(tmpdir(), "loop-pr-")), "body.md");
writeFileSync(bodyFile, body);
const push = shell("git push -u origin HEAD", { cwd });
if (!push.ok) throw new Error(`git push failed: ${push.output}`);
// Best-effort: label may not exist in the repo — never fail the PR over it.
const label = (): void => {
if (needsReview) {
shell(`gh pr edit --add-label ${sq(NEEDS_VERIFICATION_LABEL)}`, { cwd });
}
};
// Idempotent: a PR may already exist for this branch (re-entry — addressing
// review feedback in the same worktree). Update its body and return it rather
// than failing on `gh pr create`. `gh pr view` errors (ok:false) when none.
const existing = shell("gh pr view --json url --jq .url", { cwd });
if (existing.ok && existing.output.trim().startsWith("http")) {
shell(`gh pr edit --body-file ${sq(bodyFile)}`, { cwd });
label();
return firstHttpUrl(existing.output);
}
const title = `loop(${binding.id}): ${binding.title}${flags.partial ? " [partial]" : ""}`;
const baseArg = flags.base ? ` --base ${sq(flags.base)}` : "";
// Unproven/partial work goes up as a draft — visible, reviewable, unmergeable
// by accident.
const draftArg = needsReview ? " --draft" : "";
const r = shell(
`gh pr create --title ${sq(title)} --body-file ${sq(bodyFile)}${baseArg}${draftArg}`,
{ cwd }
);
if (!r.ok) throw new Error(`gh pr create failed: ${r.output}`);
label();
return firstHttpUrl(r.output);
}
/** The last `http…` line in command output (gh prints the URL last). */
function firstHttpUrl(output: string): string {
return (
output
.split("\n")
.map((l) => l.trim())
.filter((l) => l.startsWith("http"))
.at(-1) ?? output.trim()
);
}