portable-agent-layer 0.82.0 → 0.84.0

package/assets/templates/PAL/MEMORY_SYSTEM.md

@@ -55,7 +55,7 @@ Almost everything in `state/`, `signals/`, `relationship/opinions.json`, `learni
 | A reusable session insight | Session-intelligence handler (automatic) | `learning/session/YYYY-MM/*.md` |
 | A failure worth learning from | Failure-principle handler (automatic, low ratings) | `learning/failures/YYYY-MM/*.md` |
 | A rating signal | UserPromptOrchestrator rating capture | `signals/ratings.jsonl` |
-| How a user turn went (pace, length, skimming, how it received the last reply) | Prompt-time interaction measurement (automatic); read it with `pal cli interaction report` | `signals/interaction/YYYY-MM.jsonl` |
+| How a user turn went (pace, length, skimming, how it received the last reply) | Prompt-time interaction measurement (automatic, every agent; see the per-agent turn contract in SYSTEM_ARCHITECTURE.md); read it with `pal cli interaction report` | `signals/interaction/YYYY-MM.jsonl` |
 | A rolling sample of labelled messages, for auditing the reaction rules | Prompt-time interaction measurement (automatic, `reactionSampling`) | `state/reaction-samples.json` |
 | A project handoff | Project skill / detached handlers | `projects/<slug>/` |
 

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -250,6 +250,21 @@ Brief description.
 └─────────────────────┘
 ```
 
+### Per-Agent Turn Contract
+
+Every agent's turns are measured and its replies filed under the session id the agent sent. What differs is whether the prompt hook can hand context back, and where the final reply comes from.
+
+| Agent | Prompt event → context per turn | Final reply from |
+|-------|---------------------------------|------------------|
+| Claude Code | `UserPromptSubmit` → plain text | `Stop` transcript |
+| Codex | `UserPromptSubmit` → `hookSpecificOutput.additionalContext` | `Stop` `last_assistant_message` |
+| VS Code | `UserPromptSubmit` → `hookSpecificOutput.additionalContext` | `Stop` transcript |
+| opencode | `chat.message` → synthetic part | `session.idle` session messages |
+| 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.
+
 ### Design Principles
 
 - **Fail-open**: Hook errors never block the user's session

package/assets/templates/hooks.copilot.json

@@ -15,6 +15,13 @@
         "powershell": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=copilot"
       }
     ],
+    "userPromptTransformed": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/PromptTransformed.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/PromptTransformed.ts --agent=copilot"
+      }
+    ],
     "preToolUse": [
       {
         "type": "command",

package/assets/templates/hooks.cursor.json

@@ -49,6 +49,12 @@
         "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=cursor"
       }
     ],
+    "afterAgentResponse": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/AgentResponse.ts --agent=cursor"
+      }
+    ],
     "stop": [
       {
         "type": "command",

package/package.json

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

package/src/hooks/AgentResponse.ts

@@ -0,0 +1,12 @@
+/**
+ * Hook: afterAgentResponse (Cursor) — files the final reply against the turn it
+ * answered. Cursor's stop event carries no reply, this one does.
+ */
+
+import { fileFinalReply, type HookTurnPayload } from "./lib/hook-turn";
+import { isPalSpawnedInference } from "./lib/spawn-guard";
+import { readStdinJSON } from "./lib/stdin";
+
+if (isPalSpawnedInference()) process.exit(0);
+
+fileFinalReply(await readStdinJSON<HookTurnPayload>());

package/src/hooks/PromptTransformed.ts

@@ -0,0 +1,18 @@
+/**
+ * Hook: userPromptTransformed (Copilot CLI) — appends the context the prompt
+ * hook parked to the prompt the model receives.
+ */
+
+import {
+  type TransformedPromptPayload,
+  transformedPromptResponse,
+} from "./lib/parked-context";
+import { isPalSpawnedInference } from "./lib/spawn-guard";
+import { readStdinJSON } from "./lib/stdin";
+
+if (isPalSpawnedInference()) process.exit(0);
+
+const response = transformedPromptResponse(
+  await readStdinJSON<TransformedPromptPayload>()
+);
+if (response) process.stdout.write(response);

package/src/hooks/StopOrchestrator.ts

@@ -3,7 +3,6 @@
  * Fans out to independent handlers via Promise.allSettled.
  *
  * stdin: JSON object with { session_id, transcript_path, last_assistant_message, ... }
- * Transcript is read from the file at transcript_path, NOT from stdin.
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
@@ -11,22 +10,12 @@ import { blockResponse, isCodex, isCursor } from "./lib/agent";
 import { logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
-import { runStopHandlers } from "./lib/stop";
-import { readTranscriptFile } from "./lib/transcript";
+import { type StopTurnPayload, stopTurn } from "./lib/stop";
 
 // Recursion guard — spawned inference subprocesses must not record session
 // learning, ratings, or handoffs from their throwaway transcript.
 if (isPalSpawnedInference()) process.exit(0);
 
-interface StopHookInput {
-  session_id?: string;
-  sessionId?: string; // Copilot uses camelCase
-  transcript_path?: string;
-  transcriptPath?: string; // Copilot uses camelCase
-  last_assistant_message?: string;
-  lastAssistantMessage?: string; // Copilot uses camelCase
-}
-
 // Check README sync before anything else — may block the session
 try {
   // A block carrying no reason stops the turn without telling the model why, so it
@@ -50,23 +39,4 @@ try {
   logError("StopOrchestrator:readme-sync", err);
 }
 
-const input = await readStdinJSON<StopHookInput>();
-const transcriptPath = input?.transcript_path ?? input?.transcriptPath;
-const sessionId = input?.session_id ?? input?.sessionId;
-const lastAssistant = input?.last_assistant_message ?? input?.lastAssistantMessage;
-
-if (!transcriptPath) {
-  logError("StopOrchestrator", "No transcript_path in hook input");
-  process.exit(0);
-}
-
-// Read the actual transcript from the file on disk
-const messages = readTranscriptFile(transcriptPath);
-if (messages.length < 2) process.exit(0);
-
-// Serialize and run handlers
-const transcript = JSON.stringify(messages);
-await runStopHandlers(transcript, {
-  lastAssistantMessage: lastAssistant,
-  sessionId,
-});
+await stopTurn(await readStdinJSON<StopTurnPayload>());

package/src/hooks/UserPromptOrchestrator.ts

@@ -10,6 +10,7 @@
 import { injectPromptContext } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
+import { type HookTurnPayload, hookSessionId } from "./lib/hook-turn";
 import { logDebug, logError, logPromptSnapshot } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
@@ -18,18 +19,15 @@ import { readStdinJSON } from "./lib/stdin";
 // payload, not a real user message. Skip rating capture, session naming, etc.
 if (isPalSpawnedInference()) process.exit(0);
 
-interface PromptSubmitInput {
+interface PromptSubmitInput extends HookTurnPayload {
   prompt: string;
-  session_id?: string;
-  sessionId?: string; // Copilot sends this (camelCase) instead of session_id
-  conversation_id?: string; // Cursor sends this instead of session_id
 }
 
 const input = await readStdinJSON<PromptSubmitInput>();
 logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)}`);
 if (!input?.prompt) process.exit(0);
 
-const sessionId = input.session_id ?? input.sessionId ?? input.conversation_id;
+const sessionId = hookSessionId(input);
 const injected = await injectPromptContext(input.prompt, sessionId);
 logPromptSnapshot(input.prompt, injected);
 

package/src/hooks/handlers/inject-retrieval.ts

@@ -7,9 +7,10 @@
  * produces empty output, never blocks the prompt.
  */
 
-import { isCodex, isCursor } from "../lib/agent";
+import { promptContextResponse } from "../lib/agent";
 import { observeTurn } from "../lib/interaction";
 import { logDebug, logError } from "../lib/log";
+import { parkPromptContext } from "../lib/parked-context";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
@@ -60,25 +61,12 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
   return result.reminder;
 }
 
-/** Write a reminder to stdout in the correct format for the current agent.
- *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON.
- *  MUST be called at most once per hook run — Cursor/Codex expect a single JSON
- *  object on stdout, so all prompt-time context is merged before this call. */
-function writeForAgent(reminder: string): void {
-  if (isCursor()) {
-    process.stdout.write(JSON.stringify({ additional_context: reminder }));
-  } else if (isCodex()) {
-    process.stdout.write(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "UserPromptSubmit",
-          additionalContext: reminder,
-        },
-      })
-    );
-  } else {
-    process.stdout.write(`${reminder}\n`);
-  }
+/** MUST be called at most once per hook run — the JSON shapes are a single object
+ *  on stdout, so all prompt-time context is merged before this call. */
+function writeForAgent(reminder: string, sessionId?: string): void {
+  const response = promptContextResponse(reminder);
+  if (response) process.stdout.write(response);
+  else if (sessionId) parkPromptContext(sessionId, reminder);
 }
 
 /** Merge every prompt-time source — the wall clock, contextual steering, skill
@@ -108,6 +96,6 @@ export async function injectPromptContext(
   sessionId?: string
 ): Promise<string | null> {
   const combined = await getPromptContext(prompt, sessionId);
-  if (combined) writeForAgent(combined);
+  if (combined) writeForAgent(combined, sessionId);
   return combined;
 }

package/src/hooks/lib/agent.ts

@@ -245,6 +245,28 @@ function claudeBlock(reason: string, hookEventName?: string): string {
   });
 }
 
+/** Cursor's beforeSubmitPrompt documents no context field. */
+export const hearsPromptContext = () => !isCursor();
+
+/**
+ * How a prompt hook hands context to the model, in the shape this agent reads.
+ * Null for the Copilot CLI, which drops a userPromptSubmitted hook's output and
+ * takes the context on userPromptTransformed instead.
+ */
+export function promptContextResponse(context: string): string | null {
+  if (isCopilot()) return null;
+  if (isCursor()) return JSON.stringify({ additional_context: context });
+  if (isCodex() || isVscode()) {
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: context,
+      },
+    });
+  }
+  return `${context}\n`;
+}
+
 export function blockResponse(reason: string, hookEventName?: string): string {
   if (isCursor()) {
     return JSON.stringify({ permission: "deny", user_message: reason });

package/src/hooks/lib/hook-turn.ts

@@ -0,0 +1,36 @@
+/**
+ * The fields each agent's prompt and stop hooks use for the same things.
+ * Claude Code, Codex and VS Code send snake_case, the Copilot CLI camelCase, and
+ * Cursor names the session `conversation_id` and hands its final reply to
+ * `afterAgentResponse` as `text`.
+ */
+
+import { recordReply } from "./interaction";
+
+export interface HookTurnPayload {
+  session_id?: string;
+  sessionId?: string;
+  conversation_id?: string;
+  last_assistant_message?: string | null;
+  lastAssistantMessage?: string | null;
+  text?: string;
+}
+
+export function hookSessionId(payload: HookTurnPayload | null | undefined) {
+  return payload?.session_id ?? payload?.sessionId ?? payload?.conversation_id;
+}
+
+export function hookFinalReply(payload: HookTurnPayload | null | undefined) {
+  return (
+    payload?.last_assistant_message ??
+    payload?.lastAssistantMessage ??
+    payload?.text ??
+    undefined
+  );
+}
+
+export function fileFinalReply(payload: HookTurnPayload | null | undefined): void {
+  const sessionId = hookSessionId(payload);
+  const reply = hookFinalReply(payload);
+  if (sessionId && reply) recordReply(sessionId, reply);
+}

package/src/hooks/lib/interaction.ts

@@ -12,6 +12,7 @@ import {
 } from "node:fs";
 import { resolve } from "node:path";
 import { currentAttribution } from "./actor";
+import { hearsPromptContext } from "./agent";
 import {
   type Baseline,
   DEFAULT_BASELINE,
@@ -50,6 +51,7 @@ export interface TurnEvent extends MoodTurn {
   reaction: Reaction | null;
   mood?: string;
   hinted?: boolean;
+  runtime?: string;
 }
 
 interface SessionTrack {
@@ -252,7 +254,11 @@ export function observeTurn(
   const recent = [...track.recent, event].slice(-RECENT_KEPT);
   const mood = readMood(recent, baseline(session, now));
   const reminder = moodReminder(mood, track.mood ?? "");
-  appendEvent({ ...event, mood: mood.key, hinted: reminder !== null });
+  appendEvent({
+    ...event,
+    mood: mood.key,
+    hinted: reminder !== null && hearsPromptContext(),
+  });
   sampleReaction(event, text, track);
   writeTrack(session, {
     ...track,

package/src/hooks/lib/parked-context.ts

@@ -0,0 +1,75 @@
+/**
+ * The Copilot CLI drops what its userPromptSubmitted hook returns, but lets the
+ * userPromptTransformed hook that follows rewrite the prompt the model receives.
+ * The prompt hook parks its context here; the transform hook appends it.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { type HookTurnPayload, hookSessionId } from "./hook-turn";
+import { logError } from "./log";
+import { ensureDir, paths } from "./paths";
+
+const MAX_AGE_MS = 2 * 60_000;
+
+interface Parked {
+  context: string;
+  at: string;
+}
+
+export interface TransformedPromptPayload extends HookTurnPayload {
+  transformedPrompt?: string;
+}
+
+function parkedPath(): string {
+  return resolve(ensureDir(paths.state()), "parked-prompt-context.json");
+}
+
+function readParked(): Record<string, Parked> {
+  const path = parkedPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function isFresh(parked: Parked, now: Date): boolean {
+  return now.getTime() - new Date(parked.at).getTime() <= MAX_AGE_MS;
+}
+
+function writeFresh(parked: Record<string, Parked>, now: Date): void {
+  const fresh = Object.entries(parked).filter(([, p]) => isFresh(p, now));
+  writeFileSync(parkedPath(), JSON.stringify(Object.fromEntries(fresh)), "utf-8");
+}
+
+export function parkPromptContext(session: string, context: string, now = new Date()) {
+  try {
+    writeFresh({ ...readParked(), [session]: { context, at: now.toISOString() } }, now);
+  } catch (err) {
+    logError("parkPromptContext", err);
+  }
+}
+
+function takePromptContext(session: string, now: Date): string | null {
+  const parked = readParked();
+  const entry = parked[session];
+  if (!entry) return null;
+  delete parked[session];
+  writeFresh(parked, now);
+  return isFresh(entry, now) ? entry.context : null;
+}
+
+/** The userPromptTransformed reply that appends the parked context, or null to leave the prompt alone. */
+export function transformedPromptResponse(
+  payload: TransformedPromptPayload | null,
+  now = new Date()
+): string | null {
+  const session = hookSessionId(payload);
+  const facing = payload?.transformedPrompt;
+  if (!session || !facing) return null;
+  const context = takePromptContext(session, now);
+  if (!context) return null;
+  return JSON.stringify({ modifiedTransformedPrompt: `${facing}\n\n${context}` });
+}

package/src/hooks/lib/stop.ts

@@ -20,6 +20,12 @@ import { resetTab } from "../handlers/tab";
 import { updateCounts } from "../handlers/update-counts";
 import { captureWorkSession } from "../handlers/work-session";
 import { spawnDetachedInference } from "./detached-inference";
+import {
+  fileFinalReply,
+  type HookTurnPayload,
+  hookFinalReply,
+  hookSessionId,
+} from "./hook-turn";
 import { recordReply } from "./interaction";
 import { logDebug, logError } from "./log";
 import { assets, ensureDir, paths } from "./paths";
@@ -27,9 +33,30 @@ import {
   extractContent,
   extractLastAssistant,
   parseMessages,
+  readTranscriptFile,
   withFinalReply,
 } from "./transcript";
 
+export interface StopTurnPayload extends HookTurnPayload {
+  transcript_path?: string | null;
+  transcriptPath?: string | null;
+}
+
+/** 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) : [];
+  if (messages.length >= 2) {
+    await runStopHandlers(JSON.stringify(messages), {
+      lastAssistantMessage: hookFinalReply(payload),
+      sessionId: hookSessionId(payload),
+    });
+    return;
+  }
+  logDebug("stopTurn", "No readable transcript; filing only the final reply");
+  fileFinalReply(payload);
+}
+
 interface RunStopHandlersOptions {
   lastAssistantMessage?: string;
   sessionId?: string;

package/src/tools/agent/interaction.ts

@@ -15,7 +15,8 @@ const HELP = `
   PAL Interaction report
 
   Reads the measured turns in memory/signals/interaction/ (features only, no
-  text) and prints turns, channels, reactions, the hints sent, and for each
+  text) and prints turns, channels, reactions, the hints sent, per agent the
+  turns, replies filed and hints sent, and for each
   label (short, long, fast, skimming, friction) how the replies written while
   it was active compare with the replies written while none was.
 

package/src/tools/lib/interaction-report.ts

@@ -22,10 +22,17 @@ interface ReplyStats {
   correctedShare: number;
 }
 
+interface AgentCounts {
+  turns: number;
+  replies: number;
+  hints: number;
+}
+
 export interface InteractionSummary {
   turns: number;
   sessions: number;
   channels: Record<string, number>;
+  agents: Record<string, AgentCounts>;
   reactions: Record<string, number>;
   hints: Record<string, number>;
   unlogged: number;
@@ -70,6 +77,20 @@ function repliesUnderMood(events: TurnEvent[]): ReplyUnderMood[] {
   return replies;
 }
 
+/** A turn carries the reply that answered the turn before it, so a filed reply shows up there. */
+function byAgent(events: TurnEvent[]): Record<string, AgentCounts> {
+  const agents: Record<string, AgentCounts> = {};
+  for (const e of events) {
+    const agent = e.runtime ?? "unknown";
+    const counts = agents[agent] ?? { turns: 0, replies: 0, hints: 0 };
+    agents[agent] = counts;
+    counts.turns++;
+    if (e.reply) counts.replies++;
+    if (e.hinted) counts.hints++;
+  }
+  return agents;
+}
+
 export function summarize(events: TurnEvent[]): InteractionSummary {
   const replies = repliesUnderMood(events);
   const hinted = events.filter((e) => e.hinted);
@@ -77,6 +98,7 @@ export function summarize(events: TurnEvent[]): InteractionSummary {
     turns: events.length,
     sessions: new Set(events.map((e) => e.session)).size,
     channels: tally(events.map((e) => e.channel ?? "unknown")),
+    agents: byAgent(events),
     reactions: tally(events.flatMap((e) => (e.reaction ? [e.reaction] : []))),
     hints: tally(hinted.map((e) => e.mood || "back to usual")),
     unlogged: events.filter((e) => e.mood === undefined).length,
@@ -119,8 +141,20 @@ function labelLine(label: string, s: ReplyStats, usual: ReplyStats): string {
   ].join(" · ");
 }
 
-function plural(n: number, noun: string): string {
-  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+function plural(n: number, noun: string, nouns = `${noun}s`): string {
+  return `${n} ${n === 1 ? noun : nouns}`;
+}
+
+function agentLines(agents: Record<string, AgentCounts>): string[] {
+  return Object.entries(agents)
+    .sort(([, a], [, b]) => b.turns - a.turns)
+    .map(([agent, c]) =>
+      [
+        `  ${agent.padEnd(9)} ${plural(c.turns, "turn")}`,
+        `${plural(c.replies, "reply", "replies")} filed`,
+        `${plural(c.hints, "hint")} sent`,
+      ].join(" · ")
+    );
 }
 
 export function reportLines(summary: InteractionSummary, days: number): string[] {
@@ -132,6 +166,9 @@ export function reportLines(summary: InteractionSummary, days: number): string[]
     `Reactions: ${shares(summary.reactions)}`,
     `Hints sent: ${counts(summary.hints)}`,
     "",
+    "By agent:",
+    ...agentLines(summary.agents),
+    "",
     "Replies written while a label was active, against replies while none was:",
     ...LABELS.map((label) => labelLine(label, summary.byLabel[label], summary.usual)),
   ];