portable-agent-layer 0.81.1 → 0.83.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) | `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.81.1",
+  "version": "0.83.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/builtin-tools.ts

@@ -11,6 +11,7 @@ const BUILTIN_TOOLS = {
   "algorithm-synthesize": () => import("../tools/agent/algorithm-synthesize"),
   analyze: () => import("../tools/agent/analyze"),
   "handoff-note": () => import("../tools/agent/handoff-note"),
+  interaction: () => import("../tools/agent/interaction"),
   project: () => import("../tools/agent/project"),
   "relationship-note": () => import("../tools/agent/relationship-note"),
   "relationship-reflect": () => import("../tools/agent/relationship-reflect"),

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

@@ -3,9 +3,16 @@
  * Per-session tracking lives in state and is discarded with the session.
  */
 
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve } from "node:path";
 import { currentAttribution } from "./actor";
+import { hearsPromptContext } from "./agent";
 import {
   type Baseline,
   DEFAULT_BASELINE,
@@ -42,6 +49,8 @@ export interface TurnEvent extends MoodTurn {
   weekday: string;
   reply: Omit<ReplyShape, "at"> | null;
   reaction: Reaction | null;
+  mood?: string;
+  hinted?: boolean;
 }
 
 interface SessionTrack {
@@ -146,6 +155,16 @@ function readEvents(file: string): TurnEvent[] {
     });
 }
 
+export function turnsSince(since: Date): TurnEvent[] {
+  const fromMonth = since.toISOString().slice(0, 7);
+  const sinceTs = since.toISOString();
+  return readdirSync(eventsDir())
+    .filter((f) => f.endsWith(".jsonl") && f.slice(0, 7) >= fromMonth)
+    .sort()
+    .flatMap((f) => readEvents(resolve(eventsDir(), f)))
+    .filter((e) => e.ts >= sinceTs);
+}
+
 /** The user's own normal, from this month and last, outside the session being judged. */
 function baseline(session: string, now: Date = new Date()): Baseline {
   const lastMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
@@ -231,10 +250,15 @@ export function observeTurn(
   if (!text) return null;
   const track = trackOf(session);
   const event = measureTurn(text, session, track, now, channel);
-  appendEvent(event);
-  sampleReaction(event, text, track);
   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 && hearsPromptContext(),
+  });
+  sampleReaction(event, text, track);
   writeTrack(session, {
     ...track,
     updated: now.toISOString(),
@@ -243,5 +267,5 @@ export function observeTurn(
     recent,
     mood: mood.key,
   });
-  return moodReminder(mood, track.mood ?? "");
+  return reminder;
 }

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env bun
+/**
+ * Interaction report — how the user's turns went, and whether replies changed
+ * while a measured label was in the agent's context.
+ *
+ * Usage: pal cli interaction report [--days N]
+ */
+
+import { parseArgs } from "node:util";
+import { turnsSince } from "../../hooks/lib/interaction";
+import { reportLines, summarize } from "../lib/interaction-report";
+import { scriptArgs } from "../lib/script-args";
+
+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
+  label (short, long, fast, skimming, friction) how the replies written while
+  it was active compare with the replies written while none was.
+
+  Usage: pal cli interaction report [--days N]   (default 7)
+`;
+
+const DAY_MS = 86_400_000;
+
+export function run(argv: string[] = scriptArgs()) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      days: { type: "string", default: "7" },
+    },
+  });
+  const days = Number(values.days);
+  if (values.help || positionals[0] !== "report" || !(days > 0)) {
+    console.log(HELP);
+    return;
+  }
+  const events = turnsSince(new Date(Date.now() - days * DAY_MS));
+  for (const line of reportLines(summarize(events), days)) console.log(line);
+}
+
+if (import.meta.main) run();

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

@@ -0,0 +1,144 @@
+/**
+ * What `pal cli interaction report` says: how the user's turns went, and whether
+ * the agent's replies changed while a measured label was in its context.
+ */
+
+import type { TurnEvent } from "../../hooks/lib/interaction";
+import { median } from "../../hooks/lib/interaction-mood";
+
+const LABELS = ["short", "long", "fast", "skimming", "friction"] as const;
+
+interface ReplyUnderMood {
+  labels: string[];
+  words: number;
+  approved: boolean;
+  corrected: boolean;
+}
+
+interface ReplyStats {
+  replies: number;
+  medianWords: number | null;
+  approvedShare: number;
+  correctedShare: number;
+}
+
+export interface InteractionSummary {
+  turns: number;
+  sessions: number;
+  channels: Record<string, number>;
+  reactions: Record<string, number>;
+  hints: Record<string, number>;
+  unlogged: number;
+  usual: ReplyStats;
+  byLabel: Record<string, ReplyStats>;
+}
+
+function tally(values: string[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const v of values) counts[v] = (counts[v] ?? 0) + 1;
+  return counts;
+}
+
+function share(replies: ReplyUnderMood[], test: (r: ReplyUnderMood) => boolean): number {
+  return replies.length ? replies.filter(test).length / replies.length : 0;
+}
+
+function stats(replies: ReplyUnderMood[]): ReplyStats {
+  return {
+    replies: replies.length,
+    medianWords: median(replies.map((r) => r.words)),
+    approvedShare: share(replies, (r) => r.approved),
+    correctedShare: share(replies, (r) => r.corrected),
+  };
+}
+
+/** The reply to a turn arrives with the session's next turn, written under that turn's mood. */
+function repliesUnderMood(events: TurnEvent[]): ReplyUnderMood[] {
+  const lastMood = new Map<string, string | undefined>();
+  const replies: ReplyUnderMood[] = [];
+  for (const e of events) {
+    const mood = lastMood.get(e.session);
+    if (e.reply && mood !== undefined)
+      replies.push({
+        labels: mood ? mood.split(",") : [],
+        words: e.reply.words,
+        approved: e.reaction === "approved",
+        corrected: e.reaction === "corrected" || e.reaction === "repeated",
+      });
+    lastMood.set(e.session, e.mood);
+  }
+  return replies;
+}
+
+export function summarize(events: TurnEvent[]): InteractionSummary {
+  const replies = repliesUnderMood(events);
+  const hinted = events.filter((e) => e.hinted);
+  return {
+    turns: events.length,
+    sessions: new Set(events.map((e) => e.session)).size,
+    channels: tally(events.map((e) => e.channel ?? "unknown")),
+    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,
+    usual: stats(replies.filter((r) => r.labels.length === 0)),
+    byLabel: Object.fromEntries(
+      LABELS.map((label) => [
+        label,
+        stats(replies.filter((r) => r.labels.includes(label))),
+      ])
+    ),
+  };
+}
+
+function pct(n: number): string {
+  return `${Math.round(n * 100)}%`;
+}
+
+function counts(record: Record<string, number>): string {
+  const entries = Object.entries(record).sort(([, a], [, b]) => b - a);
+  return entries.length ? entries.map(([k, n]) => `${k} ${n}`).join(" · ") : "none";
+}
+
+function shares(record: Record<string, number>): string {
+  const total = Object.values(record).reduce((a, b) => a + b, 0);
+  const entries = Object.entries(record).sort(([, a], [, b]) => b - a);
+  return total ? entries.map(([k, n]) => `${k} ${pct(n / total)}`).join(" · ") : "none";
+}
+
+function words(s: ReplyStats): string {
+  return s.medianWords === null ? "-" : `${Math.round(s.medianWords)}`;
+}
+
+function labelLine(label: string, s: ReplyStats, usual: ReplyStats): string {
+  if (s.replies === 0) return `  ${label.padEnd(9)} no replies yet`;
+  return [
+    `  ${label.padEnd(9)} ${s.replies} replies`,
+    `median ${words(s)} words (usual ${words(usual)})`,
+    `approved ${pct(s.approvedShare)} (usual ${pct(usual.approvedShare)})`,
+    `corrected ${pct(s.correctedShare)} (usual ${pct(usual.correctedShare)})`,
+  ].join(" · ");
+}
+
+function plural(n: number, noun: string): string {
+  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+
+export function reportLines(summary: InteractionSummary, days: number): string[] {
+  const period = days === 1 ? "day" : plural(days, "day");
+  if (summary.turns === 0) return [`No measured turns in the last ${period}.`];
+  const lines = [
+    `Interaction report, last ${period}`,
+    `Turns: ${summary.turns} in ${plural(summary.sessions, "session")} · ${counts(summary.channels)}`,
+    `Reactions: ${shares(summary.reactions)}`,
+    `Hints sent: ${counts(summary.hints)}`,
+    "",
+    "Replies written while a label was active, against replies while none was:",
+    ...LABELS.map((label) => labelLine(label, summary.byLabel[label], summary.usual)),
+  ];
+  if (summary.unlogged)
+    lines.push(
+      "",
+      `${summary.unlogged} older turns were logged before moods were, and are left out of the comparison.`
+    );
+  return lines;
+}