@prohost/cli 0.2.3 → 0.4.0

package/dist/agent/command.js

@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { agentLogPath, buildSystemdUnit, harnessArguments, installLaunchdDaemon, launchdLabel, uninstallLaunchdDaemon, } from './daemon.js';
 import { PairError, runPair } from './pair.js';
 import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome } from './credentials.js';
-import { DEFAULT_EXEC_TIMEOUT_MS, runAgentHarness } from './run.js';
+import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
 function flagString(flags, name) {
     const value = flags[name];
     return typeof value === 'string' ? value : undefined;
@@ -28,25 +28,93 @@ function flagString(flags, name) {
 function requestedWorkdir(flags) {
     return flagString(flags, 'workdir') ?? flagString(flags, 'cwd');
 }
-/** Returned by {@link parseTimeoutSeconds} for a value that isn't a timeout. */
-const INVALID_TIMEOUT = Symbol('invalid-timeout');
+/** Returned by {@link parseSeconds} for a value that isn't a duration. */
+export const INVALID_DURATION = Symbol('invalid-duration');
 /**
- * Read `--timeout`, complaining once for both commands that take it.
+ * Longest delay a timer can hold, in milliseconds — 2^31-1, just under 24.9
+ * days.
+ *
+ * The bound is `setTimeout`'s, not ours: a delay above this overflows the timer
+ * and Node **fires it after 1 ms instead**. So `--idle-timeout 2592000` ("give
+ * it thirty days") would not merely be ignored, it would kill the very first
+ * run on the spot and report it as stalled — the exact opposite of what was
+ * asked for, with nothing to explain it. Rejected at the flag rather than
+ * clamped, because anyone typing a number this large means "no limit", and both
+ * flags already spell that `0`.
  *
- * Returns ``undefined`` when the flag was absent (the harness applies its own
- * default) and {@link INVALID_TIMEOUT} after printing the error.
+ * Checked against the *converted* value rather than against seconds, because
+ * the flags take fractions: `--timeout 2147483.9` is under any whole-second
+ * ceiling and still overflows once multiplied out.
  */
-function parseTimeoutSeconds(flags) {
-    const raw = flagString(flags, 'timeout');
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * Read a duration flag's value. Pure — exported so it can be tested without a
+ * process to write errors to.
+ *
+ * Returns ``undefined`` only when the flag was genuinely absent (the harness
+ * then applies its own default) and {@link INVALID_DURATION} for anything that
+ * is not a non-negative, finite number of seconds.
+ *
+ * ``0`` is legal for both flags that use this, and means "no limit of this
+ * kind". For `--timeout` it was rejected until long runs existed, because
+ * before heartbeats an uncapped run on a laptop that went to sleep was a row
+ * that span forever.
+ *
+ * Takes the raw flag value rather than a string, because "the operator typed
+ * this flag and got it wrong" and "the operator did not type this flag" have
+ * to be told apart. `--timeout` with nothing after it, and `--timeout -1` —
+ * which the argument parser reads as two flags, since a value cannot begin
+ * with `-` — both arrive here as `true`. Treated as absent, they would apply
+ * the default silently and leave someone believing they had set a limit they
+ * had not.
+ */
+export function parseSeconds(raw) {
     if (raw === undefined)
         return undefined;
+    // An empty string is the `--timeout ''` case, and `Number('')` is 0 — which
+    // would quietly read as "no limit" rather than as the typo it is.
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return INVALID_DURATION;
     const seconds = Number(raw);
-    if (!Number.isFinite(seconds) || seconds <= 0) {
-        process.stderr.write('--timeout must be a positive number of seconds.\n');
-        return INVALID_TIMEOUT;
+    if (!Number.isFinite(seconds) || seconds < 0 || seconds * 1000 > MAX_TIMER_DELAY_MS) {
+        return INVALID_DURATION;
     }
     return seconds;
 }
+/**
+ * Read `--timeout`, complaining once for both commands that take it.
+ *
+ * The wall-clock ceiling is opt-in now (`DEFAULT_EXEC_TIMEOUT_MS` is 0), so an
+ * absent flag means "no ceiling" rather than "two hours".
+ */
+function parseTimeoutSeconds(flags) {
+    const parsed = parseSeconds(flags.timeout);
+    if (parsed === INVALID_DURATION) {
+        // Keeps the phrase "--timeout must be a positive number" verbatim: the
+        // desktop app's supervisor matches on it to tell a misconfigured child from
+        // a recoverable crash (`desktop/src/main/agent/supervisor-policy.ts`), and
+        // it reads this CLI's stderr rather than any structured output.
+        process.stderr.write('--timeout must be a positive number of seconds under 2147484 (about 24 days), ' +
+            'or 0 for no local limit.\n');
+    }
+    return parsed;
+}
+/**
+ * Read `--idle-timeout` — how long a run may produce nothing before it is
+ * treated as stalled.
+ *
+ * Validated in both commands for the same reason `--timeout` is: baked into a
+ * plist, a bad value makes every launch exit on this check and KeepAlive
+ * restart it forever.
+ */
+function parseIdleTimeoutSeconds(flags) {
+    const parsed = parseSeconds(flags['idle-timeout']);
+    if (parsed === INVALID_DURATION) {
+        process.stderr.write('--idle-timeout must be a positive number of seconds under 2147484 (about 24 days), ' +
+            'or 0 to disable the stall watchdog.\n');
+    }
+    return parsed;
+}
 /**
  * Environment the daemon must be given explicitly.
  *
@@ -120,7 +188,10 @@ async function installDaemonCommand(flags) {
     // plist makes every launch exit on that same validation and KeepAlive restart
     // it forever.
     const timeoutSeconds = parseTimeoutSeconds(flags);
-    if (timeoutSeconds === INVALID_TIMEOUT)
+    if (timeoutSeconds === INVALID_DURATION)
+        return 1;
+    const idleTimeoutSeconds = parseIdleTimeoutSeconds(flags);
+    if (idleTimeoutSeconds === INVALID_DURATION)
         return 1;
     // Absolute, and created now. A supervisor does not inherit the installing
     // shell's current directory, so a relative `--workdir .` copied verbatim into
@@ -142,6 +213,7 @@ async function installDaemonCommand(flags) {
         exec,
         workdir,
         timeoutSeconds,
+        idleTimeoutSeconds,
         machine: flagString(flags, 'machine'),
         url: flagString(flags, 'url'),
         allowUnverified: flags['allow-unverified'] === true,
@@ -215,7 +287,10 @@ async function runCommand(flags) {
     if (!credentials)
         return 1;
     const parsedTimeout = parseTimeoutSeconds(flags);
-    if (parsedTimeout === INVALID_TIMEOUT)
+    if (parsedTimeout === INVALID_DURATION)
+        return 1;
+    const parsedIdleTimeout = parseIdleTimeoutSeconds(flags);
+    if (parsedIdleTimeout === INVALID_DURATION)
         return 1;
     // First signal stops accepting work and lets the in-flight run finish
     // reporting itself (so the server doesn't wait on a run we abandoned); a
@@ -239,6 +314,7 @@ async function runCommand(flags) {
             machine: flagString(flags, 'machine'),
             cwd: requestedWorkdir(flags),
             timeoutMs: parsedTimeout === undefined ? DEFAULT_EXEC_TIMEOUT_MS : parsedTimeout * 1000,
+            idleTimeoutMs: parsedIdleTimeout === undefined ? DEFAULT_IDLE_TIMEOUT_MS : parsedIdleTimeout * 1000,
             dryRun: flags['dry-run'] === true,
             allowUnverified: flags['allow-unverified'] === true,
             // Two spellings for the same opt-out: `--safe-tools` says what you get,

package/dist/agent/contract.d.ts

@@ -13,6 +13,7 @@
  * Server-side sources of truth:
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -28,12 +29,55 @@ export declare const RUN_STATUS_SUCCEEDED = "succeeded";
 export declare const RUN_STATUS_FAILED = "failed";
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export declare const MAX_ERROR_CHARS = 1000;
+/**
+ * The completion `error` that means "a person asked for this run to stop".
+ *
+ * A magic string on purpose, and it must be sent **exactly**: the server
+ * matches on it to word the notice it drops in the thread ("cancelled" rather
+ * than "failed"). Prefixing it with a reason, or sending
+ * `cancelled_by_user: …`, makes a deliberate stop read as a crash.
+ */
+export declare const RUN_ERROR_CANCELLED_BY_USER = "cancelled_by_user";
+/**
+ * Cap on the `progress` string sent with a heartbeat.
+ *
+ * Progress is a hint for the UI — "using Bash", the first line of what the
+ * agent is drafting — not a transcript. Bounded here so a brain that emits one
+ * enormous block of text can't turn a keep-alive into a payload.
+ */
+export declare const MAX_PROGRESS_CHARS = 200;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export declare const REDEEM_PATH = "/v1/agent-pairing/redeem";
 /** `POST` — send a message into a conversation as the paired agent. */
 export declare function conversationMessagesPath(conversationId: string): string;
 /** `POST` — close out a run. Must be called for every run, success or not. */
 export declare function agentRunCompletePath(runId: string): string;
+/**
+ * `POST` — say a run is still alive, and hear back whether it was cancelled.
+ *
+ * The server holds a lease on every running row and reaps the ones that stop
+ * being heard from; a run that legitimately takes four hours has to say so on a
+ * cadence or it is reaped mid-work. The response also carries
+ * `cancel_requested`, which is the only way a laptop behind NAT learns that
+ * somebody pressed stop.
+ */
+export declare function agentRunHeartbeatPath(runId: string): string;
+/**
+ * Where this run's heartbeats go, in descending order of how much we know.
+ *
+ * 1. The `heartbeat` block, when the payload carries one. A path the server
+ *    stated is not a guess, so it is used verbatim.
+ * 2. Otherwise, derived from the server-supplied completion path: the two
+ *    calls are the same resource, so a server that moves its agent-run routes
+ *    moves both together and a CLI already on somebody's laptop follows
+ *    without a release.
+ * 3. Otherwise the documented path, for a completion path shaped in some way
+ *    we don't recognise.
+ *
+ * Steps 2 and 3 are exactly what shipped in 0.3.0 and are not going anywhere:
+ * the block is additive, and every server that predates it must keep working.
+ */
+export declare function heartbeatPathFor(run: AgentRunRequest): string;
 /**
  * A file or image hanging off a message.
  *
@@ -177,6 +221,14 @@ export interface AgentRunRequest {
     reply_body_extra?: Record<string, unknown>;
     /** Server-supplied path to complete the run at. */
     completion_path: string;
+    /**
+     * Server-supplied path to heartbeat the run at.
+     *
+     * Absent on every server built before the `heartbeat` block was added
+     * alongside `completion`, which is most of them — see {@link heartbeatPathFor}
+     * for what happens then.
+     */
+    heartbeat_path?: string;
     /**
      * Earlier messages on this surface, oldest first. Absent on a server that
      * predates the field — which is the case the harness shipped with, so an

package/dist/agent/contract.js

@@ -13,6 +13,7 @@
  * Server-side sources of truth:
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -28,6 +29,23 @@ export const RUN_STATUS_SUCCEEDED = 'succeeded';
 export const RUN_STATUS_FAILED = 'failed';
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export const MAX_ERROR_CHARS = 1000;
+/**
+ * The completion `error` that means "a person asked for this run to stop".
+ *
+ * A magic string on purpose, and it must be sent **exactly**: the server
+ * matches on it to word the notice it drops in the thread ("cancelled" rather
+ * than "failed"). Prefixing it with a reason, or sending
+ * `cancelled_by_user: …`, makes a deliberate stop read as a crash.
+ */
+export const RUN_ERROR_CANCELLED_BY_USER = 'cancelled_by_user';
+/**
+ * Cap on the `progress` string sent with a heartbeat.
+ *
+ * Progress is a hint for the UI — "using Bash", the first line of what the
+ * agent is drafting — not a transcript. Bounded here so a brain that emits one
+ * enormous block of text can't turn a keep-alive into a payload.
+ */
+export const MAX_PROGRESS_CHARS = 200;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export const REDEEM_PATH = '/v1/agent-pairing/redeem';
 /** `POST` — send a message into a conversation as the paired agent. */
@@ -38,6 +56,42 @@ export function conversationMessagesPath(conversationId) {
 export function agentRunCompletePath(runId) {
     return `/v1/agent-runs/${encodeURIComponent(runId)}/complete`;
 }
+/**
+ * `POST` — say a run is still alive, and hear back whether it was cancelled.
+ *
+ * The server holds a lease on every running row and reaps the ones that stop
+ * being heard from; a run that legitimately takes four hours has to say so on a
+ * cadence or it is reaped mid-work. The response also carries
+ * `cancel_requested`, which is the only way a laptop behind NAT learns that
+ * somebody pressed stop.
+ */
+export function agentRunHeartbeatPath(runId) {
+    return `/v1/agent-runs/${encodeURIComponent(runId)}/heartbeat`;
+}
+/**
+ * Where this run's heartbeats go, in descending order of how much we know.
+ *
+ * 1. The `heartbeat` block, when the payload carries one. A path the server
+ *    stated is not a guess, so it is used verbatim.
+ * 2. Otherwise, derived from the server-supplied completion path: the two
+ *    calls are the same resource, so a server that moves its agent-run routes
+ *    moves both together and a CLI already on somebody's laptop follows
+ *    without a release.
+ * 3. Otherwise the documented path, for a completion path shaped in some way
+ *    we don't recognise.
+ *
+ * Steps 2 and 3 are exactly what shipped in 0.3.0 and are not going anywhere:
+ * the block is additive, and every server that predates it must keep working.
+ */
+export function heartbeatPathFor(run) {
+    if (run.heartbeat_path)
+        return run.heartbeat_path;
+    const completion = run.completion_path;
+    const suffix = '/complete';
+    return completion.endsWith(suffix)
+        ? `${completion.slice(0, -suffix.length)}/heartbeat`
+        : agentRunHeartbeatPath(run.run_id);
+}
 /**
  * Ceiling on how many context entries are kept from one payload.
  *
@@ -208,6 +262,7 @@ export function parseRunRequest(data) {
     const trigger = obj(data.trigger);
     const replyInstructions = obj(data.reply_instructions);
     const completion = obj(data.completion);
+    const heartbeat = obj(data.heartbeat);
     const context = obj(data.context);
     const declaredSurface = str(replyInstructions.surface);
     const conversationId = str(data.conversation_id) ?? str(replyInstructions.conversation_id);
@@ -250,6 +305,9 @@ export function parseRunRequest(data) {
         reply_body_key: str(replyInstructions.body_field) ?? legacyBodyKeyFor(surface),
         reply_body_extra: bodyExtra(replyInstructions.body_extra),
         completion_path: str(completion.path) ?? agentRunCompletePath(runId),
+        // No fallback of its own: an absent block is not an error, it is an older
+        // server, and `heartbeatPathFor` already knows what to do about that.
+        heartbeat_path: str(heartbeat.path),
         // Accepted both at the top level and nested under `context`, because the
         // server can move them without a CLI release either way — and a published
         // CLI cannot be redeployed to follow.

package/dist/agent/daemon.d.ts

@@ -83,6 +83,8 @@ export interface HarnessInvocation {
     exec: string;
     workdir: string;
     timeoutSeconds?: number;
+    /** Seconds of total silence before a run is treated as stalled. */
+    idleTimeoutSeconds?: number;
     machine?: string;
     url?: string;
     allowUnverified?: boolean;

package/dist/agent/daemon.js

@@ -176,8 +176,14 @@ export function harnessArguments(invocation) {
         '--workdir',
         invocation.workdir,
     ];
+    // Compared against `undefined` rather than tested for truth: `0` is a real
+    // setting for both flags — no wall-clock cap, no watchdog — and dropping it
+    // would install a daemon quietly running the defaults instead.
     if (invocation.timeoutSeconds !== undefined)
         args.push('--timeout', String(invocation.timeoutSeconds));
+    if (invocation.idleTimeoutSeconds !== undefined) {
+        args.push('--idle-timeout', String(invocation.idleTimeoutSeconds));
+    }
     if (invocation.machine)
         args.push('--machine', invocation.machine);
     if (invocation.url)

package/dist/agent/exec.d.ts

@@ -17,12 +17,49 @@ export interface ExecOptions {
     command: string;
     /** Prompt written to the child's stdin. */
     prompt: string;
-    /** Hard cap on wall-clock runtime. */
+    /**
+     * Hard cap on wall-clock runtime.
+     *
+     * ``0`` disables it: the child then runs until it exits on its own, until
+     * {@link cancelSignal} fires, or until the server gives up on the run. That
+     * is a real configuration (`--timeout 0`), not a degenerate one — some work
+     * genuinely takes hours and a local clock is the wrong thing to bound it by.
+     */
     timeoutMs: number;
+    /**
+     * Kill the run when the child produces **nothing** for this long.
+     *
+     * The question a wall clock cannot answer: is this run working, or wedged?
+     * Bytes on stdout or stderr are the one signal every brain emits — stream
+     * events, a progress line, a log — so a window of total silence is the
+     * closest thing to evidence that a child has stopped making progress rather
+     * than merely taking a while. Every chunk on either stream resets it.
+     *
+     * ``0`` or unset disables it, at which point only {@link timeoutMs}, the
+     * {@link cancelSignal} and the server's lease can end the run.
+     */
+    idleTimeoutMs?: number;
     /** Working directory for the child. Defaults to the CLI's cwd. */
     cwd?: string;
     /** Extra environment for the child, merged over ``process.env``. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Ends the run early — a person pressed stop, or the server closed the run.
+     *
+     * Terminated through exactly the same SIGTERM → grace → SIGKILL path a
+     * timeout uses, because the problem is identical: the thing being stopped is
+     * a process *group* that may be ignoring polite signals.
+     */
+    cancelSignal?: AbortSignal;
+    /**
+     * Each stdout chunk, as it arrives.
+     *
+     * The captured ``stdout`` is still returned in full; this exists for the
+     * things that cannot wait for the process to exit — reading a session id out
+     * of the first event, tracking what the agent is doing for the heartbeat, and
+     * having *something* to salvage from a run that gets killed.
+     */
+    onStdout?: (chunk: string) => void;
     /** Injectable spawn — tests substitute a fake process. */
     spawnImpl?: typeof spawn;
 }
@@ -31,18 +68,54 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
     exitCode: number | null;
+    /** The run overran {@link ExecOptions.timeoutMs}. */
     timedOut: boolean;
+    /**
+     * The run went silent for {@link ExecOptions.idleTimeoutMs} and was killed.
+     *
+     * Separate from {@link timedOut} because the two say different things to
+     * whoever reads the failure: one run used its whole budget, the other stopped
+     * doing anything at all. They are handled identically everywhere else — both
+     * are kills from outside, so both salvage partial output and keep the
+     * session they had recorded.
+     */
+    idleTimedOut: boolean;
+    /** The run was stopped through {@link ExecOptions.cancelSignal}. */
+    cancelled: boolean;
     /** Populated when the process could not be started at all. */
     error?: string;
     durationMs: number;
 }
 /** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
 export declare const MAX_OUTPUT_CHARS: number;
+/** ``error`` on a result the caller stopped deliberately. */
+export declare const CANCELLED_ERROR = "cancelled";
+/**
+ * What a timed-out run reports.
+ *
+ * Ends with the way out, because this string does not stay in `agent.log`: the
+ * server echoes a failed run's error into the thread, so the person who was
+ * waiting reads it. Told "timed out after 7200000ms" they learn only that
+ * something broke; told how to raise the ceiling they can fix it themselves.
+ * Kept to one line for the same reason.
+ */
+export declare function timeoutMessage(timeoutMs: number): string;
+/**
+ * What a run killed by the inactivity watchdog reports.
+ *
+ * Same job as {@link timeoutMessage}, and the same constraint: the server
+ * echoes a failed run's error into the thread, so this is read by the person
+ * who was waiting rather than by whoever tails `agent.log`. It has to say what
+ * happened ("nothing came out of it"), that this is an inference rather than a
+ * crash the agent reported, and how to change the judgement — in one line,
+ * because the notice it lands in has room for one.
+ */
+export declare function idleTimeoutMessage(idleTimeoutMs: number): string;
 /**
  * Execute the agent command with ``prompt`` on stdin and return its stdout.
  *
- * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
- * as ``ok: false`` with the detail filled in, because the caller must report
- * *some* outcome to the server for every run.
+ * Never throws: a spawn failure, a non-zero exit, a timeout, and a cancellation
+ * all come back as ``ok: false`` with the detail filled in, because the caller
+ * must report *some* outcome to the server for every run.
  */
 export declare function execAgent(options: ExecOptions): Promise<ExecResult>;