@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/runtime/lease-renewal.js

@@ -0,0 +1,433 @@
+"use strict";
+/**
+ * LEASE RENEWAL FOR A SLOW, SILENT TURN — the fix for "a turn is requeued
+ * underneath itself".
+ *
+ * THE PROBLEM. Lease extension rode ENTIRELY on `/ingest` piggy-backing
+ * `leaseExpiresAt`: every successful ingest pushes the visibility timeout out by
+ * LEASE_TTL_MS (120 s). `renewLease` existed on the client but had ZERO call
+ * sites. So a turn that is slow AND produces no parts for over 120 s — one long
+ * tool call, one slow model, a big file read — has its lease expire while it is
+ * still working. The watchdog then requeues the session onto ANOTHER runner, and
+ * two runners run the same turn: two writers interleaving one transcript, double
+ * the model spend, and eventually MAX_REQUEUE_ATTEMPTS poisoning the turn.
+ *
+ * THE FIX, in two halves:
+ *
+ *   1. Renew on a TIMER for the whole duration of the turn, comfortably inside
+ *      LEASE_TTL_MS, so a silent turn keeps its lease alive without waiting for
+ *      output to ingest.
+ *
+ *   2. Handle `{ renewed: false }` by ABANDONING the turn. A lease that could
+ *      not be renewed has already expired and been requeued elsewhere; another
+ *      runner owns the session now. Continuing to spend model budget on work we
+ *      no longer own is exactly the double-execution this fix exists to stop, so
+ *      the turn's AbortController is fired and the runner stops.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPROVAL_RENEW_INTERVAL_MS = exports.DEFAULT_RENEW_INTERVAL_MS = void 0;
+exports.startIsolatedLeaseRenewal = startIsolatedLeaseRenewal;
+exports.startLeaseRenewal = startLeaseRenewal;
+const node_worker_threads_1 = require("node:worker_threads");
+const contract_1 = require("../contract");
+const control_plane_1 = require("../control-plane");
+/** The default renewal cadence: half of LEASE_TTL_MS, so one lost renewal is survivable. */
+exports.DEFAULT_RENEW_INTERVAL_MS = 60_000;
+/**
+ * THE CADENCE WHILE A HUMAN IS BEING WAITED ON — and why this route, not the
+ * heartbeat.
+ *
+ * A permission prompt is only useful if it appears, and is answered, at
+ * conversational speed. Measured against the channels that existed before this
+ * change:
+ *
+ *   heartbeat            30 s   the ONLY carrier of sessionCommands
+ *   lease long-poll      25 s   but NOT polled at all during a turn — the loop
+ *                               sees `active.size >= maxConcurrentSessions` and
+ *                               sleeps 500 ms without calling the route
+ *   lease renew          60 s   per-lease, runs for the whole turn, carried
+ *                               no commands
+ *
+ * So the brief's premise — "commands ride back on BOTH the heartbeat and the
+ * lease poll, and the lease poll is far tighter" — does not hold in this build.
+ * `sessionCommands` is returned by exactly one route (handlers/runners.ts:391,
+ * the heartbeat), and the lease poll is not even called while the turn that
+ * needs the answer is running. Every approval would have cost up to 30 s.
+ *
+ * THE RENEW ROUTE IS THE RIGHT CARRIER, for three reasons that all point the
+ * same way:
+ *   1. It is the only control-plane call that already runs for the whole
+ *      duration of a turn, which is exactly the window an approval lives in.
+ *   2. It is already per-lease and per-runner authenticated, so it needs no new
+ *      auth path and no new route — `takePendingCommands` matches on the
+ *      session's runner and can simply be called there too.
+ *   3. It is the same call that keeps the turn from being scavenged. One call
+ *      proves the turn is alive AND collects the answer, so the two can never
+ *      disagree about whether the turn still exists.
+ *
+ * Two seconds matches the runner's own backend poll interval, so the answer and
+ * the backend's reaction to it land in the same beat. It is expensive only
+ * while a human is genuinely being waited on, which is rare, bounded by the
+ * person, and precisely when the extra call is worth making.
+ */
+exports.APPROVAL_RENEW_INTERVAL_MS = 2_000;
+/*
+ * A real OS thread owns both the timer and the HTTP request. Pi can therefore
+ * spend as long as it needs in synchronous output processing without starving
+ * the lease. Keep this source self-contained: `eval` means the published
+ * CommonJS package does not need a second worker entry point or a loader.
+ */
+const RENEWAL_WORKER_SOURCE = String.raw `
+const { parentPort, workerData } = require('node:worker_threads');
+let stopped = false;
+let inFlight = false;
+let urgent = false;
+let credential = workerData.runnerCredential;
+let githubTokenExpiresAt = workerData.githubTokenExpiresAt;
+let modelTokenExpiresAt = workerData.modelTokenExpiresAt;
+let timer = null;
+
+function arm() {
+  if (timer) clearInterval(timer);
+  const interval = urgent ? workerData.urgentIntervalMs : workerData.baseIntervalMs;
+  timer = setInterval(renew, interval);
+  timer.unref();
+}
+
+async function renew() {
+  if (stopped || inFlight) return;
+  inFlight = true;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15000);
+  timeout.unref();
+  try {
+    const response = await fetch(workerData.url, {
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer ' + credential,
+        'Content-Type': 'application/json',
+        [workerData.protocolHeader]: String(workerData.protocolVersion)
+      },
+      body: JSON.stringify({
+        protocolVersion: workerData.protocolVersion,
+        ...(githubTokenExpiresAt ? { githubTokenExpiresAt } : {}),
+        ...(modelTokenExpiresAt ? { modelTokenExpiresAt } : {})
+      }),
+      signal: controller.signal
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      const reason = workerData.path + ' returned ' + response.status + ': ' + text.slice(0, 400);
+      if (workerData.finalStatuses.includes(response.status)) {
+        stopped = true;
+        clearInterval(timer);
+        parentPort.postMessage({ type: 'final-error', status: response.status, reason });
+      } else {
+        parentPort.postMessage({ type: 'transient-error', reason });
+      }
+      return;
+    }
+    const result = text ? JSON.parse(text) : {};
+    if (result.githubCredential?.expiresAt) {
+      githubTokenExpiresAt = result.githubCredential.expiresAt;
+    }
+    if (result.modelTokenExpiresAt) {
+      modelTokenExpiresAt = result.modelTokenExpiresAt;
+    }
+    parentPort.postMessage({ type: 'result', result });
+    if (result.renewed === false) {
+      stopped = true;
+      clearInterval(timer);
+    }
+  } catch (error) {
+    parentPort.postMessage({
+      type: 'transient-error',
+      reason: error instanceof Error ? error.message : String(error)
+    });
+  } finally {
+    clearTimeout(timeout);
+    inFlight = false;
+  }
+}
+
+parentPort.on('message', (message) => {
+  if (message.type === 'stop') {
+    stopped = true;
+    if (timer) clearInterval(timer);
+    parentPort.close();
+  } else if (message.type === 'urgent' && urgent !== message.value) {
+    urgent = message.value;
+    arm();
+  } else if (message.type === 'credential') {
+    credential = message.value;
+  }
+});
+arm();
+`;
+/**
+ * Renew a lease outside the adapter's event loop.
+ *
+ * The callbacks still run on the main thread, but the lease extension does
+ * not depend on them. Messages wait safely in the worker port until Pi yields.
+ */
+function startIsolatedLeaseRenewal(options) {
+    const log = options.log ?? (() => undefined);
+    const path = new URL(options.url).pathname;
+    const worker = new node_worker_threads_1.Worker(RENEWAL_WORKER_SOURCE, {
+        eval: true,
+        workerData: {
+            url: options.url.replace('__LEASE_ID__', encodeURIComponent(options.leaseId)),
+            path,
+            runnerCredential: options.runnerCredential,
+            githubTokenExpiresAt: options.githubTokenExpiresAt,
+            modelTokenExpiresAt: options.modelTokenExpiresAt,
+            baseIntervalMs: options.intervalMs ?? exports.DEFAULT_RENEW_INTERVAL_MS,
+            urgentIntervalMs: options.urgentIntervalMs ?? exports.APPROVAL_RENEW_INTERVAL_MS,
+            protocolVersion: contract_1.PROTOCOL_VERSION,
+            protocolHeader: contract_1.PROTOCOL_VERSION_HEADER,
+            finalStatuses: contract_1.FINAL_HTTP_STATUSES
+        }
+    });
+    worker.unref();
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        try {
+            worker.postMessage({ type: 'stop' });
+        }
+        catch {
+            // The error event can arrive after the thread is already gone. Stopping
+            // a dead renewal worker is complete, not a new harness-level failure.
+        }
+        const forcedStop = setTimeout(() => {
+            void worker.terminate();
+        }, 1_000);
+        forcedStop.unref();
+    };
+    worker.on('message', (message) => {
+        if (stopped)
+            return;
+        if (message.type === 'result') {
+            const result = message.result;
+            if (result.sessionCommands?.length) {
+                try {
+                    options.onCommands?.(result.sessionCommands);
+                }
+                catch (error) {
+                    log('Command handler threw on a renewal', {
+                        leaseId: options.leaseId,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            if (result.githubCredential) {
+                options.onGithubCredential?.(result.githubCredential);
+            }
+            if (result.modelToken && result.modelTokenExpiresAt) {
+                options.onModelCredential?.({
+                    token: result.modelToken,
+                    expiresAt: result.modelTokenExpiresAt
+                });
+            }
+            if (result.renewed === false) {
+                const reason = result.reason ?? 'lease expired or belongs to another runner';
+                log('Lease could not be renewed; abandoning the turn', {
+                    leaseId: options.leaseId,
+                    reason
+                });
+                stop();
+                options.onLost(reason);
+            }
+            return;
+        }
+        if (message.type === 'final-error') {
+            log('Lease renewal failed with a final status; abandoning the turn', {
+                leaseId: options.leaseId,
+                status: message.status,
+                reason: message.reason
+            });
+            stop();
+            options.onLost(message.reason);
+            return;
+        }
+        log('Lease renewal failed transiently; will retry', {
+            leaseId: options.leaseId,
+            reason: message.reason
+        });
+    });
+    worker.on('error', (error) => {
+        if (stopped)
+            return;
+        const reason = `lease renewal worker failed: ${error.message}`;
+        log('Lease renewal worker failed; abandoning the turn', {
+            leaseId: options.leaseId,
+            reason
+        });
+        stop();
+        options.onLost(reason);
+    });
+    worker.on('exit', (code) => {
+        if (stopped)
+            return;
+        const reason = `lease renewal worker exited unexpectedly with code ${code}`;
+        log('Lease renewal worker exited; abandoning the turn', {
+            leaseId: options.leaseId,
+            reason
+        });
+        stopped = true;
+        options.onLost(reason);
+    });
+    return {
+        stop,
+        setUrgent: (value) => {
+            if (!stopped)
+                worker.postMessage({ type: 'urgent', value });
+        },
+        setCredential: (value) => {
+            if (!stopped)
+                worker.postMessage({ type: 'credential', value });
+        }
+    };
+}
+/**
+ * Keep a lease alive for the duration of a turn. Returns a `stop` function the
+ * caller MUST call when the turn ends, so a completed turn does not keep
+ * renewing a lease that has already been released.
+ *
+ * A renewal that fails with a TRANSIENT error (a network blip, a 500) is logged
+ * and retried on the next tick — losing one renewal is why the cadence is half
+ * the TTL. Only a definitive `renewed: false`, or a FINAL HTTP status, means the
+ * lease is truly gone and the turn must be abandoned.
+ */
+function startLeaseRenewal(options) {
+    const baseIntervalMs = options.intervalMs ?? exports.DEFAULT_RENEW_INTERVAL_MS;
+    const urgentIntervalMs = options.urgentIntervalMs ?? exports.APPROVAL_RENEW_INTERVAL_MS;
+    const setIntervalFn = options.setIntervalImpl ?? setInterval;
+    const clearIntervalFn = options.clearIntervalImpl ?? clearInterval;
+    const log = options.log ?? (() => undefined);
+    let stopped = false;
+    let inFlight = false;
+    let currentIntervalMs = baseIntervalMs;
+    let githubTokenExpiresAt = options.githubTokenExpiresAt;
+    let modelTokenExpiresAt = options.modelTokenExpiresAt;
+    // A holder rather than a bare `let`, so `stop` can reference the handle that
+    // is assigned just below without a use-before-assign or a prefer-const fight.
+    const timer = { handle: null };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (timer.handle)
+            clearIntervalFn(timer.handle);
+    };
+    const onTick = () => {
+        // Never let two renewals overlap: a renew that is slow must not have a
+        // second one queued behind it, which on a struggling control plane would
+        // only add load at the worst moment.
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        const renewalRequest = githubTokenExpiresAt || modelTokenExpiresAt
+            ? options.client.renewLease(options.leaseId, undefined, githubTokenExpiresAt, modelTokenExpiresAt)
+            : options.client.renewLease(options.leaseId);
+        void renewalRequest
+            .then((result) => {
+            if (stopped)
+                return;
+            /*
+             * COMMANDS FIRST, AND BEFORE THE renewed:false CHECK.
+             *
+             * A renewal that reports the lease gone can still be carrying the
+             * user's answer — the control plane hands out commands and evaluates
+             * the lease in the same response. Dropping them because the turn is
+             * ending would silently lose an answer the user has already given, and
+             * `delivered_at` is set at hand-off, so it would never be re-sent.
+             */
+            if (result.sessionCommands?.length) {
+                try {
+                    options.onCommands?.(result.sessionCommands);
+                }
+                catch (error) {
+                    // A bad command handler must never stop the renewal loop; that
+                    // would turn a rendering bug into a requeued turn.
+                    log('Command handler threw on a renewal', {
+                        leaseId: options.leaseId,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            if (result.githubCredential) {
+                githubTokenExpiresAt = result.githubCredential.expiresAt;
+                options.onGithubCredential?.(result.githubCredential);
+            }
+            if (result.modelToken && result.modelTokenExpiresAt) {
+                modelTokenExpiresAt = result.modelTokenExpiresAt;
+                options.onModelCredential?.({
+                    token: result.modelToken,
+                    expiresAt: result.modelTokenExpiresAt
+                });
+            }
+            if (result.renewed === false) {
+                log('Lease could not be renewed; abandoning the turn', {
+                    leaseId: options.leaseId,
+                    reason: result.reason
+                });
+                stop();
+                options.onLost(result.reason ?? 'lease expired or belongs to another runner');
+            }
+        })
+            .catch((error) => {
+            if (stopped)
+                return;
+            // A FINAL status (401/403/404/409/426) means the lease or the runner is
+            // gone for good — abandon, exactly as for `renewed: false`. A transient
+            // error is left for the next tick.
+            if (error instanceof control_plane_1.ControlPlaneError && error.final) {
+                log('Lease renewal failed with a final status; abandoning the turn', {
+                    leaseId: options.leaseId,
+                    status: error.status,
+                    code: error.code,
+                    reason: error.message
+                });
+                stop();
+                options.onLost(error.message);
+                return;
+            }
+            log('Lease renewal failed transiently; will retry', {
+                leaseId: options.leaseId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    const arm = () => {
+        timer.handle = setIntervalFn(onTick, currentIntervalMs);
+        // Never hold the event loop open on the renewal timer alone.
+        timer.handle.unref?.();
+    };
+    const setUrgent = (urgent) => {
+        if (stopped)
+            return;
+        const wanted = urgent ? urgentIntervalMs : baseIntervalMs;
+        // Idempotent. Re-arming on every call would let a caller that repeatedly
+        // asserts the same state postpone a renewal indefinitely, which on the
+        // ordinary 60 s cadence is how a lease quietly expires.
+        if (wanted === currentIntervalMs)
+            return;
+        currentIntervalMs = wanted;
+        if (timer.handle)
+            clearIntervalFn(timer.handle);
+        arm();
+        log('Lease renewal cadence changed', {
+            leaseId: options.leaseId,
+            intervalMs: currentIntervalMs,
+            urgent
+        });
+    };
+    arm();
+    return { stop, setUrgent };
+}

package/dist/runtime/mcp-auth-proxy.d.ts

@@ -0,0 +1,82 @@
+/**
+ * MCP AUTH PROXY — extracted from 20x `src/main/mcp-auth-proxy.ts`.
+ *
+ * WHY IT EXISTS, unchanged from the original: ACP, OpenCode and Claude Code all
+ * bake MCP server headers at SESSION start and none of them refresh those
+ * headers mid-session. A one-hour token therefore expires during a long agent
+ * run, and every MCP tool call after that point returns 401 with no recovery
+ * path — the session is alive, the model keeps trying, and every tool fails
+ * until a human notices. This proxy decouples token lifetime from session
+ * lifetime by fetching a fresh token PER REQUEST.
+ *
+ * AND IT MATTERS EVEN MORE ON A RUNNER. The agent is pointed at
+ * `127.0.0.1:<port>/<id>`, so the real gateway URL and the real token never
+ * appear in an MCP config file, in a backend's session state, or in anything
+ * the agent can read. The token is in this process's memory and nowhere else.
+ *
+ * WHAT CHANGED IN THE EXTRACTION
+ * - `enterpriseAuth.getJwt()` became the `TokenInjector` port, so the desktop
+ *   passes its enterprise JWT and a runner passes the session-scoped MCP token
+ *   from the lease.
+ * - `new Notification(...)` on a token failure became the `Notifier` port, a
+ *   no-op on a server.
+ * - Module-level singletons (`let server`, `let port`, three Maps and a
+ *   counter) became instance state. The original could only ever have ONE proxy
+ *   per process, which is correct for a desktop with one signed-in user and
+ *   wrong for a runner that may hold several sessions with DIFFERENT tokens.
+ *   Sharing one proxy across sessions there would let session A's agent reach
+ *   session B's targets by guessing a small integer id.
+ * - Ids are random, not `nextId++`. See `registerTarget`.
+ *
+ * ON "THE HARNESS MUST NEVER OPEN A LISTENING PORT": this binds 127.0.0.1 ONLY,
+ * exactly as the health check does. The property that rule protects is that
+ * nothing outside the host can initiate a connection to the harness, so a
+ * customer VM behind NAT needs no tunnel. A loopback socket is not reachable
+ * from the network and does not weaken it. Binding 0.0.0.0 here WOULD, and the
+ * test suite asserts the bind address.
+ */
+import { Notifier, TokenInjector } from '../ports';
+export interface McpAuthProxyOptions {
+    tokens: TokenInjector;
+    notifier?: Notifier;
+    /** Injected in tests. Defaults to console. */
+    logger?: Pick<Console, 'warn' | 'error' | 'log'>;
+}
+export declare class McpAuthProxy {
+    private readonly options;
+    private server;
+    private port;
+    private readonly targets;
+    /** Reverse lookup, so re-registering the same URL does not leak ids. */
+    private readonly idsByUrl;
+    /** One notification per integration per process, not one per failed call. */
+    private readonly notifiedFailures;
+    private readonly logger;
+    constructor(options: McpAuthProxyOptions);
+    getPort(): number | null;
+    /**
+     * Register a real MCP URL and get back a loopback URL that injects a fresh
+     * token on every forwarded request. Returns null when the proxy is not running.
+     *
+     * IDS ARE RANDOM, where the 20x original used `String(nextId++)`. A
+     * monotonic counter is fine for a desktop with a single user, but on a runner
+     * holding several sessions it means session A can reach session B's targets by
+     * requesting `/1`, `/2`, `/3` — and the proxy would dutifully attach B's
+     * token. 16 random bytes makes that unguessable. It costs nothing.
+     */
+    registerTarget(targetUrl: string, label?: string): string | null;
+    unregisterTarget(proxyUrl: string): void;
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    private handleRequest;
+    /**
+     * One notification per TARGET per process — keyed on the target id, not on
+     * the human-readable label.
+     *
+     * Two different servers can be registered under the same label (a tenant with
+     * two Jira instances, say). Keyed on the label, the second one's auth failure
+     * would be silently swallowed for ever because the first had already "used
+     * up" the notification. The id is unique by construction.
+     */
+    private reportTokenFailure;
+}