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

package/dist/adapters/coding-agent-adapter.d.ts

@@ -41,6 +41,10 @@ export interface McpServerConfig {
 export interface SessionConfig {
     agentId: string;
     taskId: string;
+    /** Leased turn identifier for timing logs. */
+    turnId?: string;
+    /** Best-effort structured log sink for turn phases. */
+    coldStartLog?: (line: string) => void;
     workspaceDir: string;
     /**
      * Refuse dev servers and app scaffolding in shell calls unless the turn's

package/dist/adapters/pi-adapter.js

@@ -21,6 +21,7 @@ const string_decoder_1 = require("string_decoder");
 const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const model_gateway_1 = require("./model-gateway");
+const cold_start_steps_1 = require("../runtime/cold-start-steps");
 const dev_server_guard_1 = require("../runtime/dev-server-guard");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 const RPC_TIMEOUT_MS = 15_000;
@@ -516,10 +517,20 @@ class PiAdapter {
         }
     }
     async spawnSession(config, resumeId) {
+        const steps = config.turnId
+            ? new cold_start_steps_1.ColdStartSteps(config.taskId, config.turnId, (line) => {
+                console.log(line);
+                config.coldStartLog?.(line);
+            })
+            : null;
         const executable = await this.findPiExecutable();
         const gateway = this.installPeakfloGateway();
+        const endMcpConfig = steps?.begin('mcp_config_write');
         const mcpConfigPath = this.buildMcpConfig(config);
+        endMcpConfig?.();
+        const endSkills = steps?.begin('skills_install');
         const skills = this.buildSkillFiles(config);
+        endSkills?.();
         const permissionExtension = this.installPermissionExtension();
         const args = [
             '--mode',
@@ -564,7 +575,9 @@ class PiAdapter {
         this.sessions.set(tempId, session);
         this.attachProcess(session);
         try {
+            const endPiReady = steps?.begin('pi_process_ready');
             const state = await this.command(session, { type: 'get_state' });
+            endPiReady?.();
             const realId = typeof state.data?.sessionFile === 'string'
                 ? state.data.sessionFile
                 : typeof state.data?.sessionId === 'string'
@@ -893,6 +906,11 @@ class PiAdapter {
     handleMessageUpdate(session, update) {
         if (!update)
             return;
+        if ((update.type === 'text_delta' || update.type === 'thinking_delta') &&
+            String(update.delta || '')) {
+            session.firstTokenEnd?.();
+            session.firstTokenEnd = undefined;
+        }
         const index = String(update.contentIndex ?? 0);
         const key = `${session.projectionId}:${session.turn}:${session.assistantMessageOrdinal}:${index}`;
         if (update.type === 'text_delta') {
@@ -1050,6 +1068,12 @@ class PiAdapter {
         session.lastError = null;
         session.sawAgentActivity = false;
         session.promptMayBeCommandOnly = message.trimStart().startsWith('/');
+        session.firstTokenEnd = config.turnId
+            ? new cold_start_steps_1.ColdStartSteps(config.taskId, config.turnId, (line) => {
+                console.log(line);
+                config.coldStartLog?.(line);
+            }).begin('first_model_token')
+            : undefined;
         this.sendRecord(session, {
             type: 'prompt',
             message,

package/dist/contract.d.ts

@@ -31,7 +31,7 @@
  *      needs to tell such a harness apart, which it does by refusing it
  *      rather than silently serving a value that would misbehave.
  */
-export declare const PROTOCOL_VERSION = 2;
+export declare const PROTOCOL_VERSION = 3;
 /**
  * The floor a harness must meet to be served `maxTurnDurationMs: null`.
  *
@@ -178,6 +178,8 @@ export declare const ROUTES: {
     readonly register: () => string;
     /** Bearer: runner credential. 30s period. */
     readonly heartbeat: (runnerId: string) => string;
+    /** Bearer: runner credential. Best-effort timing event; no transcript data. */
+    readonly coldStart: (runnerId: string) => string;
     /**
      * Bearer: runner credential. Bounded long-poll: 204 idle, 200 with work.
      *

package/dist/contract.js

@@ -42,7 +42,7 @@ exports.isPersistablePart = isPersistablePart;
  *      needs to tell such a harness apart, which it does by refusing it
  *      rather than silently serving a value that would misbehave.
  */
-exports.PROTOCOL_VERSION = 2;
+exports.PROTOCOL_VERSION = 3;
 /**
  * The floor a harness must meet to be served `maxTurnDurationMs: null`.
  *
@@ -215,6 +215,8 @@ exports.ROUTES = {
     register: () => '/api/runners/register',
     /** Bearer: runner credential. 30s period. */
     heartbeat: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/heartbeat`,
+    /** Bearer: runner credential. Best-effort timing event; no transcript data. */
+    coldStart: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/cold-start`,
     /**
      * Bearer: runner credential. Bounded long-poll: 204 idle, 200 with work.
      *

package/dist/control-plane.d.ts

@@ -81,6 +81,8 @@ export declare class ControlPlaneClient {
     /** Used only for a private IPC handoff to the baked sandbox supervisor. */
     getRunnerCredential(): string | null;
     getRunnerId(): string | null;
+    /** Diagnostics must never delay a turn. The caller handles any failure. */
+    reportColdStart(line: string): Promise<void>;
     /**
      * Give the lease-renewal worker the minimum information it needs.
      *
@@ -129,6 +131,7 @@ export declare class ControlPlaneClient {
      * 25s poll under a 15s timeout would abort every single call.
      */
     lease(waitSeconds?: number): Promise<LeaseResponse | null>;
+    acknowledgeLease(leaseId: string): Promise<LeaseRenewResponse>;
     renewLease(leaseId: string, status?: RunnerStatus, githubTokenExpiresAt?: string, modelTokenExpiresAt?: string): Promise<LeaseRenewResponse>;
     /** Metadata of the knowledge files the lease's turn may read. Never a URL. */
     knowledgeFiles(leaseId: string, datastoreId?: string): Promise<KnowledgeFilesResponse>;

package/dist/control-plane.js

@@ -114,6 +114,18 @@ class ControlPlaneClient {
     getRunnerId() {
         return this.runnerId;
     }
+    /** Diagnostics must never delay a turn. The caller handles any failure. */
+    async reportColdStart(line) {
+        if (!this.runnerId || !this.runnerCredential)
+            return;
+        await this.send({
+            method: 'POST',
+            path: contract_1.ROUTES.coldStart(this.runnerId),
+            token: this.runnerCredential,
+            body: JSON.parse(line),
+            timeoutMs: 2_000
+        });
+    }
     /**
      * Give the lease-renewal worker the minimum information it needs.
      *
@@ -248,6 +260,15 @@ class ControlPlaneClient {
     /* ------------------------------------------------------------------ */
     /* 4. lease renew                                                      */
     /* ------------------------------------------------------------------ */
+    async acknowledgeLease(leaseId) {
+        const runnerId = this.requireRunnerId();
+        return this.send({
+            method: 'POST',
+            path: contract_1.ROUTES.leaseRenew(runnerId, leaseId),
+            token: this.requireCredential(),
+            body: { protocolVersion: contract_1.PROTOCOL_VERSION, ackOnly: true }
+        });
+    }
     async renewLease(leaseId, status, githubTokenExpiresAt, modelTokenExpiresAt) {
         const runnerId = this.requireRunnerId();
         return this.send({

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.
  *
@@ -1031,6 +1032,7 @@ class Harness {
                 continue;
             }
             let lease = null;
+            const pollStartedAt = Date.now();
             try {
                 lease = await this.client.lease(this.leaseWaitSeconds);
             }
@@ -1050,12 +1052,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();
@@ -1306,6 +1350,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,

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

@@ -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;
     /**

package/dist/runtime/session-runner.js

@@ -31,6 +31,7 @@ const node_crypto_1 = require("node:crypto");
 const model_gateway_1 = require("../adapters/model-gateway");
 const contract_1 = require("../contract");
 const attachments_1 = require("./attachments");
+const cold_start_steps_1 = require("./cold-start-steps");
 const conversation_1 = require("./conversation");
 const knowledge_tools_1 = require("./knowledge-tools");
 const permission_mode_1 = require("./permission-mode");
@@ -438,6 +439,10 @@ class SessionRunner {
      */
     async run(lease, signal) {
         const { session } = lease;
+        const coldStart = new cold_start_steps_1.ColdStartSteps(session.sessionId, session.turnId, (line) => {
+            this.logger.log(line);
+            this.deps.coldStartLog?.(line);
+        });
         const startedAt = new Date().toISOString();
         const release = this.deps.notifier.keepAwake();
         let workspaceDir = null;
@@ -470,6 +475,18 @@ class SessionRunner {
             const refusal = modelGatewayRefusal(lease);
             if (refusal)
                 throw new Error(refusal);
+            // The catalogue is advisory. Fetch it while the independent workspace
+            // is prepared, then install it before the backend process starts.
+            const endModels = coldStart.begin('model_catalogue');
+            const gatewayModels = session.agent.model.gatewayUrl
+                ? (0, model_gateway_1.fetchGatewayModels)({
+                    baseUrl: session.agent.model.gatewayUrl,
+                    apiKey: lease.modelToken
+                }).finally(endModels)
+                : Promise.resolve([]);
+            if (!session.agent.model.gatewayUrl)
+                endModels();
+            const endWorkspace = coldStart.begin('workspace_prepare');
             try {
                 workspaceDir = await this.deps.workspace.prepare({
                     sessionId: session.sessionId,
@@ -486,6 +503,7 @@ class SessionRunner {
                     },
                     refusalReason: session.workspace.refusalReason
                 });
+                endWorkspace();
                 const repositoryNames = session.workspace.requestedRepositories ??
                     (session.workspace.repositories ?? []).map(({ fullName }) => fullName);
                 for (const fullName of repositoryNames) {
@@ -495,6 +513,7 @@ class SessionRunner {
                 }
             }
             catch (caught) {
+                endWorkspace();
                 const reason = caught instanceof Error ? caught.message : String(caught);
                 const status = session.workspace.refusalReason ? 'refused' : 'failed';
                 const names = session.workspace.requestedRepositories ??
@@ -530,7 +549,13 @@ class SessionRunner {
              */
             const hasDroppedAttachments = (session.input.droppedAttachments?.length ?? 0) > 0;
             if (workspaceDir) {
-                await this.syncSpaceFilesForTurn(session, workspaceDir);
+                const endSpaceFiles = coldStart.begin('space_files_sync');
+                try {
+                    await this.syncSpaceFilesForTurn(session, workspaceDir);
+                }
+                finally {
+                    endSpaceFiles();
+                }
             }
             if (workspaceDir && (hasLeasedAttachments || hasDroppedAttachments)) {
                 const sync = await (0, attachments_1.syncAttachmentsToWorkspace)(session.input.attachments, workspaceDir, {
@@ -585,10 +610,7 @@ class SessionRunner {
                  * stop a turn whose model is already known, so we fall back to exactly
                  * the previous behaviour.
                  */
-                const fetched = await (0, model_gateway_1.fetchGatewayModels)({
-                    baseUrl: session.agent.model.gatewayUrl,
-                    apiKey: lease.modelToken
-                });
+                const fetched = await gatewayModels;
                 const named = session.agent.model.model
                     ? [
                         {
@@ -622,7 +644,13 @@ class SessionRunner {
                 this.deps.modelGateway?.set(null);
             }
             adapter = this.deps.getAdapter(session.agent.backend);
-            await adapter.initialize();
+            const endAdapter = coldStart.begin('adapter_initialize');
+            try {
+                await adapter.initialize();
+            }
+            finally {
+                endAdapter();
+            }
             secretToken = this.setUpSecrets(session);
             /*
              * THE KNOWLEDGE TOOLS FOR THIS TURN (P9). Bound to this lease and this
@@ -638,6 +666,7 @@ class SessionRunner {
                 knowledgeUrl = await this.deps.knowledge.host.endpointFor(session.sessionId);
             }
             const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl);
+            config.coldStartLog = this.deps.coldStartLog;
             /*
              * REMEMBER THE CONVERSATION. This block is the fix for the defect that
              * made this a chat product that could not hold a conversation: the
@@ -749,7 +778,13 @@ class SessionRunner {
                 }
             }
             if (!backendSessionId) {
-                backendSessionId = await adapter.createSession(config);
+                const endBackend = coldStart.begin('backend_process_start');
+                try {
+                    backendSessionId = await adapter.createSession(config);
+                }
+                finally {
+                    endBackend();
+                }
                 this.deps.telemetry.record('provider.session.started', {
                     backend: session.agent.backend,
                     runtime: session.runtime
@@ -789,10 +824,18 @@ class SessionRunner {
                 : promptText;
             replayed = !resumed && memory.messages.length > 0;
             priorPartIdsForLog = priorPartIds;
-            await adapter.sendPrompt(backendSessionId, [{ type: 'text', text: promptWithHostNote, role: 'user' }], config);
+            const endPrompt = coldStart.begin('model_prompt_send');
+            try {
+                await adapter.sendPrompt(backendSessionId, [{ type: 'text', text: promptWithHostNote, role: 'user' }], config);
+            }
+            finally {
+                endPrompt();
+            }
             this.deps.telemetry.record('provider.turn.sent', {
                 backend: session.agent.backend
             });
+            const endFirstOutput = coldStart.begin('first_agent_output');
+            const endFirstIngest = coldStart.begin('first_transcript_ingest');
             /*
              * WIRE 3 NEEDS A WAY IN. `run` is one long await, and the user's answer
              * arrives on a control-plane command that the harness handles on a
@@ -817,7 +860,7 @@ class SessionRunner {
             resumed ? priorPartIds : new Set(), 
             // THE PROMPT THIS RUNNER JUST SENT. Drain uses it to recognise the
             // backend's own echo of it — see `drain`.
-            promptWithHostNote);
+            promptWithHostNote, () => endFirstOutput(), () => endFirstIngest());
             partsProduced = drained.parts;
             if (signal.aborted) {
                 stopReason = 'aborted';
@@ -1031,6 +1074,7 @@ class SessionRunner {
          * the drain. That has not been true since the error path was added.
          */
         await this.flush(session.sessionId, this.pending.splice(0), turn, true, modelMessages);
+        coldStart.summary();
         this.deps.telemetry.record('provider.turn.memory', {
             resumed,
             replayed,
@@ -1101,7 +1145,7 @@ class SessionRunner {
      */
     async drain(adapter, backendSessionId, config, session, signal, alreadySeenPartIds = new Set(), 
     /** The exact text `sendPrompt` was given this turn, for echo filtering. */
-    sentPromptText = null) {
+    sentPromptText = null, onFirstOutput, onFirstIngest) {
         let providerError;
         let timedOut = false;
         let idleTimedOut = false;
@@ -1110,6 +1154,7 @@ class SessionRunner {
         const seenPartIds = new Set(alreadySeenPartIds);
         const partContentLengths = new Map();
         let produced = 0;
+        let firstOutputSeen = false;
         let idleSeen = 0;
         let wake = null;
         adapter.onDataAvailable = () => {
@@ -1236,8 +1281,14 @@ class SessionRunner {
                  */
                 produced += await this.emitPendingApproval(adapter, backendSessionId, session);
                 if (freshParts.length > 0) {
+                    if (!firstOutputSeen) {
+                        firstOutputSeen = true;
+                        onFirstOutput?.();
+                    }
                     produced += this.record(session.sessionId, freshParts);
                     await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+                    if (firstOutputSeen)
+                        onFirstIngest?.();
                     // Real output resets the quiet counter. A backend is idle BETWEEN
                     // tool calls as well as at the end of a turn, so ending on the first
                     // idle would truncate almost every transcript at the first tool.
@@ -2142,6 +2193,7 @@ class SessionRunner {
             // would have made them no longer "extracted unchanged", which is worth
             // more than the tidier name.
             taskId: session.sessionId,
+            turnId: session.turnId,
             workspaceDir,
             devServerPolicy: session.agent.devServerPolicy,
             model: qualifiedModelId(session.agent.model),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.4-rc.2",
+  "version": "0.2.5-rc.1",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",