portable-agent-layer 0.79.3 → 0.80.0

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

@@ -70,6 +70,10 @@
           "type": "boolean",
           "description": "One line of the current time with every prompt, in identity.principal.timezone, so a session resumed hours later knows the day changed."
         },
+        "interactionAwareness": {
+          "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."
+        },
         "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

@@ -19,7 +19,8 @@ memory/
 │   └── token-usage.jsonl               # Per-call inference token usage
 │
 ├── signals/
-│   └── ratings.jsonl                   # Append-only rating signals (explicit + implicit)
+│   ├── ratings.jsonl                   # Append-only rating signals (explicit + implicit)
+│   └── interaction/YYYY-MM.jsonl       # Measured features of each user turn (never the text)
 │
 ├── relationship/
 │   ├── YYYY-MM/YYYY-MM-DD.md           # Daily interaction notes (W / O / B)
@@ -54,6 +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, corrections) | Prompt-time interaction measurement (automatic) | `signals/interaction/YYYY-MM.jsonl` |
 | A project handoff | Project skill / detached handlers | `projects/<slug>/` |
 
 ## Format conventions

package/assets/templates/pal-settings.json

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

package/package.json

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

package/src/hooks/UserPromptOrchestrator.ts

@@ -30,7 +30,7 @@ logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)
 if (!input?.prompt) process.exit(0);
 
 const sessionId = input.session_id ?? input.sessionId ?? input.conversation_id;
-const injected = await injectPromptContext(input.prompt);
+const injected = await injectPromptContext(input.prompt, sessionId);
 logPromptSnapshot(input.prompt, injected);
 
 const results = await Promise.allSettled([

package/src/hooks/handlers/inject-retrieval.ts

@@ -8,6 +8,7 @@
  */
 
 import { isCodex, isCursor } from "../lib/agent";
+import { observeTurn } from "../lib/interaction";
 import { logDebug, logError } from "../lib/log";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
@@ -85,9 +86,13 @@ function writeForAgent(reminder: string): void {
  *  produced anything. The clock leads: it is the only part that is true of the
  *  moment rather than of the prompt.
  *  @lintignore dynamically imported by opencode plugin */
-export async function getPromptContext(prompt: string): Promise<string | null> {
+export async function getPromptContext(
+  prompt: string,
+  sessionId?: string
+): Promise<string | null> {
   const parts = [
     getWallClockReminder(),
+    withinBudget(() => observeTurn(prompt, sessionId), BUDGET_MS),
     getSteeringReminder(prompt),
     getSkillReminder(prompt),
     await getRetrievalReminder(prompt),
@@ -98,8 +103,11 @@ export async function getPromptContext(prompt: string): Promise<string | null> {
 
 /** Gather all prompt-time context and do the one per-agent write. Returns the
  *  combined reminder that was injected, or null if there was nothing to inject. */
-export async function injectPromptContext(prompt: string): Promise<string | null> {
-  const combined = await getPromptContext(prompt);
+export async function injectPromptContext(
+  prompt: string,
+  sessionId?: string
+): Promise<string | null> {
+  const combined = await getPromptContext(prompt, sessionId);
   if (combined) writeForAgent(combined);
   return combined;
 }

package/src/hooks/handlers/rating.ts

@@ -13,6 +13,7 @@ import { resolve } from "node:path";
 import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { paths } from "../lib/paths";
+import { isSystemText, stripInjectedTags } from "../lib/prompt-text";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
@@ -128,35 +129,6 @@ function isPraise(prompt: string): boolean {
   );
 }
 
-// ── System-Injected Tag Stripping ──
-
-/**
- * Strip IDE/system-injected XML tags from the prompt to recover the raw user text.
- * Claude Code VSCode extension prepends tags like <ide_opened_file>...</ide_opened_file>
- * and <ide_selection>...</ide_selection> to the prompt field in hooks.
- */
-const INJECTED_TAG_RE =
-  /<(?:ide_opened_file|ide_selection|system-reminder|task-notification)[^>]*>[\s\S]*?<\/(?:ide_opened_file|ide_selection|system-reminder|task-notification)>/gi;
-
-function stripInjectedTags(prompt: string): string {
-  return prompt.replace(INJECTED_TAG_RE, "").trim();
-}
-
-// ── System Text Filters ──
-
-const SYSTEM_TEXT_PATTERNS = [
-  /^<task-notification>/i,
-  /^<system-reminder>/i,
-  /^This session is being continued from a previous conversation/i,
-  /^Please continue the conversation/i,
-  /^Note:.*was read before/i,
-];
-
-function isSystemText(prompt: string): boolean {
-  const trimmed = prompt.trim();
-  return SYSTEM_TEXT_PATTERNS.some((re) => re.test(trimmed));
-}
-
 // ── Sentiment Analysis ──
 
 const SENTIMENT_SCHEMA = {

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

@@ -0,0 +1,103 @@
+/**
+ * What the user's recent turns say about how they want to work right now,
+ * measured against their own history rather than a fixed idea of a user.
+ */
+
+export interface MoodTurn {
+  words: number;
+  gapSec: number | null;
+  afterBreak: boolean;
+  skimmed: boolean;
+  interrupted: boolean;
+  repeated: boolean;
+  corrected: boolean;
+}
+
+export interface Baseline {
+  words: number;
+  gapSec: number;
+}
+
+export const DEFAULT_BASELINE: Baseline = { words: 30, gapSec: 120 };
+
+export interface Mood {
+  key: string;
+  facts: string[];
+}
+
+const WINDOW = 6;
+const MIN_TURNS = 3;
+
+export function median(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+function duration(sec: number): string {
+  return sec < 90 ? `${Math.round(sec)}s` : `${Math.round(sec / 60)}m`;
+}
+
+/** A break starts a new sitting; turns before it describe a different moment. */
+function currentSitting(turns: MoodTurn[]): MoodTurn[] {
+  const lastBreak = turns.findLastIndex((t) => t.afterBreak);
+  return turns.slice(Math.max(lastBreak, 0)).slice(-WINDOW);
+}
+
+/** Time away is not a signal of focus, so a break's own gap never counts toward pace. */
+function paceFact(sitting: MoodTurn[], base: Baseline): [string, string] | null {
+  const gaps = sitting
+    .filter((t) => t.gapSec !== null && !t.afterBreak)
+    .map((t) => t.gapSec as number);
+  const pace = gaps.length >= MIN_TURNS ? median(gaps) : null;
+  if (pace === null || pace > base.gapSec / 2) return null;
+  return [
+    "fast",
+    `replying fast (median ${duration(pace)} after your reply, usually ${duration(base.gapSec)})`,
+  ];
+}
+
+function lengthFact(sitting: MoodTurn[], base: Baseline): [string, string] | null {
+  if (sitting.length < MIN_TURNS) return null;
+  const words = median(sitting.map((t) => t.words)) as number;
+  const usual = `median ${Math.round(words)} words, usually ${Math.round(base.words)}`;
+  if (words <= base.words / 2) return ["short", `writing short messages (${usual})`];
+  if (words >= base.words * 2) return ["long", `writing long messages (${usual})`];
+  return null;
+}
+
+function countOf(turns: MoodTurn[], test: (t: MoodTurn) => boolean): number {
+  return turns.filter(test).length;
+}
+
+function skimFact(sitting: MoodTurn[]): [string, string] | null {
+  if (countOf(sitting.slice(-3), (t) => t.skimmed) < 2) return null;
+  return ["skimming", "answering your recent replies faster than they can be read"];
+}
+
+function frictionFact(sitting: MoodTurn[]): [string, string] | null {
+  const rough = (t: MoodTurn) => t.corrected || t.repeated || t.interrupted;
+  if (countOf(sitting.slice(-4), rough) < 2) return null;
+  return ["friction", "correcting, repeating or interrupting in recent turns"];
+}
+
+export function readMood(turns: MoodTurn[], base: Baseline): Mood {
+  const sitting = currentSitting(turns);
+  const found = [
+    paceFact(sitting, base),
+    lengthFact(sitting, base),
+    skimFact(sitting),
+    frictionFact(sitting),
+  ].filter((f): f is [string, string] => f !== null);
+  return { key: found.map(([label]) => label).join(","), facts: found.map(([, f]) => f) };
+}
+
+/** Said only when the picture changes, including once when it returns to normal. */
+export function moodReminder(mood: Mood, previousKey: string): string | null {
+  if (mood.key === previousKey) return null;
+  const text = mood.key
+    ? `Interaction, measured over this sitting: the user is ${mood.facts.join("; ")}. Adapt how you reply to this.`
+    : "Interaction: the user's recent turns are back to their usual pattern.";
+  return `<system-reminder>${text}</system-reminder>`;
+}

package/src/hooks/lib/interaction.ts

@@ -0,0 +1,235 @@
+/**
+ * Measures every user turn in code and logs the features, never the text.
+ * Per-session tracking lives in state and is discarded with the session.
+ */
+
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { currentAttribution } from "./actor";
+import {
+  type Baseline,
+  DEFAULT_BASELINE,
+  type MoodTurn,
+  median,
+  moodReminder,
+  readMood,
+} from "./interaction-mood";
+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 {
+  at: string;
+  words: number;
+  listItems: number;
+  headings: number;
+  asked: boolean;
+}
+
+export interface TurnEvent extends MoodTurn {
+  ts: string;
+  session: string;
+  channel: string | null;
+  hour: number;
+  weekday: string;
+  reply: Omit<ReplyShape, "at"> | null;
+}
+
+interface SessionTrack {
+  updated: string;
+  lastPrompt?: string;
+  lastPromptAt?: string;
+  reply?: ReplyShape;
+  recent: TurnEvent[];
+  mood?: string;
+}
+
+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;
+}
+
+function replyShape(text: string, at: Date): ReplyShape {
+  const lines = text.split("\n");
+  return {
+    at: at.toISOString(),
+    words: wordCount(text),
+    listItems: lines.filter((l) => /^\s*(?:[-*]|\d+\.)\s/.test(l)).length,
+    headings: lines.filter((l) => /^#{1,6}\s/.test(l)).length,
+    asked: text.trim().endsWith("?"),
+  };
+}
+
+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;
+  if (!reply || !track.lastPromptAt) return null;
+  return reply.at >= track.lastPromptAt ? reply : null;
+}
+
+function isSkimmed(reply: ReplyShape | null, gapSec: number | null): boolean {
+  if (!reply || gapSec === null || gapSec <= 0 || reply.words < SKIM_MIN_WORDS)
+    return false;
+  return reply.words / gapSec > SKIM_WORDS_PER_SEC;
+}
+
+function replyFeatures({ at: _at, ...features }: ReplyShape): Omit<ReplyShape, "at"> {
+  return features;
+}
+
+function measureTurn(
+  text: string,
+  session: string,
+  track: SessionTrack,
+  now: Date,
+  channel: string | null
+): TurnEvent {
+  const reply = answeredReply(track);
+  const gapSec = reply ? (now.getTime() - new Date(reply.at).getTime()) / 1000 : null;
+  return {
+    ts: now.toISOString(),
+    session,
+    channel,
+    ...localClock(now),
+    words: wordCount(text),
+    gapSec,
+    afterBreak: gapSec !== null && gapSec > BREAK_SEC,
+    skimmed: isSkimmed(reply, gapSec),
+    interrupted: Boolean(track.lastPromptAt) && !reply,
+    repeated: isRepeat(text, track.lastPrompt),
+    corrected: CORRECTION_RE.test(text),
+    reply: reply ? replyFeatures(reply) : null,
+  };
+}
+
+function eventsDir(): string {
+  return ensureDir(resolve(paths.signals(), "interaction"));
+}
+
+function monthFile(date: Date): string {
+  return resolve(eventsDir(), `${date.toISOString().slice(0, 7)}.jsonl`);
+}
+
+function appendEvent(event: TurnEvent): void {
+  const line = { ...currentAttribution(), type: "turn", ...event };
+  appendFileSync(monthFile(new Date(event.ts)), `${JSON.stringify(line)}\n`);
+}
+
+function readEvents(file: string): TurnEvent[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line) as TurnEvent];
+      } catch {
+        return [];
+      }
+    });
+}
+
+/** 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));
+  const events = [
+    ...readEvents(monthFile(lastMonth)),
+    ...readEvents(monthFile(now)),
+  ].filter((e) => e.session !== session);
+  const gaps = events
+    .filter((e) => e.gapSec !== null && !e.afterBreak)
+    .map((e) => e.gapSec);
+  return {
+    words:
+      events.length >= BASELINE_MIN_SAMPLES
+        ? (median(events.map((e) => e.words)) as number)
+        : DEFAULT_BASELINE.words,
+    gapSec:
+      gaps.length >= BASELINE_MIN_SAMPLES
+        ? (median(gaps as number[]) as number)
+        : DEFAULT_BASELINE.gapSec,
+  };
+}
+
+function tracksFile(): string {
+  return resolve(paths.state(), "interaction-sessions.json");
+}
+
+function readTracks(): Record<string, SessionTrack> {
+  try {
+    return JSON.parse(readFileSync(tracksFile(), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeTrack(session: string, track: SessionTrack): void {
+  const tracks = { ...readTracks(), [session]: track };
+  const kept = Object.entries(tracks)
+    .sort(([, a], [, b]) => b.updated.localeCompare(a.updated))
+    .slice(0, MAX_TRACKED_SESSIONS);
+  writeFileSync(tracksFile(), JSON.stringify(Object.fromEntries(kept)), "utf-8");
+}
+
+function trackOf(session: string): SessionTrack {
+  return readTracks()[session] ?? { updated: "", recent: [] };
+}
+
+/** Called when the agent finishes a reply, so the next turn can be measured against it. */
+export function recordReply(
+  session: string,
+  reply: string,
+  now: Date = new Date()
+): void {
+  if (!session || !reply.trim() || !isEnabled("interactionAwareness")) return;
+  const track = trackOf(session);
+  writeTrack(session, {
+    ...track,
+    updated: now.toISOString(),
+    reply: replyShape(reply, now),
+  });
+}
+
+/** Logs the turn and returns a reminder when the session's picture changed. */
+export function observeTurn(
+  prompt: string,
+  session: string | undefined,
+  now: Date = new Date(),
+  channel: string | null = process.env.PAL_CHANNEL || null
+): string | null {
+  if (!session || isSystemText(prompt) || !isEnabled("interactionAwareness")) return null;
+  const text = stripInjectedTags(prompt);
+  if (!text) return null;
+  const track = trackOf(session);
+  const event = measureTurn(text, session, track, now, channel);
+  appendEvent(event);
+  const recent = [...track.recent, event].slice(-RECENT_KEPT);
+  const mood = readMood(recent, baseline(session, now));
+  writeTrack(session, {
+    ...track,
+    updated: now.toISOString(),
+    lastPrompt: text,
+    lastPromptAt: now.toISOString(),
+    recent,
+    mood: mood.key,
+  });
+  return moodReminder(mood, track.mood ?? "");
+}

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

@@ -0,0 +1,24 @@
+/**
+ * The prompt field carries more than the user typed: IDE tags, reminders, task
+ * notifications and continuation boilerplate arrive through the same hook.
+ */
+
+const INJECTED_TAG_RE =
+  /<(?:ide_opened_file|ide_selection|system-reminder|task-notification)[^>]*>[\s\S]*?<\/(?:ide_opened_file|ide_selection|system-reminder|task-notification)>/gi;
+
+export function stripInjectedTags(prompt: string): string {
+  return prompt.replace(INJECTED_TAG_RE, "").trim();
+}
+
+const SYSTEM_TEXT_PATTERNS = [
+  /^<task-notification>/i,
+  /^<system-reminder>/i,
+  /^This session is being continued from a previous conversation/i,
+  /^Please continue the conversation/i,
+  /^Note:.*was read before/i,
+];
+
+export function isSystemText(prompt: string): boolean {
+  const trimmed = prompt.trim();
+  return SYSTEM_TEXT_PATTERNS.some((re) => re.test(trimmed));
+}

package/src/hooks/lib/relationship.ts

@@ -102,10 +102,12 @@ export function loadRecentNotes(days: number = 2): string {
   const cutoff = new Date();
   cutoff.setDate(cutoff.getDate() - days);
 
+  const cutoffMonth = `${cutoff.getFullYear()}-${String(cutoff.getMonth() + 1).padStart(2, "0")}`;
   const sections: string[] = [];
 
   for (const monthDir of readdirSync(relDir).sort().reverse()) {
     if (!/^\d{4}-\d{2}$/.test(monthDir)) continue;
+    if (monthDir < cutoffMonth) break;
     const monthPath = resolve(relDir, monthDir);
 
     let files: string[];
@@ -129,8 +131,6 @@ export function loadRecentNotes(days: number = 2): string {
         // skip unreadable files
       }
     }
-
-    if (sections.length > 0) break; // only go back one month at most
   }
 
   return sections.join("\n\n---\n\n");

package/src/hooks/lib/stop.ts

@@ -20,6 +20,7 @@ import { resetTab } from "../handlers/tab";
 import { updateCounts } from "../handlers/update-counts";
 import { captureWorkSession } from "../handlers/work-session";
 import { spawnDetachedInference } from "./detached-inference";
+import { recordReply } from "./interaction";
 import { logDebug, logError } from "./log";
 import { assets, ensureDir, paths } from "./paths";
 import {
@@ -48,6 +49,7 @@ export async function runStopHandlers(
 
   // Cache last assistant response (session-scoped)
   cacheLastResponse(messages, options.lastAssistantMessage, options.sessionId);
+  if (options.sessionId) recordFinalReply(messages, options.sessionId);
 
   // Always persist last exchange — drives CompactRecover + "Pick Up Where You Left Off"
   if (options.sessionId) persistLastExchange(messages, options.sessionId);
@@ -161,6 +163,17 @@ function cacheLastResponse(
   }
 }
 
+function recordFinalReply(
+  messages: ReturnType<typeof parseMessages>,
+  sessionId: string
+): void {
+  try {
+    recordReply(sessionId, extractContent(extractLastAssistant(messages)));
+  } catch (err) {
+    logError("runStopHandlers:recordReply", err);
+  }
+}
+
 /** Write transcript to a fresh tmp file and return the path. Child unlinks it. */
 async function writeTranscriptTmp(transcript: string): Promise<string> {
   const dir = await mkdtemp(resolve(tmpdir(), "pal-transcript-"));

package/src/hooks/lib/wall-clock.ts

@@ -57,6 +57,12 @@ export function localDay(now: Date = new Date()): string {
   return `${f.year}-${f.month}-${f.day}`;
 }
 
+/** Hour (0-23) and short weekday in the principal's timezone. */
+export function localClock(now: Date = new Date()): { hour: number; weekday: string } {
+  const f = fieldsIn(now, zoneOrUtc(identity().principal.timezone));
+  return { hour: Number(f.hour), weekday: f.weekday };
+}
+
 export function getWallClockReminder(now: Date = new Date()): string | null {
   if (!isEnabled("wallClock")) return null;
   const line = wallClockLine(now, identity().principal.timezone);

package/src/targets/opencode/plugin.ts

@@ -175,7 +175,7 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       const text = partsToText(output.parts ?? []);
       if (!text.trim()) return;
 
-      const injectedText = (await getPromptContext(text)) ?? "";
+      const injectedText = (await getPromptContext(text, input.sessionID)) ?? "";
       logPromptSnapshot(text, injectedText || null);
 
       await Promise.allSettled([