portable-agent-layer 0.80.0 → 0.81.0

package/assets/schema/pal-settings.schema.json

@@ -74,6 +74,10 @@
           "type": "boolean",
           "description": "Measure each user turn (pace, message length, skimming, corrections; never the text) into memory/signals/interaction/, and tell the agent when the session's pattern changes."
         },
+        "reactionSampling": {
+          "type": "boolean",
+          "description": "Keep a rolling local sample (about 230 messages) of user message text, its reaction label and the end of the reply it answered, in memory/state/reaction-samples.json, so the reaction rules can be audited. Stores message text; set false to keep none."
+        },
         "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
       }
     },

package/assets/templates/PAL/MEMORY_SYSTEM.md

@@ -55,7 +55,8 @@ 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, corrections) | 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) | `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>/` |
 
 ## Format conventions

package/assets/templates/pal-settings.json

@@ -27,6 +27,7 @@
     "skillMatching": true,
     "wallClock": true,
     "interactionAwareness": true,
+    "reactionSampling": true,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

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

package/src/hooks/lib/context.ts

@@ -14,6 +14,7 @@ import { loadHandoffContext } from "./handoff-context";
 import { loadOpinionContext } from "./opinions";
 import { paths, toPath } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
+import { loadReactionAuditNudge } from "./reaction-audit";
 import { loadRecentNotes } from "./relationship";
 import { loadFailurePatterns } from "./semi-static";
 import { sessionDir } from "./session-dir";
@@ -220,12 +221,14 @@ export function buildSystemReminder(
       : "";
   // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
   const algoReview = oncePerDay("algorithm-review", loadAlgorithmReviewNudge());
+  const reactionAudit = oncePerDay("reaction-audit", loadReactionAuditNudge());
   const reflectNudge = oncePerDay("reflect", loadReflectNudge());
   const analyzeNudge = oncePerDay("analyze", loadAnalyzeNudge());
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
   if (algoReview) parts.push(algoReview);
+  if (reactionAudit) parts.push(reactionAudit);
   if (reflectNudge) parts.push(reflectNudge);
   if (analyzeNudge) parts.push(analyzeNudge);
   if (selfModel) parts.push(selfModel);

package/src/hooks/lib/interaction-reaction.ts

@@ -0,0 +1,71 @@
+/**
+ * How the user's message answers the agent's previous reply, read in code.
+ * This is the outcome a reply is judged by, so precision beats recall:
+ * anything unclear is a follow-up, never a guess at approval or complaint.
+ */
+
+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;
+
+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;
+
+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());
+}
+
+export function isRepeat(text: string, previous: string | undefined): boolean {
+  if (!previous || extractKeywords(text).size < REPEAT_MIN_KEYWORDS) return false;
+  return similarity(text, previous) >= REPEAT_SIMILARITY;
+}
+
+function isApproval(text: string): boolean {
+  const trimmed = text.trim();
+  if (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;
+}
+
+/** 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;
+}
+
+export function reactionTo(text: string, context: ReplyContext): Reaction {
+  if (isCorrection(text)) return "corrected";
+  if (isRepeat(text, context.previousPrompt)) return "repeated";
+  if (isApproval(text)) return "approved";
+  if (isNewTopic(text, context)) return "new-topic";
+  return "follow-up";
+}
+
+export function replyKeywords(reply: string): string[] {
+  return [...extractKeywords(reply)];
+}

package/src/hooks/lib/interaction-samples.ts

@@ -0,0 +1,62 @@
+/**
+ * A rolling, local sample of labelled messages with the reply they answered,
+ * kept so the reaction rules can be audited against the user's real language.
+ * Follow-ups get most of the room: that is where the rules' misses land.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Reaction } from "./interaction-reaction";
+import { paths } from "./paths";
+import { isEnabled } from "./settings";
+
+export interface ReactionSample {
+  ts: string;
+  session: string;
+  reaction: Reaction;
+  text: string;
+  replyEnd: string;
+}
+
+const KEPT: Record<Reaction, number> = {
+  "follow-up": 150,
+  approved: 20,
+  corrected: 20,
+  repeated: 20,
+  "new-topic": 20,
+};
+const TEXT_MAX = 1000;
+const REPLY_END_MAX = 600;
+
+function samplesFile(): string {
+  return resolve(paths.state(), "reaction-samples.json");
+}
+
+/** @lintignore exercised directly by test/interaction-samples.test.ts */
+export function readSamples(): ReactionSample[] {
+  try {
+    return JSON.parse(readFileSync(samplesFile(), "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+/** A rare label keeps its own room, so frequent approvals never push out the corrections. */
+function newestPerReaction(samples: ReactionSample[]): ReactionSample[] {
+  const kept = (Object.keys(KEPT) as Reaction[]).flatMap((reaction) =>
+    samples.filter((s) => s.reaction === reaction).slice(-KEPT[reaction])
+  );
+  return kept.sort((a, b) => a.ts.localeCompare(b.ts));
+}
+
+/** The end of a reply is what the user's next message usually answers. */
+export function replyEnd(reply: string): string {
+  return reply.trim().slice(-REPLY_END_MAX);
+}
+
+export function keepSample(sample: ReactionSample): void {
+  if (!isEnabled("reactionSampling")) return;
+  const trimmed = { ...sample, text: sample.text.slice(0, TEXT_MAX) };
+  const samples = newestPerReaction([...readSamples(), trimmed]);
+  writeFileSync(samplesFile(), JSON.stringify(samples), "utf-8");
+}

package/src/hooks/lib/interaction.ts

@@ -14,10 +14,17 @@ import {
   moodReminder,
   readMood,
 } from "./interaction-mood";
+import {
+  isCorrection,
+  isRepeat,
+  type Reaction,
+  reactionTo,
+  replyKeywords,
+} from "./interaction-reaction";
+import { keepSample, replyEnd } from "./interaction-samples";
 import { ensureDir, paths } from "./paths";
 import { isSystemText, stripInjectedTags } from "./prompt-text";
 import { isEnabled } from "./settings";
-import { extractKeywords, similarity } from "./text-similarity";
 import { localClock } from "./wall-clock";
 
 interface ReplyShape {
@@ -35,6 +42,7 @@ export interface TurnEvent extends MoodTurn {
   hour: number;
   weekday: string;
   reply: Omit<ReplyShape, "at"> | null;
+  reaction: Reaction | null;
 }
 
 interface SessionTrack {
@@ -42,6 +50,8 @@ interface SessionTrack {
   lastPrompt?: string;
   lastPromptAt?: string;
   reply?: ReplyShape;
+  replyKeywords?: string[];
+  replyEnd?: string;
   recent: TurnEvent[];
   mood?: string;
 }
@@ -49,15 +59,10 @@ interface SessionTrack {
 const BREAK_SEC = 20 * 60;
 const SKIM_MIN_WORDS = 150;
 const SKIM_WORDS_PER_SEC = 10;
-const REPEAT_SIMILARITY = 0.6;
-const REPEAT_MIN_KEYWORDS = 5;
 const RECENT_KEPT = 12;
 const MAX_TRACKED_SESSIONS = 20;
 const BASELINE_MIN_SAMPLES = 20;
 
-const CORRECTION_RE =
-  /^(?:(?:no|nope)(?:[,.!]|$)|wrong\b|that'?s 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;
-
 function wordCount(text: string): number {
   return text.split(/\s+/).filter(Boolean).length;
 }
@@ -73,11 +78,6 @@ function replyShape(text: string, at: Date): ReplyShape {
   };
 }
 
-function isRepeat(text: string, previous: string | undefined): boolean {
-  if (!previous || extractKeywords(text).size < REPEAT_MIN_KEYWORDS) return false;
-  return similarity(text, previous) >= REPEAT_SIMILARITY;
-}
-
 /** The reply belongs to this turn only if it arrived after the previous prompt. */
 function answeredReply(track: SessionTrack): ReplyShape | null {
   const reply = track.reply;
@@ -115,8 +115,14 @@ function measureTurn(
     skimmed: isSkimmed(reply, gapSec),
     interrupted: Boolean(track.lastPromptAt) && !reply,
     repeated: isRepeat(text, track.lastPrompt),
-    corrected: CORRECTION_RE.test(text),
+    corrected: isCorrection(text),
     reply: reply ? replyFeatures(reply) : null,
+    reaction: reply
+      ? reactionTo(text, {
+          previousPrompt: track.lastPrompt,
+          replyKeywords: track.replyKeywords ?? [],
+        })
+      : null,
   };
 }
 
@@ -205,6 +211,19 @@ export function recordReply(
     ...track,
     updated: now.toISOString(),
     reply: replyShape(reply, now),
+    replyKeywords: replyKeywords(reply),
+    replyEnd: replyEnd(reply),
+  });
+}
+
+function sampleReaction(event: TurnEvent, text: string, track: SessionTrack): void {
+  if (!event.reaction) return;
+  keepSample({
+    ts: event.ts,
+    session: event.session,
+    reaction: event.reaction,
+    text,
+    replyEnd: track.replyEnd ?? "",
   });
 }
 
@@ -221,6 +240,7 @@ export function observeTurn(
   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));
   writeTrack(session, {

package/src/hooks/lib/prompt-text.ts

@@ -16,6 +16,7 @@ const SYSTEM_TEXT_PATTERNS = [
   /^This session is being continued from a previous conversation/i,
   /^Please continue the conversation/i,
   /^Note:.*was read before/i,
+  /^Another Claude session sent a message:/i,
 ];
 
 export function isSystemText(prompt: string): boolean {

package/src/hooks/lib/reaction-audit.ts

@@ -0,0 +1,115 @@
+/**
+ * Reaction-rule audit cadence and comparison. Maintainer-only: the nudge fires
+ * solely in a PAL checkout (see algorithm-review.ts), and the audit never edits
+ * the rules, it only reports where a model's reading disagrees with them.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isMaintainerEnv } from "./algorithm-review";
+import type { Reaction } from "./interaction-reaction";
+import { type ReactionSample, readSamples } from "./interaction-samples";
+import { paths } from "./paths";
+
+interface AuditMark {
+  lastAuditTs: string;
+  followUpShare: number;
+}
+
+export interface BlindSample {
+  id: string;
+  text: string;
+  replyEnd: string;
+}
+
+interface Disagreement extends BlindSample {
+  rule: Reaction;
+  model: string;
+}
+
+export interface AuditComparison {
+  compared: number;
+  agreed: number;
+  disagreements: Disagreement[];
+}
+
+const NUDGE_MIN_NEW = 40;
+const DRIFT_MIN_NEW = 20;
+const DRIFT_MIN_DELTA = 0.15;
+
+function markFile(): string {
+  return resolve(paths.state(), "reaction-audit.json");
+}
+
+function readAuditMark(): AuditMark | null {
+  try {
+    const parsed = JSON.parse(readFileSync(markFile(), "utf-8"));
+    return typeof parsed.lastAuditTs === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function followUpShare(samples: ReactionSample[]): number {
+  if (samples.length === 0) return 0;
+  return samples.filter((s) => s.reaction === "follow-up").length / samples.length;
+}
+
+export function unauditedSamples(mark = readAuditMark()): ReactionSample[] {
+  const samples = readSamples();
+  return mark ? samples.filter((s) => s.ts > mark.lastAuditTs) : samples;
+}
+
+/** The rule's label stays out, so the model's reading is a second opinion, not a review. */
+export function blindSamples(samples: ReactionSample[]): BlindSample[] {
+  return samples.map(({ ts, text, replyEnd }) => ({ id: ts, text, replyEnd }));
+}
+
+export function compareLabels(
+  samples: ReactionSample[],
+  modelLabels: Record<string, string>
+): AuditComparison {
+  const labelled = samples.filter((s) => modelLabels[s.ts]);
+  const disagreements = labelled
+    .filter((s) => modelLabels[s.ts] !== s.reaction)
+    .map((s) => ({
+      ...blindSamples([s])[0],
+      rule: s.reaction,
+      model: modelLabels[s.ts],
+    }));
+  return {
+    compared: labelled.length,
+    agreed: labelled.length - disagreements.length,
+    disagreements,
+  };
+}
+
+export function writeAuditMark(now: Date = new Date()): void {
+  const mark: AuditMark = {
+    lastAuditTs: now.toISOString(),
+    followUpShare: followUpShare(readSamples()),
+  };
+  writeFileSync(markFile(), `${JSON.stringify(mark, null, 2)}\n`);
+}
+
+function auditReason(): string | null {
+  const mark = readAuditMark();
+  const fresh = unauditedSamples(mark);
+  if (fresh.length >= NUDGE_MIN_NEW) return `${fresh.length} new labelled messages`;
+  if (!mark || fresh.length < DRIFT_MIN_NEW) return null;
+  const share = followUpShare(fresh);
+  if (Math.abs(share - mark.followUpShare) < DRIFT_MIN_DELTA) return null;
+  const pct = (n: number) => `${Math.round(n * 100)}%`;
+  return `the follow-up share moved from ${pct(mark.followUpShare)} to ${pct(share)}`;
+}
+
+/** Formatted nudge section for the session reminder, or "" when it shouldn't fire. */
+export function loadReactionAuditNudge(cwd: string = process.cwd()): string {
+  if (!isMaintainerEnv(cwd)) return "";
+  const reason = auditReason();
+  if (!reason) return "";
+  return [
+    "## Reaction Rules Audit Due",
+    `🔎 ${reason} since the last audit — run \`/reaction-audit\` to check the reaction rules against them.`,
+  ].join("\n");
+}