@parcha/pi-durable-disk 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/hosts/local-host.js

@@ -20,6 +20,7 @@ import { ARCHIL_SCOPED, DEAD_CONNECTION, DEFAULT_MOUNT_ROOT, runPath } from "../
 import { EXIT_FENCED, EXIT_HELD, PdaError } from "../errors.js";
 import { LOCAL_PARK_THRESHOLD_MS } from "../park.js";
 import { processTable, thisBoot } from "../process-table.js";
+import { attemptEnv } from "./attempt-env.js";
 export class LocalHostError extends PdaError {
     constructor(code, message, options = {}) {
         super(code, message, options);
@@ -161,13 +162,13 @@ export function localHost(opts = {}) {
             return rm(path, { force: true });
         await root(["/bin/rm", "-f", path]);
     }
-    async function startUnit(ref, token) {
+    async function startUnit(ref, token, extra) {
         const unit = `${prefix}${ref.id}-${Date.now().toString(36)}${Math.floor(Math.random() * 1296).toString(36).padStart(2, "0")}`;
         if (!UNIT_SAFE.test(unit))
             throw new LocalHostError("INVALID_ARGUMENT", `unit name ${unit} is not safe`);
         const mountpoint = mountpointOf(ref);
         const handle = { driver: "local", mode: "systemd", host: hostName, bootId, unit, mountpoint };
-        const env = { ...opts.env, PATH: SAFE_PATH, PDA_HOLDER: holderEnv(handle) };
+        const env = { ...opts.env, ...extra, PATH: SAFE_PATH, PDA_HOLDER: holderEnv(handle) };
         const path = tokenFile(unit);
         await writeTokenFile(path, token);
         let started = false;
@@ -202,7 +203,7 @@ export function localHost(opts = {}) {
             await (started ? emptyTokenFile(path) : removeFile(path)).catch(() => { });
         }
     }
-    async function startChild(ref, token) {
+    async function startChild(ref, token, extra) {
         const tag = `${prefix}${ref.id}-${Date.now().toString(36)}`;
         const mountpoint = mountpointOf(ref);
         const base = { driver: "local", mode: "child", host: hostName, bootId, mountpoint, tag };
@@ -211,7 +212,7 @@ export function localHost(opts = {}) {
             const { openSync } = await import("node:fs");
             out = openSync(join(opts.logDir, `${tag}.log`), "a", 0o600);
         }
-        const env = { ...opts.env, PATH: SAFE_PATH, LANG: "C.UTF-8", HOME: process.env.HOME ?? "/", PDA_HOLDER: holderEnv(base) };
+        const env = { ...opts.env, ...extra, PATH: SAFE_PATH, LANG: "C.UTF-8", HOME: process.env.HOME ?? "/", PDA_HOLDER: holderEnv(base) };
         const child = spawn(command[0], [...command.slice(1), ...runFlags(ref), "--token-stdin"], { detached: true, stdio: ["pipe", out, out], env });
         await new Promise((resolve, reject) => {
             child.once("spawn", resolve);
@@ -288,9 +289,11 @@ export function localHost(opts = {}) {
     return {
         hostName,
         mountRoot,
-        start(ref, token) {
+        kills: "process",
+        async start(ref, token, attempt) {
             runPath(ref.id);
-            return mode === "systemd" ? startUnit(ref, token) : startChild(ref, token);
+            const extra = attemptEnv(attempt, (m) => new LocalHostError("INVALID_ARGUMENT", m));
+            return mode === "systemd" ? startUnit(ref, token, extra) : startChild(ref, token, extra);
         },
         async status(h) {
             if (!mine(h))
@@ -347,6 +350,31 @@ export function localHost(opts = {}) {
             await root([SYSTEMCTL, "reset-failed", `${h.unit}.service`]);
             await removeFile(tokenFile(h.unit));
         },
+        async kill(h) {
+            if (!mine(h) || h.bootId !== bootId)
+                return;
+            if (h.mode === "child") {
+                const pid = Number(h.pid);
+                // As in stop: only a real process, and only the one the handle names (its start ticks).
+                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number" || procStartTicks(pid) !== h.startTicks)
+                    return;
+                try {
+                    process.kill(-pid, "SIGKILL");
+                }
+                catch {
+                    // gone already
+                }
+                return;
+            }
+            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
+                return;
+            // Every process of the unit's control group at once, the instance's commands included. Its FUSE daemon runs in a
+            // scope of its own and keeps the mount, as after an OOM kill; the unit restarts in place unless restart is off.
+            const r = await root([SYSTEMCTL, "kill", "--signal=SIGKILL", "--kill-whom=all", `${h.unit}.service`]);
+            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
+                throw new LocalHostError("KILL_FAILED", `systemctl kill ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+            }
+        },
     };
 }
 /**

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 export { openDurableRun, RunError, StoreBehindSealError } from "./run.js";
-export type { BeforeResume, DurableRun, LeaseOptions, OpenDurableRunOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunEnv, RunErrorCode, RunLease, StoreHeadSource, StoreReads } from "./run.js";
+export type { AfterClaim, BeforeResume, DurableRun, LeaseOptions, OpenDurableRunOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunEnv, RunErrorCode, RunLease, RunSeed, RunSeedDir, StoreHeadSource, StoreReads } from "./run.js";
 export { localRun } from "./local-run.js";
 export type { LocalRun } from "./local-run.js";
-export { CLAIM_UNMOUNTED, openClaimDir, RunRecordError } from "./status.js";
+export { CLAIM_UNMOUNTED, openClaimDir, readLocalRunStatus, RunRecordError } from "./status.js";
 export type { ClaimDir, OpenClaimDirOptions, PersistRecord, RunHolder, RunRecord, RunStatus } from "./status.js";
 export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySafe } from "./env.js";
 export type { ArchilEnvClaim, ArchilEnvFactory, ArchilEnvOptions, EnvErrorCode } from "./env.js";
 export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
 export type { AcquireOptions, ArchilHost, Claim, ControlApi, PathlessResolver, RunRef, Unmounted } from "./claim.js";
+export { readReleased, withClaim } from "./with-claim.js";
+export type { ClaimControl, HeldPath, WithClaimOptions } from "./with-claim.js";
 export { PathOutsideWorkError } from "./confine.js";
 export type { RefusalReason } from "./confine.js";
 export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
@@ -25,6 +27,8 @@ export { DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest } from "./h
 export type { CreateSandboxBody, DaytonaClient, DaytonaHostErrorCode, DaytonaHostOptions, DaytonaRestOptions, ExecResult, SandboxInfo } from "./hosts/daytona.js";
 export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
 export type { RequestOptions, RunResponse, RunServer, ServeConfigErrorCode, ServeErrorCode, ServeOptions } from "./serve.js";
+export { archilPlace, localPlace, PlaceError } from "./place.js";
+export type { ArchilPlaceOptions, LocalPlaceOptions, Place, PlaceContext, PlaceErrorCode, PlaceExit, PlaceKill, PlaceOutcome, PlacePaths, PlaceRecovery, PlaceRunner, PlaceSignal, PlaceStatus, RunnerOrder } from "./place.js";
 export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
 export type { BusyState, DrainOptions, Parking, ParkOptions, ParkResult, ParkTarget } from "./park.js";
 export { fork, ForkError, forkLocal } from "./fork.js";

package/dist/index.js

@@ -4,9 +4,11 @@
 // The run: open it, on a disk or a local directory, with its environment, its claim and the errors it fails with.
 export { openDurableRun, RunError, StoreBehindSealError } from "./run.js";
 export { localRun } from "./local-run.js";
-export { CLAIM_UNMOUNTED, openClaimDir, RunRecordError } from "./status.js";
+export { CLAIM_UNMOUNTED, openClaimDir, readLocalRunStatus, RunRecordError } from "./status.js";
 export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySafe } from "./env.js";
 export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
+// A short exclusive claim on any path of a disk, and a consistent S3 read of a released file (an agent home beside the runs).
+export { readReleased, withClaim } from "./with-claim.js";
 export { PathOutsideWorkError } from "./confine.js";
 export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
 // The app contract: what `--app` names.
@@ -18,6 +20,8 @@ export { dockerHost, DockerHostError } from "./hosts/docker.js";
 export { DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest } from "./hosts/daytona.js";
 // Serve: one HTTP request runs one turn.
 export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
+// Places: where a run lives for a supervisor that kills it and brings it back (agentrun's reference place seam).
+export { archilPlace, localPlace, PlaceError } from "./place.js";
 // Parking: an idle run gives its host back.
 export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
 // Fork: a new run from a run's committed state.

package/dist/lease.d.ts

@@ -1,5 +1,5 @@
 export { EXIT_DATAERR, EXIT_SOFTWARE, LeaseLapsedError, openRunLease, OWNER_LOCK, RunError, StoreBehindSealError, storeHead, STORE_FILE } from "./run.js";
-export type { LeaseOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunErrorCode, RunLease, StoreHeadSource } from "./run.js";
+export type { LeaseOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunErrorCode, RunLease, RunSeed, RunSeedDir, StoreHeadSource } from "./run.js";
 export * from "./errors.js";
 export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";
 export type { ArchilStore, OpenOptions, PragmaMismatch, Profile } from "./store.js";

package/dist/place.d.ts

@@ -0,0 +1,190 @@
+import type { Delegation } from "disk";
+import { PdaError } from "./errors.js";
+import { type RunRecord } from "./status.js";
+import { type EnsureOptions, type HostDriver, type SupervisorControl } from "./supervise.js";
+export type PlaceKill = "process" | "box";
+/** The run's paths in the place: its id, its directory, and the `work` and `store` under it. */
+export type PlacePaths = {
+    id: string;
+    root: string;
+    work: string;
+    store: string;
+};
+/**
+ * How the run stood when a runner ended: the instance's own report, or `run.json` as it left it. `status` is the run's
+ * word: `complete` when it delivered, else `failed`.
+ */
+export type PlaceOutcome = {
+    status: string;
+    generation: number | null;
+    code?: string | null;
+    message?: string;
+    record?: unknown;
+    storeSha256?: string;
+};
+/** How a runner ended. `exit`: the exit code or signal (local), or the host's status (`stopped`, `failed`, `gone`) or `SIGKILL` when the place killed it (archil). */
+export type PlaceExit = {
+    exit: number | string | null;
+    signal: string | null;
+    outcome?: PlaceOutcome;
+    stderr: string;
+};
+/** One instance of the run in a place. `epoch`: 1 on a plain directory; on a disk, the generation the instance opens. */
+export type PlaceRunner = {
+    epoch: number;
+    pid?: number;
+    exited: Promise<PlaceExit>;
+};
+/** What a runner is handed: its number in the run, its environment, and for a place with a token, the attempt's mount token. */
+export type RunnerOrder = {
+    gen: number;
+    env: Record<string, string>;
+    stdin?: string;
+};
+/** What the place reads of the run, the way it reads it: `run.json`, and on a disk the run's delegations. */
+export type PlaceStatus = {
+    record: RunRecord | null;
+    delegations?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned" | "isPending">[];
+};
+/** What a recovery did. A takeover on a disk lists what it revoked, and `ms` is the whole of it (revoke and start). */
+export type PlaceRecovery = {
+    runner: PlaceRunner;
+    restored?: {
+        checkpoint: string;
+        head: number;
+    };
+    replayed?: {
+        from: number;
+        to: number;
+    };
+    revoked?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned">[];
+    ms?: number;
+};
+/**
+ * What a runner announces to its supervisor: a crossing it took, or a request to be killed at one (it parks there until
+ * the kill). `signals-failed` is the place's own last word when it could not read the requests: it ends the iterator,
+ * which never rejects. `code` is the failing read's error code when it has one (CONTROL_API_FAILED for a read that timed
+ * out), else SIGNALS_FAILED.
+ */
+export type PlaceSignal = {
+    kind: "crossing" | "kill-request";
+    crossing: {
+        point: string;
+        n: number;
+        pid?: number;
+        info?: Record<string, unknown>;
+    };
+    /** The attempt's nonce the runner wrote into its request, lifted out of `crossing`: the supervisor honors a kill request only with the nonce it minted for that attempt. */
+    nonce?: string;
+} | {
+    kind: "signals-failed";
+    code: string;
+    message: string;
+};
+/**
+ * What the supervisor hands a place factory: the run's paths as it computed them, how to take the boxes the run made,
+ * and where attempt n's runner writes its kill request (a file of the supervisor's machine).
+ */
+export type PlaceContext = {
+    paths: PlacePaths;
+    self?: string;
+    destroyBoxes?: () => void | Promise<void>;
+    requestFile?: (attempt: number) => string;
+};
+export interface Place {
+    /** `local` or `archil`, for the recording's lines. */
+    readonly name: string;
+    readonly paths: PlacePaths;
+    /** A place whose instance opens a claim mints each attempt's mount token: the supervisor passes it as the runner's stdin, never in argv or env. */
+    token?(attempt: number): string | undefined | Promise<string | undefined>;
+    /** What this place can lose. */
+    readonly kills: ReadonlyArray<PlaceKill>;
+    start(order: RunnerOrder): Promise<PlaceRunner>;
+    /**
+     * Where attempt `attempt`'s runner writes its kill request, as a path in the place (the supervisor puts it in the
+     * runner's order). A place with `signals` has it, and `signals(attempt)` reads what is written there.
+     */
+    requestFile?(attempt: number): string;
+    /**
+     * The kill requests (and crossings) attempt `attempt`'s runner announces. The supervisor stops reading with `return()`
+     * once the runner has exited, and `return()` ends a pending `next()`.
+     */
+    signals?(attempt: number): AsyncIterable<PlaceSignal>;
+    /** Takes the runner away abruptly, as a crash would. Safe on a runner that is already gone. */
+    kill(runner: PlaceRunner, kind: PlaceKill): Promise<void>;
+    status?(): Promise<PlaceStatus>;
+    /** Kills `last` if it still runs, then starts the next runner. */
+    recover(last: PlaceRunner, kind: PlaceKill, order: RunnerOrder): Promise<PlaceRecovery>;
+    checkpoint?(): Promise<{
+        taken: boolean;
+        heldBy?: string;
+    }>;
+    move?(to: Place): Promise<Record<string, unknown>>;
+    /** Lets the run go: stops what still runs (its commands too) and removes what the place made for it (tokens), never the run's directory. */
+    release(): Promise<void>;
+}
+export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED";
+export declare class PlaceError extends PdaError {
+    constructor(code: PlaceErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface LocalPlaceOptions {
+    /** The app module `run --app` loads. */
+    app: string;
+    /** The run's directory. Default: the context's `paths.root`. */
+    root?: string;
+    /** The instance program; `run` and its flags are appended. Default: this Node and the package's CLI. */
+    command?: string[];
+    /** Extra flags for `run` (heartbeat periods, a park threshold). */
+    runArgs?: string[];
+}
+/**
+ * The run on a directory of this machine: each runner is `pi-durable-disk run --dir <root> --id <id> --app <app>`, a
+ * child in its own process group, with `{ PATH, ...order.env }` and nothing else of this process's environment. No disk,
+ * no key and no token. A process kill is SIGKILL to the group, and the next runner resumes the run from the directory; a
+ * box kill also takes the boxes the run made (`destroyBoxes`), so `kills` has `box` only when the context gives that.
+ * A runner's outcome is the instance's `{"outcome":...}` line on stdout, or, without one, `run.json` as it left it.
+ */
+export declare function localPlace(options: LocalPlaceOptions): (ctx: PlaceContext) => Place;
+export interface ArchilPlaceOptions {
+    disk: string;
+    region: string;
+    /** The disk's control API (`archilControl`). The place holds it; no instance ever does. */
+    control: SupervisorControl;
+    /**
+     * The driver that runs the instance (`localHost`, `dockerHost`, `daytonaHost`), set up with the app the instance runs.
+     * Its `kill` and `kills` are the place's.
+     */
+    host: HostDriver;
+    /** The run's id on the disk. Default: the context's `paths.id`. */
+    id?: string;
+    /** Where the driver mounts runs, for `paths`. Default: the driver's `mountRoot`, else /mnt/archil. */
+    mountRoot?: string;
+    /** More for each start's `ensureRunning`: the run directory's owner (`create`), token prefix and TTL, timeouts. */
+    ensure?: Omit<EnsureOptions, "control" | "demand" | "mountToken">;
+    /** How often a runner's host status is read. Default 1 s. */
+    pollMs?: number;
+    /** How long a start waits on a mount another start has in flight. Default 60 s. */
+    startTimeoutMs?: number;
+    /** How often `signals` reads the attempt's kill request over S3. Default 500 ms (the runner waits at its crossing). */
+    signalPollMs?: number;
+    /**
+     * How long those reads may fail (anything but a missing object) without a break before the iterator yields one
+     * `signals-failed` and ends. Default 60 s.
+     */
+    signalFailMs?: number;
+}
+/**
+ * The run on an Archil disk, its instance run by a host driver. `token(attempt)` mints the attempt's mount token through
+ * the place's control, and the runner it is handed to mounts with it. A start is `ensureRunning` (it creates the run's
+ * directory with `ensure.create` and writes the start mark) with that token and the order's environment. A kill is the
+ * driver's `kill`: `process` or `box`, whichever the driver takes. A recovery is the takeover: the dead holder's
+ * delegations revoked (its lease counts as expired, since the place killed it) and the next instance started, which
+ * `revoked` and `ms` report. A runner writes its kill request in the run's directory (`requestFile`), and `signals` reads
+ * it over S3. A runner ends when the driver no longer reports it running, or when the place killed it; its
+ * outcome is `run.json` read over S3, with `code`, `message`, `record` and `storeSha256` from the detail of the last
+ * status the app set. `release` stops every instance it started and removes every token it minted; the run's directory
+ * stays (`deleteRunTree`).
+ */
+export declare function archilPlace(options: ArchilPlaceOptions): (ctx: PlaceContext) => Place;