harness-dispatch 0.4.0 → 0.6.0

package/dist/jobs.d.ts

@@ -10,91 +10,13 @@
  * by the unit-test suite, which injects fake dispatchers a separate
  * process could not see).
  */
-import type { RuntimeHolder } from "./mcp/config-hot-reload.js";
-import type { DispatchResult, DispatcherEvent, RouteHints, RoutingDecision, WorkspacePolicy } from "./types.js";
-export interface JobDeps {
-    holder: RuntimeHolder;
-}
-export interface StartJobInput {
-    prompt: string;
-    files?: string[];
-    workingDir?: string;
-    hints?: RouteHints;
-    workspacePolicy?: WorkspacePolicy;
-    service?: 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.
-     */
-    status: "queued" | "running" | "completed" | "failed" | "orphaned";
-    createdAt: string;
-    updatedAt: string;
-    jobDir: string;
-    service?: string;
-    route?: string;
-    success?: boolean;
-    /** Bounded copy — full text in output/stderr.log. */
-    error?: string;
-    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;
-}
-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;
-    /** 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;
-}
-/**
- * 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 declare function setJobRetentionDays(days: number | undefined): void;
-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>;
-}
+import type { RouterConfig } from "./types.js";
+import { buildContextPreamble } from "./jobs/context.js";
+import { setJobRetentionDays } from "./jobs/store.js";
+import type { JobDeps, JobManifest, JobResultPayload, JobStatus, StartedJob, StartJobInput } from "./jobs/types.js";
+export { buildContextPreamble };
+export { setJobRetentionDays };
+export type { JobDeps, JobManifest, JobResultPayload, JobStatus, StartedJob, StartJobInput };
 /**
  * Rebuild a job's input from its on-disk bundle and execute it. This is the
  * detached runner's whole job; the manifest deliberately carries everything
@@ -103,6 +25,83 @@ export interface StartedJob {
  * created.
  */
 export declare function executeJobDir(deps: JobDeps, jobDir: string): Promise<void>;
+/**
+ * Occupied slots: jobs actually executing right now. Counts `running` (and
+ * plain `queued` — a runner spawned but not yet started) only while the
+ * heartbeat is fresh, so a crashed runner's slot is reclaimed by the same
+ * ORPHAN_THRESHOLD_MS rule that already frees its status. Slot-queued jobs
+ * are waiting for a slot, not holding one.
+ */
+/**
+ * What one run of a route costs against the concurrency budget.
+ *
+ * Unknown routes count as a full 1.0 on purpose. A job that has not been
+ * routed yet (no forced `service`) has no weight to look up, and this bound
+ * exists because a measured burst of 13 concurrent CLIs exhausted memory —
+ * so the safe assumption for "might be anything" is "might be heavy".
+ */
+export declare function resourceWeightFor(status: JobStatus, config: RouterConfig | undefined): number;
+/**
+ * Capacity currently in use, as a weighted sum rather than a job count.
+ *
+ * With every weight at 1.0 this is exactly the old count, so an existing
+ * `max_concurrent_runs` keeps its previous meaning.
+ */
+export declare function activeCapacity(statuses: Array<{
+    status: JobStatus;
+}>, config: RouterConfig | undefined): number;
+/**
+ * How many supervisor PROCESSES may exist, regardless of how many jobs run.
+ *
+ * Previously every job got its own detached Node process. Measured on Windows
+ * with Node 24: a bare node process is 52 MB RSS and one that has bootstrapped
+ * a runtime is 65 MB, against ~54 MB for the agent CLI it exists to supervise.
+ * So more than half the memory of a concurrent run was wrapper, and it scaled
+ * linearly — 13 concurrent jobs meant 845 MB of supervision before any agent
+ * had read a file. That is the concurrency ceiling.
+ *
+ * A supervisor is almost entirely idle: it waits on a child process and writes
+ * the result. One can watch several at once for the cost of async I/O, so
+ * wrapper memory becomes O(1) in the number of jobs instead of O(N), capped
+ * here at ~260 MB.
+ *
+ * Four rather than one purely to bound blast radius: a supervisor crash strands
+ * only the jobs it held. Those are recoverable anyway — the job directory is
+ * the source of truth and the heartbeat check already marks stranded jobs
+ * orphaned — but losing a quarter of in-flight work beats losing all of it.
+ */
+export declare const SUPERVISOR_POOL_SIZE = 4;
+/**
+ * Take exclusive ownership of a job directory.
+ *
+ * `wx` fails if the file exists, atomically, on both Windows and POSIX — which
+ * is what stops two supervisors racing onto the same job. A claim left behind
+ * by a crashed supervisor is reclaimed once that job's heartbeat has gone
+ * stale, by the same ORPHAN_THRESHOLD_MS rule used everywhere else.
+ *
+ * Exported for tests: the one-winner property under concurrent reclaim is the
+ * invariant, and it is only checkable by calling this directly.
+ */
+export declare function claimJobDir(jobDir: string, status: JobStatus): Promise<boolean>;
+/**
+ * Supervisor main loop: claim work, run several jobs at once, exit when idle.
+ *
+ * Exiting on idle keeps the no-jobs steady state at zero processes, same as
+ * before — the pool is a way to share supervision cost while work exists, not
+ * a daemon.
+ */
+export declare function runSupervisor(deps: JobDeps, supervisorId?: string): Promise<void>;
+/**
+ * Start slot-queued jobs, oldest first, until the machine is at its limit.
+ *
+ * Deliberately has no daemon behind it: this runs on every new dispatch and
+ * again as each runner exits, which between them covers every moment a slot
+ * can free. The cost of that choice is that if every runner dies while jobs
+ * are queued, the queue resumes on the next dispatch rather than immediately.
+ * Bounded waiting was the explicit alternative and was not chosen — a queued
+ * job keeps its jobId and its artifacts either way, so nothing is lost.
+ */
+export declare function drainSlotQueue(config: RouterConfig | undefined, configPath: string | undefined): Promise<void>;
 export declare function startAsyncJob(deps: JobDeps, input: StartJobInput): Promise<JobStatus>;
 export declare function startAsyncJobTracked(deps: JobDeps, input: StartJobInput): Promise<StartedJob>;
 export declare function getAsyncJob(jobId: string): Promise<{
@@ -113,4 +112,85 @@ export declare function getAsyncJob(jobId: string): Promise<{
     partialOutput?: string;
 }>;
 export declare function listAsyncJobs(): Promise<JobStatus[]>;
+/** What a cancel request actually did — the caller needs to tell these apart. */
+export interface CancelOutcome {
+    jobId: string;
+    /**
+     * `cancelled`  — it was queued and never started; stopped outright.
+     * `cancelling` — it is running; teardown requested and lands shortly.
+     * `already_finished` — it had already reached a terminal state; nothing done.
+     */
+    outcome: "cancelled" | "cancelling" | "already_finished";
+    status: JobStatus["status"];
+    message: string;
+}
+/**
+ * Ask a job to stop.
+ *
+ * Cancellation cannot be a signal here: jobs run inside POOLED supervisors,
+ * and the only pid recorded against a job belongs to a process that is also
+ * running other jobs, so signalling it would cancel work nobody asked to
+ * cancel. Instead this writes a marker the run itself honours — it drops out
+ * of its event stream, which triggers the dispatcher's teardown (killTree on
+ * the agent CLI and its children) and releases the workspace lock through the
+ * same path a normal finish uses.
+ *
+ * Two consequences worth stating plainly, because a caller who assumes
+ * otherwise will be surprised:
+ *
+ *   1. It is not instantaneous. A running job stops within about a second;
+ *      `cancelling` means requested, not done. Poll job_status to see it land.
+ *   2. Work already done is NOT undone. A cancelled agent may have already
+ *      edited files in the workspace, and those edits stay. Cancelling stops
+ *      further work; it is not a rollback.
+ *
+ * A cancelled run is deliberately not recorded as a failure: the route's
+ * circuit breaker and failure count never see it, because the caller changing
+ * their mind says nothing about whether the route works.
+ */
+export declare function cancelJob(jobId: string, reason?: string): Promise<CancelOutcome>;
+/**
+ * Inspect or resolve the isolated workspace a finished job left behind.
+ *
+ * Looks the job up the same way job_status does, then hands off to
+ * workspace-resolve.ts. Kept here so the caller only ever needs a jobId —
+ * where the workspace lives, and which policy produced it, are details
+ * recorded in the job's own result.
+ */
+export declare function resolveJobWorkspace(jobId: string, action: "diff" | "apply" | "discard", opts?: {
+    force?: boolean;
+}): Promise<unknown>;
+export interface RetryOutcome {
+    jobId: string;
+    retryOf: string;
+    service?: string;
+    reusedFrom: {
+        prompt: boolean;
+        files: number;
+        workingDir: string;
+    };
+    message: string;
+}
+/**
+ * Run a finished job's task again.
+ *
+ * The last verb missing from the job lifecycle: you could start work, watch
+ * it, stop it, and resolve its workspace — but if it failed, reproducing it
+ * meant reconstructing the prompt, the file list, the working directory and
+ * the hints by hand, from a job record that already holds all four. The
+ * machinery to execute a job bundle existed (executeJobDir) and simply was
+ * not reachable from outside.
+ *
+ * The prompt is taken from prompt.md, which is the FROZEN prompt — including
+ * any context preamble the original dispatch rendered in. A retry therefore
+ * reproduces what the delegate actually saw, not what the caller typed.
+ *
+ * `service` retargets the attempt, which is the common case rather than an
+ * afterthought: the reason a run failed is often the route, not the task
+ * ("codex hit its usage limit — try claude"). Omit it to reuse the original
+ * route, or to let the router pick again if the original had none.
+ */
+export declare function retryJob(jobId: string, deps: JobDeps, opts?: {
+    service?: string;
+}): Promise<RetryOutcome>;
 //# sourceMappingURL=jobs.d.ts.map

package/dist/jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAIV,YAAY,EAGb,MAAM,YAAY,CAAC;AASpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAcL,mBAAmB,EAOpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,aAAa,EACd,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC;AAiS7F;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAchF;AAkGD;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAQ7F;AAeD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,EACtC,MAAM,EAAE,YAAY,GAAG,SAAS,GAC/B,MAAM,CAUR;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAatC;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAuCrF;AAwBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6EvF;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAyJD,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAE3F;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA+FnG;AAOD,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxD,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CA2DD;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAgB1D;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,EAAE,WAAW,GAAG,YAAY,GAAG,kBAAkB,CAAC;IACzD,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAiDtF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,EACb,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,OAAO,CAAC,YAAY,CAAC,CA+CvB"}