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

package/dist/runtime/conversation.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * THE MODEL-FACING CONVERSATION — the thing that was missing.
+ *
+ * We shipped a conversation product in which the conversation never reached the
+ * model. `SessionRunner` created a backend session, sent ONLY the new user
+ * text, and destroyed the session again, every turn. The UI transcript was
+ * complete and correct the whole time, which is exactly why nobody noticed.
+ *
+ * WHY A SECOND LOG, BESIDE THE TRANSCRIPT WE ALREADY HAVE. The transcript is a
+ * UI PROJECTION. It is shaped for rendering: ephemeral step markers are
+ * dropped, tool calls are flattened into a display payload, streaming deltas
+ * overwrite each other in place, and content is truncated when it is too large
+ * to store. Every one of those is right for a screen and lossy for a prompt.
+ * Replaying a projection back at a model is guessing at what the model was
+ * told. This log records what the model was ACTUALLY given and what it
+ * ACTUALLY said, so a replay is a replay rather than a reconstruction.
+ *
+ * TWO WAYS TO REMEMBER, AND THE ORDER MATTERS.
+ *
+ *   1. RESUME THE BACKEND SESSION. When the backend still holds the session —
+ *      OpenCode does, and every adapter in this package implements
+ *      `resumeSession` — the cheapest and most faithful thing is to keep
+ *      talking to it. Nothing is reconstructed, tool results and reasoning stay
+ *      exactly as the backend recorded them, and no tokens are re-sent.
+ *
+ *   2. REPLAY THE LOG INTO A FRESH SESSION. When the backend session is gone —
+ *      a new sandbox, a redeployed runner, a crashed OpenCode — this log is the
+ *      only memory left. It is a genuine downgrade: the model sees a
+ *      transcript of the conversation rather than its own context. It is also
+ *      the difference between a user repeating themselves and a user losing
+ *      the thread entirely.
+ *
+ * `resumeFromRev` is what tells the runner which of those it is in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_REPLAY_CHARS = void 0;
+exports.trimHistory = trimHistory;
+exports.buildReplayPrompt = buildReplayPrompt;
+exports.assistantTextFrom = assistantTextFrom;
+/**
+ * How much replayed history to put in front of a prompt, in characters.
+ *
+ * A CEILING, NOT A TARGET. Without one, a long-running session eventually
+ * builds a prompt bigger than the model's context window and every turn fails
+ * — and it fails at the WORST moment, once the user has invested a long
+ * conversation in it. Trimming from the FRONT keeps the most recent exchanges,
+ * which are the ones that carry the pronouns.
+ *
+ * This is a stop-gap and is deliberately labelled as one: the right answer is
+ * summarisation at a compaction checkpoint, which is S7's work. A crude ceiling
+ * that keeps a session alive beats an elegant plan that is not written yet.
+ */
+exports.MAX_REPLAY_CHARS = 24_000;
+/**
+ * Rough allowance per message for the `Role: ` prefix and its newline.
+ *
+ * An estimate, and deliberately a slight over-estimate: the ceiling exists to
+ * keep a prompt inside a context window, and erring small costs a little
+ * history while erring large costs the turn.
+ */
+const PER_MESSAGE_OVERHEAD_CHARS = 16;
+/** Says plainly that the model is not seeing the whole message. */
+const TRUNCATION_NOTE = '[earlier part of this message omitted] ';
+/**
+ * Keep the most recent messages that fit inside the ceiling.
+ *
+ * Walks BACKWARDS from the newest, so the tail is preserved and the head is
+ * what gets dropped.
+ */
+function trimHistory(history, maxChars = exports.MAX_REPLAY_CHARS) {
+    const kept = [];
+    let used = 0;
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const message = history[i];
+        const cost = message.content.length + PER_MESSAGE_OVERHEAD_CHARS;
+        if (used + cost <= maxChars) {
+            kept.push(message);
+            used += cost;
+            continue;
+        }
+        /*
+         * THE NEWEST MESSAGE IS TRUNCATED, NOT WAVED THROUGH.
+         *
+         * This function's first version broke out of the loop on `kept.length > 0`,
+         * which reads as "always keep at least one" and behaves as "the newest
+         * message is exempt from the limit". A single very large message therefore
+         * defeated the ceiling COMPLETELY — at the one moment the ceiling exists
+         * for, since an oversized message is exactly what pushes a prompt past the
+         * context window.
+         *
+         * Truncating from the FRONT of the message keeps its ending, which is
+         * where a tool result puts its conclusion and where a long answer puts its
+         * summary. The marker is left in the text so the model is not misled into
+         * thinking it has the whole thing.
+         */
+        if (kept.length === 0) {
+            const room = maxChars - PER_MESSAGE_OVERHEAD_CHARS - TRUNCATION_NOTE.length;
+            if (room > 0) {
+                kept.push({
+                    role: message.role,
+                    content: TRUNCATION_NOTE + message.content.slice(-room)
+                });
+            }
+        }
+        break;
+    }
+    return kept.reverse();
+}
+/**
+ * Build the prompt for a fresh backend session that must be told what happened.
+ *
+ * THE MARKERS ARE LOAD-BEARING, and the reason is not cosmetic. The replayed
+ * history is presented as a QUOTED RECORD inside a single user message, not as
+ * a stack of alternating turns, because a fresh session has no message history
+ * to stack them into. Without a clear boundary the model cannot tell which part
+ * of the text is the conversation so far and which part is the question it is
+ * being asked now, and it answers the wrong one — usually by replying to the
+ * oldest message in the log.
+ *
+ * Returns the raw input unchanged when there is nothing to replay, so a first
+ * turn is byte-for-byte what it always was and cannot regress.
+ */
+function buildReplayPrompt(history, input) {
+    const trimmed = trimHistory(history);
+    if (trimmed.length === 0)
+        return input;
+    const lines = trimmed.map((message) => `${message.role === 'user' ? 'User' : 'Assistant'}: ${message.content}`);
+    return [
+        'The conversation so far, which you should treat as your own memory of it:',
+        '',
+        '<conversation>',
+        ...lines,
+        '</conversation>',
+        '',
+        'Continue that conversation. Reply only to the new message below.',
+        '',
+        input
+    ].join('\n');
+}
+/**
+ * Reduce a turn's projected parts to the assistant text the model produced.
+ *
+ * ONLY `text` PARTS, and only assistant ones. A tool call's payload is a record
+ * of what the agent DID, and replaying it as prose would tell the model it once
+ * said a blob of JSON. What belongs in a conversation log is what was said.
+ */
+function assistantTextFrom(parts) {
+    return parts
+        .filter((part) => part.role === 'assistant' &&
+        (part.partType === 'text' || part.partType === 'reasoning-text') &&
+        typeof part.content === 'string' &&
+        part.content.trim().length > 0)
+        .map((part) => part.content.trim())
+        .join('\n\n');
+}

package/dist/runtime/lease-renewal.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+import type { LeasedGitHubCredential, SessionCommand } from '../types';
+/** The default renewal cadence: half of LEASE_TTL_MS, so one lost renewal is survivable. */
+export declare const DEFAULT_RENEW_INTERVAL_MS = 60000;
+/**
+ * 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.
+ */
+export declare const APPROVAL_RENEW_INTERVAL_MS = 2000;
+export interface RenewedLease {
+    renewed: boolean;
+    reason?: string;
+    /**
+     * Commands the control plane had queued for this runner.
+     *
+     * ADDITIVE AND OPTIONAL, so protocol v1 is untouched: a control plane that
+     * does not send them yields `undefined` and the harness behaves exactly as
+     * before, collecting commands on the heartbeat alone.
+     */
+    sessionCommands?: SessionCommand[];
+    githubCredential?: LeasedGitHubCredential;
+    /**
+     * A replacement per-turn model token, present only when the request's
+     * `modelTokenExpiresAt` entered the refresh margin. See
+     * `SessionRunner.updateModelCredential` for how it reaches a running turn.
+     */
+    modelToken?: string;
+    modelTokenExpiresAt?: string;
+}
+export interface LeaseRenewer {
+    renewLease(leaseId: string, status?: undefined, githubTokenExpiresAt?: string, modelTokenExpiresAt?: string): Promise<RenewedLease>;
+}
+export interface LeaseRenewalOptions {
+    client: LeaseRenewer;
+    leaseId: string;
+    /**
+     * Fired when the lease can no longer be renewed. In the harness this is the
+     * turn's `AbortController.abort`, which stops the session runner and prevents
+     * any further ingest for a session another runner now owns.
+     */
+    onLost: (reason: string) => void;
+    intervalMs?: number;
+    /**
+     * The cadence to use while `isUrgent()` is true. Defaults to
+     * `APPROVAL_RENEW_INTERVAL_MS`.
+     */
+    urgentIntervalMs?: number;
+    /**
+     * Commands that came back on a renewal. Called for every renewal that carries
+     * any, whatever the cadence — so an ABORT also arrives sooner than the
+     * heartbeat would have delivered it, which is a free improvement to a path
+     * that used to cost up to 30 s.
+     */
+    onCommands?: (commands: SessionCommand[]) => void;
+    githubTokenExpiresAt?: string;
+    onGithubCredential?: (credential: LeasedGitHubCredential) => void;
+    /** See `RenewedLease.modelTokenExpiresAt`. */
+    modelTokenExpiresAt?: string;
+    onModelCredential?: (credential: {
+        token: string;
+        expiresAt: string;
+    }) => void;
+    /** Injected in tests so the timer does not cost real wall-clock. */
+    setIntervalImpl?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    clearIntervalImpl?: (handle: NodeJS.Timeout) => void;
+    log?: (message: string, extra?: Record<string, unknown>) => void;
+}
+/**
+ * The handle a caller keeps for the life of the turn.
+ *
+ * `setUrgent` is EVENT-DRIVEN rather than a predicate the loop polls. The loop
+ * must not hold its own copy of a state the runner owns — it would drift, and
+ * the drift is silent in the expensive direction: the harness would keep
+ * renewing every two seconds long after the approval had been answered. The
+ * runner already knows the exact instant a prompt opens and closes, so it says
+ * so, and the cadence changes immediately instead of at the next tick.
+ */
+export interface LeaseRenewalHandle {
+    /** Stop renewing. MUST be called when the turn ends. */
+    stop(): void;
+    /**
+     * Switch between the ordinary cadence and the approval cadence. Idempotent:
+     * setting the cadence already in force does not re-arm the timer, so a
+     * chatty caller cannot postpone a renewal for ever by asking for the same
+     * thing repeatedly.
+     */
+    setUrgent(urgent: boolean): void;
+    /** Replace the credential after the control plane rotates it. */
+    setCredential?(credential: string): void;
+}
+export interface IsolatedLeaseRenewalOptions extends Omit<LeaseRenewalOptions, 'client' | 'setIntervalImpl' | 'clearIntervalImpl'> {
+    url: string;
+    runnerCredential: string;
+}
+/**
+ * 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.
+ */
+export declare function startIsolatedLeaseRenewal(options: IsolatedLeaseRenewalOptions): LeaseRenewalHandle;
+/**
+ * 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.
+ */
+export declare function startLeaseRenewal(options: LeaseRenewalOptions): LeaseRenewalHandle;