portable-agent-layer 0.108.0 → 0.109.0

package/README.md

@@ -97,7 +97,8 @@ pal cli status        # check your setup
 | `pal cli timezone [<zone>]` | Show or set your timezone. IANA names only, validated before it is stored |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
-| `pal cli rule` | Review the rules drafted from your corrections — `list [--all] [--json]`, `approve <id>`, `deny <id>`. A draft steers nothing until approved; a denied one is never drafted again |
+| `pal cli rule` | Review the rules drafted from your corrections — `list [--all] [--json]`, `approve <id>`, `opinion <id>`, `deny <id>`, `retire <id>`, `add-opinion --kind --when --steering`. A draft steers nothing until approved; a denied one is never drafted again. An opinion has no trigger and steers every session, at most 8 of them and one per correction kind; `list --all` shows each one's correction-kind rate before and after approval |
+| `pal cli correction` | The kinds of mistakes you corrected — `kinds [--days N] [--split DATE] [--json]` shows each kind per 100 turns, before and after a date with `--split`; `backfill` labels confirmed corrections without a kind or with one from an older prompt, and `--relabel` labels every one again |
 | `pal cli server` | The morning screen: a local page to open before a terminal — three moves for today, an urgent/important grid over every project *and* every stated goal, where you left off, and a drawer holding the signal and the action ledger — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250. No model runs on page load |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.108.0",
+  "version": "0.109.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -70,7 +70,11 @@
     "eval:waiting-on": "bun eval/run.ts waiting-on",
     "eval:reaction": "bun eval/run.ts reaction",
     "eval:correction-check": "bun eval/run.ts correction-check",
-    "eval:entity-extraction": "bun eval/entity-extraction/build-prompt.ts && bun eval/run.ts entity-extraction"
+    "eval:entity-extraction": "bun eval/entity-extraction/build-prompt.ts && bun eval/run.ts entity-extraction",
+    "eval:correction-kind": "bun eval/correction-kind/build-prompt.ts && bun eval/run.ts correction-kind",
+    "eval:correction-kind:test": "bun eval/correction-kind/test-set.ts",
+    "eval:rule-drafter": "bun eval/rule-drafter/build-prompt.ts && bun eval/run.ts rule-drafter",
+    "eval:rule-drafter:test": "bun eval/rule-drafter/test-set.ts"
   },
   "lint-staged": {
     "*.ts": [

package/src/cli/correction.ts

@@ -0,0 +1,115 @@
+/**
+ * pal cli correction — the kinds of mistakes the user corrected, and how often.
+ *
+ * Subcommands:
+ *   kinds [--days N] [--split DATE] [--json]   Corrections per 100 turns, by kind
+ *   backfill [--relabel]                        Label the confirmed corrections without a current kind
+ */
+
+import { readTurns } from "../hooks/lib/adaptation-turns";
+import {
+  backfillCorrectionKinds,
+  type KindLabeller,
+  labelWithInference,
+} from "../hooks/lib/correction-backfill";
+import { type KindRates, kindRates, splitRates } from "../hooks/lib/correction-rates";
+import { group, leaf, runCommand, UsageError } from "../tools/lib/command";
+
+function correctionCommandFor(label: KindLabeller) {
+  return group({
+    summary: "The kinds of mistakes you corrected, and how often",
+    commands: {
+      kinds: leaf({
+        summary: "Corrections per 100 turns, by kind",
+        options: {
+          days: { type: "string", description: "Window in days (default 30)" },
+          split: { type: "string", description: "Compare before and after this date" },
+          json: { type: "boolean", description: "Machine-readable output" },
+        },
+        run: ({ values }) => cmdKinds(values.days, values.split, values.json === true),
+      }),
+      backfill: leaf({
+        summary: "Label the confirmed corrections without a kind of the current version",
+        options: {
+          relabel: {
+            type: "boolean",
+            description: "Label every confirmed correction again, after a prompt change",
+          },
+        },
+        run: ({ values }) => cmdBackfill(label, values.relabel === true),
+      }),
+    },
+  });
+}
+
+export const correctionCommand = correctionCommandFor(labelWithInference);
+
+export function runCorrection(
+  args: string[],
+  label: KindLabeller = labelWithInference
+): Promise<number> {
+  return runCommand(correctionCommandFor(label), args, ["pal", "cli", "correction"]);
+}
+
+function windowDays(days: string | undefined): number {
+  if (days === undefined) return 30;
+  const parsed = Number(days);
+  if (!Number.isInteger(parsed) || parsed < 1)
+    throw new UsageError(`--days must be a whole number of days, got "${days}"`);
+  return parsed;
+}
+
+function splitDate(split: string): Date {
+  const at = new Date(split);
+  if (Number.isNaN(at.getTime()))
+    throw new UsageError(`--split must be a date such as 2026-10-20, got "${split}"`);
+  return at;
+}
+
+function kindLine(name: string, count: string, rate: string, extra = ""): string {
+  return `  ${name.padEnd(22)}${count.padStart(4)}  ${rate.padStart(5)}${extra}`;
+}
+
+function formatRates(rates: KindRates, title: string): string {
+  const stale = rates.stale ? `, ${rates.stale} labelled by an older prompt` : "";
+  const header = `${title}: ${rates.turns} turns, ${rates.corrections} confirmed corrections, ${rates.unlabelled} without a kind${stale}`;
+  const rows = rates.kinds.map((rate) => {
+    const names = rate.suggestions.length
+      ? `  (${[...new Set(rate.suggestions)].join(", ")})`
+      : "";
+    return kindLine(rate.kind, String(rate.count), rate.per100.toFixed(1), names);
+  });
+  return [header, kindLine("kind", "n", "/100"), ...rows].join("\n");
+}
+
+function cmdKinds(days: string | undefined, split: string | undefined, json: boolean) {
+  const turns = readTurns(windowDays(days));
+  const result = split ? splitRates(turns, splitDate(split)) : kindRates(turns);
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  const sections =
+    "before" in result
+      ? [
+          formatRates(result.before, "Before ".concat(split ?? "")),
+          formatRates(result.after, "From ".concat(split ?? "")),
+        ]
+      : [formatRates(result, "Last ".concat(String(windowDays(days)), " days"))];
+  console.log(sections.join("\n\n"));
+  return 0;
+}
+
+function labelledLine(turn: { ts: string; issue: string }, kind: string): string {
+  return `${turn.ts.slice(0, 16)}  ${kind}  ${turn.issue}`;
+}
+
+async function cmdBackfill(label: KindLabeller, relabel: boolean) {
+  const result = await backfillCorrectionKinds({
+    label,
+    relabel,
+    onLabelled: (turn, kind) => console.log(labelledLine(turn, kind?.kind ?? "failed")),
+  });
+  console.log(`Labelled ${result.labelled}, failed ${result.failed}.`);
+  return result.failed > 0 ? 1 : 0;
+}

package/src/cli/rule.ts

@@ -4,17 +4,32 @@
  * Subcommands:
  *   list [--all] [--json]   Drafts waiting for a decision (--all: every rule)
  *   approve <id>            Turn a draft into a rule that steers
+ *   opinion <id>            Keep a draft as an opinion, steering every session
  *   deny <id>               Reject a draft; it stays on record so it is not redrafted
+ *   retire <id>             End an approved rule or opinion
+ *   add-opinion --kind K --when W --steering S [--evidence E]
  */
 
 import {
   type AdaptationRule,
+  addOpinion,
   decideRule,
-  type RuleStatus,
+  isOpinion,
   readRules,
+  retireRule,
   type TriggerProof,
 } from "../hooks/lib/adaptation-rules";
-import { group, leaf, runCommand } from "../tools/lib/command";
+import { readTurns, type Turn } from "../hooks/lib/adaptation-turns";
+import { CORRECTION_KINDS, type CorrectionKindName } from "../hooks/lib/correction-kind";
+import {
+  EFFECT_WINDOW_DAYS,
+  type OpinionEffect,
+  opinionEffectOf,
+} from "../hooks/lib/correction-rates";
+import { gateAdvice } from "../hooks/lib/opinion-gate";
+import { group, leaf, runCommand, UsageError } from "../tools/lib/command";
+
+type DecideResult = ReturnType<typeof decideRule>;
 
 export const ruleCommand = group({
   summary: "Review the rules PAL drafted from your corrections",
@@ -30,12 +45,36 @@ export const ruleCommand = group({
     approve: leaf({
       summary: "Approve a draft so it steers",
       args: "<id>",
-      run: ({ positionals }) => cmdDecide(positionals[0], "approved"),
+      run: ({ positionals }) =>
+        report(positionals[0], decideRule(positionals[0], "approved")),
+    }),
+    opinion: leaf({
+      summary: "Keep a draft as an opinion, steering every session without a trigger",
+      args: "<id>",
+      run: ({ positionals }) =>
+        report(positionals[0], decideRule(positionals[0], "opinion")),
     }),
     deny: leaf({
       summary: "Deny a draft; it stays on record so it is not drafted again",
       args: "<id>",
-      run: ({ positionals }) => cmdDecide(positionals[0], "denied"),
+      run: ({ positionals }) =>
+        report(positionals[0], decideRule(positionals[0], "denied")),
+    }),
+    retire: leaf({
+      summary: "End an approved rule or opinion",
+      args: "<id>",
+      run: ({ positionals }) => report(positionals[0], retireRule(positionals[0])),
+    }),
+    "add-opinion": leaf({
+      summary: "Write an opinion by hand; it is approved at once",
+      options: {
+        kind: { type: "string", description: "The correction kind it prevents" },
+        when: { type: "string", description: "The situation, in one sentence" },
+        steering: { type: "string", description: "The instruction, imperative" },
+        evidence: { type: "string", description: "Why it is needed" },
+      },
+      run: ({ values }) =>
+        cmdAddOpinion(values.kind, values.when, values.steering, values.evidence),
     }),
   },
 });
@@ -54,37 +93,105 @@ function cmdList(all: boolean, json: boolean): number {
     console.log(all ? "No rules yet." : "No drafts waiting.");
     return 0;
   }
-  console.log(rules.map(formatRule).join("\n\n"));
+  const measure: Measure = { turns: readTurns(EFFECT_WINDOW_DAYS), rules: readRules() };
+  console.log(rules.map((rule) => formatRule(rule, measure)).join("\n\n"));
   return 0;
 }
 
-function formatRule(rule: AdaptationRule): string {
+interface Measure {
+  turns: Turn[];
+  rules: AdaptationRule[];
+}
+
+function formatRule(rule: AdaptationRule, measure: Measure): string {
+  const label = isOpinion(rule) ? "opinion" : rule.status;
   return [
-    `${rule.id}  [${rule.status}]  ${rule.when}`,
+    `${rule.id}  [${label}]  ${rule.when}`,
     ...(rule.widens ? [`  widens: ${rule.widens}`] : []),
-    `  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`,
+    ...(rule.trigger
+      ? [`  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`]
+      : []),
     `  steering: ${rule.steering}`,
+    ...(rule.kind ? [`  kind: ${rule.kind}`] : []),
     ...(rule.check ? [`  check: ${rule.check}`] : []),
     ...(rule.proof ? [`  proof: ${formatProof(rule.proof)}`] : []),
+    ...offerLines(rule),
+    ...gateLines(rule, measure),
+    ...effectLines(rule, measure),
     ...rule.evidence.map((e) => `  evidence: ${e}`),
   ].join("\n");
 }
 
+function offerLines(rule: AdaptationRule): string[] {
+  if (rule.offer !== "opinion-only" || rule.status !== "draft" || rule.opinionGate)
+    return [];
+  const why = rule.trigger ? "the trigger did not prove" : "no trigger";
+  return [`  offer: ${why}; keep it as an opinion or deny it`];
+}
+
+function gateLines(rule: AdaptationRule, { turns, rules }: Measure): string[] {
+  const advice = gateAdvice(rule, rules, turns);
+  return advice ? [`  no opinion: ${advice}`] : [];
+}
+
+function effectLines(rule: AdaptationRule, { turns, rules }: Measure): string[] {
+  const effect = opinionEffectOf(rule, rules, turns);
+  if (!effect) return [];
+  return [
+    `  effect: ${formatWindows(effect)} (${effect.verdict})`,
+    `  other kinds: ${formatWindows(effect.control)}`,
+  ];
+}
+
+function formatWindows({
+  before,
+  after,
+}: Pick<OpinionEffect, "before" | "after">): string {
+  return `${before.count} in ${before.turns} turns before (${before.per100.toFixed(1)}/100), ${after.count} in ${after.turns} after (${after.per100.toFixed(1)}/100)`;
+}
+
 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 resultLine(id: string, rule: AdaptationRule): string {
+  if (rule.id !== id)
+    return `Rule ${rule.id} now triggers on: ${rule.trigger?.pattern} (widened by ${id})`;
+  const label = isOpinion(rule) ? "kept as an opinion" : rule.status;
+  return `Rule ${id} ${label}: ${rule.when}`;
 }
 
-function cmdDecide(id: string, decision: Exclude<RuleStatus, "draft">): number {
-  const result = decideRule(id, decision);
+function report(id: string, result: DecideResult): number {
   if (!result.ok) {
     console.error(result.reason);
     return 1;
   }
-  console.log(decisionLine(id, decision, result.rule));
+  console.log(resultLine(id, result.rule));
   return 0;
 }
+
+function correctionKind(kind: string | undefined): CorrectionKindName {
+  if (CORRECTION_KINDS.includes(kind as CorrectionKindName))
+    return kind as CorrectionKindName;
+  throw new UsageError(`--kind must be one of ${CORRECTION_KINDS.join(", ")}`);
+}
+
+function required(name: string, value: string | undefined): string {
+  if (!value?.trim()) throw new UsageError(`--${name} is required`);
+  return value.trim();
+}
+
+function cmdAddOpinion(
+  kind: string | undefined,
+  when: string | undefined,
+  steering: string | undefined,
+  evidence: string | undefined
+): number {
+  const result = addOpinion({
+    kind: correctionKind(kind),
+    when: required("when", when),
+    steering: required("steering", steering),
+    evidence: evidence?.trim() ? [evidence.trim()] : [],
+  });
+  return report(result.ok ? result.rule.id : "", result);
+}

package/src/cli/tree.ts

@@ -15,6 +15,7 @@ import {
 } from "../tools/lib/command";
 import { builtinTools, builtinToolVerbs } from "./builtin-tools";
 import { contentCommand } from "./content";
+import { correctionCommand } from "./correction";
 import { costCommand } from "./cost";
 import { eventsCommand } from "./events";
 import { identityCommand } from "./identity";
@@ -169,6 +170,7 @@ export function cliTree(admin: AdminHandlers): Group {
       knowledge: knowledgeCommand,
       ledger: ledgerCommand,
       rule: ruleCommand,
+      correction: correctionCommand,
       server: serverCommand,
       skill: skillCommand,
       subagent: subagentCommand,

package/src/hooks/handlers/rating.ts

@@ -17,6 +17,12 @@ import {
 } from "../lib/adaptation-candidates";
 import { readRules } from "../lib/adaptation-rules";
 import { appendTurn, readTurns, withRequests } from "../lib/adaptation-turns";
+import {
+  correctionKindRequest,
+  needsCorrectionKind,
+  parseCorrectionKind,
+  withCorrectionKind,
+} from "../lib/correction-kind";
 import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
@@ -231,6 +237,16 @@ async function checkCorrection(reply: string, message: string, sessionId?: strin
   return result.success ? parseCorrectionCheck(result.output) : null;
 }
 
+async function labelCorrectionKind(
+  reply: string,
+  message: string,
+  issue: string,
+  sessionId?: string
+) {
+  const result = await inference(correctionKindRequest(reply, message, issue, sessionId));
+  return result.success ? parseCorrectionKind(result.output) : null;
+}
+
 function knownRules() {
   const waiting = readCandidates().filter((candidate) => candidate.verdict === "waiting");
   return [
@@ -251,7 +267,7 @@ async function draftRuleCandidate(sessionId?: string): Promise<void> {
   else logDebug("rule-drafter", `no candidate: ${result.output ?? result.error ?? ""}`);
 }
 
-/** Background mode: label the reaction, check a possible correction, store the rating. */
+/** Background mode: label the reaction, check a possible correction, name a confirmed one's kind, store the rating. */
 async function runReactionRatingAndStore(
   message: string,
   reply: string,
@@ -273,7 +289,10 @@ async function runReactionRatingAndStore(
       label,
       check
     );
-    if (turn) appendTurn(turn, sentAt);
+    const kind = needsCorrectionKind(turn)
+      ? await labelCorrectionKind(reply, message, turn.issue, sessionId)
+      : null;
+    if (turn) appendTurn(withCorrectionKind(turn, kind), sentAt);
     if (turn?.confirmed) await draftRuleCandidate(sessionId);
   } catch (err) {
     const { logError } = await import("../lib/log");

package/src/hooks/handlers/update-check.ts

@@ -134,6 +134,11 @@ async function checkRepo(): Promise<UpdateCache> {
   }
 }
 
+/** npm's latest tag lags a fresh release by seconds; an older latest is never an update. */
+export function isNewerRelease(latest: string, current: string): boolean {
+  return Bun.semver.order(latest, current) === 1;
+}
+
 async function checkNpm(): Promise<UpdateCache> {
   const current = getInstalledVersion();
 
@@ -149,7 +154,7 @@ async function checkNpm(): Promise<UpdateCache> {
 
     return {
       checkedAt: new Date().toISOString(),
-      available: latest !== current,
+      available: isNewerRelease(latest, current),
       current,
       latest,
       mode: "package",

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

@@ -1,15 +1,24 @@
 /**
  * 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.
+ * with the proof of its trigger. A proven candidate becomes a draft rule; one
+ * whose trigger failed becomes a draft that can only be kept as an opinion, since
+ * the mistake recurs even when no pattern catches it, but only once its kind has
+ * recurred enough to measure. 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 {
+  addDraft,
+  type DraftInput,
+  type OpinionGate,
+  readRules,
+  type TriggerProof,
+} from "./adaptation-rules";
 import type { RequestedTurn } from "./adaptation-turns";
+import { opinionGate } from "./opinion-gate";
 import { paths } from "./paths";
 import {
   type ProofVerdict,
@@ -22,12 +31,10 @@ export interface CandidateInput extends DraftInput {
   check: string;
 }
 
-export interface Candidate extends CandidateInput {
+export type Candidate = CandidateInput & {
   id: string;
   createdAt: string;
-  verdict: ProofVerdict;
-  proof: TriggerProof;
-}
+} & ({ verdict: ProofVerdict; proof: TriggerProof } | { verdict: "untriggered" });
 
 function candidatesPath(): string {
   return resolve(paths.adaptation(), "candidates.jsonl");
@@ -59,15 +66,35 @@ function writeCandidates(candidates: Candidate[]): void {
 }
 
 function prove(candidate: Candidate, turns: RequestedTurn[]): Candidate {
+  if (!candidate.trigger) return { ...candidate, verdict: "untriggered" };
   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;
+function canOnlyBeOpinion(candidate: Candidate): boolean {
+  const unproven = candidate.verdict === "failed" || candidate.verdict === "untriggered";
+  return unproven && !candidate.widens;
+}
+
+function gateFor(candidate: Candidate, turns: RequestedTurn[]): OpinionGate | undefined {
+  if (!candidate.kind || candidate.widens) return undefined;
+  return opinionGate(candidate.kind, readRules(), turns);
+}
+
+function draftOf(candidate: Candidate, turns: RequestedTurn[]): DraftInput | null {
   const { id: _id, createdAt: _createdAt, verdict: _verdict, ...draft } = candidate;
-  addDraft(draft);
+  const gate = gateFor(candidate, turns);
+  const gated = gate ? { ...draft, opinionGate: gate } : draft;
+  if (!canOnlyBeOpinion(candidate)) return gated;
+  if (!candidate.kind || (gate && "corrections" in gate)) return null;
+  return { ...gated, offer: "opinion-only" };
+}
+
+function promoteIfDecided(candidate: Candidate, turns: RequestedTurn[]): void {
+  if (candidate.verdict !== "passed" && !canOnlyBeOpinion(candidate)) return;
+  const draft = draftOf(candidate, turns);
+  if (draft) addDraft(draft);
 }
 
 export function recordCandidate(
@@ -82,7 +109,7 @@ export function recordCandidate(
   } as Candidate;
   const candidate = prove(fresh, turns);
   writeCandidates([...readCandidates(), candidate]);
-  promoteIfPassed(candidate);
+  promoteIfDecided(candidate, turns);
   return candidate;
 }
 
@@ -91,5 +118,6 @@ export function reproveWaiting(turns: RequestedTurn[]): void {
   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);
+  for (const candidate of updated.filter((_c, i) => candidates[i].verdict === "waiting"))
+    promoteIfDecided(candidate, turns);
 }