portable-agent-layer 0.86.2 → 0.87.0

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

@@ -94,6 +94,10 @@
           "type": "boolean",
           "description": "Opt-in, off by default. Send a reply with an unbacked result or status claim back to the agent once, asking it to show the output or say the result is unverified. Needs claimCheck. Not on Cursor, whose stop payload carries no reply text."
         },
+        "adaptationRules": {
+          "type": "boolean",
+          "description": "Let the rules you approved from your past corrections steer the agent: a rule triggered by your prompt is injected before the agent answers, and a reply that matches a rule's trigger is sent back to the agent once at stop. Each firing is logged to memory/adaptation/rule-events.jsonl. Set false to switch every rule off. Reply-side rules do not run on Cursor, whose stop payload carries no reply text, or on opencode, whose plugin does not run the stop check."
+        },
         "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/skills/rule-review/SKILL.md

@@ -38,6 +38,8 @@ Each draft prints as:
 <id>  [draft]  <situation>
   trigger (<prompt|reply>): <pattern>
   steering: <steering>
+  check: <how to tell the steering was followed>
+  proof: fired on <n>/<n> corrections, <n>/<n> ordinary turns
   evidence: <line>
 ```
 
@@ -83,10 +85,14 @@ Present each draft as one compact block, nothing else in between:
 Draft <id>
   When:     <situation>
   Steer:    <steering>
+  Check:    <check>
+  Proof:    fired on <n>/<n> corrections, <n>/<n> ordinary turns
   Evidence: <evidence line>
             <evidence line>
 ```
 
+The proof is the trigger replayed over the last 30 days of turns: how many of the user's confirmed corrections it would have caught, and how many ordinary turns it would have fired on needlessly. Omit the Check or Proof line when the listing has none.
+
 Follow the list with one question, e.g. "Approve or deny each? Reply with the id and your decision." After a single draft, "Approve or deny <id>?" is enough.
 
 After each decision, output the CLI's result line (or error reason) verbatim and nothing more unless the user asked a question.

package/assets/templates/pal-settings.json

@@ -32,6 +32,7 @@
     "reactionSampling": true,
     "claimCheck": true,
     "claimCheckBlocks": false,
+    "adaptationRules": true,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

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

package/src/cli/rule.ts

@@ -12,6 +12,7 @@ import {
   decideRule,
   type RuleStatus,
   readRules,
+  type TriggerProof,
 } from "../hooks/lib/adaptation-rules";
 
 const DECISIONS: Record<string, Exclude<RuleStatus, "draft">> = {
@@ -47,10 +48,16 @@ function formatRule(rule: AdaptationRule): string {
     `${rule.id}  [${rule.status}]  ${rule.when}`,
     `  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`,
     `  steering: ${rule.steering}`,
+    ...(rule.check ? [`  check: ${rule.check}`] : []),
+    ...(rule.proof ? [`  proof: ${formatProof(rule.proof)}`] : []),
     ...rule.evidence.map((e) => `  evidence: ${e}`),
   ].join("\n");
 }
 
+function formatProof(proof: TriggerProof): string {
+  return `fired on ${proof.firedCorrections}/${proof.corrections} corrections, ${proof.firedOrdinary}/${proof.ordinary} ordinary turns`;
+}
+
 function cmdDecide(
   id: string | undefined,
   decision: Exclude<RuleStatus, "draft">

package/src/hooks/StopOrchestrator.ts

@@ -6,6 +6,7 @@
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
+import { watchReplyRules } from "./lib/adaptation-steering";
 import { stopBlockResponse } from "./lib/agent";
 import { watchClaims } from "./lib/claim-log";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
@@ -42,4 +43,13 @@ try {
 } catch (err) {
   logError("StopOrchestrator:claim-check", err);
 }
+try {
+  const sendBack = watchReplyRules(payload);
+  if (sendBack) {
+    process.stdout.write(stopBlockResponse(sendBack));
+    process.exit(0);
+  }
+} catch (err) {
+  logError("StopOrchestrator:adaptation-rules", err);
+}
 await stopTurn(payload);

package/src/hooks/UserPromptOrchestrator.ts

@@ -29,12 +29,13 @@ const input = await readStdinJSON<PromptSubmitInput>();
 logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)}`);
 if (!input?.prompt) process.exit(0);
 
+const sentAt = new Date();
 const sessionId = hookSessionId(input);
 const injected = await injectPromptContext(input.prompt, sessionId);
 logPromptSnapshot(input.prompt, injected);
 
 const results = await Promise.allSettled([
-  captureRating(input.prompt, sessionId),
+  captureRating(input.prompt, sessionId, sentAt),
   captureSessionName(input.prompt, sessionId ?? ""),
 ]);
 

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

@@ -7,6 +7,7 @@
  * produces empty output, never blocks the prompt.
  */
 
+import { promptRulesReminder } from "../lib/adaptation-steering";
 import { promptContextResponse } from "../lib/agent";
 import { dueNudgeReminder } from "../lib/daily-nudge";
 import { observeTurn } from "../lib/interaction";
@@ -82,6 +83,7 @@ export async function getPromptContext(
 ): Promise<string | null> {
   const parts = [
     getWallClockReminder(),
+    withinBudget(() => promptRulesReminder(prompt, sessionId), BUDGET_MS),
     withinBudget(() => getRepoStateReminder(), BUDGET_MS),
     withinBudget(() => observeTurn(prompt, sessionId), BUDGET_MS),
     withinBudget(() => dueNudgeReminder(), BUDGET_MS),

package/src/hooks/handlers/rating.ts

@@ -10,9 +10,17 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import {
+  readCandidates,
+  recordCandidate,
+  reproveWaiting,
+} from "../lib/adaptation-candidates";
+import { readRules } from "../lib/adaptation-rules";
+import { appendTurn, readTurns, withRequests } from "../lib/adaptation-turns";
 import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
+import { logDebug } from "../lib/log";
 import { paths } from "../lib/paths";
 import { isSystemText, stripInjectedTags } from "../lib/prompt-text";
 import {
@@ -21,7 +29,14 @@ import {
   ratingContext,
   ratingFromLabels,
   reactionRequest,
+  turnFromLabels,
 } from "../lib/reaction-rating";
+import {
+  canRepeat,
+  correctionsToDraftFrom,
+  drafterRequest,
+  parseDraft,
+} from "../lib/rule-drafter";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
@@ -171,7 +186,7 @@ function handleRating(
 
 // ── Implicit Rating ──
 
-function handleImplicitReaction(message: string, sessionId?: string): void {
+function handleImplicitReaction(message: string, sentAt: Date, sessionId?: string): void {
   const trimmed = message.trim();
   const reply = replyEnd(getLastResponse(sessionId));
 
@@ -197,6 +212,7 @@ function handleImplicitReaction(message: string, sessionId?: string): void {
       sessionId ?? "",
       Buffer.from(trimmed).toString("base64"),
       Buffer.from(reply).toString("base64"),
+      sentAt.toISOString(),
     ],
     "rating"
   );
@@ -208,11 +224,32 @@ async function labelReaction(reply: string, message: string, sessionId?: string)
   return result.success ? parseReactionLabel(result.output) : null;
 }
 
+function knownRules() {
+  const waiting = readCandidates().filter((candidate) => candidate.verdict === "waiting");
+  return [
+    ...readRules(),
+    ...waiting.map((candidate) => ({ ...candidate, status: "candidate" })),
+  ];
+}
+
+async function draftRuleCandidate(sessionId?: string): Promise<void> {
+  const turns = withRequests(readTurns());
+  reproveWaiting(turns);
+  const corrections = correctionsToDraftFrom(turns);
+  if (!canRepeat(corrections)) return;
+  const result = await inference(drafterRequest(corrections, knownRules(), sessionId));
+  if (result.usage) logTokenUsage("rule-drafter", result.usage);
+  const candidate = result.success ? parseDraft(result.output, corrections) : null;
+  if (candidate) recordCandidate(candidate, turns);
+  else logDebug("rule-drafter", `no candidate: ${result.output ?? result.error ?? ""}`);
+}
+
 /** Background mode: label the reaction, confirm a correction, store the rating. */
 async function runReactionRatingAndStore(
   message: string,
   reply: string,
-  sessionId?: string
+  sessionId: string | undefined,
+  sentAt: Date
 ): Promise<void> {
   try {
     const first = await labelReaction(reply, message, sessionId);
@@ -223,6 +260,13 @@ async function runReactionRatingAndStore(
     if (first && rating !== null) {
       handleRating(rating, ratingContext(first, message), "implicit", reply, message);
     }
+    const turn = turnFromLabels(
+      { session: sessionId ?? "", message, replyEnd: reply },
+      first,
+      confirmation
+    );
+    if (turn) appendTurn(turn, sentAt);
+    if (turn?.confirmed) await draftRuleCandidate(sessionId);
   } catch (err) {
     const { logError } = await import("../lib/log");
     logError("rating:reaction-child", err);
@@ -231,7 +275,11 @@ async function runReactionRatingAndStore(
 
 // ── Main Export ──
 
-export function captureRating(message: string, sessionId?: string): void {
+export function captureRating(
+  message: string,
+  sessionId?: string,
+  sentAt: Date = new Date()
+): void {
   // Strip IDE/system-injected tags to recover raw user text
   const cleaned = stripInjectedTags(message);
 
@@ -250,7 +298,7 @@ export function captureRating(message: string, sessionId?: string): void {
 
   // Path 2: Implicit reaction — the praise fast-path runs synchronously, the
   // model path detaches to a background bun subprocess (mirrors session-name).
-  handleImplicitReaction(cleaned, sessionId);
+  handleImplicitReaction(cleaned, sentAt, sessionId);
 }
 
 // Background reaction entry point
@@ -260,10 +308,12 @@ if (process.argv[2] === "--sentiment") {
   const replyB64 = process.argv[5];
   if (msgB64 && replyB64) {
     const decode = (b64: string) => Buffer.from(b64, "base64").toString("utf-8");
+    const sentAt = new Date(process.argv[6] ?? "");
     await runReactionRatingAndStore(
       decode(msgB64),
       decode(replyB64),
-      sid === "" ? undefined : sid
+      sid === "" ? undefined : sid,
+      Number.isNaN(sentAt.getTime()) ? new Date() : sentAt
     );
   }
   process.exit(0);

package/src/hooks/lib/adaptation-candidates.ts

@@ -0,0 +1,89 @@
+/**
+ * Rule candidates: drafts the small model wrote from repeated corrections, each
+ * with the proof of its trigger. Only a proven candidate becomes a draft in the
+ * rule store for the user to review; one the log is still too short to judge
+ * waits and is proven again as the log grows.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { addDraft, type DraftInput, type TriggerProof } from "./adaptation-rules";
+import type { RequestedTurn } from "./adaptation-turns";
+import { paths } from "./paths";
+import { type ProofVerdict, proofVerdict, proveTrigger } from "./rule-proof";
+
+export interface CandidateInput extends DraftInput {
+  check: string;
+}
+
+export interface Candidate extends CandidateInput {
+  id: string;
+  createdAt: string;
+  verdict: ProofVerdict;
+  proof: TriggerProof;
+}
+
+function candidatesPath(): string {
+  return resolve(paths.adaptation(), "candidates.jsonl");
+}
+
+function parseLine(line: string): Candidate | null {
+  try {
+    const parsed = JSON.parse(line) as Candidate;
+    return typeof parsed.createdAt === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readCandidates(): Candidate[] {
+  const path = candidatesPath();
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .map(parseLine)
+    .filter((candidate): candidate is Candidate => candidate !== null);
+}
+
+function writeCandidates(candidates: Candidate[]): void {
+  const path = candidatesPath();
+  const pending = `${path}.${process.pid}.tmp`;
+  writeFileSync(pending, candidates.map((c) => `${JSON.stringify(c)}\n`).join(""));
+  renameSync(pending, path);
+}
+
+function prove(candidate: Candidate, turns: RequestedTurn[]): Candidate {
+  const proof = proveTrigger(candidate.trigger, turns);
+  return { ...candidate, proof, verdict: proofVerdict(proof) };
+}
+
+function promoteIfPassed(candidate: Candidate): void {
+  if (candidate.verdict !== "passed") return;
+  const { id: _id, createdAt: _createdAt, verdict: _verdict, ...draft } = candidate;
+  addDraft(draft);
+}
+
+export function recordCandidate(
+  input: CandidateInput,
+  turns: RequestedTurn[],
+  now: Date = new Date()
+): Candidate {
+  const fresh = {
+    ...input,
+    id: randomUUID().slice(0, 8),
+    createdAt: now.toISOString(),
+  } as Candidate;
+  const candidate = prove(fresh, turns);
+  writeCandidates([...readCandidates(), candidate]);
+  promoteIfPassed(candidate);
+  return candidate;
+}
+
+export function reproveWaiting(turns: RequestedTurn[]): void {
+  const candidates = readCandidates();
+  if (!candidates.some((c) => c.verdict === "waiting")) return;
+  const updated = candidates.map((c) => (c.verdict === "waiting" ? prove(c, turns) : c));
+  writeCandidates(updated);
+  updated.filter((c, i) => candidates[i].verdict === "waiting").forEach(promoteIfPassed);
+}

package/src/hooks/lib/adaptation-rules.ts

@@ -12,17 +12,28 @@ import { paths } from "./paths";
 export type RuleStatus = "draft" | "approved" | "denied";
 type Decision = Exclude<RuleStatus, "draft">;
 
-interface RuleTrigger {
+export interface RuleTrigger {
   /** Whether the pattern is matched against the user's prompt or the assistant's reply. */
   side: "prompt" | "reply";
   pattern: string;
 }
 
+/** Where the trigger fired when replayed over the turn log. */
+export interface TriggerProof {
+  firedCorrections: number;
+  corrections: number;
+  firedOrdinary: number;
+  ordinary: number;
+}
+
 export interface DraftInput {
   when: string;
   trigger: RuleTrigger;
   steering: string;
   evidence: string[];
+  /** How to tell from a reply whether the steering was followed. */
+  check?: string;
+  proof?: TriggerProof;
 }
 
 export interface AdaptationRule extends DraftInput {

package/src/hooks/lib/adaptation-steering.ts

@@ -0,0 +1,87 @@
+/**
+ * Approved adaptation rules at work: a prompt-side rule is injected when its
+ * trigger matches the user's prompt; a reply-side rule sends a matching reply
+ * back once at stop. Every fire is logged so a rule's effect can be measured.
+ */
+
+import { appendFileSync } from "node:fs";
+import { type AdaptationRule, type RuleTrigger, readRules } from "./adaptation-rules";
+import { alreadySentBack } from "./claim-log";
+import { hookFinalReply, hookSessionId } from "./hook-turn";
+import { replyEnd } from "./interaction-samples";
+import { ruleEventsPath } from "./rule-effect";
+import { isEnabled } from "./settings";
+import type { StopTurnPayload } from "./stop";
+
+const REMINDER_MAX = 1500;
+const REMINDER_HEADER =
+  "Rules the user approved from past corrections — follow them on this turn:";
+
+type Side = RuleTrigger["side"];
+
+function triggers(rule: AdaptationRule, side: Side, text: string): boolean {
+  if (rule.status !== "approved" || rule.trigger.side !== side) return false;
+  try {
+    return new RegExp(rule.trigger.pattern, "i").test(text);
+  } catch {
+    return false;
+  }
+}
+
+function firingRules(side: Side, text: string): AdaptationRule[] {
+  if (!isEnabled("adaptationRules") || !text) return [];
+  return readRules().filter((rule) => triggers(rule, side, text));
+}
+
+function logFire(
+  rules: AdaptationRule[],
+  side: Side,
+  session: string,
+  now: Date,
+  sentBack?: boolean
+): void {
+  const lines = rules.map((rule) =>
+    JSON.stringify({ ts: now.toISOString(), rule: rule.id, side, session, sentBack })
+  );
+  appendFileSync(ruleEventsPath(), `${lines.join("\n")}\n`);
+}
+
+function withinBudget(rules: AdaptationRule[]): AdaptationRule[] {
+  let size = REMINDER_HEADER.length + "<system-reminder>\n\n</system-reminder>".length;
+  return rules.filter((rule) => {
+    size += rule.steering.length + 3;
+    return size <= REMINDER_MAX;
+  });
+}
+
+export function promptRulesReminder(
+  prompt: string,
+  sessionId?: string,
+  now: Date = new Date()
+): string | null {
+  const fired = withinBudget(firingRules("prompt", prompt));
+  if (fired.length === 0) return null;
+  logFire(fired, "prompt", sessionId ?? "unknown", now);
+  return [
+    "<system-reminder>",
+    REMINDER_HEADER,
+    ...fired.map((rule) => `- ${rule.steering}`),
+    "</system-reminder>",
+  ].join("\n");
+}
+
+function sendBackReason(rules: AdaptationRule[]): string {
+  const steering = rules.map((rule) => rule.steering).join(" ");
+  return `Your reply matches a rule the user approved from past corrections. ${steering}`;
+}
+
+export function watchReplyRules(
+  payload: StopTurnPayload | null,
+  now: Date = new Date()
+): string | null {
+  const fired = firingRules("reply", replyEnd(hookFinalReply(payload) ?? ""));
+  if (!payload || fired.length === 0) return null;
+  const sentBack = !alreadySentBack(payload);
+  logFire(fired, "reply", hookSessionId(payload) ?? "unknown", now, sentBack);
+  return sentBack ? sendBackReason(fired) : null;
+}

package/src/hooks/lib/adaptation-turns.ts

@@ -0,0 +1,110 @@
+/**
+ * The turn log: every message the reaction rater labelled, with the end of the
+ * reply it answered. Rule drafts are proven by replaying their trigger over it.
+ *
+ * One append-only file per month, so parallel sessions never rewrite each
+ * other's lines; a month is deleted whole once it ends before the window.
+ */
+
+import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+const WINDOW_DAYS = 30;
+const MESSAGE_MAX = 800;
+const REPLY_END_MAX = 600;
+const DAY_MS = 86_400_000;
+const MONTH_FILE = /^turns-(\d{4})-(\d{2})\.jsonl$/;
+
+export interface TurnInput {
+  session: string;
+  message: string;
+  replyEnd: string;
+  reaction: string;
+  issue: string;
+  /** Set on a correction: whether the second label agreed. */
+  confirmed?: boolean;
+}
+
+export interface Turn extends TurnInput {
+  ts: string;
+}
+
+export interface RequestedTurn extends Turn {
+  /** The user's request the reply answered, when that message was logged too. */
+  prompt: string;
+}
+
+function precedingRequest(turns: Turn[], index: number): string {
+  const session = turns[index].session;
+  for (let i = index - 1; i >= 0; i--) {
+    if (turns[i].session === session) return turns[i].message;
+  }
+  return "";
+}
+
+export function withRequests(turns: Turn[]): RequestedTurn[] {
+  return turns.map((turn, index) => ({
+    ...turn,
+    prompt: precedingRequest(turns, index),
+  }));
+}
+
+function monthFile(date: Date): string {
+  return `turns-${date.toISOString().slice(0, 7)}.jsonl`;
+}
+
+function monthEnd(file: string): number | null {
+  const match = MONTH_FILE.exec(file);
+  return match ? Date.UTC(Number(match[1]), Number(match[2]), 1) : null;
+}
+
+function monthFiles(): string[] {
+  const dir = paths.adaptation();
+  return existsSync(dir)
+    ? readdirSync(dir)
+        .filter((f) => MONTH_FILE.test(f))
+        .sort()
+    : [];
+}
+
+function pruneMonthsBefore(cutoff: number): void {
+  for (const file of monthFiles()) {
+    const end = monthEnd(file);
+    if (end !== null && end <= cutoff)
+      rmSync(resolve(paths.adaptation(), file), { force: true });
+  }
+}
+
+export function appendTurn(turn: TurnInput, now: Date = new Date()): void {
+  const record: Turn = {
+    ts: now.toISOString(),
+    ...turn,
+    message: turn.message.slice(0, MESSAGE_MAX),
+    replyEnd: turn.replyEnd.slice(-REPLY_END_MAX),
+  };
+  appendFileSync(
+    resolve(paths.adaptation(), monthFile(now)),
+    `${JSON.stringify(record)}\n`
+  );
+  pruneMonthsBefore(now.getTime() - WINDOW_DAYS * DAY_MS);
+}
+
+function parseLine(line: string): Turn | null {
+  try {
+    const parsed = JSON.parse(line) as Turn;
+    return typeof parsed.ts === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readTurns(days: number = WINDOW_DAYS, now: Date = new Date()): Turn[] {
+  const cutoff = now.getTime() - days * DAY_MS;
+  return monthFiles()
+    .flatMap((file) =>
+      readFileSync(resolve(paths.adaptation(), file), "utf-8").split("\n")
+    )
+    .map(parseLine)
+    .filter((turn): turn is Turn => turn !== null && Date.parse(turn.ts) >= cutoff);
+}

package/src/hooks/lib/claim-log.ts

@@ -72,7 +72,7 @@ function record({ check, commands, session, blocked }: Watched, now: Date) {
   appendFileSync(monthFile(now), `${JSON.stringify(line)}\n`);
 }
 
-function alreadySentBack(payload: StopTurnPayload): boolean {
+export function alreadySentBack(payload: StopTurnPayload): boolean {
   return payload.stop_hook_active === true || (payload.loop_count ?? 0) > 0;
 }
 

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

@@ -6,6 +6,8 @@
  * go-ahead, a question or news carries no rating at all.
  */
 
+import type { TurnInput } from "./adaptation-turns";
+
 const MODEL_REACTIONS = [
   "corrected",
   "repeated",
@@ -109,6 +111,24 @@ export function ratingFromLabels(
   return RATING_BY_REACTION[first.reaction] ?? null;
 }
 
+interface SeenTurn {
+  session: string;
+  message: string;
+  replyEnd: string;
+}
+
+export function turnFromLabels(
+  seen: SeenTurn,
+  first: ReactionLabel | null,
+  confirmation: ReactionLabel | null
+): TurnInput | null {
+  if (!first) return null;
+  const turn = { ...seen, reaction: first.reaction, issue: first.issue };
+  return isCorrectionLabel(first)
+    ? { ...turn, confirmed: isCorrectionLabel(confirmation) }
+    : turn;
+}
+
 export function ratingContext(label: ReactionLabel, message: string): string {
   const what = label.reaction === "praised" ? "Praised the reply" : label.issue;
   return `${what || label.reaction}: ${message.slice(0, 200)}`;