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

package/dist/runtime/session-runner.js

@@ -31,11 +31,14 @@ 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");
 const projection_1 = require("./projection");
 const space_files_1 = require("./space-files");
+/** A missing Pi consumption event must not hold the lease open for its full RPC timeout. */
+const FINAL_STEER_ACK_WAIT_MS = 5_000;
 /** How often the runner asks the adapter for new output when nothing pushes. */
 const POLL_INTERVAL_MS = 2_000;
 /**
@@ -381,6 +384,150 @@ class SessionRunner {
      * three are what `answerPendingApproval` needs and cannot otherwise reach.
      */
     turnContext = null;
+    pendingSteers = new Set();
+    deferredSteers = [];
+    steerDispatchChain = Promise.resolve();
+    nextSteerOrder = 0;
+    steeredPrompts = [];
+    steerEchoes = new Map();
+    steerTurnGeneration = 0;
+    steerAcknowledgementsClosed = false;
+    async waitForSteerAcknowledgements() {
+        const pending = [...this.pendingSteers];
+        if (pending.length === 0) {
+            this.steerAcknowledgementsClosed = true;
+            return;
+        }
+        let timeout;
+        try {
+            const settled = await Promise.race([
+                Promise.allSettled(pending).then(() => true),
+                new Promise((resolve) => {
+                    timeout = setTimeout(() => resolve(false), FINAL_STEER_ACK_WAIT_MS);
+                })
+            ]);
+            if (!settled) {
+                // Final ingest releases the lease and requeues every steer that has
+                // not been acknowledged. A late acknowledgement cannot claim it.
+                this.logger.warn(`[SessionRunner] steer-final-wait-timeout session=${this.turnContext?.sessionId ?? 'unknown'} pending=${pending.length}`);
+            }
+        }
+        finally {
+            this.steerAcknowledgementsClosed = true;
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    }
+    /** A command can arrive on heartbeat or renewal while run() is in drain(). */
+    steerMessage(command) {
+        const context = this.turnContext;
+        if (!context) {
+            if (this.steerAcknowledgementsClosed) {
+                this.rejectLateSteer(command);
+            }
+            else {
+                this.deferredSteers.push(command);
+            }
+            return;
+        }
+        if (context.sessionId !== command.sessionId ||
+            !context.adapter.steerUserMessage) {
+            this.rejectLateSteer(command);
+            return;
+        }
+        if (this.steerAcknowledgementsClosed) {
+            this.rejectLateSteer(command);
+            return;
+        }
+        const generation = this.steerTurnGeneration;
+        const order = this.nextSteerOrder++;
+        // Preparation (not Pi consumption) is serial. Fast sends enter Pi's queue
+        // in transcript order, so steeringMode=all can use all at one boundary.
+        const prepared = this.steerDispatchChain.then(async () => {
+            let prompt = command.input.content;
+            if (context.workspaceDir &&
+                (command.input.attachments?.length ||
+                    command.input.droppedAttachments?.length)) {
+                const sync = await (0, attachments_1.syncAttachmentsToWorkspace)(command.input.attachments, context.workspaceDir, {
+                    fetchImpl: this.deps.fetchAttachment,
+                    logger: this.logger,
+                    turnId: command.turnId
+                });
+                for (const dropped of command.input.droppedAttachments ?? []) {
+                    sync.failed.push({
+                        name: (0, attachments_1.sanitizeAttachmentName)(dropped.name),
+                        reason: dropped.reason
+                    });
+                }
+                const note = (0, attachments_1.attachmentPromptNote)(sync);
+                if (note)
+                    prompt = `${prompt}\n\n${note}`;
+            }
+            const seen = this.turnContext === context
+                ? context.adapter.steerUserMessage(context.backendSessionId, prompt, context.config)
+                : Promise.resolve(false);
+            // Pi can emit the user echo before the consumption acknowledgement
+            // returns. Filter that echo as soon as the prompt enters its queue.
+            const echoes = this.steerEchoes.get(prompt) ?? [];
+            echoes.push(command.turnId);
+            this.steerEchoes.set(prompt, echoes);
+            return { prompt, seen };
+        });
+        this.steerDispatchChain = prepared.then(() => undefined, () => undefined);
+        const task = prepared
+            .then(async ({ prompt, seen: consumed }) => {
+            const seen = await consumed;
+            if (!seen ||
+                this.steerAcknowledgementsClosed ||
+                generation !== this.steerTurnGeneration) {
+                if (!seen)
+                    this.logger.warn(`[SessionRunner] steer unconfirmed; queued for next turn (session=${command.sessionId}, turn=${command.turnId})`);
+                this.forgetSteerEcho(prompt, command.turnId);
+                // Pi rejected the steer, or its queue did not consume it. Reset the
+                // durable message now; release remains the fallback if this fails.
+                await command.acknowledge(false);
+                return;
+            }
+            // Record Pi's consumption before the network ack. If the ack hangs,
+            // final ingest must still log what Pi saw in this turn. A queued
+            // fallback can replay that text under the at-least-once crash rule.
+            this.steeredPrompts.push({ order, text: prompt });
+            await command.acknowledge(true);
+        })
+            .catch((error) => {
+            this.logger.warn(`[SessionRunner] steer failed for ${command.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        this.pendingSteers.add(task);
+        void task.finally(() => this.pendingSteers.delete(task));
+    }
+    rejectLateSteer(command) {
+        void command.acknowledge(false).catch((error) => {
+            this.logger.warn(`[SessionRunner] late steer reset failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    forgetSteerEcho(text, turnId) {
+        const echoes = this.steerEchoes.get(text);
+        if (!echoes)
+            return;
+        const index = echoes.indexOf(turnId);
+        if (index >= 0)
+            echoes.splice(index, 1);
+        if (echoes.length === 0)
+            this.steerEchoes.delete(text);
+    }
+    consumesSteerEcho(part) {
+        for (const [text, echoes] of this.steerEchoes) {
+            if (!this.isExactSteerEcho(part, text))
+                continue;
+            // Each matching user part consumes one steer, even when several steers
+            // have exactly the same text.
+            echoes.shift();
+            if (echoes.length === 0)
+                this.steerEchoes.delete(text);
+            return true;
+        }
+        return false;
+    }
     /** The approval currently shown to the user, if any. */
     openApproval = null;
     /** The transcript identity of an ordinary agent question, if one is open. */
@@ -438,6 +585,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;
@@ -464,12 +615,31 @@ class SessionRunner {
          */
         let turnContent = session.input.content;
         this.turnParts = [];
+        this.steerTurnGeneration++;
+        this.steerAcknowledgementsClosed = false;
+        this.pendingSteers.clear();
+        this.steeredPrompts = [];
+        this.steerDispatchChain = Promise.resolve();
+        this.nextSteerOrder = 0;
+        this.steerEchoes.clear();
         this.modelTokenExpiresAt = lease.modelTokenExpiresAt ?? null;
         this.modelKeyExpiryNoticeShown = false;
         try {
             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 +656,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 +666,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 +702,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 +763,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 +797,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 +819,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 +931,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 +977,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
@@ -804,8 +1000,12 @@ class SessionRunner {
                 sessionId: session.sessionId,
                 backendSessionId,
                 adapter,
-                config
+                config,
+                workspaceDir
             };
+            for (const command of this.deferredSteers.splice(0)) {
+                this.steerMessage(command);
+            }
             const drained = await this.drain(adapter, backendSessionId, config, session, signal, 
             // RESUMING REPLAYS THE WHOLE BACKEND SESSION. `pollMessages` is asked
             // for "everything not in these sets", and on a resumed session that is
@@ -817,7 +1017,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';
@@ -903,6 +1103,7 @@ class SessionRunner {
              * turn happened to reset it.
              */
             this.turnContext = null;
+            this.deferredSteers.length = 0;
             this.closeApproval(session.sessionId);
             this.deps.knowledge?.host.bindTurn(session.sessionId, null);
             this.closeQuestion(session.sessionId);
@@ -997,9 +1198,18 @@ class SessionRunner {
          * but a conversation that silently doubles in size every turn, which is the
          * kind of defect that looks fine for a week.
          */
+        // Give Pi a short time to confirm consumption. Final ingest requeues any
+        // unconfirmed steer; an absent event must not keep the lease alive.
+        await this.waitForSteerAcknowledgements();
         const spoken = (0, conversation_1.assistantTextFrom)(this.turnParts.filter((part) => !priorPartIdsForLog.has(part.partId)));
         const modelMessages = [
             { role: 'user', content: turnContent },
+            // This store keeps one assistant message per turn. Steers retain their
+            // order, but their exact interleaving with streamed assistant text is
+            // not represented in this compact replay log.
+            ...this.steeredPrompts
+                .sort((a, b) => a.order - b.order)
+                .map(({ text }) => ({ role: 'user', content: text })),
             ...(spoken ? [{ role: 'assistant', content: spoken }] : [])
         ];
         // Store locally FIRST, for the same reason parts are: the local copy is
@@ -1031,6 +1241,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,
@@ -1074,6 +1285,12 @@ class SessionRunner {
             return false;
         return sentPromptText.trim().startsWith(echoed);
     }
+    isExactSteerEcho(part, steeredPrompt) {
+        if (typeof part.role !== 'string' || part.role.toLowerCase() !== 'user')
+            return false;
+        const text = part.content ?? part.text;
+        return typeof text === 'string' && text.trim() === steeredPrompt.trim();
+    }
     /**
      * Poll the adapter until the turn goes quiet or the signal aborts.
      *
@@ -1101,7 +1318,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 +1327,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 = () => {
@@ -1224,7 +1442,11 @@ class SessionRunner {
                  * are recorded by the answer path itself, with the `answer-…` part id.
                  */
                 const freshParts = sentPromptText && sentPromptText.length > 0
-                    ? parts.filter((part) => !this.isEchoOfTurnPrompt(part, sentPromptText))
+                    ? parts.filter((part) => {
+                        if (this.isEchoOfTurnPrompt(part, sentPromptText))
+                            return false;
+                        return !this.consumesSteerEcho(part);
+                    })
                     : parts;
                 /*
                  * WIRE 2: A PENDING PERMISSION BECOMES A TRANSCRIPT PART.
@@ -1236,8 +1458,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 +2370,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/dist/types.d.ts

@@ -333,7 +333,7 @@ export interface SessionCommand {
      * 'abort' stops the turn; 'answer' resolves a pending question part;
      * 'release-workspace' removes a checkout after the session ends.
      */
-    command: 'abort' | 'answer' | 'release-workspace';
+    command: 'abort' | 'answer' | 'release-workspace' | 'steer';
     /** Set when command is 'answer' — the partId of the question being answered. */
     partId?: string;
     /** Set when command is 'answer' — the user's reply. */
@@ -350,6 +350,12 @@ export interface SessionCommand {
      * questions, and ids are none of those things.
      */
     optionId?: string;
+    /** A steer targets only this live lease. */
+    leaseId?: string;
+    /** The durable queued turn that becomes the fallback if steering fails. */
+    turnId?: string;
+    /** The message, with signed attachment URLs, from the control plane. */
+    input?: LeasedTurnInput;
     /** De-duplication key. The same commandId must be applied at most once. */
     commandId: string;
 }
@@ -788,6 +794,8 @@ export interface IngestResponse {
      * "the lease expired while it was working" bug.
      */
     leaseExpiresAt: string;
+    /** Commands collected at this model/tool boundary. Older APIs omit it. */
+    sessionCommands?: SessionCommand[];
 }
 export interface IngestRejection {
     partId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.4",
+  "version": "0.2.5-rc.2",
   "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",