product-console-companion 0.5.0 → 0.5.2

package/README.md

@@ -88,11 +88,22 @@ npx product-console-companion run
 (this is what `connect` already ran for you, unless you passed `--no-run`) polls each configured
 connection every few seconds until Ctrl+C. Nothing runs while this isn't running — see the parent
 plan's Section 7 for why that's deliberate (goal 4: no AI spend while you're not around to
-notice).
+notice). The companion periodically confirms that it is still watching while idle and always
+reports why its process exits, including an unexpected exit that should be restarted.
+
+For an unattended run, use a simple supervisor loop so the companion comes back even if its
+process is stopped by something outside its control:
+
+```powershell
+while ($true) { npx product-console-companion@latest run; Write-Host "companion exited - restarting in 5s"; Start-Sleep 5 }
+```
+
+With this loop, Ctrl+C exits the current companion and then starts it again. Close the terminal
+window to stop it for good.
 
 ## What's NOT yet implemented (be aware before relying on this)
 
-- **Per-task budget is not enforced client-side for the `api-key` backend.** Every dispatched
+- **The `api-key` backend does not enforce the per-task budget.** Every dispatched
   task carries a `maxBudgetUsd` (visible in the `run` log line); `api-key-caller.ts` does not
   track spend against it or abort a call that exceeds it. The `cli` backend passes it straight
   through as `claude`'s own `--max-budget-usd`, which the CLI does enforce (confirmed

package/dist/cli.js

@@ -7,6 +7,41 @@ import { CompanionClient, CompanionHttpError } from './http-client.js';
 import { assertIsRepo, currentCommit } from './local-scan.js';
 import { runAnalyseShipmentTask, runDesignPromptTask, runGenerateSpecBatchTask, runGenericTask, runProposeNewCapabilitiesTask, runProposeSkeletonTask, runVerifyModuleTask } from './api-key-caller.js';
 import { runAnalyseShipmentTaskViaCli, runDesignPromptTaskViaCli, runGenerateSpecBatchTaskViaCli, runGenericTaskViaCli, runProposeNewCapabilitiesTaskViaCli, runProposeSkeletonTaskViaCli, runVerifyModuleTaskViaCli } from './claude-cli-caller.js';
+let expectedExitReason = null;
+let unexpectedExitReason = null;
+function asError(reason) {
+    return reason instanceof Error ? reason : new Error(String(reason));
+}
+function logFatal(label, reason) {
+    const error = asError(reason);
+    console.error(`${label}: ${error.message}`);
+    console.error(error.stack ?? '(no stack available)');
+    return error;
+}
+process.on('uncaughtException', (reason) => {
+    const error = logFatal('FATAL uncaught exception', reason);
+    unexpectedExitReason = `uncaught exception: ${error.message}`;
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    const error = logFatal('FATAL unhandled rejection', reason);
+    unexpectedExitReason = `unhandled rejection: ${error.message}`;
+    process.exit(1);
+});
+process.on('exit', (code) => {
+    const timestamp = new Date().toISOString();
+    if (unexpectedExitReason) {
+        const reason = /[.!?]$/.test(unexpectedExitReason) ? unexpectedExitReason : `${unexpectedExitReason}.`;
+        console.error(`[${timestamp}] Companion exited unexpectedly (code ${code}): ${reason} Restart it to keep watching for work.`);
+    }
+    else if (expectedExitReason) {
+        const reason = /[.!?]$/.test(expectedExitReason) ? expectedExitReason : `${expectedExitReason}.`;
+        console.log(`[${timestamp}] Companion exited normally (code ${code}): ${reason}`);
+    }
+    else {
+        console.error(`[${timestamp}] Companion exited unexpectedly (code ${code}) without completing its command. Restart it to keep watching for work.`);
+    }
+});
 /** A flag with nothing after it (end of argv, or the next token is itself another "--flag") is
  *  treated as a bare boolean ("true") rather than swallowing the following flag as its value —
  *  needed for --no-run below. Every existing "--flag value" pair still parses exactly as before. */
@@ -136,6 +171,10 @@ const IDLE_POLL_MS = 5000;
 /** How often to extend a claimed task's lease while it's in flight — comfortably inside the
  *  server's ~2-minute lease window (server/store.ts's LOCAL_TASK_LEASE_MS). */
 const HEARTBEAT_MS = 30_000;
+/** How long to wait before retrying after something escapes the per-operation error handling. */
+const LOOP_RECOVERY_DELAY_MS = 1000;
+/** A quiet proof-of-life while no task is claimed. */
+const IDLE_STATUS_MS = 5 * 60_000;
 /** The explicitly repo-aware task kinds, companion-side. Everything else falls through to a
  *  connectionless runner: only our server creates tasks, their ModelTaskSpec is self-describing
  *  (model, effort, maxTokens, system, stable/volatile text, optional schema), and graph reasoning
@@ -163,12 +202,13 @@ async function runTask(task, backend, anthropic, repoPath) {
     return backend === 'cli' ? runGenericTaskViaCli(task, repoPath) : runGenericTask(anthropic, task, repoPath);
 }
 async function runOneTask(anthropic, backend, client, repoPath, task) {
-    console.log(`[${new Date().toISOString()}] claimed ${task.kind} task ${task.id} via ${backend} (budget $${task.maxBudgetUsd.toFixed(2)} — not yet enforced client-side, see README)`);
+    console.log(`[${new Date().toISOString()}] claimed ${task.kind} task ${task.id} via ${backend} (budget $${task.maxBudgetUsd.toFixed(2)})`);
     const heartbeat = setInterval(() => {
-        void client.heartbeat(task.id).catch((err) => console.error('  heartbeat failed:', err instanceof Error ? err.message : err));
+        void client.heartbeat(task.id).catch((err) => console.error('  heartbeat warning:', err instanceof Error ? err.message : err));
     }, HEARTBEAT_MS);
     try {
         const { result, filesRead } = await runTask(task, backend, anthropic, repoPath);
+        clearInterval(heartbeat);
         await client.reportResult(task.id, result, filesRead);
         console.log(`  done — reported result (${filesRead.length} file${filesRead.length === 1 ? '' : 's'} read)`);
     }
@@ -241,54 +281,76 @@ async function cmdRun() {
     console.log('Waiting for work — leave this running. Ctrl+C any time to stop.');
     let stopping = false;
     process.on('SIGINT', () => {
-        if (stopping)
+        if (stopping) {
+            expectedExitReason = 'forced stop after a second Ctrl+C';
             process.exit(1); // second Ctrl+C: stop waiting, exit immediately
+        }
         console.log('\nStopping after the current poll — Ctrl+C again to force quit.');
+        expectedExitReason = 'stopped by Ctrl+C';
         stopping = true;
     });
+    let lastIdleStatusAt = Date.now();
     while (!stopping) {
-        let claimedAny = false;
-        for (const c of config.connections) {
-            if (stopping)
-                break;
-            let claim;
-            try {
-                claim = await client.claimNext(c.connectionId);
+        try {
+            let claimedAny = false;
+            for (const c of config.connections) {
+                if (stopping)
+                    break;
+                let claim;
+                try {
+                    claim = await client.claimNext(c.connectionId);
+                }
+                catch (err) {
+                    if (err instanceof CompanionHttpError && err.status === 401) {
+                        console.error('Token rejected (revoked?) — stopping. Pair a new token and reconnect.');
+                        expectedExitReason = 'the server rejected its token; pair a new token and reconnect';
+                        return;
+                    }
+                    console.error(`Poll failed for ${c.connectionId}:`, err instanceof Error ? err.message : err);
+                    continue;
+                }
+                if (!claim.task)
+                    continue;
+                claimedAny = true;
+                await runOneTask(anthropic, c.backend, client, c.repoPath, claim.task);
             }
-            catch (err) {
-                if (err instanceof CompanionHttpError && err.status === 401) {
-                    console.error('Token rejected (revoked?) — stopping. Pair a new token and reconnect.');
-                    return;
+            if (!stopping && config.pollWorkspaceTasks) {
+                let claim;
+                try {
+                    claim = await client.claimNext();
+                }
+                catch (err) {
+                    if (err instanceof CompanionHttpError && err.status === 401) {
+                        console.error('Token rejected (revoked?) — stopping. Pair a new token and reconnect.');
+                        expectedExitReason = 'the server rejected its token; pair a new token and reconnect';
+                        return;
+                    }
+                    console.error('Workspace-level poll failed:', err instanceof Error ? err.message : err);
+                    claim = { task: null };
+                }
+                if (claim.task) {
+                    claimedAny = true;
+                    // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
+                    await runOneTask(anthropic, workspaceBackend, client, process.cwd(), claim.task);
                 }
-                console.error(`Poll failed for ${c.connectionId}:`, err instanceof Error ? err.message : err);
-                continue;
             }
-            if (!claim.task)
-                continue;
-            claimedAny = true;
-            await runOneTask(anthropic, c.backend, client, c.repoPath, claim.task);
-        }
-        if (!stopping && config.pollWorkspaceTasks) {
-            let claim;
-            try {
-                claim = await client.claimNext();
+            if (claimedAny) {
+                lastIdleStatusAt = Date.now();
             }
-            catch (err) {
-                if (err instanceof CompanionHttpError && err.status === 401) {
-                    console.error('Token rejected (revoked?) — stopping. Pair a new token and reconnect.');
-                    return;
+            else if (!stopping) {
+                const now = Date.now();
+                if (now - lastIdleStatusAt >= IDLE_STATUS_MS) {
+                    console.log(`[${new Date(now).toISOString()}] still watching — no work claimed.`);
+                    lastIdleStatusAt = now;
                 }
-                console.error('Workspace-level poll failed:', err instanceof Error ? err.message : err);
-                claim = { task: null };
-            }
-            if (claim.task) {
-                claimedAny = true;
-                // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
-                await runOneTask(anthropic, workspaceBackend, client, process.cwd(), claim.task);
+                await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
             }
         }
-        if (!claimedAny && !stopping)
-            await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
+        catch (err) {
+            console.error('Unexpected run-loop error:', err instanceof Error ? err.message : err);
+            if (!stopping)
+                await new Promise((r) => setTimeout(r, LOOP_RECOVERY_DELAY_MS));
+        }
     }
     console.log('Stopped.');
 }
@@ -301,4 +363,12 @@ async function main() {
     console.log('Usage: product-console-companion <connect|run> [flags]');
     process.exitCode = cmd ? 1 : 0;
 }
-void main();
+main()
+    .then(() => {
+    expectedExitReason ??= 'command completed';
+})
+    .catch((reason) => {
+    const error = logFatal('FATAL top-level error', reason);
+    unexpectedExitReason = `top-level error: ${error.message}`;
+    process.exitCode = 1;
+});

package/dist/http-client.js

@@ -1,3 +1,8 @@
+const WHOAMI_TIMEOUT_MS = 15_000;
+const CLAIM_TIMEOUT_MS = 10_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+const RESULT_TIMEOUT_MS = 60_000;
+const ERROR_REPORT_TIMEOUT_MS = 30_000;
 export class CompanionHttpError extends Error {
     status;
     constructor(status, message) {
@@ -12,10 +17,11 @@ export class CompanionClient {
         this.url = url;
         this.token = token;
     }
-    async call(path, init) {
+    async call(path, timeoutMs, init) {
         const res = await fetch(`${this.url}${path}`, {
             ...init,
             headers: { ...init?.headers, Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(timeoutMs),
         });
         const body = (await res.json().catch(() => ({})));
         if (!res.ok)
@@ -23,22 +29,22 @@ export class CompanionClient {
         return body;
     }
     whoami() {
-        return this.call('/api/companion/whoami');
+        return this.call('/api/companion/whoami', WHOAMI_TIMEOUT_MS);
     }
     claimNext(connectionId) {
-        return this.call(connectionId ? `/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}` : '/api/companion/tasks/next');
+        return this.call(connectionId ? `/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}` : '/api/companion/tasks/next', CLAIM_TIMEOUT_MS);
     }
     heartbeat(taskId) {
-        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, { method: 'POST' });
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, HEARTBEAT_TIMEOUT_MS, { method: 'POST' });
     }
     reportResult(taskId, result, filesRead) {
-        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/result`, {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/result`, RESULT_TIMEOUT_MS, {
             method: 'POST',
             body: JSON.stringify({ result, filesRead }),
         });
     }
     reportError(taskId, error) {
-        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/error`, {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/error`, ERROR_REPORT_TIMEOUT_MS, {
             method: 'POST',
             body: JSON.stringify({ error }),
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-console-companion",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Local-first BYOS companion for the Fynch Product Console — reads code and runs AI calls from your own machine instead of the hosted server.",
   "type": "module",
   "license": "MIT",