harness-dispatch 0.5.0 → 0.6.0

package/dist/jobs/store.js

@@ -0,0 +1,279 @@
+/**
+ * The job store: where a job lives on disk and how it is written.
+ *
+ * Split out of jobs.ts. These are the primitives every other part of the job
+ * system sits on — path resolution, atomic writes, status reads, retention —
+ * and they depend on nothing above them, so they lift out cleanly and can be
+ * reasoned about (and tested) without starting a dispatch.
+ *
+ * The atomicity here is load-bearing rather than incidental: a status file
+ * half-written when a reader arrives is indistinguishable from a crashed
+ * runner, which is why every write goes through tmp+rename with a retry for
+ * Windows EPERM.
+ */
+import { existsSync } from "node:fs";
+import { chmod, copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { stateRoot } from "../state-dir.js";
+/**
+ * Dispatcher error strings are unbounded (a corrupted downstream config once
+ * produced a 173KB parse error). Full text always lands in stderr.log; the
+ * JSON surfaces returned over MCP carry a bounded copy.
+ */
+const MAX_JSON_ERROR_CHARS = 4000;
+/** Suggested delay before an agent checks `job_status` again. */
+export const SUGGESTED_POLL_SECONDS = 300;
+/**
+ * A "running" status whose updatedAt is older than this is a lie — the
+ * process that owned the run is gone (several missed heartbeats), so
+ * readers report the job as orphaned instead of keeping callers polling a
+ * corpse forever. Generous multiple of the heartbeat so an event-loop
+ * stall can't produce false orphans.
+ */
+export const ORPHAN_THRESHOLD_MS = 90_000;
+/**
+ * Compute-on-read orphan detection. Never writes the verdict back — the
+ * status file stays whatever the (dead) owner last wrote, so a future
+ * attach/recovery feature keeps its evidence intact.
+ */
+export function withOrphanCheck(status) {
+    // Waiting for a concurrency slot is not death: nothing is heartbeating for
+    // it by design, so the staleness rule below would misreport every job that
+    // waits longer than 90s. drainSlotQueue() is what moves it forward.
+    if (status.slotQueued)
+        return status;
+    if (status.status !== "running" && status.status !== "queued")
+        return status;
+    const beat = Date.parse(status.updatedAt);
+    if (Number.isFinite(beat) && Date.now() - beat <= ORPHAN_THRESHOLD_MS)
+        return status;
+    return {
+        ...status,
+        status: "orphaned",
+        success: false,
+        error: "The dispatch server that started this job exited before the run finished — " +
+            "the background run died with it. Re-dispatch the task; this job will never complete.",
+    };
+}
+export function boundedError(error) {
+    if (error === undefined)
+        return undefined;
+    if (error.length <= MAX_JSON_ERROR_CHARS)
+        return error;
+    return (error.slice(0, MAX_JSON_ERROR_CHARS) +
+        ` … [truncated ${error.length - MAX_JSON_ERROR_CHARS} chars — full text in output/stderr.log]`);
+}
+export function pollInstructions(jobId) {
+    return (`Job runs in the background; CLI harnesses typically take 3-15 minutes. ` +
+        `Wait ~${Math.round(SUGGESTED_POLL_SECONDS / 60)} minutes (e.g. sleep), then call ` +
+        `job_status with jobId=${jobId}. While status is "running", partialOutput shows ` +
+        `progress; check again until status is "completed" or "failed". Results persist ` +
+        `on disk, so checking late loses nothing.`);
+}
+export function jobsRoot() {
+    return process.env.HARNESS_DISPATCH_JOBS_DIR ?? path.join(stateRoot(), "jobs");
+}
+const DEFAULT_JOB_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+let configuredJobMaxAgeMs;
+/**
+ * Config-driven retention (`retention: { jobs_days: N }` in config.yaml) —
+ * set at runtime bootstrap and on every hot reload. Precedence:
+ * HARNESS_DISPATCH_JOB_MAX_AGE_MS env > config > 7-day default.
+ */
+export function setJobRetentionDays(days) {
+    configuredJobMaxAgeMs =
+        days !== undefined && Number.isFinite(days) && days >= 0
+            ? days * 24 * 60 * 60 * 1000
+            : undefined;
+}
+export function jobMaxAgeMs() {
+    const raw = process.env.HARNESS_DISPATCH_JOB_MAX_AGE_MS;
+    const parsed = raw ? Number(raw) : NaN;
+    if (Number.isFinite(parsed) && parsed >= 0)
+        return parsed;
+    return configuredJobMaxAgeMs ?? DEFAULT_JOB_MAX_AGE_MS;
+}
+/**
+ * Nothing ever pruned old job directories — status.json/result.json/output
+ * logs and every snapshotted context file accumulated under jobsRoot()
+ * forever. Prune anything with no activity for the retention window
+ * (default 7 days, override via HARNESS_DISPATCH_JOB_MAX_AGE_MS) each time a
+ * new job is about to start. Job directory mtime is a reasonable proxy for
+ * "last activity": writeJson's tmp-then-rename touches the job dir on every
+ * status update, so a running (or freshly completed but unpolled) job keeps
+ * bumping it — only genuinely abandoned jobs go stale. Best effort: a prune
+ * failure must never block starting the job that was actually requested.
+ */
+export async function pruneStaleJobs() {
+    const maxAgeMs = jobMaxAgeMs();
+    // 0 means KEEP FOREVER, not "prune immediately". The same config file
+    // establishes `max_concurrent_runs: 0` as "disable the bound", inviting the
+    // same reading here — and the old behaviour deleted RUNNING jobs out from
+    // under their runners (a job dir's mtime only moves on a 15s heartbeat, so
+    // at age 0 every beat gap was fatal): the runner's next write failed and
+    // the caller's jobId turned into "No such job".
+    if (maxAgeMs === 0)
+        return;
+    const root = jobsRoot();
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const jobDir = path.join(root, entry.name);
+        try {
+            const info = await stat(jobDir);
+            if (now - info.mtimeMs <= maxAgeMs)
+                continue;
+            // mtime is a proxy for activity; never delete a job that is
+            // demonstrably in flight. A live runner heartbeats status.json inside
+            // the orphan window, so running/queued with a fresh beat means "working
+            // right now", whatever retention says. An unreadable status file falls
+            // through to the mtime rule — that is the abandoned case.
+            try {
+                const status = JSON.parse(await readFile(path.join(jobDir, "status.json"), "utf8"));
+                const beat = Date.parse(status.updatedAt ?? "");
+                if ((status.status === "running" || status.status === "queued") &&
+                    Number.isFinite(beat) &&
+                    now - beat <= ORPHAN_THRESHOLD_MS) {
+                    continue;
+                }
+            }
+            catch {
+                // Fall through to the mtime rule.
+            }
+            await rm(jobDir, { recursive: true, force: true });
+        }
+        catch {
+            // best effort — a locked/already-gone/permission-denied entry is skipped
+        }
+    }
+}
+export function timestamp() {
+    return new Date().toISOString();
+}
+export function safeBaseName(filePath) {
+    return path.basename(filePath).replace(/[^A-Za-z0-9_.-]/g, "_");
+}
+export async function writeJson(filePath, value) {
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.${randomUUID().slice(0, 8)}.tmp`;
+    await writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await renameWithRetry(tmpPath, filePath);
+}
+async function renameWithRetry(tmpPath, filePath) {
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        try {
+            await rename(tmpPath, filePath);
+            return;
+        }
+        catch (err) {
+            const code = typeof err === "object" && err !== null ? err.code : undefined;
+            if (code !== "EPERM" && code !== "EACCES" && code !== "EBUSY")
+                throw err;
+            await delay(25 * (attempt + 1));
+        }
+    }
+    await rename(tmpPath, filePath);
+}
+export async function readJson(filePath) {
+    return JSON.parse(await readFile(filePath, "utf8"));
+}
+export async function updateStatus(jobDir, status) {
+    await writeJson(path.join(jobDir, "status.json"), {
+        ...status,
+        updatedAt: timestamp(),
+    });
+}
+export async function snapshotFiles(jobDir, files) {
+    const out = [];
+    const filesDir = path.join(jobDir, "context", "files");
+    await mkdir(filesDir, { recursive: true, mode: 0o700 });
+    for (const [index, originalPath] of files.entries()) {
+        const item = { originalPath };
+        try {
+            const fileStat = await stat(originalPath);
+            if (!fileStat.isFile()) {
+                item.error = "not a regular file";
+                out.push(item);
+                continue;
+            }
+            const snapshotName = `${String(index + 1).padStart(3, "0")}-${safeBaseName(originalPath)}`;
+            const snapshotPath = path.join(filesDir, snapshotName);
+            await copyFile(originalPath, snapshotPath);
+            await chmod(snapshotPath, 0o600);
+            item.snapshotPath = snapshotPath;
+            item.sizeBytes = fileStat.size;
+        }
+        catch (err) {
+            item.error = err instanceof Error ? err.message : String(err);
+        }
+        out.push(item);
+    }
+    await writeJson(path.join(jobDir, "context", "files.json"), out);
+    return out;
+}
+/**
+ * The only jobId shape this module ever produces. Kept adjacent to
+ * `assertValidJobId` so the two cannot drift.
+ */
+export function newJobId() {
+    return `job-${Date.now()}-${randomUUID().slice(0, 8)}`;
+}
+export const JOB_ID_RE = /^job-\d+-[0-9a-f]{8}$/;
+/**
+ * Reject anything that isn't a jobId we generated, BEFORE it reaches
+ * path.join.
+ *
+ * The MCP schema validates this too, but the check belongs here as well:
+ * path.join(jobsRoot(), "../../etc/hosts") escapes the jobs root, and this
+ * function is reachable from more than one caller. Validating only at the
+ * schema would mean any future caller silently reintroduces the traversal.
+ */
+export function assertValidJobId(jobId) {
+    if (!JOB_ID_RE.test(jobId)) {
+        throw new Error(`Invalid jobId ${JSON.stringify(jobId)} — expected job-<timestamp>-<8 hex chars>.`);
+    }
+}
+/**
+ * Cancellation is COOPERATIVE, by a marker file rather than a signal.
+ *
+ * Killing a pid is not available here: jobs run inside pooled supervisors
+ * (SUPERVISOR_POOL_SIZE), and one supervisor runs several jobs at once, so
+ * the only pid recorded against a job belongs to a process that is also
+ * running other people's work. Signalling it would cancel jobs nobody asked
+ * to cancel.
+ *
+ * So the canceller writes a marker and the RUN tears itself down: it drops
+ * out of its event stream, which triggers the dispatcher's own teardown
+ * (killTree on the agent CLI and its children) and releases the workspace
+ * lock through the same path a normal finish uses. The cost is that
+ * cancellation is not instant — it lands within one poll interval.
+ */
+const CANCEL_MARKER = "cancel.json";
+export async function requestCancel(jobDir, reason) {
+    await writeFile(path.join(jobDir, CANCEL_MARKER), JSON.stringify({ at: timestamp(), ...(reason !== undefined ? { reason } : {}) }), { encoding: "utf8", mode: 0o600 });
+}
+/** True once a cancel has been requested for this job. Cheap enough to poll. */
+export function cancelRequested(jobDir) {
+    return existsSync(path.join(jobDir, CANCEL_MARKER));
+}
+/** The reason recorded with a cancel request, if one was given. */
+export async function cancelReason(jobDir) {
+    try {
+        const raw = await readFile(path.join(jobDir, CANCEL_MARKER), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.reason === "string" ? parsed.reason : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/jobs/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/jobs/store.ts"],"names":[],"mappings":"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"}

package/dist/jobs/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The shapes a job is written and read as.
+ *
+ * Split out of jobs.ts so the store, the supervisor and the dispatch path can
+ * share them without importing each other. These types are the actual
+ * contract between processes — a detached runner rebuilds its whole input
+ * from JobManifest, and every reader of a job's state goes through JobStatus
+ * — so they are the one part of the job system that must stay stable.
+ */
+import type { DispatchResult, DispatcherEvent, RouteHints, RoutingDecision, WorkspacePolicy } from "../types.js";
+import type { RuntimeHolder } from "../mcp/config-hot-reload.js";
+export interface JobDeps {
+    holder: RuntimeHolder;
+}
+export interface StartJobInput {
+    prompt: string;
+    /**
+     * Earlier jobs whose results this one should be able to see.
+     *
+     * A delegate previously received a prompt and a file list and nothing else,
+     * so a second delegated step could not see what the first produced. The only
+     * way to chain work was for the orchestrator to read job A's output into its
+     * OWN context and re-summarise it into job B's prompt — spending exactly the
+     * context that delegating was meant to save, and losing detail in the
+     * retelling.
+     *
+     * Naming the prior jobs instead moves that transfer into the tool: their
+     * prompts and outputs are rendered into B's prompt directly, at full
+     * fidelity, without passing through the orchestrator.
+     */
+    contextJobs?: string[];
+    files?: string[];
+    workingDir?: string;
+    hints?: RouteHints;
+    workspacePolicy?: WorkspacePolicy;
+    service?: string;
+    /**
+     * The job this one is a retry of.
+     *
+     * Recorded so a chain of attempts is traceable after the fact — without it,
+     * three attempts at the same task look like three unrelated jobs, and the
+     * one that finally worked cannot be connected to the two that did not.
+     */
+    retryOf?: string;
+    /**
+     * Live dispatcher-event tap, used by the `dispatch` tool to forward MCP
+     * progress notifications during its inline grace window. Never serialized
+     * (the manifest lists its fields explicitly), never awaited, and a throw
+     * here must not fail the job.
+     */
+    onEvent?: (event: DispatcherEvent) => void;
+}
+export interface JobStatus {
+    jobId: string;
+    /**
+     * "orphaned" is never written to disk — it's computed on read: a job
+     * whose status file says "running" but whose heartbeat (updatedAt) has
+     * gone stale means the server process that owned the background run
+     * exited (session restart, crash) and the run died with it. Reporting it
+     * as still "running" forever is a lie that makes callers poll a corpse.
+     */
+    /**
+     * "cancelled" is terminal and deliberate: someone asked for this run to
+     * stop. It is distinct from "failed" because the run did not go wrong —
+     * treating a cancellation as a failure would charge the route's breaker and
+     * failure count for the caller changing their mind.
+     */
+    status: "queued" | "running" | "completed" | "failed" | "orphaned" | "cancelled";
+    createdAt: string;
+    updatedAt: string;
+    jobDir: string;
+    service?: string;
+    route?: string;
+    success?: boolean;
+    /** Bounded copy — full text in output/stderr.log. */
+    error?: string;
+    /**
+     * END-TO-END milliseconds for the run: routing, workspace preparation and
+     * any workspace-lock wait included. Deliberately NOT the same number as
+     * result.durationMs, which times the harness attempt alone — one job
+     * legitimately reports 116ms there and 15s here when it queued behind a
+     * shared_locked workspace. Both are real; they answer different questions.
+     */
+    durationMs?: number;
+    /** Suggested seconds to wait before polling action=get again. */
+    nextPollSeconds?: number;
+    /** Agent-facing guidance on how to collect the result. */
+    instructions?: string;
+    /** Set when workingDir was omitted and defaulted to the router's own cwd. */
+    warning?: string;
+    /**
+     * Queued because the machine is at `max_concurrent_runs`, NOT because its
+     * owner died. Load-bearing for orphan detection: a slot-queued job has no
+     * process heartbeating for it, so without this flag the 90s staleness rule
+     * would report a job that is merely waiting its turn as a dead one.
+     * Cleared the moment a slot frees and its runner is spawned.
+     */
+    slotQueued?: true;
+}
+export interface JobManifest {
+    jobId: string;
+    createdAt: string;
+    workingDir: string;
+    promptPath: string;
+    files: Array<{
+        originalPath: string;
+        snapshotPath?: string;
+        sizeBytes?: number;
+        error?: string;
+    }>;
+    hints?: RouteHints;
+    workspacePolicy?: WorkspacePolicy;
+    service?: string;
+    /** The job this one retries — see StartJobInput.retryOf. */
+    retryOf?: string;
+    /** Set when workingDir was omitted and defaulted to the router's own cwd. */
+    warning?: string;
+}
+export interface JobResultPayload {
+    jobId: string;
+    result: DispatchResult;
+    decision: RoutingDecision | null;
+}
+export interface StartedJob {
+    status: JobStatus;
+    /**
+     * Resolves once the run has reached a terminal state on disk (result.json
+     * or a failed/orphaned status). Never rejects. In detached mode this is a
+     * disk watcher on the job directory — the run itself lives in a separate
+     * job-runner process; in in-process mode (HARNESS_DISPATCH_INPROC_JOBS=1,
+     * used by unit tests with injected fakes) it is the runJob promise itself.
+     */
+    completion: Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACjH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH;;;;;OAKG;IACH,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/jobs/types.js

@@ -0,0 +1,11 @@
+/**
+ * The shapes a job is written and read as.
+ *
+ * Split out of jobs.ts so the store, the supervisor and the dispatch path can
+ * share them without importing each other. These types are the actual
+ * contract between processes — a detached runner rebuilds its whole input
+ * from JobManifest, and every reader of a job's state goes through JobStatus
+ * — so they are the one part of the job system that must stay stable.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jobs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}