@prohost/cli 0.2.3 → 0.4.0

package/dist/agent/prompt.js

@@ -6,6 +6,87 @@
  * a shell script that greps it. The reply contract is stated explicitly so an
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
+/**
+ * Say the run's budget in a unit a reader thinks in.
+ *
+ * Rounded on purpose — the agent is being told roughly how much room it has,
+ * and "about 120 minutes" is the honest shape of a ceiling it will never be
+ * told the exact remainder of.
+ */
+function renderBudget(timeoutMs) {
+    if (timeoutMs >= 90 * 60_000) {
+        const hours = timeoutMs / 3_600_000;
+        return `about ${Number.isInteger(hours) ? hours : hours.toFixed(1)} hours`;
+    }
+    if (timeoutMs >= 60_000)
+        return `about ${Math.round(timeoutMs / 60_000)} minutes`;
+    return `about ${Math.max(1, Math.round(timeoutMs / 1_000))} seconds`;
+}
+/**
+ * The bullet that tells the agent what its run is actually bounded by.
+ *
+ * Three shapes, and each says something different about how to work:
+ *
+ * * **A wall-clock ceiling** (`--timeout <n>`) means budget the turn. Naming
+ *   the number is what stops an agent from treating two hours like five
+ *   minutes — the failure this replaced was a multi-minute coding task killed
+ *   at 300s having been told only that "a limit" existed. A watchdog set
+ *   *shorter* than the ceiling is named alongside it, because it is then the
+ *   deadline that actually fires first: told only "you have two hours", an
+ *   agent has no reason to break up the quiet forty-minute step that kills it
+ *   at fifteen.
+ * * **The watchdog alone** — the default — means the turn is bounded by
+ *   *silence*, not duration. That is a limit an agent can actually act on, and
+ *   it must be stated as what it is, because an agent told it has "no limit"
+ *   and then killed at fifteen minutes of quiet was told something false.
+ * * **Neither** means nothing local will stop the run, which still needs a word
+ *   about pace: nothing is posted until the turn ends, so a run that explores
+ *   forever reads, from the thread, exactly like one that crashed.
+ */
+function timeBudgetLines(timeoutMs, idleTimeoutMs) {
+    // Said nothing about by the caller: say nothing back, rather than describe a
+    // regime this prompt has not been told is in force.
+    if (timeoutMs === undefined && idleTimeoutMs === undefined)
+        return [];
+    const wallMs = timeoutMs ?? 0;
+    const idleMs = idleTimeoutMs ?? 0;
+    if (wallMs > 0) {
+        return [
+            `- You have ${renderBudget(wallMs)} for this whole turn. Past that you are killed`,
+            '  mid-thought and the person waiting gets nothing, so spend the budget on the',
+            '  work and leave yourself room to write the answer.',
+            // Only when it can actually fire first. A watchdog window at or above the
+            // ceiling is unreachable — a run silent that long has already overrun —
+            // and naming an unreachable limit is noise the agent has to reason past.
+            ...(idleMs > 0 && idleMs < wallMs
+                ? [
+                    '- Going quiet ends the turn early, well before that: produce no output at',
+                    `  all for ${renderBudget(idleMs)} and the run is killed and reported as`,
+                    '  stalled. Ordinary work clears that on its own; a single step that will',
+                    '  be silent for longer is the one thing to break up.',
+                ]
+                : []),
+        ];
+    }
+    if (idleMs > 0) {
+        return [
+            '- There is no fixed time limit on this turn, so work that genuinely takes a',
+            '  while is fine — finish it rather than cutting it short. What is limited is',
+            `  silence: produce no output at all for ${renderBudget(idleMs)} and the run is`,
+            '  killed and reported as stalled. Ordinary work clears that on its own; a',
+            '  single step that will be quiet for longer than that is the one thing to',
+            '  break up. Nothing you write is posted until the turn ends, so keep moving',
+            '  toward an answer rather than exploring indefinitely.',
+        ];
+    }
+    return [
+        '- There is no time limit on this turn and nothing local will stop it, so work',
+        '  that genuinely takes a while is fine — finish it rather than cutting it',
+        '  short. But nothing you write is posted until the turn ends, so a run that',
+        '  explores indefinitely is indistinguishable from one that crashed. Keep',
+        '  moving toward an answer.',
+    ];
+}
 /**
  * Describe one attachment.
  *
@@ -139,6 +220,11 @@ export function buildPrompt(run, context) {
             '  as you call them. Do the work rather than proposing it — but that\n' +
             '  also means a mistaken action happens for real, so check before you\n' +
             '  change or delete anything.', '- Nothing about your access changes after this turn. Do not say a tool is', '  "connecting", "loading", or about to become available, and do not', '  promise to follow up.', 
+    // Stated up here with the other facts about the shape of the invocation,
+    // not buried under the tool advice: how long the agent has changes how it
+    // should approach the work, so it has to be read before any of the "go and
+    // look" bullets below.
+    ...timeBudgetLines(context.timeoutMs, context.idleTimeoutMs), 
     // Claude Code lazy-loads part of its catalog — WebSearch/WebFetch among
     // them — so a run that inspects its loaded tools concludes it cannot
     // browse and says so to a customer, when one ToolSearch call away it
@@ -169,8 +255,7 @@ export function buildPrompt(run, context) {
             '  tell anyone you have no access to some repository, codebase, log, or',
             '  capability, take a QUICK look for it: the usual places a checkout',
             '  lives, `gh auth status`, whether the command is on PATH. A quick',
-            '  look, not an audit — this run has a hard time limit and somebody',
-            '  waiting at the end of it.',
+            '  look, not an audit — there is somebody waiting at the end of this.',
             '- "Looking" means running the command, not inspecting your own tool',
             '  list. Say you have no shell, no file access, or no checkout only',
             '  after an attempt failed and you can quote what it said. Introspection',

package/dist/agent/run.d.ts

@@ -16,12 +16,46 @@
  * * **Runs are deduped on ``run_id``.** Webhook deliveries retry, and each
  *   attempt is mirrored to this socket. Without dedupe a retry would execute
  *   the command a second time and post a second reply.
+ *
+ * Runs can be long — hours — so every run this process has accepted and not yet
+ * reported is heartbeated (see `heartbeat.ts`), including the ones still queued
+ * behind the executing one. That keeps the server's lease alive and is the only
+ * way a stop pressed in the UI reaches a machine that accepts no connections.
  */
 import type { spawn } from 'node:child_process';
 import WebSocket from 'ws';
 import type { AgentCredentials } from './credentials.js';
-/** Default ceiling on one agent invocation. */
-export declare const DEFAULT_EXEC_TIMEOUT_MS = 300000;
+/**
+ * Default ceiling on one agent invocation: none.
+ *
+ * The wall clock kept being raised — five minutes, then two hours — because it
+ * was answering the wrong question. "How long has this run been going?" does
+ * not distinguish a wedged child from a productive one; it only distinguishes
+ * long work from short, and killing long work is precisely the failure the two
+ * previous defaults each produced in production. What the harness can actually
+ * observe is whether the child is *doing* anything, which is what
+ * {@link DEFAULT_IDLE_TIMEOUT_MS} watches.
+ *
+ * So a run is now bounded by three things, none of them a fixed duration:
+ * the inactivity watchdog (default 15 minutes of total silence), the server's
+ * lease on the run (heartbeats stop, the row is reaped), and the Stop button in
+ * ProhostAI (which reaches this machine on the next heartbeat). `--timeout`
+ * remains fully supported for anyone who wants a hard ceiling as well.
+ */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 0;
+/**
+ * Default silence window before a run is treated as stalled.
+ *
+ * Fifteen minutes is chosen against what real work looks like, not against
+ * what feels responsive: an agent mid-task emits stream events, tool calls and
+ * log lines continuously, so the gaps in a healthy run are seconds. The long
+ * tail that legitimately goes quiet is a single slow tool call — a test suite,
+ * a build, a big fetch — and fifteen minutes clears those comfortably while
+ * still catching the failure this exists for, a child wedged on a stdin prompt
+ * that heartbeats look perfectly healthy for and that burns the operator's
+ * tokens and their agent's availability indefinitely.
+ */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 900000;
 export interface AgentRunOptions {
     /** Shell command that runs the agent, e.g. ``claude -p``. */
     exec: string;
@@ -30,8 +64,16 @@ export interface AgentRunOptions {
     url?: string;
     /** Machine name shown in the ProhostAI UI. Defaults to the OS hostname. */
     machine?: string;
-    /** Per-run execution timeout. */
+    /**
+     * Per-run wall-clock ceiling. ``0`` disables it, and that is now the default
+     * — see {@link DEFAULT_EXEC_TIMEOUT_MS}.
+     */
     timeoutMs?: number;
+    /**
+     * How long a run may produce no output at all before it is killed. ``0``
+     * disables the watchdog — see {@link DEFAULT_IDLE_TIMEOUT_MS}.
+     */
+    idleTimeoutMs?: number;
     /** Print the reply that would be posted and make no writes. */
     dryRun?: boolean;
     /** Execute runs whose signature could not be verified. Off by default. */
@@ -73,6 +115,12 @@ export interface AgentRunOptions {
     };
     /** Environment used to locate the run ledger (tests point this at a temp dir). */
     env?: NodeJS.ProcessEnv;
+    /**
+     * How often open runs are heartbeated. Defaults to
+     * {@link HEARTBEAT_INTERVAL_MS}; tests shorten it so a cancellation arrives
+     * inside a test's lifetime.
+     */
+    heartbeatIntervalMs?: number;
 }
 export interface AgentRunMetrics {
     connections: number;