portable-agent-layer 0.84.1 → 0.84.3

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.3",
   "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),

package/src/targets/copilot/install.ts

@@ -14,10 +14,9 @@ import {
   countSkills,
   loadCopilotHooksTemplate,
   log,
-  readJson,
   vscodeSettingsFile,
-  writeJson,
 } from "../lib";
+import { enableCopilotInstructions } from "../vscode-settings";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const COPILOT_DIR = platform.copilotDir();
@@ -58,18 +57,15 @@ const manualHint =
   'Add manually: { "chat.instructionsFilesLocations": { "~/.copilot/instructions": true } }';
 if (vsSettingsPath) {
   try {
-    const settings = readJson<Record<string, unknown>>(vsSettingsPath, {});
-    const existing =
-      typeof settings["chat.instructionsFilesLocations"] === "object" &&
-      settings["chat.instructionsFilesLocations"] !== null
-        ? (settings["chat.instructionsFilesLocations"] as Record<string, unknown>)
-        : {};
-    settings["chat.instructionsFilesLocations"] = {
-      ...existing,
-      "~/.copilot/instructions": true,
-    };
-    writeJson(vsSettingsPath, settings);
-    log.success("Enabled ~/.copilot/instructions in VS Code settings");
+    const outcome = enableCopilotInstructions(vsSettingsPath);
+    if (outcome === "enabled")
+      log.success("Enabled ~/.copilot/instructions in VS Code settings");
+    if (outcome === "needs-manual-edit")
+      log.warn(
+        `VS Code settings aren't plain JSON, so PAL left them untouched — ${manualHint}`
+      );
+    if (outcome === "vscode-never-launched")
+      log.info("Skipped VS Code settings — VS Code has not been launched yet");
   } catch {
     log.warn(`Could not update VS Code settings — ${manualHint}`);
   }

package/src/targets/vscode-settings.ts

@@ -0,0 +1,56 @@
+/**
+ * VS Code's settings.json is JSONC. PAL rewrites it only when it parses as
+ * strict JSON, because a rewrite would drop the user's comments.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { writeJson } from "./lib";
+
+const LOCATIONS_KEY = "chat.instructionsFilesLocations";
+const COPILOT_INSTRUCTIONS = "~/.copilot/instructions";
+
+type Settings = Record<string, unknown>;
+
+type InstructionsOutcome =
+  | "enabled"
+  | "already-enabled"
+  | "needs-manual-edit"
+  | "vscode-never-launched";
+
+function parsed(raw: string, parse: (text: string) => unknown): Settings | null {
+  try {
+    const value = parse(raw);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? (value as Settings)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function locationsOf(settings: Settings): Settings {
+  const locations = settings[LOCATIONS_KEY];
+  return typeof locations === "object" && locations !== null
+    ? (locations as Settings)
+    : {};
+}
+
+function writeEnabled(settingsPath: string, settings: Settings): InstructionsOutcome {
+  writeJson(settingsPath, {
+    ...settings,
+    [LOCATIONS_KEY]: { ...locationsOf(settings), [COPILOT_INSTRUCTIONS]: true },
+  });
+  return "enabled";
+}
+
+export function enableCopilotInstructions(settingsPath: string): InstructionsOutcome {
+  if (!existsSync(dirname(settingsPath))) return "vscode-never-launched";
+  if (!existsSync(settingsPath)) return writeEnabled(settingsPath, {});
+  const raw = readFileSync(settingsPath, "utf-8");
+  const settings = parsed(raw, Bun.JSONC.parse);
+  if (settings && locationsOf(settings)[COPILOT_INSTRUCTIONS] === true)
+    return "already-enabled";
+  const strict = parsed(raw, JSON.parse);
+  return strict ? writeEnabled(settingsPath, strict) : "needs-manual-edit";
+}