@dna113p/machines 0.1.0 → 0.3.0

package/dist/src/run-inbox.d.ts

@@ -0,0 +1,49 @@
+import type { HumanRequest, HumanResponse, HumanRunner } from "./index.ts";
+import { type RunStatusHuman } from "./run-status.ts";
+type PendingRequest = Pick<RunStatusHuman, "choices" | "discussion"> & {
+    readonly requestId: string;
+};
+export interface RunResponse {
+    readonly directory: string;
+    readonly runId: string;
+    readonly requestId: string;
+    readonly response: HumanResponse;
+    /** How long to wait for the run to take the response. */
+    readonly timeoutMilliseconds?: number;
+}
+/**
+ * Answers a waiting run from another process of the same user. Resolves once
+ * the run has left the request and named this delivery among the responses it
+ * took; otherwise throws, having taken the response back unless the run
+ * already has it.
+ */
+export declare function respondToRun(options: RunResponse): Promise<void>;
+/**
+ * Hands `accept` the first valid inbox response to a request, then stops; the
+ * returned function stops earlier. Start watching before the request is
+ * published: whatever is already in the inbox predates it and is dropped.
+ * The run's record must name the `delivery` it applies before leaving the
+ * request, or the sender is told its response was not taken.
+ */
+export declare function watchRunInbox(directory: string, runId: string, request: PendingRequest, accept: (response: HumanResponse, delivery: string | undefined) => void): () => void;
+export interface InboxHumanOptions {
+    readonly directory: string;
+    readonly runId: string;
+    /** Publishes the request in the run's record so that others can answer it. */
+    publish(request: RunStatusHuman & {
+        readonly requestId: string;
+    }): void;
+    /** Names, in the run's record, the inbox response that answered the request. */
+    acknowledge(delivery: string): void;
+    readonly terminal?: (request: HumanRequest, signal: AbortSignal) => Promise<string>;
+    /** The terminal cannot answer this request; only the inbox can. */
+    readonly onTerminalClosed?: (requestId: string) => void;
+    /** The terminal gave an answer the request does not allow, and is asked again. */
+    readonly onTerminalRefused?: (reason: string) => void;
+}
+/**
+ * A Human runner for a published run: asks on the terminal and watches the
+ * run's inbox, and whichever answers first wins.
+ */
+export declare function inboxHuman(options: InboxHumanOptions): HumanRunner;
+export {};

package/dist/src/run-inbox.js

@@ -0,0 +1,229 @@
+import { randomUUID } from "node:crypto";
+import { linkSync, readFileSync, renameSync, rmSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { deliveryRetentionMilliseconds, isFileSafeId, isProcessAlive, readRunStatuses, runDeliveryPath, runInboxPath, } from "./run-status.js";
+import { TerminalInputClosed, terminalHuman } from "./terminal-human.js";
+const pollMilliseconds = 100;
+const confirmationMilliseconds = 5_000;
+/**
+ * Answers a waiting run from another process of the same user. Resolves once
+ * the run has left the request and named this delivery among the responses it
+ * took; otherwise throws, having taken the response back unless the run
+ * already has it.
+ */
+export async function respondToRun(options) {
+    const { directory, runId, requestId, response } = options;
+    const published = () => (isFileSafeId(runId)
+        ? readRunStatuses(directory).find((record) => record.id === runId)
+        : undefined);
+    const record = published();
+    if (record === undefined)
+        throw new Error(`Machine run "${runId}" is not published in ${directory}`);
+    const request = pendingRequest(record);
+    if (request === undefined)
+        throw new Error(`Machine run "${runId}" is not waiting for Human input`);
+    if (request.requestId === undefined) {
+        throw new Error(`Machine run "${runId}" does not take a response from outside its host`);
+    }
+    if (request.requestId !== requestId) {
+        throw new Error(`Machine run "${runId}" is waiting on request "${request.requestId}", not "${requestId}"`);
+    }
+    const refusal = responseRefusal(request, response);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    const delivery = randomUUID();
+    const withdraw = deliver(directory, runId, { delivery, requestId, response });
+    const timeout = options.timeoutMilliseconds ?? confirmationMilliseconds;
+    const delivered = Date.now();
+    while (true) {
+        const current = published();
+        const left = pendingRequest(current)?.requestId !== requestId;
+        // The run also removes a response it discards, so only its record says which ones it took.
+        if (left && current?.deliveries?.includes(delivery) === true)
+            return;
+        const waited = Date.now() - delivered;
+        // A record still names every response its run took since this one was delivered.
+        if (left && waited < deliveryRetentionMilliseconds) {
+            withdraw();
+            throw new Error(`Response to Machine run "${runId}" was not confirmed: the run left request "${requestId}" without taking it`);
+        }
+        if (left || waited >= timeout) {
+            throw new Error(`Response to Machine run "${runId}" was not confirmed within ${timeout / 1_000}s${withdraw() ? "; it was withdrawn and will not be applied" : ""}`);
+        }
+        await sleep(Math.min(pollMilliseconds / 2, timeout));
+    }
+}
+/**
+ * Hands `accept` the first valid inbox response to a request, then stops; the
+ * returned function stops earlier. Start watching before the request is
+ * published: whatever is already in the inbox predates it and is dropped.
+ * The run's record must name the `delivery` it applies before leaving the
+ * request, or the sender is told its response was not taken.
+ */
+export function watchRunInbox(directory, runId, request, accept) {
+    takeRunResponse(directory, runId);
+    const timer = setInterval(() => {
+        const message = takeRunResponse(directory, runId);
+        // A response to another request, or one this request does not allow, is discarded.
+        if (message === undefined || message.requestId !== request.requestId)
+            return;
+        if (responseRefusal(request, message.response) !== undefined)
+            return;
+        clearInterval(timer);
+        accept(message.response, message.delivery);
+    }, pollMilliseconds);
+    return () => clearInterval(timer);
+}
+/**
+ * A Human runner for a published run: asks on the terminal and watches the
+ * run's inbox, and whichever answers first wins.
+ */
+export function inboxHuman(options) {
+    const { directory, runId } = options;
+    const terminal = options.terminal ?? askTerminal;
+    return (request) => new Promise((resolve, reject) => {
+        const requestId = randomUUID();
+        const asked = new AbortController();
+        let settled = false;
+        const settle = (finish) => {
+            if (settled)
+                return;
+            settled = true;
+            stopWatching();
+            asked.abort();
+            finish();
+        };
+        const stopWatching = watchRunInbox(directory, runId, { ...request, requestId }, (response, delivery) => {
+            settle(() => {
+                if (delivery !== undefined)
+                    options.acknowledge(delivery);
+                resolve(response);
+            });
+        });
+        options.publish({ ...request, requestId });
+        const ask = () => new Promise((answer) => answer(terminal(request, asked.signal))).then((answer) => {
+            if (settled)
+                return;
+            // Only a valid answer wins: one the request does not allow leaves it waiting on both sources.
+            const refusal = responseRefusal(request, answer);
+            if (refusal === undefined)
+                return settle(() => resolve(answer));
+            options.onTerminalRefused?.(refusal);
+            void ask();
+        }, (cause) => {
+            if (settled)
+                return;
+            // Without terminal input the published request is the only way to
+            // answer. When nobody can see it either, fail as an unpublished run does.
+            const visible = readRunStatuses(directory)
+                .some((record) => record.id === runId && record.human?.requestId === requestId);
+            if (cause instanceof TerminalInputClosed && visible)
+                options.onTerminalClosed?.(requestId);
+            else
+                settle(() => reject(cause));
+        });
+        void ask();
+    });
+}
+function askTerminal(request, signal) {
+    // Input that ended during an earlier request never closes a new prompt, so say it is closed.
+    return process.stdin.readableEnded ? Promise.reject(new TerminalInputClosed()) : terminalHuman(request, signal);
+}
+function pendingRequest(record) {
+    // A record whose process is gone can no longer be answered.
+    return record?.status === "waiting" && isProcessAlive(record.pid) ? record.human : undefined;
+}
+/** Why a request does not allow a response, checked before delivery and again on receipt. */
+function responseRefusal(request, response) {
+    if (typeof response === "string") {
+        return request.choices === undefined || request.choices.includes(response)
+            ? undefined
+            : `Expected one of: ${request.choices.join(", ")}`;
+    }
+    if (request.discussion !== true)
+        return "This Human request does not support discussion";
+    return response.text.trim() === "" || response.text.length > 8000
+        ? "Question must contain 1–8000 characters"
+        : undefined;
+}
+/**
+ * Puts a response in the run's inbox, which holds one at a time. Returns a
+ * function that takes it back and tells whether it did: false means the run
+ * already has it.
+ *
+ * The inbox's name is shared by every sender, so nothing can be learned from it
+ * and then acted on: it may hold a later response by then. A response therefore
+ * has a second name that carries its delivery, and removing that name, which
+ * only one process can do, decides who owns it. Only the run removes a file
+ * from the inbox.
+ */
+function deliver(directory, runId, message) {
+    const sent = runDeliveryPath(directory, runId, message.delivery);
+    try {
+        writeFileSync(sent, `${JSON.stringify(message)}\n`, { mode: 0o600 });
+        // The run only ever sees a whole response, and a link, unlike a rename,
+        // cannot replace one that is already pending.
+        linkSync(sent, runInboxPath(directory, runId));
+    }
+    catch (cause) {
+        rmSync(sent, { force: true });
+        if (cause.code !== "EEXIST")
+            throw cause;
+        throw new Error(`Machine run "${runId}" already has a response pending`);
+    }
+    return () => {
+        try {
+            // Emptied through its own name first, so that what stays in the inbox until
+            // the run next reads it, and discards it, no longer holds the response.
+            truncateSync(sent);
+            unlinkSync(sent);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** Removes whatever is pending from the inbox and returns it if it is a response the run now owns. */
+function takeRunResponse(directory, runId) {
+    const taken = join(directory, `.${runId}.${randomUUID()}.inbox.taken`);
+    try {
+        // Moved out before it is read, so what is read is what was removed, whatever arrives next.
+        renameSync(runInboxPath(directory, runId), taken);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const message = JSON.parse(readFileSync(taken, "utf8"));
+        if (!isInboxMessage(message))
+            return undefined;
+        // Fails when the sender has taken the response back.
+        if (message.delivery !== undefined)
+            unlinkSync(runDeliveryPath(directory, runId, message.delivery));
+        return message;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        rmSync(taken, { force: true });
+    }
+}
+function isInboxMessage(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const { delivery, requestId, response } = value;
+    if (typeof requestId !== "string")
+        return false;
+    // The delivery becomes part of a file name.
+    if (delivery !== undefined && (typeof delivery !== "string" || !/^[A-Za-z0-9_-]+$/u.test(delivery)))
+        return false;
+    if (typeof response === "string")
+        return true;
+    if (response === null || typeof response !== "object")
+        return false;
+    const question = response;
+    return question.type === "question" && typeof question.text === "string";
+}

package/dist/src/run-status.d.ts

@@ -0,0 +1,97 @@
+import type { StateValue } from "xstate";
+/** One published run, stored as `<MACHINES_RUN_STATUS_DIR>/<id>.json`. */
+export interface RunStatusRecord {
+    /** Version 1 records carry only `human.prompt`. */
+    readonly schemaVersion: 1 | 2;
+    readonly id: string;
+    readonly pid: number;
+    readonly owner?: string;
+    /** The enclosing run when this one was started from inside another Machine. */
+    readonly parent?: string;
+    /** What this run is for, as its launcher chose to describe it. */
+    readonly label?: string;
+    readonly machine: string;
+    readonly path: string;
+    readonly cwd: string;
+    readonly status: "running" | "waiting" | "completed" | "failed";
+    readonly state?: string;
+    /** When the current state was entered. */
+    readonly stateSince?: string;
+    readonly agent?: RunStatusAgent;
+    /** Present while the current Agent state waits for a usage limit to reset; `status` stays `running`. */
+    readonly limit?: RunStatusLimit;
+    readonly human?: RunStatusHuman;
+    /** Names the inbox responses the run took lately, so that each sender can tell; never a response. */
+    readonly deliveries?: readonly string[];
+    readonly error?: string;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+}
+/** The pending Human request: what a surface needs to show it and to answer it. */
+export interface RunStatusHuman {
+    readonly prompt: string;
+    /** Names this request to `machine respond`; absent when the run takes no outside response. */
+    readonly requestId?: string;
+    readonly choices?: readonly string[];
+    readonly suggestions?: readonly string[];
+    readonly discussion?: boolean;
+}
+export interface RunStatusAgent {
+    readonly harness: string;
+    readonly model?: string;
+    readonly thinking?: string;
+}
+/** A wait for an Agent usage limit: a one-line summary, and when the wait is expected to end. */
+export interface RunStatusLimit {
+    readonly text: string;
+    readonly until?: string;
+}
+export interface RunStatusRun {
+    readonly id?: string;
+    readonly machine: string;
+    readonly path: string;
+    readonly cwd: string;
+    readonly startedAt?: string;
+}
+/** A present key replaces its field; a present key holding `undefined` clears it. */
+export interface RunStatusChange {
+    readonly status?: "running" | "waiting";
+    readonly state?: StateValue;
+    readonly agent?: RunStatusAgent;
+    /** Leaving the state clears it as well. */
+    readonly limit?: RunStatusLimit;
+    readonly human?: RunStatusHuman;
+    /** Names an inbox response the run took, in addition to those its record already names. */
+    readonly delivery?: string;
+}
+export type RunStatusOutcome = {
+    readonly state?: StateValue;
+} | {
+    readonly error: string;
+};
+export interface RunStatusPublisher {
+    update(change: RunStatusChange): void;
+    finish(outcome: RunStatusOutcome): void;
+}
+/** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
+export declare const deliveryRetentionMilliseconds = 60000;
+/** The directory runs publish to, or undefined while publication is off. */
+export declare function runStatusDirectory(environment?: NodeJS.ProcessEnv): string | undefined;
+/** The one pending outside response for a run, kept beside its record. */
+export declare function runInboxPath(directory: string, id: string): string;
+/**
+ * A second name for a response in a run's inbox, which its sender keeps. Only
+ * the sender and the run remove it, and whichever does owns the response.
+ */
+export declare function runDeliveryPath(directory: string, id: string, delivery: string): string;
+/**
+ * Publishes one run for hosts that can only read files, such as a status line.
+ * Opt-in through MACHINES_RUN_STATUS_DIR. Publication is presentation: it never
+ * throws, and it records neither Machine input nor output.
+ */
+export declare function createRunStatusPublisher(run: RunStatusRun, environment?: NodeJS.ProcessEnv): RunStatusPublisher;
+/** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
+export declare function readRunStatuses(directory: string): RunStatusRecord[];
+/** The id becomes a file name, so it must not be able to leave the directory. */
+export declare function isFileSafeId(id: string): boolean;
+export declare function isProcessAlive(pid: number): boolean;

package/dist/src/run-status.js

@@ -0,0 +1,285 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+const staleAfterMilliseconds = 60 * 60 * 1_000;
+/** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
+export const deliveryRetentionMilliseconds = 60_000;
+const disabled = { update() { }, finish() { } };
+let temporaryFiles = 0;
+/** The directory runs publish to, or undefined while publication is off. */
+export function runStatusDirectory(environment = process.env) {
+    const configured = environment.MACHINES_RUN_STATUS_DIR;
+    return configured === undefined || configured === "" ? undefined : resolve(configured);
+}
+/** The one pending outside response for a run, kept beside its record. */
+export function runInboxPath(directory, id) {
+    return join(directory, `${id}.inbox`);
+}
+/**
+ * A second name for a response in a run's inbox, which its sender keeps. Only
+ * the sender and the run remove it, and whichever does owns the response.
+ */
+export function runDeliveryPath(directory, id, delivery) {
+    return join(directory, `.${id}.${delivery}.inbox.sent`);
+}
+/**
+ * Publishes one run for hosts that can only read files, such as a status line.
+ * Opt-in through MACHINES_RUN_STATUS_DIR. Publication is presentation: it never
+ * throws, and it records neither Machine input nor output.
+ */
+export function createRunStatusPublisher(run, environment = process.env) {
+    const directory = runStatusDirectory(environment);
+    const id = run.id ?? randomUUID();
+    if (directory === undefined || !isFileSafeId(id))
+        return disabled;
+    const owner = environment.MACHINES_RUN_OWNER || environment.CLAUDE_CODE_SESSION_ID || undefined;
+    const parent = environment.MACHINES_RUN_PARENT || undefined;
+    const label = formatLabel(environment.MACHINES_RUN_LABEL);
+    const startedAt = run.startedAt ?? new Date().toISOString();
+    let status = "running";
+    let state;
+    let stateSince;
+    let agent;
+    let limit;
+    let human;
+    let deliveries = [];
+    let error;
+    const publish = () => {
+        const record = {
+            schemaVersion: 2,
+            id,
+            pid: process.pid,
+            ...(owner === undefined ? {} : { owner }),
+            ...(parent === undefined ? {} : { parent }),
+            ...(label === undefined ? {} : { label }),
+            machine: run.machine,
+            path: run.path,
+            cwd: run.cwd,
+            status,
+            ...(state === undefined ? {} : { state }),
+            ...(stateSince === undefined ? {} : { stateSince }),
+            ...(agent === undefined ? {} : { agent }),
+            ...(limit === undefined ? {} : { limit }),
+            ...(human === undefined ? {} : { human }),
+            ...(deliveries.length === 0 ? {} : { deliveries: deliveries.map((delivery) => delivery.id) }),
+            ...(error === undefined ? {} : { error }),
+            startedAt,
+            updatedAt: new Date().toISOString(),
+        };
+        try {
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            // Readers only ever see a whole record: write beside it, then rename over it.
+            const temporary = join(directory, `.${id}.${process.pid}.${temporaryFiles += 1}.tmp`);
+            try {
+                writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+                renameSync(temporary, join(directory, `${id}.json`));
+            }
+            catch (cause) {
+                rmSync(temporary, { force: true });
+                throw cause;
+            }
+        }
+        catch {
+            // A status line is never worth a run: an unwritable directory is ignored.
+        }
+    };
+    try {
+        pruneRunStatuses(directory);
+    }
+    catch {
+        // Pruning is best effort for the same reason.
+    }
+    publish();
+    return {
+        update(change) {
+            if (status === "completed" || status === "failed")
+                return;
+            const nextState = "state" in change ? formatState(change.state) : state;
+            const next = {
+                status: change.status ?? status,
+                state: nextState,
+                agent: "agent" in change ? pickAgent(change.agent) : agent,
+                // A wait belongs to the state whose Agent is waiting.
+                limit: "limit" in change ? pickLimit(change.limit) : nextState === state ? limit : undefined,
+                human: "human" in change ? pickHuman(change.human) : human,
+                // A later response must not hide an earlier one from a sender that has yet to look.
+                deliveries: change.delivery === undefined ? deliveries : [
+                    ...deliveries.filter((delivery) => Date.now() - delivery.takenAt < deliveryRetentionMilliseconds),
+                    { id: change.delivery, takenAt: Date.now() },
+                ],
+            };
+            // Repeated notifications for an unchanged run do not need another write.
+            if (JSON.stringify(next) === JSON.stringify({ status, state, agent, limit, human, deliveries }))
+                return;
+            if (next.state !== state)
+                stateSince = new Date().toISOString();
+            ({ status, state, agent, limit, human, deliveries } = next);
+            publish();
+        },
+        finish(outcome) {
+            if (status === "completed" || status === "failed")
+                return;
+            if ("error" in outcome) {
+                status = "failed";
+                error = outcome.error;
+            }
+            else {
+                status = "completed";
+                state = formatState(outcome.state) ?? state;
+            }
+            stateSince = undefined;
+            agent = undefined;
+            limit = undefined;
+            human = undefined;
+            publish();
+            try {
+                // Nothing reads the inbox from here on, and only the run empties it.
+                rmSync(runInboxPath(directory, id), { force: true });
+            }
+            catch {
+                // Left for pruning.
+            }
+        },
+    };
+}
+/** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
+export function readRunStatuses(directory) {
+    return readRecordFiles(directory).map(({ record }) => record);
+}
+function pruneRunStatuses(directory) {
+    const now = Date.now();
+    for (const { file, record } of readRecordFiles(directory)) {
+        const settled = record.status === "completed" || record.status === "failed" || !isProcessAlive(record.pid);
+        if (!settled || now - Date.parse(record.updatedAt) <= staleAfterMilliseconds)
+            continue;
+        try {
+            rmSync(file, { force: true });
+            // A response nobody collected goes with the run it was meant for, under each of its names.
+            const id = basename(file, ".json");
+            rmSync(runInboxPath(directory, id), { force: true });
+            for (const name of readdirSync(directory)) {
+                if (!name.startsWith(`.${id}.`))
+                    continue;
+                if (/^[^.]+\.inbox\.(?:sent|taken)$/u.test(name.slice(id.length + 2)))
+                    rmSync(join(directory, name), { force: true });
+            }
+        }
+        catch {
+            // Another publisher may have pruned it first.
+        }
+    }
+}
+function readRecordFiles(directory) {
+    let names;
+    try {
+        names = readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        if (name.startsWith(".") || !name.endsWith(".json"))
+            continue;
+        const file = join(directory, name);
+        try {
+            const record = JSON.parse(readFileSync(file, "utf8"));
+            if (isRunStatusRecord(record))
+                found.push({ file, record });
+        }
+        catch {
+            // Not a record, or replaced while it was being read.
+        }
+    }
+    return found;
+}
+function isRunStatusRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    const agent = record.agent;
+    const human = record.human;
+    const limit = record.limit;
+    return (record.schemaVersion === 1 || record.schemaVersion === 2)
+        && typeof record.id === "string" && record.id !== ""
+        && Number.isSafeInteger(record.pid) && record.pid > 0
+        && isOptionalString(record.owner)
+        && isOptionalString(record.parent)
+        && isOptionalString(record.label)
+        && (record.stateSince === undefined || isTimestamp(record.stateSince))
+        && typeof record.machine === "string"
+        && typeof record.path === "string"
+        && typeof record.cwd === "string"
+        && (record.status === "running" || record.status === "waiting"
+            || record.status === "completed" || record.status === "failed")
+        && isOptionalString(record.state)
+        && (agent === undefined || (agent !== null && typeof agent === "object" && typeof agent.harness === "string"
+            && isOptionalString(agent.model) && isOptionalString(agent.thinking)))
+        && (human === undefined || (human !== null && typeof human === "object" && typeof human.prompt === "string"
+            && isOptionalString(human.requestId) && isOptionalStrings(human.choices) && isOptionalStrings(human.suggestions)
+            && (human.discussion === undefined || typeof human.discussion === "boolean")))
+        && (limit === undefined || (limit !== null && typeof limit === "object" && typeof limit.text === "string"
+            && isOptionalString(limit.until)))
+        && isOptionalStrings(record.deliveries)
+        && isOptionalString(record.error)
+        && isTimestamp(record.startedAt)
+        && isTimestamp(record.updatedAt);
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+function isOptionalStrings(value) {
+    return value === undefined || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function isTimestamp(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+/** The id becomes a file name, so it must not be able to leave the directory. */
+export function isFileSafeId(id) {
+    return /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/u.test(id);
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        // EPERM means the process exists but belongs to someone else.
+        return cause.code === "EPERM";
+    }
+}
+function formatState(state) {
+    if (state === undefined)
+        return undefined;
+    return typeof state === "string" ? state : JSON.stringify(state);
+}
+/** One short line: a label is a caption, not a place for task text. */
+function formatLabel(label) {
+    const line = label?.split(/\r?\n/u).map((part) => part.trim()).find((part) => part !== "");
+    return line === undefined ? undefined : line.slice(0, 160);
+}
+function pickAgent(agent) {
+    if (agent === undefined)
+        return undefined;
+    return {
+        harness: agent.harness,
+        ...(agent.model === undefined ? {} : { model: agent.model }),
+        ...(agent.thinking === undefined ? {} : { thinking: agent.thinking }),
+    };
+}
+function pickLimit(limit) {
+    if (limit === undefined)
+        return undefined;
+    return { text: limit.text, ...(limit.until === undefined ? {} : { until: limit.until }) };
+}
+function pickHuman(human) {
+    if (human === undefined)
+        return undefined;
+    return {
+        prompt: human.prompt,
+        ...(human.requestId === undefined ? {} : { requestId: human.requestId }),
+        ...(human.choices === undefined ? {} : { choices: [...human.choices] }),
+        ...(human.suggestions === undefined ? {} : { suggestions: [...human.suggestions] }),
+        ...(human.discussion === true ? { discussion: true } : {}),
+    };
+}