@peakflo/agent-harness 0.2.4 → 0.2.5-rc.2

package/dist/harness.js

@@ -21,6 +21,7 @@ const sqlite_store_1 = require("./store/sqlite-store");
 const version_1 = require("./version");
 /** Backoff after a lease poll fails, so an unreachable control plane is not hammered. */
 const LEASE_ERROR_BACKOFF_MS = 5_000;
+const LEASE_MIN_EMPTY_POLL_MS = 250;
 /**
  * How often the model catalogue is re-probed once the harness is running.
  *
@@ -150,10 +151,15 @@ class Harness {
     releaseGitHubGuard = null;
     /** sessionId -> the controller that aborts its turn. */
     active = new Map();
+    activeLeaseIds = new Map();
     /** Renewal workers that must receive a credential rotation in flight. */
     activeRenewals = new Set();
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     appliedCommands = new Set();
+    /** Prune lease-bound command IDs when their session turn ends. */
+    appliedCommandsBySession = new Map();
+    /** A steer can arrive on renewal while a leased runner is still starting. */
+    deferredSteers = new Map();
     /** Session-end cleanup waits for an active turn to save its dirty work. */
     pendingWorkspaceReleases = new Set();
     /**
@@ -338,6 +344,7 @@ class Harness {
         }
         this.stopping = true;
         this.status = 'draining';
+        this.deferredSteers.clear();
         if (this.heartbeatTimer) {
             clearTimeout(this.heartbeatTimer);
             this.heartbeatTimer = null;
@@ -506,9 +513,7 @@ class Harness {
             }
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
-            for (const command of response.sessionCommands ?? []) {
-                this.applyCommand(command);
-            }
+            this.applyCommandsSafely(response.sessionCommands ?? []);
             log('Reused stored runner credential', {
                 runnerId: stored.runnerId,
                 tenantId: stored.tenantId
@@ -782,9 +787,7 @@ class Harness {
             }
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
-            for (const command of response.sessionCommands ?? []) {
-                this.applyCommand(command);
-            }
+            this.applyCommandsSafely(response.sessionCommands ?? []);
             if (response.action === 'drain') {
                 this.status = 'draining';
                 log('Control plane asked the harness to drain');
@@ -822,21 +825,85 @@ class Harness {
         }
         this.scheduleHeartbeat();
     }
+    /** A bad command must not stop the others or fail a transcript ingest. */
+    applyCommandsSafely(commands) {
+        for (const command of commands) {
+            try {
+                this.applyCommand(command);
+            }
+            catch (error) {
+                // Commands are a side channel. An application error must not reject
+                // the ingest of model output or skip the commands after this one.
+                this.forgetAppliedCommand(command);
+                log('Session command failed', {
+                    sessionId: command.sessionId,
+                    commandId: command.commandId,
+                    command: command.command,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    }
+    forgetAppliedCommand(command) {
+        this.appliedCommands.delete(command.commandId);
+        const ids = this.appliedCommandsBySession.get(command.sessionId);
+        ids?.delete(command.commandId);
+        if (ids?.size === 0)
+            this.appliedCommandsBySession.delete(command.sessionId);
+    }
+    clearAppliedCommandsForSession(sessionId) {
+        for (const id of this.appliedCommandsBySession.get(sessionId) ?? []) {
+            this.appliedCommands.delete(id);
+        }
+        this.appliedCommandsBySession.delete(sessionId);
+    }
     /**
-     * Apply a command that rode back on a heartbeat.
+     * Apply a command that rode back on a heartbeat or ingest response.
      *
-     * Idempotent by `commandId`, because the contract lets the control plane
-     * repeat a command until it observes the effect — it has no other way to
-     * know, since it cannot dial in and ask.
+     * Idempotent by `commandId`, because the control plane may repeat a command
+     * until it observes the effect; it cannot dial the harness to ask.
      */
     applyCommand(command) {
         if (this.appliedCommands.has(command.commandId)) {
             return;
         }
         this.appliedCommands.add(command.commandId);
+        const sessionCommands = this.appliedCommandsBySession.get(command.sessionId) ?? new Set();
+        sessionCommands.add(command.commandId);
+        this.appliedCommandsBySession.set(command.sessionId, sessionCommands);
+        if (command.command === 'steer') {
+            const runner = this.runners.get(command.sessionId);
+            if (!runner || !command.turnId || !command.leaseId || !command.input) {
+                if (!runner && command.turnId && command.leaseId && command.input) {
+                    this.deferredSteers.set(command.commandId, command);
+                }
+                this.forgetAppliedCommand(command);
+                // The durable turn remains queued until Pi confirms consumption.
+                return;
+            }
+            if (this.activeLeaseIds.get(command.sessionId) !== command.leaseId) {
+                this.forgetAppliedCommand(command);
+                return;
+            }
+            runner.steerMessage({
+                sessionId: command.sessionId,
+                turnId: command.turnId,
+                input: command.input,
+                acknowledge: async (consumed) => (await this.client.acknowledgeSteer(command.sessionId, command.leaseId, command.turnId, consumed)).delivery
+            });
+            return;
+        }
         if (command.command === 'abort') {
             const controller = this.active.get(command.sessionId);
-            if (controller) {
+            const activeLeaseId = this.activeLeaseIds.get(command.sessionId);
+            if (!controller || (command.optionId && !activeLeaseId)) {
+                // A command can arrive between lease claim and local runner setup.
+                // Leave its id open so the control plane's safe abort redelivery can
+                // apply it once this exact lease is active.
+                this.forgetAppliedCommand(command);
+                return;
+            }
+            if (!command.optionId || activeLeaseId === command.optionId) {
                 log('Aborting session by control-plane command', {
                     sessionId: command.sessionId
                 });
@@ -854,7 +921,7 @@ class Harness {
                 });
             }
             else {
-                void this.releaseSessionWorkspace(command.sessionId);
+                void this.releaseSessionWorkspace(command.sessionId).finally(() => this.forgetAppliedCommand(command));
             }
             return;
         }
@@ -895,7 +962,7 @@ class Harness {
                  * all that can be said here; what this buys is that a redelivery would
                  * be attempted rather than discarded as a duplicate.
                  */
-                this.appliedCommands.delete(command.commandId);
+                this.forgetAppliedCommand(command);
                 log('Answer arrived for a session this runner is no longer running', {
                     sessionId: command.sessionId,
                     commandId: command.commandId
@@ -963,6 +1030,16 @@ class Harness {
             });
         }
     }
+    /** Deliver commands received while the leased runner was still starting. */
+    flushDeferredSteers(sessionId, leaseId) {
+        for (const [commandId, command] of this.deferredSteers) {
+            if (command.sessionId !== sessionId)
+                continue;
+            this.deferredSteers.delete(commandId);
+            if (command.leaseId === leaseId)
+                this.applyCommandsSafely([command]);
+        }
+    }
     async releaseSessionWorkspace(sessionId) {
         try {
             const released = await this.workspace.release(sessionId, { force: true });
@@ -992,7 +1069,7 @@ class Harness {
      *    backend.
      */
     recoverFailedAnswer(runner, command, reason) {
-        this.appliedCommands.delete(command.commandId);
+        this.forgetAppliedCommand(command);
         void runner.reportApprovalFailure(command.sessionId, reason).catch(() => {
             // If even that cannot be delivered, the log at the call site is all
             // there is. Never let reporting a failure become a second failure.
@@ -1031,6 +1108,7 @@ class Harness {
                 continue;
             }
             let lease = null;
+            const pollStartedAt = Date.now();
             try {
                 lease = await this.client.lease(this.leaseWaitSeconds);
             }
@@ -1050,12 +1128,54 @@ class Harness {
                 continue;
             }
             if (!lease) {
-                // 204: no work. Poll again immediately — the wait already happened
-                // server-side, which is the entire point of a bounded long-poll.
+                // The server normally long-polls. A 204 returned immediately during
+                // a fence or by a faulty proxy must not make this process spin.
+                const waitLeft = LEASE_MIN_EMPTY_POLL_MS - (Date.now() - pollStartedAt);
+                if (waitLeft > 0)
+                    await sleep(waitLeft);
                 continue;
             }
+            const leaseReceived = JSON.stringify({
+                event: 'cold_start_step',
+                sessionId: lease.session.sessionId,
+                turnId: lease.session.turnId,
+                step: 'lease_poll_to_pickup',
+                startedAt: new Date(pollStartedAt).toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Date.now() - pollStartedAt
+            });
+            log(leaseReceived);
+            void this.client.reportColdStart(leaseReceived).catch(() => undefined);
             this.observeHarnessPin(lease.harnessVersion);
             this.observeSandboxToolsPin(lease.sandboxToolsVersion);
+            // Protocol 3 uses a short visibility window until the runner confirms
+            // receipt. A dropped GET response is then reclaimed within nine seconds.
+            // Do not start work unless the acknowledgement extends this lease.
+            let leaseAcknowledged = false;
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                try {
+                    const acknowledged = await this.client.acknowledgeLease(lease.leaseId);
+                    if (!acknowledged.renewed) {
+                        log('Lease acknowledgement refused', { leaseId: lease.leaseId });
+                        break;
+                    }
+                    leaseAcknowledged = true;
+                    break;
+                }
+                catch (error) {
+                    log('Lease acknowledgement failed', {
+                        leaseId: lease.leaseId,
+                        attempt: attempt + 1,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                    if (attempt < 2)
+                        await sleep(500);
+                }
+            }
+            if (!leaseAcknowledged) {
+                await sleep(LEASE_ERROR_BACKOFF_MS);
+                continue;
+            }
             void this.runLeasedTurn(lease);
         }
         await this.stop();
@@ -1186,15 +1306,14 @@ class Harness {
          */
         const renewalCallbacks = {
             leaseId: lease.leaseId,
+            // A running turn does not poll the lease endpoint. Ingest returns
+            // commands at each output boundary; a silent tool relies on heartbeat
+            // or this normal renewal interval, which can take up to a minute.
             intervalMs: this.deps.leaseRenewIntervalMs,
             // While a permission prompt is open, renew — and therefore collect
             // commands — every couple of seconds instead of every minute.
             urgentIntervalMs: this.deps.approvalRenewIntervalMs,
-            onCommands: (commands) => {
-                for (const command of commands) {
-                    this.applyCommand(command);
-                }
-            },
+            onCommands: (commands) => this.applyCommandsSafely(commands),
             githubTokenExpiresAt: lease.githubCredential?.expiresAt,
             onGithubCredential: (credential) => {
                 githubWorkspace.setCredential?.(sessionId, credential);
@@ -1306,6 +1425,9 @@ class Harness {
             secrets: this.secrets,
             events: this.events,
             telemetry: this.telemetry,
+            coldStartLog: (line) => {
+                void this.client.reportColdStart(line).catch(() => undefined);
+            },
             notifier: this.notifier,
             artifacts: this.artifacts,
             conversation: this.conversation,
@@ -1348,7 +1470,9 @@ class Harness {
                 final,
                 modelMessages
             })
-                .then(() => undefined)
+                .then((response) => {
+                this.applyCommandsSafely(response.sessionCommands ?? []);
+            })
         });
         runnerRef = runner;
         // Registered BEFORE the turn starts. A permission can be raised on the
@@ -1357,6 +1481,8 @@ class Harness {
         // running" — which is indistinguishable, in the log, from a real
         // mis-routing.
         this.runners.set(sessionId, runner);
+        this.activeLeaseIds.set(sessionId, lease.leaseId);
+        this.flushDeferredSteers(sessionId, lease.leaseId);
         try {
             const result = await runner.run(lease, controller.signal);
             log('Turn finished', {
@@ -1399,6 +1525,14 @@ class Harness {
             // that arrives during the commit must defer, never delete under Git.
             this.active.delete(sessionId);
             this.runners.delete(sessionId);
+            this.activeLeaseIds.delete(sessionId);
+            // The control plane expires lease-bound commands at turn end. Keep IDs
+            // only while their lease can redeliver them; a warm runner serves many turns.
+            this.clearAppliedCommandsForSession(sessionId);
+            for (const [commandId, command] of this.deferredSteers) {
+                if (command.sessionId === sessionId)
+                    this.deferredSteers.delete(commandId);
+            }
             // Revoke ONLY this session's tokens. A process-wide revoke here blanked
             // the credential of every concurrent turn still running.
             this.tokens.revokeTargets(mcpTargetUrls);

package/dist/runtime/cold-start-steps.d.ts

@@ -0,0 +1,11 @@
+/** Timing for one leased turn. Values in this log contain no credentials. */
+export declare class ColdStartSteps {
+    private readonly sessionId;
+    private readonly turnId;
+    private readonly log;
+    private readonly startedAt;
+    private readonly steps;
+    constructor(sessionId: string, turnId: string, log: (line: string) => void);
+    begin(step: string): () => void;
+    summary(): void;
+}

package/dist/runtime/cold-start-steps.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColdStartSteps = void 0;
+/** Timing for one leased turn. Values in this log contain no credentials. */
+class ColdStartSteps {
+    sessionId;
+    turnId;
+    log;
+    startedAt = Date.now();
+    steps = {};
+    constructor(sessionId, turnId, log) {
+        this.sessionId = sessionId;
+        this.turnId = turnId;
+        this.log = log;
+    }
+    begin(step) {
+        const startedAt = Date.now();
+        let ended = false;
+        return () => {
+            if (ended)
+                return;
+            ended = true;
+            const endedAt = Date.now();
+            const durationMs = Math.max(0, endedAt - startedAt);
+            this.steps[step] = durationMs;
+            try {
+                this.log(JSON.stringify({
+                    event: 'cold_start_step',
+                    sessionId: this.sessionId,
+                    turnId: this.turnId,
+                    step,
+                    startedAt: new Date(startedAt).toISOString(),
+                    endedAt: new Date(endedAt).toISOString(),
+                    durationMs
+                }));
+            }
+            catch {
+                // A diagnostic sink must never stop an agent turn.
+            }
+        };
+    }
+    summary() {
+        try {
+            this.log(JSON.stringify({
+                event: 'cold_start_summary',
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                durationMs: Math.max(0, Date.now() - this.startedAt),
+                steps: this.steps
+            }));
+        }
+        catch {
+            // A diagnostic sink must never stop an agent turn.
+        }
+    }
+}
+exports.ColdStartSteps = ColdStartSteps;

package/dist/runtime/session-runner.d.ts

@@ -21,7 +21,7 @@
 import type { CodingAgentAdapter } from '../adapters';
 import { SessionModelGateway } from '../adapters/model-gateway';
 import { ArtifactInspector, ConversationStore, EventSink, ModelMessageRecord, Notifier, SecretProvider, Telemetry, TranscriptStore, WorkspaceProvider } from '../ports';
-import { LeaseResponse, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
+import { LeaseResponse, LeasedTurnInput, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
 import { KnowledgeToolHost, type KnowledgeControl } from './knowledge-tools';
 import { McpAuthProxy } from './mcp-auth-proxy';
 export interface SessionRunnerDeps {
@@ -40,6 +40,8 @@ export interface SessionRunnerDeps {
     secrets: SecretProvider;
     events: EventSink;
     telemetry: Telemetry;
+    /** Send a structured timing event to the control plane without waiting. */
+    coldStartLog?: (line: string) => void;
     notifier: Notifier;
     artifacts: ArtifactInspector;
     /**
@@ -258,6 +260,25 @@ export declare class SessionRunner {
      * three are what `answerPendingApproval` needs and cannot otherwise reach.
      */
     private turnContext;
+    private readonly pendingSteers;
+    private readonly deferredSteers;
+    private steerDispatchChain;
+    private nextSteerOrder;
+    private steeredPrompts;
+    private readonly steerEchoes;
+    private steerTurnGeneration;
+    private steerAcknowledgementsClosed;
+    private waitForSteerAcknowledgements;
+    /** A command can arrive on heartbeat or renewal while run() is in drain(). */
+    steerMessage(command: {
+        sessionId: string;
+        turnId: string;
+        input: LeasedTurnInput;
+        acknowledge: (consumed: boolean) => Promise<'steered' | 'queued'>;
+    }): void;
+    private rejectLateSteer;
+    private forgetSteerEcho;
+    private consumesSteerEcho;
     /** The approval currently shown to the user, if any. */
     private openApproval;
     /** The transcript identity of an ordinary agent question, if one is open. */
@@ -323,6 +344,7 @@ export declare class SessionRunner {
      * from the echoed text must not slip past the prefix check on that alone.
      */
     private isEchoOfTurnPrompt;
+    private isExactSteerEcho;
     /**
      * Poll the adapter until the turn goes quiet or the signal aborts.
      *