portable-agent-layer 0.86.1 → 0.86.3

package/README.md

@@ -91,6 +91,7 @@ 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 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) |
@@ -203,7 +204,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `presentation` | Build branded slide decks from outlines |
 | `projects` | Look up, resume, register, or manage tracked projects |
 | `reflect` | Diagnose why a PAL behavior didn't trigger |
-| `telos` | Inspect or update goals, beliefs, strategies, narratives |
+| `rule-review` | Approve or deny the rules PAL drafted from your corrections || `telos` | Inspect or update goals, beliefs, strategies, narratives |
 | `think` | Structured first-pass reasoning on a problem |
 
 ---

package/assets/skills/rule-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rule-review
+license: MIT
+description: "Review the adaptation rule drafts PAL wrote from the user's corrections and record the user's approve-or-deny decision for each via the rule CLI. Use when the user asks what rule drafts are waiting, wants to review pending rules, or says to approve or deny a rule draft. Not for editing the shipped steering hints or for the opinion tracker."
+argument-hint: "[list | approve <id> | deny <id>]"
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "rule-review"
+    - "rule review"
+    - "rule drafts"
+    - "pending rules"
+    - "review rules"
+    - "approve the rule"
+    - "deny the rule"
+    - "adaptation rules"
+---
+
+# Rule review
+
+An adaptation rule is "when this situation happens (trigger), steer the assistant like this (steering)", backed by evidence from the user's past corrections. PAL drafts them; every rule starts as a draft and steers nothing until the user approves it. A denied draft stays on record so it is never drafted again. A draft can only be approved or denied, never edited.
+
+Your job: show the user the drafts and record their decision. The decision is the user's alone. Never approve or deny a draft the user has not explicitly decided on.
+
+## Workflow
+
+### 1. List the drafts
+
+When the user asks what rule drafts are waiting, wants to review rules, or invokes the skill without an id, run:
+
+```bash
+pal cli rule list
+```
+
+Each draft prints as:
+
+```
+<id>  [draft]  <situation>
+  trigger (<prompt|reply>): <pattern>
+  steering: <steering>
+  evidence: <line>
+```
+
+- If the output is `No drafts waiting.`, tell the user that and stop.
+- Otherwise present every draft in the format under "Output format", then ask the user to approve or deny each one. Keep the ids from this listing; they are what a follow-up decision refers to.
+
+When the user asks about rules already decided (approved, denied, history, all rules), run `pal cli rule list --all` instead and present them the same way, showing each rule's status.
+
+### 2. Resolve which draft the user means
+
+Map the user's decision to exactly one draft id before running anything:
+
+- The user names an id → use that id.
+- The user says "approve it", "deny it", "approve", "deny", "yes approve", or "reject" right after you presented exactly one draft → use that draft's id.
+- The user says "approve them all" or "deny all" after a listing → one command per listed id, in the order listed.
+- The user refers to a draft by its content ("the one about commit messages") and exactly one presented draft matches → use its id.
+- Anything else, including several drafts presented with no id named, or a decision given before any listing in this conversation → do not guess. Run step 1 if there is no listing yet, then ask which id the user means.
+
+A bare "yes", "ok", "fine", or "looks good" is not a decision. Ask "approve or deny <id>?" and wait.
+
+### 3. Record the decision
+
+Run the matching command:
+
+```bash
+pal cli rule approve <id>
+pal cli rule deny <id>
+```
+
+Report the CLI's result line verbatim, e.g. `Rule 3f9a1c2e approved: <situation>`.
+
+If the command exits 1, report its reason verbatim. The reasons are `No rule with id <id>` and `Rule <id> was already <approved|denied>`. On the first, re-run `pal cli rule list` and show the current ids. On the second, say the draft was already decided and leave it.
+
+### 4. Handle requests to change a draft
+
+Editing a draft is not supported, so never offer it and never rewrite a draft's text yourself. When the user wants a different wording, scope, or steering, say so and give the two options: deny the draft, or approve it as is. Then wait for that decision.
+
+## Output format
+
+Present each draft as one compact block, nothing else in between:
+
+```
+Draft <id>
+  When:     <situation>
+  Steer:    <steering>
+  Evidence: <evidence line>
+            <evidence line>
+```
+
+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.
+
+## When to use
+
+- The user asks what rule drafts are pending, waiting, or need review.
+- The user asks to review, approve, or deny an adaptation rule.
+- The user says "approve it" or "deny it" right after you presented a draft.
+- The user asks which rules have been approved or denied so far.
+
+## Do NOT use
+
+- To change the shipped contextual-steering hints. Those live under the `steering` key in `pal-settings.json`, not in rules.
+- For the opinion tracker (confirming or contradicting a tracked preference). That is the `opinion` skill.
+- To edit, reword, or merge a draft. Editing is not supported; the only outcomes are approve or deny.
+- To approve or deny on the user's behalf because a draft "looks reasonable". Wait for the explicit decision.

package/package.json

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

package/src/cli/index.ts

@@ -17,6 +17,7 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
+ *   rule list|approve|deny [id]       Review rules drafted from your corrections
  *   server start|stop|restart|status  The control room, a local page over ~/.pal
  *   <tool> [args]                     Run a built-in agent tool (project, thread, analyze, …)
  *   skill run <skill> <tool> [-- args]  Run a skill's own tool by name, not by path
@@ -202,6 +203,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "rule": {
+      const { runRule } = await import("./rule");
+      const code = await runRule(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "server": {
       const { runServer } = await import("./server");
       const code = await runServer(args);
@@ -298,6 +305,7 @@ function showHelp() {
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
                                             e.g. ledger log --project X --since 7d
+    pal cli rule list|approve|deny [id]     Review rules drafted from your corrections
     pal cli server start|stop|restart|status  The control room: a local page to open before a terminal
     pal cli skill run <skill> <tool> [-- args]  Run ~/.pal/skills/<skill>/tools/<tool> by name
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents

package/src/cli/rule.ts

@@ -0,0 +1,77 @@
+/**
+ * pal cli rule — review the adaptation rules drafted from the user's corrections.
+ *
+ * Subcommands:
+ *   list [--all] [--json]   Drafts waiting for a decision (--all: every rule)
+ *   approve <id>            Turn a draft into a rule that steers
+ *   deny <id>               Reject a draft; it stays on record so it is not redrafted
+ */
+
+import {
+  type AdaptationRule,
+  decideRule,
+  type RuleStatus,
+  readRules,
+} from "../hooks/lib/adaptation-rules";
+
+const DECISIONS: Record<string, Exclude<RuleStatus, "draft">> = {
+  approve: "approved",
+  deny: "denied",
+};
+
+export async function runRule(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub === "list") return cmdList(rest);
+  if (sub && sub in DECISIONS) return cmdDecide(rest[0], DECISIONS[sub]);
+  showHelp();
+  return sub === undefined || sub === "help" ? 0 : 1;
+}
+
+function cmdList(args: string[]): number {
+  const all = args.includes("--all");
+  const rules = readRules().filter((r) => all || r.status === "draft");
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(rules, null, 2));
+    return 0;
+  }
+  if (rules.length === 0) {
+    console.log(all ? "No rules yet." : "No drafts waiting.");
+    return 0;
+  }
+  console.log(rules.map(formatRule).join("\n\n"));
+  return 0;
+}
+
+function formatRule(rule: AdaptationRule): string {
+  return [
+    `${rule.id}  [${rule.status}]  ${rule.when}`,
+    `  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`,
+    `  steering: ${rule.steering}`,
+    ...rule.evidence.map((e) => `  evidence: ${e}`),
+  ].join("\n");
+}
+
+function cmdDecide(
+  id: string | undefined,
+  decision: Exclude<RuleStatus, "draft">
+): number {
+  if (!id) {
+    console.error("Give the rule id: pal cli rule approve|deny <id>");
+    return 1;
+  }
+  const result = decideRule(id, decision);
+  if (!result.ok) {
+    console.error(result.reason);
+    return 1;
+  }
+  console.log(`Rule ${id} ${decision}: ${result.rule.when}`);
+  return 0;
+}
+
+function showHelp(): void {
+  console.log(`pal cli rule — review adaptation rules drafted from your corrections
+
+  pal cli rule list [--all] [--json]   Drafts waiting for a decision
+  pal cli rule approve <id>            Approve a draft so it steers
+  pal cli rule deny <id>               Deny a draft; it is not drafted again`);
+}

package/src/hooks/handlers/rating.ts

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { appendTurn } from "../lib/adaptation-turns";
 import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
@@ -21,6 +22,7 @@ import {
   ratingContext,
   ratingFromLabels,
   reactionRequest,
+  turnFromLabels,
 } from "../lib/reaction-rating";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
@@ -223,6 +225,12 @@ 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);
   } catch (err) {
     const { logError } = await import("../lib/log");
     logError("rating:reaction-child", err);

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

@@ -0,0 +1,83 @@
+/**
+ * Adaptation rules: "when this happens, steer like this", learned from the
+ * user's corrections. A rule starts as a draft and only steers once the user
+ * approves it. A denied rule stays on record so the same rule is not drafted again.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+export type RuleStatus = "draft" | "approved" | "denied";
+type Decision = Exclude<RuleStatus, "draft">;
+
+interface RuleTrigger {
+  /** Whether the pattern is matched against the user's prompt or the assistant's reply. */
+  side: "prompt" | "reply";
+  pattern: string;
+}
+
+export interface DraftInput {
+  when: string;
+  trigger: RuleTrigger;
+  steering: string;
+  evidence: string[];
+}
+
+export interface AdaptationRule extends DraftInput {
+  id: string;
+  status: RuleStatus;
+  createdAt: string;
+  decidedAt?: string;
+}
+
+type DecideResult = { ok: true; rule: AdaptationRule } | { ok: false; reason: string };
+
+export function rulesPath(): string {
+  return resolve(paths.adaptation(), "rules.json");
+}
+
+export function readRules(): AdaptationRule[] {
+  const path = rulesPath();
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return Array.isArray(parsed) ? (parsed as AdaptationRule[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeRules(rules: AdaptationRule[]): void {
+  const path = rulesPath();
+  const pending = `${path}.${process.pid}.tmp`;
+  writeFileSync(pending, `${JSON.stringify(rules, null, 2)}\n`, "utf-8");
+  renameSync(pending, path);
+}
+
+export function addDraft(input: DraftInput): AdaptationRule {
+  const rule: AdaptationRule = {
+    ...input,
+    id: randomUUID().slice(0, 8),
+    status: "draft",
+    createdAt: new Date().toISOString(),
+  };
+  writeRules([...readRules(), rule]);
+  return rule;
+}
+
+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}` };
+  const decided: AdaptationRule = {
+    ...rule,
+    status: decision,
+    decidedAt: new Date().toISOString(),
+  };
+  writeRules(rules.map((r) => (r.id === id ? decided : r)));
+  return { ok: true, rule: decided };
+}

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

@@ -0,0 +1,90 @@
+/**
+ * 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;
+}
+
+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/paths.ts

@@ -98,6 +98,7 @@ export const paths = {
   wisdom: () => ensureDir(home("memory", "wisdom", "frames")),
   wisdomState: () => ensureDir(home("memory", "wisdom", "state")),
   relationship: () => ensureDir(home("memory", "relationship")),
+  adaptation: () => ensureDir(home("memory", "adaptation")),
   knowledge: () => ensureDir(home("memory", "knowledge")),
   knowledgeDomain: (d: string) => ensureDir(home("memory", "knowledge", d)),
   failures: () => ensureDir(home("memory", "learning", "failures")),

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