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

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
@@ -182,6 +186,8 @@ export interface CodingAgentAdapter {
      * not (the caller still has the transcript note either way).
      */
     steerTurn?(sessionId: string, text: string, config: SessionConfig): Promise<boolean>;
+    /** A human message. Return true only once the live backend has accepted it. */
+    steerUserMessage?(sessionId: string, text: string, config: SessionConfig): Promise<boolean>;
     /**
      * Get current session status
      */

package/dist/adapters/pi-adapter.d.ts

@@ -89,6 +89,7 @@ export declare class PiAdapter implements CodingAgentAdapter {
     private consumeStdout;
     private handleJsonlLine;
     private rejectPending;
+    private refreshSteeringActivityAtIdle;
     private handleEvent;
     private handleExtensionUiRequest;
     private uiRequestMessage;
@@ -110,6 +111,8 @@ export declare class PiAdapter implements CodingAgentAdapter {
      * into an already-running turn must not reset them.
      */
     steerTurn(sessionId: string, text: string, _config: SessionConfig): Promise<boolean>;
+    /** Resolve only when Pi emits the queued user message into the active turn. */
+    steerUserMessage(sessionId: string, text: string, _config: SessionConfig): Promise<boolean>;
     getStatus(sessionId: string, _config: SessionConfig): Promise<SessionStatus>;
     private settlePendingTurnError;
     pollMessages(sessionId: string): Promise<MessagePart[]>;

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;
@@ -29,6 +30,9 @@ const MINIMUM_PI_VERSION = [0, 80, 5];
 const PI_PERMISSION_MODE_ENV = 'PEAKFLO_PI_PERMISSION_MODE';
 exports.PI_DEV_SERVER_POLICY_ENV = 'PF_DEV_SERVER_POLICY_FILE';
 const TERMINAL_ERROR_SETTLE_GRACE_MS = 1_000;
+// A tool may be silent for the full progress-guard window. Turn finalization
+// has its own short bound; this timer protects an active turn with no echo.
+const STEER_CONSUMPTION_TIMEOUT_MS = 20 * 60_000;
 const piInstanceIdCache = new Map();
 /**
  * Most model providers cap function/tool `name` at 64 characters. Pi forwards
@@ -227,6 +231,16 @@ function textFromContent(content) {
         .map((block) => String(block.text ?? ''))
         .join('');
 }
+function normalizeSteerText(text) {
+    return text.replace(/\r\n?/g, '\n').trim();
+}
+function safeSteeringError(error) {
+    // Pi may include the submitted prompt in an RPC error. Never log the error
+    // text here; even URL and token redaction cannot remove arbitrary user data.
+    return error instanceof Error && /timed out/i.test(error.message)
+        ? 'rpc-timeout'
+        : 'rpc-error';
+}
 function resultText(result) {
     if (!result || typeof result !== 'object')
         return '';
@@ -470,6 +484,8 @@ class PiAdapter {
             status: 'idle',
             lastError: null,
             pending: new Map(),
+            pendingSteers: [],
+            steeringSupported: true,
             parts: [],
             allMessages: [],
             stdoutBuffer: '',
@@ -501,6 +517,17 @@ class PiAdapter {
         };
     }
     async applySelection(session, config) {
+        // An older Pi can reject this RPC. Keep ordinary turns working and let the
+        // control plane queue any steer that this process cannot consume.
+        try {
+            await this.command(session, { type: 'set_steering_mode', mode: 'all' });
+        }
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Pi did not accept steering mode; this session will queue new messages: ${safeSteeringError(error)}`);
+            // We cannot prove that Pi applied the mode after a timeout. Treat both
+            // explicit rejection and transport failure as a queue fallback.
+            session.steeringSupported = false;
+        }
         if (config.model && config.model !== 'default') {
             const { provider, modelId } = this.splitModel(config.model);
             if (!provider || !modelId) {
@@ -516,10 +543,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 +601,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'
@@ -656,12 +695,41 @@ class PiAdapter {
         }
     }
     rejectPending(session, error) {
+        for (const steer of session.pendingSteers.splice(0))
+            steer.resolve(false);
         for (const request of session.pending.values()) {
             clearTimeout(request.timer);
             request.reject(error);
         }
         session.pending.clear();
     }
+    async refreshSteeringActivityAtIdle(session) {
+        const observedTurn = session.turn;
+        try {
+            const state = await this.command(session, { type: 'get_state' });
+            if (session.turn !== observedTurn ||
+                session.status === 'error' ||
+                session.closing)
+                return;
+            if (Number(state.data?.pendingMessageCount ?? 0) > 0 ||
+                state.data?.isStreaming === true) {
+                session.status = 'busy';
+            }
+            else {
+                session.status = 'idle';
+            }
+        }
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Could not inspect steering queue at idle: ${safeSteeringError(error)}`);
+            if (session.turn === observedTurn &&
+                session.status !== 'error' &&
+                !session.closing)
+                session.status = 'idle';
+        }
+        // An empty queue is not proof of non-consumption: Pi can remove a message
+        // just before emitting message_start. The turn close requeues unconfirmed
+        // messages after its bounded wait.
+    }
     handleEvent(session, event) {
         if (event.type === 'response') {
             const response = event;
@@ -715,10 +783,17 @@ class PiAdapter {
                 break;
             case 'agent_settled': {
                 this.cancelPendingUiRequests(session, 'This request is no longer active.');
-                if (session.pendingTurnError)
+                if (session.pendingTurnError) {
                     this.settlePendingTurnError(session);
-                else
-                    session.status = 'idle';
+                }
+                else {
+                    session.status = session.pendingSteers.length ? 'busy' : 'idle';
+                    // Pi can settle after a tool even with a steer still queued.
+                    // Keep the session busy until this state read completes.
+                    if (session.pendingSteers.length) {
+                        void this.refreshSteeringActivityAtIdle(session);
+                    }
+                }
                 session.promptMayBeCommandOnly = false;
                 break;
             }
@@ -726,6 +801,16 @@ class PiAdapter {
                 const message = event.message;
                 if (message?.role === 'assistant')
                     session.assistantMessageOrdinal++;
+                if (message?.role === 'user') {
+                    const text = textFromContent(message.content);
+                    // Pi gives no steer ID on this event. Match the oldest equal text.
+                    // This assumes an equal user event came from Pi's prompt queue; an
+                    // unrelated equal user event could confirm the steer early.
+                    const index = session.pendingSteers.findIndex((steer) => normalizeSteerText(steer.text) === normalizeSteerText(text));
+                    if (index >= 0) {
+                        session.pendingSteers.splice(index, 1)[0].resolve(true);
+                    }
+                }
                 break;
             }
             case 'message_update':
@@ -893,6 +978,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 +1140,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,
@@ -1083,8 +1179,45 @@ class PiAdapter {
             });
             return true;
         }
-        catch {
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Pi could not accept a steer message: ${safeSteeringError(error)}`);
+            return false;
+        }
+    }
+    /** Resolve only when Pi emits the queued user message into the active turn. */
+    async steerUserMessage(sessionId, text, _config) {
+        const session = this.sessions.get(sessionId);
+        if (!session ||
+            session.status !== 'busy' ||
+            session.steeringSupported === false ||
+            !text)
             return false;
+        let resolveSeen;
+        const seen = new Promise((resolve) => {
+            resolveSeen = resolve;
+        });
+        const waiter = { text, resolve: resolveSeen };
+        session.pendingSteers.push(waiter);
+        // A timeout can requeue text Pi already consumed if its user event was
+        // lost. Durable exact-once recovery is tracked by task_1791540809105_ual6uq3.
+        const timer = setTimeout(() => resolveSeen(false), STEER_CONSUMPTION_TIMEOUT_MS);
+        timer.unref?.();
+        try {
+            await this.command(session, {
+                type: 'steer',
+                message: text
+            });
+            return await seen;
+        }
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Pi could not accept a steer message: ${safeSteeringError(error)}`);
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+            const index = session.pendingSteers.indexOf(waiter);
+            if (index >= 0)
+                session.pendingSteers.splice(index, 1);
         }
     }
     async getStatus(sessionId, _config) {

package/dist/capabilities.d.ts

@@ -32,6 +32,8 @@ import { RunnerCapabilities } from './types';
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
  */
 export declare const HARNESS_FEATURES: readonly ["spaceFiles"];
+/** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
+export declare function supportsPiSteering(version: string | null): boolean;
 export interface ProbeResult {
     installed: boolean;
     version: string | null;

package/dist/capabilities.js

@@ -26,6 +26,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HARNESS_FEATURES = void 0;
+exports.supportsPiSteering = supportsPiSteering;
 exports.probe = probe;
 exports.probeCapabilities = probeCapabilities;
 const node_child_process_1 = require("node:child_process");
@@ -42,6 +43,25 @@ const PROBE_TIMEOUT_MS = 10_000;
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
  */
 exports.HARNESS_FEATURES = ['spaceFiles'];
+/** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
+function supportsPiSteering(version) {
+    if (!version)
+        return false;
+    // Only a stable release was verified. A prerelease or custom build can
+    // change the RPC contract even when its base version meets the minimum.
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match)
+        return false;
+    const parts = match.slice(1, 4).map(Number);
+    const minimum = [0, 84, 3];
+    for (let index = 0; index < minimum.length; index++) {
+        if (parts[index] > minimum[index])
+            return true;
+        if (parts[index] < minimum[index])
+            return false;
+    }
+    return true;
+}
 /**
  * The coding-agent backends this harness knows how to drive, and the command
  * that reports each one's version.
@@ -105,7 +125,7 @@ function probe(command, args = ['--version']) {
                 const raw = String(stdout).trim();
                 // Same expression as detect.js: pick the first version-like token, and
                 // fall back to the first line when a tool prints something exotic.
-                const match = raw.match(/(\d+\.\d+[\w.-]*)/);
+                const match = raw.match(/(\d+\.\d+[\w.+-]*)/);
                 finish({
                     installed: true,
                     version: match ? match[1] : raw.split('\n')[0] || null
@@ -165,7 +185,12 @@ async function probeCapabilities(options = {}) {
         git: git.installed,
         docker: docker.installed,
         maxConcurrentSessions: options.maxConcurrentSessions ?? 1,
-        features: [...exports.HARNESS_FEATURES],
+        features: [
+            ...exports.HARNESS_FEATURES,
+            ...(backends.some((backend) => backend.name === 'pi' && supportsPiSteering(backend.version))
+                ? ['steerMessages']
+                : [])
+        ],
         labels: options.labels
     };
 }

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.
      *
@@ -194,6 +196,7 @@ export declare const ROUTES: {
     readonly lease: (runnerId: string, waitSeconds?: number, protocolVersion?: number) => string;
     /** Bearer: runner credential. Visibility-timeout renewal. */
     readonly leaseRenew: (runnerId: string, leaseId: string) => string;
+    readonly steerAck: (runnerId: string, leaseId: string, turnId: string) => string;
     /** Bearer: runner credential. Metadata of the knowledge files this turn may read. */
     readonly knowledgeFiles: (runnerId: string, leaseId: string) => string;
     /** Bearer: runner credential. A short-lived download URL for one knowledge file. */

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.
      *
@@ -234,6 +236,7 @@ exports.ROUTES = {
     },
     /** Bearer: runner credential. Visibility-timeout renewal. */
     leaseRenew: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/renew`,
+    steerAck: (runnerId, leaseId, turnId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/steer/${encodeURIComponent(turnId)}/ack`,
     /** Bearer: runner credential. Metadata of the knowledge files this turn may read. */
     knowledgeFiles: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/knowledge/files`,
     /** Bearer: runner credential. A short-lived download URL for one knowledge file. */

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>;
@@ -147,6 +150,9 @@ export declare class ControlPlaneClient {
      * idempotent.
      */
     ingest(sessionId: string, request: Omit<IngestRequest, 'protocolVersion'>): Promise<IngestResponse>;
+    acknowledgeSteer(sessionId: string, leaseId: string, turnId: string, consumed: boolean): Promise<{
+        delivery: 'steered' | 'queued';
+    }>;
     /**
      * Read the session's model-facing conversation back from the control plane.
      *

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({
@@ -308,6 +329,14 @@ class ControlPlaneClient {
             body: { protocolVersion: contract_1.PROTOCOL_VERSION, ...request }
         }));
     }
+    async acknowledgeSteer(sessionId, leaseId, turnId, consumed) {
+        return this.withRetry('steer-ack', () => this.send({
+            method: 'POST',
+            path: contract_1.ROUTES.steerAck(this.requireRunnerId(), leaseId, turnId),
+            token: this.requireCredential(),
+            body: { protocolVersion: contract_1.PROTOCOL_VERSION, sessionId, consumed }
+        }));
+    }
     /* ------------------------------------------------------------------ */
     /* 5b. session history — the runner's READ path                        */
     /* ------------------------------------------------------------------ */

package/dist/harness.d.ts

@@ -174,10 +174,15 @@ export declare class Harness {
     private releaseGitHubGuard;
     /** sessionId -> the controller that aborts its turn. */
     private readonly active;
+    private readonly activeLeaseIds;
     /** Renewal workers that must receive a credential rotation in flight. */
     private readonly activeRenewals;
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     private readonly appliedCommands;
+    /** Prune lease-bound command IDs when their session turn ends. */
+    private readonly appliedCommandsBySession;
+    /** A steer can arrive on renewal while a leased runner is still starting. */
+    private readonly deferredSteers;
     /** Session-end cleanup waits for an active turn to save its dirty work. */
     private readonly pendingWorkspaceReleases;
     /**
@@ -283,14 +288,19 @@ export declare class Harness {
     private modelsNeedRefresh;
     private scheduleHeartbeat;
     private sendHeartbeat;
+    /** A bad command must not stop the others or fail a transcript ingest. */
+    private applyCommandsSafely;
+    private forgetAppliedCommand;
+    private clearAppliedCommandsForSession;
     /**
-     * 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.
      */
     private applyCommand;
+    /** Deliver commands received while the leased runner was still starting. */
+    private flushDeferredSteers;
     private releaseSessionWorkspace;
     /**
      * A user's answer did not reach the backend. Do the two things that keep it