portable-agent-layer 0.85.3 → 0.85.5

package/package.json

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

package/src/hooks/lib/interaction-hint-check.ts

@@ -0,0 +1,46 @@
+/**
+ * Whether a reply followed the hint it was written under. A label saying the user
+ * wants less asks for a reply at most half the user's usual one, the same factor
+ * of two the mood rules use to call a message short.
+ */
+
+import { approvedShare, type Side, type Split } from "./interaction-preferences";
+
+const ASKS_FOR_LESS = ["short", "fast", "skimming"];
+
+function lengthTarget(usualReplyWords: number): number {
+  return Math.round(usualReplyWords / 2);
+}
+
+export function asksForLess(moodKey: string | undefined): boolean {
+  return (moodKey ?? "").split(",").some((label) => ASKS_FOR_LESS.includes(label));
+}
+
+/** Null when the reply was not written under a hint for less, or nothing says what usual is. */
+export function followedHint(
+  moodKey: string | undefined,
+  replyWords: number | undefined,
+  usualReplyWords: number | null
+): boolean | null {
+  if (replyWords === undefined || usualReplyWords === null) return null;
+  if (!asksForLess(moodKey)) return null;
+  return replyWords <= lengthTarget(usualReplyWords);
+}
+
+function pct(s: Side): string {
+  return `${Math.round(approvedShare(s) * 100)}%`;
+}
+
+function citedApprovals(evidence: Split | null): string {
+  if (!evidence) return "";
+  return ` Replies ${evidence.shape} were approved ${pct(evidence.has)} of the time, longer ones ${pct(evidence.lacks)}.`;
+}
+
+export function ignoredHintReminder(
+  replyWords: number,
+  usualReplyWords: number,
+  evidence: Split | null
+): string {
+  const target = lengthTarget(usualReplyWords);
+  return `<system-reminder>Interaction: the user still wants less. Your last reply was ${replyWords} words (usually ${usualReplyWords}); keep this one under ${target} words.${citedApprovals(evidence)}</system-reminder>`;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * What the user's reactions say about the replies they get: for each shape a reply
+ * can take, how often replies with it were approved against replies without it.
+ * A split counts as evidence only with enough replies on both sides and a gap wider
+ * than noise; the data is thin, so most splits are expected to say not yet.
+ */
+
+import { median } from "./interaction-mood";
+
+const MIN_REPLIES_PER_SIDE = 20;
+const MIN_GAP = 0.1;
+
+interface ReplyFeatures {
+  words: number;
+  listItems: number;
+  headings: number;
+  asked: boolean;
+}
+
+interface ReactedTurn {
+  reply: ReplyFeatures | null;
+  reaction: string | null;
+}
+
+interface Outcome {
+  reply: ReplyFeatures;
+  approved: boolean;
+}
+
+export interface Side {
+  replies: number;
+  approved: number;
+}
+
+export interface Split {
+  shape: string;
+  opposite: string;
+  has: Side;
+  lacks: Side;
+}
+
+function outcomes(events: ReactedTurn[]): Outcome[] {
+  return events.flatMap((e) =>
+    e.reply && e.reaction ? [{ reply: e.reply, approved: e.reaction === "approved" }] : []
+  );
+}
+
+function side(outcomes: Outcome[]): Side {
+  return {
+    replies: outcomes.length,
+    approved: outcomes.filter((o) => o.approved).length,
+  };
+}
+
+function splitBy(
+  outcomes: Outcome[],
+  shape: string,
+  opposite: string,
+  test: (reply: ReplyFeatures) => boolean
+): Split {
+  return {
+    shape,
+    opposite,
+    has: side(outcomes.filter((o) => test(o.reply))),
+    lacks: side(outcomes.filter((o) => !test(o.reply))),
+  };
+}
+
+function lengthSplit(outcomes: Outcome[]): Split {
+  const cut = Math.round(median(outcomes.map((o) => o.reply.words)) ?? 0);
+  return splitBy(
+    outcomes,
+    `under ${cut} words`,
+    `${cut} words or more`,
+    (r) => r.words < cut
+  );
+}
+
+export function splits(events: ReactedTurn[]): Split[] {
+  const reacted = outcomes(events);
+  return [
+    lengthSplit(reacted),
+    splitBy(reacted, "with a list", "without a list", (r) => r.listItems > 0),
+    splitBy(reacted, "with headings", "without headings", (r) => r.headings > 0),
+    splitBy(reacted, "ending with a question", "not ending with one", (r) => r.asked),
+  ];
+}
+
+export function approvedShare(s: Side): number {
+  return s.replies ? s.approved / s.replies : 0;
+}
+
+export function hasEnoughReplies(split: Split): boolean {
+  return Math.min(split.has.replies, split.lacks.replies) >= MIN_REPLIES_PER_SIDE;
+}
+
+export function isEvidence(split: Split): boolean {
+  const gap = Math.abs(approvedShare(split.has) - approvedShare(split.lacks));
+  return hasEnoughReplies(split) && gap >= MIN_GAP;
+}
+
+export function reactedReplies(events: ReactedTurn[]): number {
+  return outcomes(events).length;
+}
+
+/** The length split, when it is evidence that the user approves shorter replies. */
+export function shorterApprovedMore(events: ReactedTurn[]): Split | null {
+  const length = lengthSplit(outcomes(events));
+  if (!isEvidence(length)) return null;
+  return approvedShare(length.has) > approvedShare(length.lacks) ? length : null;
+}

package/src/hooks/lib/interaction.ts

@@ -13,6 +13,7 @@ import {
 import { resolve } from "node:path";
 import { currentAttribution } from "./actor";
 import { hearsPromptContext } from "./agent";
+import { asksForLess, followedHint, ignoredHintReminder } from "./interaction-hint-check";
 import {
   type Baseline,
   DEFAULT_BASELINE,
@@ -21,6 +22,7 @@ import {
   moodReminder,
   readMood,
 } from "./interaction-mood";
+import { shorterApprovedMore } from "./interaction-preferences";
 import {
   isCorrection,
   isRepeat,
@@ -51,6 +53,7 @@ export interface TurnEvent extends MoodTurn {
   reaction: Reaction | null;
   mood?: string;
   hinted?: boolean;
+  complied?: boolean;
   runtime?: string;
 }
 
@@ -166,13 +169,21 @@ export function turnsSince(since: Date): TurnEvent[] {
     .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 {
+/** This month and last, outside the session being judged. */
+function historyOutside(session: string, now: Date): TurnEvent[] {
   const lastMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
-  const events = [
-    ...readEvents(monthFile(lastMonth)),
-    ...readEvents(monthFile(now)),
-  ].filter((e) => e.session !== session);
+  return [...readEvents(monthFile(lastMonth)), ...readEvents(monthFile(now))].filter(
+    (e) => e.session !== session
+  );
+}
+
+function usualReplyWords(history: TurnEvent[]): number | null {
+  const replies = history.flatMap((e) => (e.reply ? [e.reply.words] : []));
+  return replies.length >= BASELINE_MIN_SAMPLES ? median(replies) : null;
+}
+
+/** The user's own normal, measured on their history. */
+function baseline(events: TurnEvent[]): Baseline {
   const gaps = events
     .filter((e) => e.gapSec !== null && !e.afterBreak)
     .map((e) => e.gapSec);
@@ -239,7 +250,25 @@ function sampleReaction(event: TurnEvent, text: string, track: SessionTrack): vo
   });
 }
 
-/** Logs the turn and returns a reminder when the session's picture changed. */
+/** Only while the user still wants less: once the mood is back to usual, length is not the point. */
+function reminderForIgnoredHint(
+  complied: boolean | null,
+  moodKey: string,
+  replyWords: number | undefined,
+  usualReply: number | null,
+  history: TurnEvent[]
+): string | null {
+  if (complied !== false || !asksForLess(moodKey)) return null;
+  if (replyWords === undefined || usualReply === null) return null;
+  return ignoredHintReminder(replyWords, usualReply, shorterApprovedMore(history));
+}
+
+function joinReminders(...reminders: (string | null)[]): string | null {
+  const said = reminders.filter((r): r is string => r !== null);
+  return said.length ? said.join("\n") : null;
+}
+
+/** Logs the turn and returns a reminder when the session's picture changed, or a hint went unheeded. */
 export function observeTurn(
   prompt: string,
   session: string | undefined,
@@ -250,14 +279,24 @@ export function observeTurn(
   const text = stripInjectedTags(prompt);
   if (!text) return null;
   const track = trackOf(session);
+  const history = historyOutside(session, now);
+  const usualReply = usualReplyWords(history);
   const event = measureTurn(text, session, track, now, channel);
+  const replyWords = event.reply?.words;
+  const complied = hearsPromptContext()
+    ? followedHint(track.mood, replyWords, usualReply)
+    : null;
   const recent = [...track.recent, event].slice(-RECENT_KEPT);
-  const mood = readMood(recent, baseline(session, now));
-  const reminder = moodReminder(mood, track.mood ?? "");
+  const mood = readMood(recent, baseline(history));
+  const reminder = joinReminders(
+    moodReminder(mood, track.mood ?? ""),
+    reminderForIgnoredHint(complied, mood.key, replyWords, usualReply, history)
+  );
   appendEvent({
     ...event,
     mood: mood.key,
     hinted: reminder !== null && hearsPromptContext(),
+    ...(complied !== null && { complied }),
   });
   sampleReaction(event, text, track);
   writeTrack(session, {

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

@@ -5,6 +5,15 @@
 
 import type { TurnEvent } from "../../hooks/lib/interaction";
 import { median } from "../../hooks/lib/interaction-mood";
+import {
+  approvedShare,
+  hasEnoughReplies,
+  isEvidence,
+  reactedReplies,
+  type Side,
+  type Split,
+  splits,
+} from "../../hooks/lib/interaction-preferences";
 
 const LABELS = ["short", "long", "fast", "skimming", "friction"] as const;
 
@@ -13,6 +22,12 @@ interface ReplyUnderMood {
   words: number;
   approved: boolean;
   corrected: boolean;
+  complied?: boolean;
+}
+
+interface HintFollowing {
+  checked: number;
+  followed: number;
 }
 
 interface ReplyStats {
@@ -20,6 +35,7 @@ interface ReplyStats {
   medianWords: number | null;
   approvedShare: number;
   correctedShare: number;
+  followed: HintFollowing;
 }
 
 interface AgentCounts {
@@ -38,6 +54,17 @@ export interface InteractionSummary {
   unlogged: number;
   usual: ReplyStats;
   byLabel: Record<string, ReplyStats>;
+  approvals: Approvals;
+  approvalsByChannel: Record<string, Approvals>;
+}
+
+interface Approvals {
+  reacted: number;
+  splits: Split[];
+}
+
+function approvals(events: TurnEvent[]): Approvals {
+  return { reacted: reactedReplies(events), splits: splits(events) };
 }
 
 function tally(values: string[]): Record<string, number> {
@@ -56,6 +83,10 @@ function stats(replies: ReplyUnderMood[]): ReplyStats {
     medianWords: median(replies.map((r) => r.words)),
     approvedShare: share(replies, (r) => r.approved),
     correctedShare: share(replies, (r) => r.corrected),
+    followed: {
+      checked: replies.filter((r) => r.complied !== undefined).length,
+      followed: replies.filter((r) => r.complied === true).length,
+    },
   };
 }
 
@@ -71,6 +102,7 @@ function repliesUnderMood(events: TurnEvent[]): ReplyUnderMood[] {
         words: e.reply.words,
         approved: e.reaction === "approved",
         corrected: e.reaction === "corrected" || e.reaction === "repeated",
+        complied: e.complied,
       });
     lastMood.set(e.session, e.mood);
   }
@@ -109,9 +141,20 @@ export function summarize(events: TurnEvent[]): InteractionSummary {
         stats(replies.filter((r) => r.labels.includes(label))),
       ])
     ),
+    approvals: approvals(events),
+    approvalsByChannel: approvalsByChannel(events),
   };
 }
 
+function approvalsByChannel(events: TurnEvent[]): Record<string, Approvals> {
+  const channels = Map.groupBy(events, (e) => e.channel ?? "unknown");
+  return Object.fromEntries(
+    [...channels]
+      .map(([channel, turns]) => [channel, approvals(turns)] as const)
+      .filter(([, a]) => a.reacted > 0)
+  );
+}
+
 function pct(n: number): string {
   return `${Math.round(n * 100)}%`;
 }
@@ -133,18 +176,52 @@ function words(s: ReplyStats): string {
 
 function labelLine(label: string, s: ReplyStats, usual: ReplyStats): string {
   if (s.replies === 0) return `  ${label.padEnd(9)} no replies yet`;
-  return [
+  const parts = [
     `  ${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(" · ");
+  ];
+  if (s.followed.checked)
+    parts.push(`followed ${s.followed.followed} of ${s.followed.checked}`);
+  return parts.join(" · ");
 }
 
 function plural(n: number, noun: string, nouns = `${noun}s`): string {
   return `${n} ${n === 1 ? noun : nouns}`;
 }
 
+function approvedOf(s: Side): string {
+  return `${pct(approvedShare(s))} of ${s.replies}`;
+}
+
+function splitLine(split: Split): string {
+  const head = `  ${split.shape}:`;
+  if (!hasEnoughReplies(split))
+    return `${head} too few replies (${split.has.replies} against ${split.lacks.replies})`;
+  if (!isEvidence(split))
+    return `${head} no real difference (${approvedOf(split.has)} against ${approvedOf(split.lacks)})`;
+  return `${head} approved ${approvedOf(split.has)} · ${split.opposite}: ${approvedOf(split.lacks)}`;
+}
+
+function approvalLines(title: string, a: Approvals): string[] {
+  return [
+    "",
+    `${title}, from ${plural(a.reacted, "reacted reply", "reacted replies")}:`,
+    ...a.splits.map(splitLine),
+  ];
+}
+
+function allApprovalLines(summary: InteractionSummary): string[] {
+  if (summary.approvals.reacted === 0) return [];
+  return [
+    ...approvalLines("What gets approved", summary.approvals),
+    ...Object.entries(summary.approvalsByChannel).flatMap(([channel, a]) =>
+      approvalLines(`On ${channel}`, a)
+    ),
+  ];
+}
+
 function agentLines(agents: Record<string, AgentCounts>): string[] {
   return Object.entries(agents)
     .sort(([, a], [, b]) => b.turns - a.turns)
@@ -171,6 +248,7 @@ export function reportLines(summary: InteractionSummary, days: number): string[]
     "",
     "Replies written while a label was active, against replies while none was:",
     ...LABELS.map((label) => labelLine(label, summary.byLabel[label], summary.usual)),
+    ...allApprovalLines(summary),
   ];
   if (summary.unlogged)
     lines.push(