portable-agent-layer 0.85.4 → 0.85.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.85.4",
+  "version": "0.85.6",
   "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,115 @@
+/**
+ * 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";
+import { approvalIsKnown } from "./interaction-reaction";
+
+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;
+  reactionRules?: number;
+}
+
+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 && approvalIsKnown(e)
+      ? [{ 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-reaction.ts

@@ -6,7 +6,21 @@
 
 import { extractKeywords, similarity } from "./text-similarity";
 
-export type Reaction = "corrected" | "repeated" | "approved" | "new-topic" | "follow-up";
+export type Reaction =
+  | "corrected"
+  | "repeated"
+  | "approved"
+  | "go-ahead"
+  | "new-topic"
+  | "follow-up";
+
+/** Logged with each reaction, so a log read under older rules is not read with today's meaning. */
+export const REACTION_RULES = 2;
+const GO_AHEAD_SPLIT = 2;
+
+export function approvalIsKnown(turn: { reactionRules?: number }): boolean {
+  return (turn.reactionRules ?? 1) >= GO_AHEAD_SPLIT;
+}
 
 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 don'?t see (?:the|your) (?!(?:problem|issue|point|harm|difference|need|reason)\b))/i;
@@ -15,7 +29,10 @@ const CLAIM_DISPUTED_RE =
   /\byou(?:'re| are) (?:partially |partly |completely |totally )?wrong\b|\b(?:isn'?t|wasn'?t|aren'?t|weren'?t) (?:added|included|fixed|pushed|committed|applied|merged)\b/i;
 
 const APPROVAL_RE =
-  /^(?:(?:understood|got it|ok(?:ay)?),?\s+)?(?: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;
+  /^(?:(?:understood|got it|ok(?:ay)?),?\s+)?(?: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 PRAISE_RE =
+  /\b(?:good|great|nice|perfect|cool|amazing|awesome|excellent|brilliant|works|thanks|thank you|thx|exactly|correct|agreed|lgtm|well done|good job|love it|sounds good|looks (?:good|right)|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|start|fix (?:all|them|both)|approved|let'?s (?:see|do|go|build|start|fix|ship)|(?:add|do|fix) (?:it )?(?:pls|please))\b/i;
@@ -51,7 +68,7 @@ function sentences(text: string): string[] {
     .filter(Boolean);
 }
 
-function isApproval(text: string): boolean {
+function isAcceptance(text: string): boolean {
   const trimmed = text.trim();
   if (trimmed.includes("?") || FAILURE_RE.test(trimmed)) return false;
   if (HEDGE_RE.test(trimmed.split(/[.!?\n]/)[0])) return false;
@@ -61,6 +78,11 @@ function isApproval(text: string): boolean {
   return isShortGoAhead(all[0] ?? "") && !HEDGE_RE.test(trimmed);
 }
 
+/** A yes or a go only gives permission to continue; approval judges the work itself. */
+function praisesTheResult(text: string): boolean {
+  return PRAISE_RE.test(text);
+}
+
 /** 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());
@@ -69,7 +91,7 @@ function isNewTopic(text: string): boolean {
 export function reactionTo(text: string, previousPrompt: string | undefined): Reaction {
   if (isCorrection(text)) return "corrected";
   if (isRepeat(text, previousPrompt)) return "repeated";
-  if (isApproval(text)) return "approved";
+  if (isAcceptance(text)) return praisesTheResult(text) ? "approved" : "go-ahead";
   if (isNewTopic(text)) return "new-topic";
   return "follow-up";
 }

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

@@ -21,6 +21,7 @@ export interface ReactionSample {
 const KEPT: Record<Reaction, number> = {
   "follow-up": 150,
   approved: 20,
+  "go-ahead": 20,
   corrected: 20,
   repeated: 20,
   "new-topic": 20,

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,9 +22,11 @@ import {
   moodReminder,
   readMood,
 } from "./interaction-mood";
+import { shorterApprovedMore } from "./interaction-preferences";
 import {
   isCorrection,
   isRepeat,
+  REACTION_RULES,
   type Reaction,
   reactionTo,
 } from "./interaction-reaction";
@@ -49,8 +52,10 @@ export interface TurnEvent extends MoodTurn {
   weekday: string;
   reply: Omit<ReplyShape, "at"> | null;
   reaction: Reaction | null;
+  reactionRules?: number;
   mood?: string;
   hinted?: boolean;
+  complied?: boolean;
   runtime?: string;
 }
 
@@ -126,6 +131,7 @@ function measureTurn(
     corrected: isCorrection(text),
     reply: reply ? replyFeatures(reply) : null,
     reaction: reply ? reactionTo(text, track.lastPrompt) : null,
+    ...(reply && { reactionRules: REACTION_RULES }),
   };
 }
 
@@ -166,13 +172,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 +253,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 +282,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,14 +5,30 @@
 
 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";
+import { approvalIsKnown } from "../../hooks/lib/interaction-reaction";
 
 const LABELS = ["short", "long", "fast", "skimming", "friction"] as const;
 
 interface ReplyUnderMood {
   labels: string[];
   words: number;
-  approved: boolean;
+  approved: boolean | null;
   corrected: boolean;
+  complied?: boolean;
+}
+
+interface HintFollowing {
+  checked: number;
+  followed: number;
 }
 
 interface ReplyStats {
@@ -20,6 +36,7 @@ interface ReplyStats {
   medianWords: number | null;
   approvedShare: number;
   correctedShare: number;
+  followed: HintFollowing;
 }
 
 interface AgentCounts {
@@ -36,8 +53,20 @@ export interface InteractionSummary {
   reactions: Record<string, number>;
   hints: Record<string, number>;
   unlogged: number;
+  readBeforeGoAhead: 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> {
@@ -54,8 +83,15 @@ function stats(replies: ReplyUnderMood[]): ReplyStats {
   return {
     replies: replies.length,
     medianWords: median(replies.map((r) => r.words)),
-    approvedShare: share(replies, (r) => r.approved),
+    approvedShare: share(
+      replies.filter((r) => r.approved !== null),
+      (r) => r.approved === true
+    ),
     correctedShare: share(replies, (r) => r.corrected),
+    followed: {
+      checked: replies.filter((r) => r.complied !== undefined).length,
+      followed: replies.filter((r) => r.complied === true).length,
+    },
   };
 }
 
@@ -69,14 +105,20 @@ function repliesUnderMood(events: TurnEvent[]): ReplyUnderMood[] {
       replies.push({
         labels: mood ? mood.split(",") : [],
         words: e.reply.words,
-        approved: e.reaction === "approved",
+        approved: approvalIsKnown(e) ? e.reaction === "approved" : null,
         corrected: e.reaction === "corrected" || e.reaction === "repeated",
+        complied: e.complied,
       });
     lastMood.set(e.session, e.mood);
   }
   return replies;
 }
 
+function reactionName(e: TurnEvent): string {
+  if (e.reaction === "approved" && !approvalIsKnown(e)) return "approved or go-ahead";
+  return e.reaction ?? "";
+}
+
 /** A turn carries the reply that answered the turn before it, so a filed reply shows up there. */
 function byAgent(events: TurnEvent[]): Record<string, AgentCounts> {
   const agents: Record<string, AgentCounts> = {};
@@ -99,7 +141,8 @@ export function summarize(events: TurnEvent[]): InteractionSummary {
     sessions: new Set(events.map((e) => e.session)).size,
     channels: tally(events.map((e) => e.channel ?? "unknown")),
     agents: byAgent(events),
-    reactions: tally(events.flatMap((e) => (e.reaction ? [e.reaction] : []))),
+    reactions: tally(events.flatMap((e) => (e.reaction ? [reactionName(e)] : []))),
+    readBeforeGoAhead: events.filter((e) => e.reaction && !approvalIsKnown(e)).length,
     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)),
@@ -109,9 +152,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 +187,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,11 +259,17 @@ 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(
       "",
       `${summary.unlogged} older turns were logged before moods were, and are left out of the comparison.`
     );
+  if (summary.readBeforeGoAhead)
+    lines.push(
+      "",
+      `${summary.readBeforeGoAhead} older replies were read before go-ahead was split from approval, and are left out of the approval figures.`
+    );
   return lines;
 }