portable-agent-layer 0.86.3 → 0.88.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

@@ -36,8 +36,11 @@ Each draft prints as:
 
 ```
 <id>  [draft]  <situation>
+  widens: <id of an approved rule>        (only on a widening)
   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 +86,16 @@ 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.
+
+A draft with a `widens:` line is not a new rule. An approved rule missed a correction because its trigger did not match the user's wording, and the draft is that rule with a wider trigger. Add a line `Widens:   rule <id>; approving replaces its trigger with the one above` under When. Approving it updates the approved rule and the draft disappears; the CLI then reports `Rule <id> now triggers on: <pattern> (widened by <draft id>)`. Report that line verbatim too. Denying it leaves the approved rule as it was.
+
 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.3",
+  "version": "0.88.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">> = {
@@ -45,12 +46,24 @@ function cmdList(args: string[]): number {
 function formatRule(rule: AdaptationRule): string {
   return [
     `${rule.id}  [${rule.status}]  ${rule.when}`,
+    ...(rule.widens ? [`  widens: ${rule.widens}`] : []),
     `  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 decisionLine(id: string, decision: string, rule: AdaptationRule): string {
+  if (rule.id === id) return `Rule ${id} ${decision}: ${rule.when}`;
+  return `Rule ${rule.id} now triggers on: ${rule.trigger.pattern} (widened by ${id})`;
+}
+
 function cmdDecide(
   id: string | undefined,
   decision: Exclude<RuleStatus, "draft">
@@ -64,7 +77,7 @@ function cmdDecide(
     console.error(result.reason);
     return 1;
   }
-  console.log(`Rule ${id} ${decision}: ${result.rule.when}`);
+  console.log(decisionLine(id, decision, result.rule));
   return 0;
 }
 

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,10 +10,17 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { appendTurn } from "../lib/adaptation-turns";
+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 {
@@ -24,6 +31,13 @@ import {
   reactionRequest,
   turnFromLabels,
 } from "../lib/reaction-rating";
+import {
+  canRepeat,
+  canWiden,
+  correctionsToDraftFrom,
+  drafterRequest,
+  parseDraft,
+} from "../lib/rule-drafter";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
@@ -173,7 +187,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));
 
@@ -199,6 +213,7 @@ function handleImplicitReaction(message: string, sessionId?: string): void {
       sessionId ?? "",
       Buffer.from(trimmed).toString("base64"),
       Buffer.from(reply).toString("base64"),
+      sentAt.toISOString(),
     ],
     "rating"
   );
@@ -210,11 +225,33 @@ 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);
+  const known = knownRules();
+  if (!canRepeat(corrections) && !canWiden(corrections, known)) return;
+  const result = await inference(drafterRequest(corrections, known, sessionId));
+  if (result.usage) logTokenUsage("rule-drafter", result.usage);
+  const candidate = result.success ? parseDraft(result.output, corrections, known) : 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);
@@ -230,7 +267,8 @@ async function runReactionRatingAndStore(
       first,
       confirmation
     );
-    if (turn) appendTurn(turn);
+    if (turn) appendTurn(turn, sentAt);
+    if (turn?.confirmed) await draftRuleCandidate(sessionId);
   } catch (err) {
     const { logError } = await import("../lib/log");
     logError("rating:reaction-child", err);
@@ -239,7 +277,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);
 
@@ -258,7 +300,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
@@ -268,10 +310,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,95 @@
+/**
+ * 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,
+  widenedProofVerdict,
+} 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);
+  const verdict = candidate.widens ? widenedProofVerdict(proof) : proofVerdict(proof);
+  return { ...candidate, proof, verdict };
+}
+
+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,30 @@ 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;
+  /** The approved rule whose trigger this draft replaces with a wider one. */
+  widens?: string;
 }
 
 export interface AdaptationRule extends DraftInput {
@@ -67,12 +80,34 @@ export function addDraft(input: DraftInput): AdaptationRule {
   return rule;
 }
 
+function approveWidening(
+  rules: AdaptationRule[],
+  widening: AdaptationRule
+): DecideResult {
+  const target = rules.find((r) => r.id === widening.widens);
+  if (target?.status !== "approved")
+    return { ok: false, reason: `Rule ${widening.widens} is not an approved rule` };
+  const widened: AdaptationRule = {
+    ...target,
+    trigger: widening.trigger,
+    evidence: [...target.evidence, ...widening.evidence],
+    proof: widening.proof,
+  };
+  writeRules(
+    rules
+      .filter((r) => r.id !== widening.id)
+      .map((r) => (r.id === target.id ? widened : r))
+  );
+  return { ok: true, rule: widened };
+}
+
 export function decideRule(id: string, decision: Decision): DecideResult {
   const rules = readRules();
   const rule = rules.find((r) => r.id === id);
   if (!rule) return { ok: false, reason: `No rule with id ${id}` };
   if (rule.status !== "draft")
     return { ok: false, reason: `Rule ${id} was already ${rule.status}` };
+  if (rule.widens && decision === "approved") return approveWidening(rules, rule);
   const decided: AdaptationRule = {
     ...rule,
     status: decision,

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

@@ -30,6 +30,26 @@ 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`;
 }

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;
 }