portable-agent-layer 0.81.0 → 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.0",
+  "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-reaction.ts

@@ -8,11 +8,6 @@ import { extractKeywords, similarity } from "./text-similarity";
 
 export type Reaction = "corrected" | "repeated" | "approved" | "new-topic" | "follow-up";
 
-export interface ReplyContext {
-  previousPrompt?: string;
-  replyKeywords: string[];
-}
-
 const CORRECTION_RE =
   /^(?:(?:no|nope|wrong)(?:[,.!]|$)|(?:that'?s|this is|it'?s) (?:wrong|not)\b|not what i\b|i said\b|i told you\b|you forgot\b|you missed\b|still (?:broken|failing|wrong)\b)/i;
 
@@ -20,15 +15,16 @@ const APPROVAL_RE =
   /^(?:good|great|nice|perfect|cool|amazing|awesome|excellent|brilliant|works|it works|thanks|thank you|thx|y+e+s+|yep|yeah|yup|sure|exactly|correct|agreed|lgtm|well done|love it|sounds good|looks good|that'?s it|(?:it|this|that) (?:is|'s) (?:fine|good|great|right))\b/i;
 
 const GO_AHEAD_RE =
-  /^(?:go ahead|go|do it|proceed|continue|merge|push|ship|commit|build|approved|let'?s (?:see|do|go))\b/i;
+  /^(?:go ahead|go|do it|proceed|continue|merge|push|ship|commit|build|start|fix (?:all|them|both)|approved|let'?s (?:see|do|go))\b/i;
+
+const NEW_TOPIC_RE =
+  /^(?:(?:ok(?:ay)?|btw|also),?\s+)?(?:new (?:\w+ ){0,2}(?:task|topic|question|thing)|(?:different|unrelated|separate|another) (?:task|topic|question|thing)|unrelated\b|switching (?:gears|topics?)|change of (?:topic|subject))/i;
 
 const GO_AHEAD_MAX_WORDS = 6;
 const BARE_OK_RE = /^(?:ok(?:ay)?|k)[,.!]?(?:\s+\S+){0,2}$/i;
 const HEDGE_RE = /\b(?:but|however|though|except|instead)\b/i;
 const REPEAT_SIMILARITY = 0.6;
 const REPEAT_MIN_KEYWORDS = 5;
-const NEW_TOPIC_MIN_KEYWORDS = 4;
-const NEW_TOPIC_MAX_OVERLAP = 0.15;
 
 export function isCorrection(text: string): boolean {
   return CORRECTION_RE.test(text.trim());
@@ -39,33 +35,36 @@ export function isRepeat(text: string, previous: string | undefined): boolean {
   return similarity(text, previous) >= REPEAT_SIMILARITY;
 }
 
+function isShortGoAhead(sentence: string): boolean {
+  return GO_AHEAD_RE.test(sentence) && sentence.split(/\s+/).length <= GO_AHEAD_MAX_WORDS;
+}
+
+function lastSentence(text: string): string {
+  return (
+    text
+      .split(/[.!\n]\s*/)
+      .filter(Boolean)
+      .at(-1)
+      ?.trim() ?? ""
+  );
+}
+
 function isApproval(text: string): boolean {
   const trimmed = text.trim();
-  if (HEDGE_RE.test(trimmed.split(/[.!?\n]/)[0])) return false;
+  if (trimmed.includes("?") || HEDGE_RE.test(trimmed.split(/[.!?\n]/)[0])) return false;
   if (APPROVAL_RE.test(trimmed) || BARE_OK_RE.test(trimmed)) return true;
-  return GO_AHEAD_RE.test(trimmed) && trimmed.split(/\s+/).length <= GO_AHEAD_MAX_WORDS;
+  return isShortGoAhead(trimmed) || isShortGoAhead(lastSentence(trimmed));
 }
 
-/** Few of the message's words appear in the exchange it follows. */
-function isNewTopic(text: string, context: ReplyContext): boolean {
-  const words = extractKeywords(text);
-  if (words.size < NEW_TOPIC_MIN_KEYWORDS) return false;
-  const exchange = new Set([
-    ...context.replyKeywords,
-    ...extractKeywords(context.previousPrompt ?? ""),
-  ]);
-  const shared = [...words].filter((w) => exchange.has(w)).length;
-  return shared / words.size <= NEW_TOPIC_MAX_OVERLAP;
+/** Word overlap was measured against real messages and does not separate topics; only saying so does. */
+function isNewTopic(text: string): boolean {
+  return NEW_TOPIC_RE.test(text.trim());
 }
 
-export function reactionTo(text: string, context: ReplyContext): Reaction {
+export function reactionTo(text: string, previousPrompt: string | undefined): Reaction {
   if (isCorrection(text)) return "corrected";
-  if (isRepeat(text, context.previousPrompt)) return "repeated";
+  if (isRepeat(text, previousPrompt)) return "repeated";
   if (isApproval(text)) return "approved";
-  if (isNewTopic(text, context)) return "new-topic";
+  if (isNewTopic(text)) return "new-topic";
   return "follow-up";
 }
-
-export function replyKeywords(reply: string): string[] {
-  return [...extractKeywords(reply)];
-}

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 {
@@ -19,7 +25,6 @@ import {
   isRepeat,
   type Reaction,
   reactionTo,
-  replyKeywords,
 } from "./interaction-reaction";
 import { keepSample, replyEnd } from "./interaction-samples";
 import { ensureDir, paths } from "./paths";
@@ -43,6 +48,8 @@ export interface TurnEvent extends MoodTurn {
   weekday: string;
   reply: Omit<ReplyShape, "at"> | null;
   reaction: Reaction | null;
+  mood?: string;
+  hinted?: boolean;
 }
 
 interface SessionTrack {
@@ -50,7 +57,6 @@ interface SessionTrack {
   lastPrompt?: string;
   lastPromptAt?: string;
   reply?: ReplyShape;
-  replyKeywords?: string[];
   replyEnd?: string;
   recent: TurnEvent[];
   mood?: string;
@@ -117,12 +123,7 @@ function measureTurn(
     repeated: isRepeat(text, track.lastPrompt),
     corrected: isCorrection(text),
     reply: reply ? replyFeatures(reply) : null,
-    reaction: reply
-      ? reactionTo(text, {
-          previousPrompt: track.lastPrompt,
-          replyKeywords: track.replyKeywords ?? [],
-        })
-      : null,
+    reaction: reply ? reactionTo(text, track.lastPrompt) : null,
   };
 }
 
@@ -153,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));
@@ -211,7 +222,6 @@ export function recordReply(
     ...track,
     updated: now.toISOString(),
     reply: replyShape(reply, now),
-    replyKeywords: replyKeywords(reply),
     replyEnd: replyEnd(reply),
   });
 }
@@ -239,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(),
@@ -251,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;
+}