portable-agent-layer 0.84.1 → 0.84.2

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -263,7 +263,7 @@ Every agent's turns are measured and its replies filed under the session id the
 | Cursor | `beforeSubmitPrompt` → `additional_context`, undocumented | `afterAgentResponse` `text` (`AgentResponse.ts`) |
 | Copilot CLI | `userPromptTransformed` → `modifiedTransformedPrompt` (`PromptTransformed.ts`) | `agentStop` transcript |
 
-The Copilot CLI drops what its `userPromptSubmitted` hook returns, so that hook only measures the turn and parks the context; `userPromptTransformed` fires next and appends it to the prompt the model receives. Cursor documents no context field on `beforeSubmitPrompt`, so PAL offers `additional_context` there but logs no interaction hint as sent until it is shown to reach the model; its documented context channel is session start. `test/agent-turns.test.ts` holds each agent to this table.
+The Copilot CLI drops what its `userPromptSubmitted` hook returns, so that hook only measures the turn and parks the context; `userPromptTransformed` fires next and appends it to the prompt the model receives. It also writes the reply to the `agentStop` transcript only after that hook returns, so a stop whose transcript still ends on the user's message hands off to a detached `StopDeferred.ts`, which waits for the reply before running the stop handlers. Cursor documents no context field on `beforeSubmitPrompt`, so PAL offers `additional_context` there but logs no interaction hint as sent until it is shown to reach the model; its documented context channel is session start. `test/agent-turns.test.ts` holds each agent to this table.
 
 ### Design Principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.84.1",
+  "version": "0.84.2",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/hooks/StopDeferred.ts

@@ -0,0 +1,11 @@
+/**
+ * Detached child of a stop hook that returned before the agent wrote its reply
+ * to the transcript. argv: the deferred payload's path.
+ */
+
+import { isPalSpawnedInference } from "./lib/spawn-guard";
+import { finishDeferredStop } from "./lib/stop";
+
+if (isPalSpawnedInference()) process.exit(0);
+
+await finishDeferredStop(process.argv[2] ?? "");

package/src/hooks/lib/stop.ts

@@ -4,7 +4,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { mkdtemp, rename, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
@@ -42,10 +42,89 @@ export interface StopTurnPayload extends HookTurnPayload {
   transcriptPath?: string | null;
 }
 
+type Transcript = ReturnType<typeof readTranscriptFile>;
+
+interface ReplyWait {
+  timeoutMs: number;
+  intervalMs: number;
+}
+
+const REPLY_WAIT: ReplyWait = { timeoutMs: 15_000, intervalMs: 200 };
+
+function transcriptOf(payload: StopTurnPayload | null): Transcript {
+  const transcriptPath = payload?.transcript_path ?? payload?.transcriptPath;
+  return transcriptPath ? readTranscriptFile(transcriptPath) : [];
+}
+
+/** The Copilot CLI writes the reply to its transcript only after agentStop returns. */
+function replyNotWrittenYet(payload: StopTurnPayload | null, messages: Transcript) {
+  return messages.at(-1)?.role === "user" && !hookFinalReply(payload);
+}
+
+async function transcriptOnceReplied(
+  payload: StopTurnPayload,
+  wait: ReplyWait
+): Promise<Transcript | null> {
+  const deadline = Date.now() + wait.timeoutMs;
+  for (;;) {
+    const messages = transcriptOf(payload);
+    if (!replyNotWrittenYet(payload, messages)) return messages;
+    if (Date.now() >= deadline) return null;
+    await Bun.sleep(wait.intervalMs);
+  }
+}
+
+function deferStopTurn(payload: StopTurnPayload): void {
+  try {
+    const deferId: string = randomUUID();
+    const payloadPath = resolve(paths.state(), `stop-deferred.${deferId}.json`);
+    writeFileSync(payloadPath, JSON.stringify(payload), "utf-8");
+    const scriptPath = resolve(assets.hooks(), "StopDeferred.ts");
+    spawnDetachedInference(scriptPath, [payloadPath], "stop-deferred");
+  } catch (err) {
+    logError("deferStopTurn", err);
+  }
+}
+
+function takeDeferredPayload(payloadPath: string): StopTurnPayload | null {
+  try {
+    return JSON.parse(readFileSync(payloadPath, "utf-8"));
+  } catch {
+    return null;
+  } finally {
+    rmSync(payloadPath, { force: true });
+  }
+}
+
+/** Runs the stop a hook deferred, once the reply it was waiting for is in the transcript. */
+export async function finishDeferredStop(
+  payloadPath: string,
+  wait: ReplyWait = REPLY_WAIT
+): Promise<void> {
+  const payload = takeDeferredPayload(payloadPath);
+  if (!payload) return;
+  const messages = await transcriptOnceReplied(payload, wait);
+  if (!messages) {
+    logDebug("finishDeferredStop", "The reply never reached the transcript");
+    return;
+  }
+  await runTurnStop(payload, messages);
+}
+
 /** Everything a stop hook does once the agent's payload is read. */
 export async function stopTurn(payload: StopTurnPayload | null): Promise<void> {
-  const transcriptPath = payload?.transcript_path ?? payload?.transcriptPath;
-  const messages = transcriptPath ? readTranscriptFile(transcriptPath) : [];
+  const messages = transcriptOf(payload);
+  if (payload && replyNotWrittenYet(payload, messages)) {
+    deferStopTurn(payload);
+    return;
+  }
+  await runTurnStop(payload, messages);
+}
+
+async function runTurnStop(
+  payload: StopTurnPayload | null,
+  messages: Transcript
+): Promise<void> {
   if (messages.length >= 2) {
     await runStopHandlers(JSON.stringify(messages), {
       lastAssistantMessage: hookFinalReply(payload),