@karowanorg/orc-core 0.1.0

package/dist/rundir.js

@@ -0,0 +1,299 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { canonicalJson, sha256Hex } from "./canonical.js";
+/** State home: ~/.orc or $ORC_HOME. One run = one directory under runs/. */
+export function orcHome() {
+    return process.env.ORC_HOME ?? path.join(os.homedir(), ".orc");
+}
+export function runsDir() {
+    return path.join(orcHome(), "runs");
+}
+export function runDir(runId) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(runId))
+        throw new Error(`invalid run id: ${runId}`);
+    return path.join(runsDir(), runId);
+}
+export function newRunId(name) {
+    const slug = (name ?? "run").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 24) || "run";
+    const rand = randomBytes(8).toString("hex");
+    return `r_${slug}_${rand}`;
+}
+function writeAll(fd, data) {
+    let offset = 0;
+    while (offset < data.byteLength) {
+        const written = fs.writeSync(fd, data, offset, data.byteLength - offset);
+        if (written === 0)
+            throw new Error("failed to make progress writing record");
+        offset += written;
+    }
+}
+function readFully(fd, data, length, position) {
+    let offset = 0;
+    while (offset < length) {
+        const read = fs.readSync(fd, data, offset, length - offset, position + offset);
+        if (read === 0)
+            break;
+        offset += read;
+    }
+    return offset;
+}
+function truncateUnterminatedTail(filePath) {
+    if (!fs.existsSync(filePath))
+        return;
+    const fd = fs.openSync(filePath, "r+");
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size === 0)
+            return;
+        const last = Buffer.allocUnsafe(1);
+        if (readFully(fd, last, 1, size - 1) !== 1)
+            return;
+        if (last[0] === 0x0a)
+            return;
+        const chunk = Buffer.allocUnsafe(Math.min(size, 64 * 1024));
+        for (let end = size; end > 0;) {
+            const start = Math.max(0, end - chunk.byteLength);
+            const read = readFully(fd, chunk, end - start, start);
+            const newline = chunk.subarray(0, read).lastIndexOf(0x0a);
+            if (newline >= 0) {
+                fs.ftruncateSync(fd, start + newline + 1);
+                return;
+            }
+            end = start;
+        }
+        fs.ftruncateSync(fd, 0);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Append-only JSONL file with an explicit fsync mode.
+ * The journal uses fsync-per-append (the WAL); the trace sidecar fsyncs only
+ * on leaf close records.
+ */
+export class JsonlAppender {
+    filePath;
+    fd;
+    constructor(filePath) {
+        this.filePath = filePath;
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        // A record without its newline was never committed. Remove it before the
+        // next append so corruption cannot become an accepted interior line.
+        truncateUnterminatedTail(filePath);
+        this.fd = fs.openSync(filePath, "a");
+    }
+    append(record, opts) {
+        writeAll(this.fd, Buffer.from(JSON.stringify(record) + "\n"));
+        if (opts?.fsync !== false)
+            fs.fsyncSync(this.fd);
+    }
+    close() {
+        try {
+            fs.closeSync(this.fd);
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}
+/** Read a JSONL file tolerating a torn final line (crash-during-append). */
+export function readJsonl(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const raw = fs.readFileSync(filePath, "utf8");
+    const out = [];
+    const lines = raw.split("\n");
+    // The final split element is either empty (committed newline) or the one
+    // uncommitted crash fragment readers are allowed to ignore.
+    lines.pop();
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch (err) {
+            throw new Error(`malformed JSONL record in ${filePath} at line ${index + 1}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return out;
+}
+export function runPaths(runId) {
+    const dir = runDir(runId);
+    return {
+        dir,
+        manifest: path.join(dir, "manifest.json"),
+        program: path.join(dir, "program.bundle.js"),
+        journal: path.join(dir, "journal.jsonl"),
+        traces: path.join(dir, "traces.jsonl"),
+        control: path.join(dir, "control.jsonl"),
+        results: path.join(dir, "results"),
+        report: path.join(dir, "report.html"),
+        lock: path.join(dir, "supervisor.lock"),
+    };
+}
+export function createRunDir(manifest, programBundle) {
+    const paths = runPaths(manifest.runId);
+    fs.mkdirSync(runsDir(), { recursive: true });
+    fs.mkdirSync(paths.dir);
+    fs.mkdirSync(paths.results);
+    fs.writeFileSync(paths.program, programBundle);
+    fs.writeFileSync(paths.manifest, JSON.stringify(manifest, null, 2));
+    return paths;
+}
+export function readManifest(runId) {
+    return JSON.parse(fs.readFileSync(runPaths(runId).manifest, "utf8"));
+}
+export function listRuns() {
+    const dir = runsDir();
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir)) {
+        try {
+            out.push(readManifest(entry));
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    return out.sort((a, b) => b.createdAtMs - a.createdAtMs);
+}
+/** Content-addressed result body storage. */
+export function writeResult(paths, body) {
+    const canonical = canonicalJson(body);
+    const sha = sha256Hex(canonical);
+    const file = path.join(paths.results, `${sha}.json`);
+    if (!fs.existsSync(file)) {
+        const tmp = file + ".tmp";
+        fs.writeFileSync(tmp, canonical);
+        const fd = fs.openSync(tmp, "r+");
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fs.renameSync(tmp, file);
+    }
+    return { sha, sizeBytes: Buffer.byteLength(canonical) };
+}
+export function readResult(paths, sha) {
+    const file = path.join(paths.results, `${sha}.json`);
+    const raw = fs.readFileSync(file, "utf8");
+    if (sha256Hex(raw) !== sha)
+        throw new Error(`result body digest mismatch for ${sha}`);
+    return JSON.parse(raw);
+}
+export function readJournal(runId) {
+    return readJsonl(runPaths(runId).journal);
+}
+export function readTraces(runId) {
+    return readJsonl(runPaths(runId).traces);
+}
+export function readControl(runId) {
+    return readJsonl(runPaths(runId).control);
+}
+export function appendControl(runId, msg) {
+    const appender = new JsonlAppender(runPaths(runId).control);
+    appender.append(msg, { fsync: true });
+    appender.close();
+}
+// ---------------------------------------------------------------------------
+// Supervisor lock: a platform advisory lock held by a tiny child process.
+// ---------------------------------------------------------------------------
+const LOCK_READY = "orc-lock-ready:";
+const LOCK_HOLDER = `process.stdout.write(${JSON.stringify(LOCK_READY)}+process.pid+"\\n");process.stdin.resume()`;
+export async function acquireLock(paths) {
+    fs.mkdirSync(path.dirname(paths.lock), { recursive: true });
+    const command = process.platform === "darwin"
+        ? ["/usr/bin/lockf", "-k", "-s", "-t", "0", paths.lock]
+        : process.platform === "linux"
+            ? ["flock", "-n", paths.lock]
+            : undefined;
+    if (!command) {
+        throw new Error(`supervisor locking is unsupported on ${process.platform}`);
+    }
+    command.push(process.execPath, "-e", LOCK_HOLDER);
+    const child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe"] });
+    child.stdin.on("error", () => {
+        /* acquisition/exit paths report the child outcome */
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    const exited = new Promise((resolve) => {
+        child.once("close", (code, signal) => resolve({ code, signal }));
+    });
+    const spawnFailed = new Promise((_, reject) => {
+        child.once("error", reject);
+    });
+    let holderPid;
+    let acquireTimer;
+    try {
+        await Promise.race([
+            new Promise((resolve) => {
+                const onData = () => {
+                    const match = stdout.match(/orc-lock-ready:(\d+)\n/);
+                    if (!match)
+                        return;
+                    holderPid = Number(match[1]);
+                    child.stdout.removeListener("data", onData);
+                    resolve();
+                };
+                child.stdout.on("data", onData);
+            }),
+            exited.then(({ code, signal }) => {
+                throw new Error(code === 75 || (process.platform === "linux" && code === 1)
+                    ? "run is owned by a live supervisor"
+                    : `failed to acquire supervisor lock (${signal ?? code}): ${stderr.trim()}`);
+            }),
+            spawnFailed,
+            new Promise((_, reject) => {
+                acquireTimer = setTimeout(() => reject(new Error("timed out acquiring supervisor lock")), 5_000);
+                acquireTimer.unref();
+            }),
+        ]);
+    }
+    catch (err) {
+        child.stdin.end();
+        child.kill();
+        await exited;
+        throw err;
+    }
+    finally {
+        if (acquireTimer)
+            clearTimeout(acquireTimer);
+    }
+    let released = false;
+    const lost = exited.then(({ code, signal }) => {
+        if (!released) {
+            throw new Error(`supervisor lock holder exited unexpectedly (${signal ?? code})`);
+        }
+        return new Promise(() => undefined);
+    });
+    void lost.catch(() => undefined);
+    return {
+        holderPid: holderPid,
+        lost,
+        beat() {
+            if (child.exitCode !== null)
+                throw new Error("supervisor lock was lost");
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            child.stdin.end();
+            await exited;
+        },
+    };
+}

package/dist/status.d.ts

@@ -0,0 +1,10 @@
+import type { ApprovalRequest, JournalRecord, LeafTraceRecord, RunManifest, RunStatus, TraceRecord } from "./contracts.js";
+/**
+ * Pure projection: journal (deterministic status) + trace sidecar (detail,
+ * running/failed leaves) -> RunStatus. Journal status wins where present.
+ */
+export declare function projectStatus(manifest: RunManifest, journal: JournalRecord[], traces: TraceRecord[]): RunStatus;
+/** Supersession: highest attempt wins; within an attempt, highest rev wins. */
+export declare function latestLeafTraces(traces: TraceRecord[]): Map<number, LeafTraceRecord>;
+export declare function openApprovals(traces: TraceRecord[]): ApprovalRequest[];
+export declare function statusForRun(runId: string): RunStatus;

package/dist/status.js

@@ -0,0 +1,147 @@
+import { readJournal, readManifest, readTraces } from "./rundir.js";
+/**
+ * Pure projection: journal (deterministic status) + trace sidecar (detail,
+ * running/failed leaves) -> RunStatus. Journal status wins where present.
+ */
+export function projectStatus(manifest, journal, traces) {
+    const leaves = new Map();
+    const rearmed = new Set();
+    for (const rec of journal) {
+        if (rec.t === "call") {
+            leaves.set(rec.seq, {
+                seq: rec.seq,
+                id: rec.id,
+                phase: rec.phase,
+                kind: rec.kind,
+                readOnly: rec.readOnly,
+                status: "pending",
+            });
+        }
+        else if (rec.t === "done") {
+            const leaf = leaves.get(rec.seq);
+            if (leaf) {
+                rearmed.delete(rec.seq);
+                leaf.status = rec.status;
+                leaf.error = rec.error;
+                leaf.resultSha = rec.resultSha;
+                leaf.attempt = rec.attempt;
+            }
+        }
+        else if (rec.t === "attempt") {
+            const leaf = leaves.get(rec.seq);
+            if (leaf) {
+                rearmed.delete(rec.seq);
+                leaf.status = "pending";
+                leaf.error = undefined;
+                leaf.resultSha = undefined;
+                leaf.endMs = undefined;
+                leaf.attempt = rec.attempt;
+            }
+        }
+        else if (rec.t === "retry") {
+            for (const seq of rec.seqs) {
+                const leaf = leaves.get(seq);
+                if (!leaf)
+                    continue;
+                rearmed.add(seq);
+                leaf.status = "pending";
+                leaf.error = undefined;
+                leaf.resultSha = undefined;
+                leaf.endMs = undefined;
+            }
+        }
+    }
+    // Overlay sidecar detail; sidecar supplies "running" and timing/harness info.
+    const bestTrace = latestLeafTraces(traces);
+    for (const [seq, tr] of bestTrace) {
+        const leaf = leaves.get(seq);
+        if (!leaf || rearmed.has(seq))
+            continue;
+        const currentAttempt = leaf.attempt ?? 0;
+        if (tr.attempt < currentAttempt)
+            continue;
+        leaf.harness = tr.harness;
+        leaf.host = tr.host;
+        leaf.startMs = tr.startMs;
+        leaf.endMs = tr.endMs;
+        if (tr.status === "running" && (tr.attempt > currentAttempt || leaf.status === "pending")) {
+            leaf.status = "running";
+            leaf.attempt = tr.attempt;
+            leaf.error = undefined;
+            leaf.resultSha = undefined;
+        }
+        if (leaf.status === "pending" && (tr.status === "ok" || tr.status === "error")) {
+            // journal completion lost/behind; sidecar close is still informative
+            leaf.status = tr.status;
+            leaf.error = tr.error;
+            leaf.attempt = tr.attempt;
+        }
+    }
+    // Last finish wins; a retry record after it means a resume re-armed the run.
+    let finish;
+    let finishIdx = -1;
+    journal.forEach((r, i) => {
+        if (r.t === "finish") {
+            finish = r;
+            finishIdx = i;
+        }
+    });
+    const retriedAfterFinish = journal.some((r, i) => r.t === "retry" && i > finishIdx);
+    const state = !finish || retriedAfterFinish ? "running" : finish.status === "completed" ? "completed" : finish.status;
+    const all = [...leaves.values()].sort((a, b) => a.seq - b.seq);
+    const settled = state !== "running";
+    if (settled) {
+        for (const leaf of all) {
+            if (leaf.status === "running") {
+                leaf.status = "pending";
+                leaf.endMs = undefined;
+            }
+        }
+    }
+    const pendingApprovals = settled ? [] : openApprovals(traces);
+    const endMs = settled ? Math.max(...all.map((l) => l.endMs ?? 0), manifest.createdAtMs) : undefined;
+    return {
+        runId: manifest.runId,
+        state,
+        totalCalls: all.length,
+        ok: all.filter((l) => l.status === "ok").length,
+        failed: all.filter((l) => l.status === "error").length,
+        running: all.filter((l) => l.status === "running").length,
+        approvalsPending: pendingApprovals.length,
+        leaves: all,
+        resultSha: settled ? finish?.resultSha : undefined,
+        error: settled ? finish?.error : undefined,
+        startedAtMs: manifest.createdAtMs,
+        endedAtMs: endMs,
+        approvalMode: manifest.approvalMode,
+        allowWrites: manifest.allowWrites,
+    };
+}
+/** Supersession: highest attempt wins; within an attempt, highest rev wins. */
+export function latestLeafTraces(traces) {
+    const best = new Map();
+    for (const rec of traces) {
+        if (rec.t !== "leaf")
+            continue;
+        const cur = best.get(rec.seq);
+        if (!cur || rec.attempt > cur.attempt || (rec.attempt === cur.attempt && rec.rev > cur.rev)) {
+            best.set(rec.seq, rec);
+        }
+    }
+    return best;
+}
+export function openApprovals(traces) {
+    const open = new Map();
+    for (const rec of traces) {
+        if (rec.t !== "event")
+            continue;
+        if (rec.event.kind === "approval-requested")
+            open.set(rec.event.approval.id, rec.event.approval);
+        if (rec.event.kind === "approval-resolved")
+            open.delete(rec.event.approvalId);
+    }
+    return [...open.values()];
+}
+export function statusForRun(runId) {
+    return projectStatus(readManifest(runId), readJournal(runId), readTraces(runId));
+}

package/dist/supervisor.d.ts

@@ -0,0 +1,34 @@
+import { type Executor, type ExtensionLeaf, type Harness, type Policy, type RunManifest, type RunStatus } from "./contracts.js";
+import { newRunId } from "./rundir.js";
+export interface Registry {
+    harnesses: Map<string, Harness>;
+    extensions: Map<string, ExtensionLeaf>;
+    defaultHarness: string;
+    executorFor(host: string | undefined): Executor;
+}
+export interface LaunchOptions {
+    programPath: string;
+    cwd?: string;
+    host?: string;
+    brief: string;
+    allowWrites?: boolean;
+    approvalMode?: RunManifest["approvalMode"];
+    sandbox?: boolean;
+    sandboxDirs?: string[];
+    maxParallel?: number;
+    idleTimeout?: number | false;
+    budgetUsd?: number;
+    name?: string;
+    defaultHarness?: string;
+}
+export interface SupervisorHooks {
+    /** Called (debounced by the caller if desired) after journal/trace appends. */
+    onUpdate?(runId: string): void;
+}
+export declare const ORC_VERSION = "0.1.0";
+/** Static pre-scan: does the program source declare any write leaf? */
+export declare function sourceRequestsWrite(source: string): boolean;
+export declare function prepareRun(opts: LaunchOptions, registry: Registry): Promise<RunManifest>;
+export declare function superviseRun(runId: string, registry: Registry, hooks?: SupervisorHooks, policy?: Policy): Promise<RunStatus>;
+export declare function leafSystemPrompt(readOnly: boolean, cwd: string, brief: string): string;
+export { newRunId };