portable-agent-layer 0.81.1 → 0.82.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); 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.81.1",
+  "version": "0.82.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/lib/interaction.ts

@@ -3,7 +3,13 @@
  * 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 {
@@ -42,6 +48,8 @@ export interface TurnEvent extends MoodTurn {
   weekday: string;
   reply: Omit<ReplyShape, "at"> | null;
   reaction: Reaction | null;
+  mood?: string;
+  hinted?: boolean;
 }
 
 interface SessionTrack {
@@ -146,6 +154,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 +249,11 @@ 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 });
+  sampleReaction(event, text, track);
   writeTrack(session, {
     ...track,
     updated: now.toISOString(),
@@ -243,5 +262,5 @@ export function observeTurn(
     recent,
     mood: mood.key,
   });
-  return moodReminder(mood, track.mood ?? "");
+  return reminder;
 }

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;
+}