portable-agent-layer 0.108.0 → 0.109.0

package/src/hooks/lib/models.ts

@@ -56,12 +56,16 @@ export function isFixedModelRoute(route: string): route is FixedModelRoute {
   return Object.hasOwn(INFERENCE_MODELS, route);
 }
 
-/** Callers whose prompt has been evaluated on Haiku 5.5; the rest stay on HAIKU_MODEL until theirs is. */
-const ANTHROPIC_EVALUATED_ON_HAIKU_5_5 = new Set(["rule-drafter"]);
+/**
+ * Callers on Haiku 5.5: those whose prompt passed its eval there, and every new
+ * caller, whose eval is iterated on 5.5 until it passes. The rest stay on
+ * HAIKU_MODEL until theirs is evaluated.
+ */
+const ANTHROPIC_ON_HAIKU_5_5 = new Set(["rule-drafter", "correction-kind"]);
 
 function evaluatedModel(models: RouteModels, caller?: string): string | undefined {
   const onAnthropic = models === ANTHROPIC_MODELS;
-  return onAnthropic && caller && ANTHROPIC_EVALUATED_ON_HAIKU_5_5.has(caller)
+  return onAnthropic && caller && ANTHROPIC_ON_HAIKU_5_5.has(caller)
     ? HAIKU_5_5_MODEL
     : undefined;
 }

package/src/hooks/lib/opinion-gate.ts

@@ -0,0 +1,73 @@
+/**
+ * Whether a draft may be kept as an opinion. Opinions steer every session, so
+ * one is offered only once its kind has recurred enough to be measured, and
+ * only while no opinion or undecided draft already targets that kind: a second
+ * one would share its rate.
+ */
+
+import { type AdaptationRule, isOpinion, type OpinionGate } from "./adaptation-rules";
+import type { Turn } from "./adaptation-turns";
+import { hasCurrentKind } from "./correction-kind";
+import { type OpinionEffect, opinionEffectOf } from "./correction-rates";
+
+const MIN_KIND_CORRECTIONS = 5;
+
+function correctionsOfKind(kind: string, turns: Turn[]): number {
+  return turns.filter(
+    (turn) =>
+      turn.confirmed === true && hasCurrentKind(turn) && turn.correctionKind.kind === kind
+  ).length;
+}
+
+function offersOpinion(rule: AdaptationRule): boolean {
+  return rule.status === "draft" && !rule.widens && !rule.opinionGate;
+}
+
+function sameKind(kind: string, rules: AdaptationRule[]): AdaptationRule | undefined {
+  return rules.find((r) => r.kind === kind && (isOpinion(r) || offersOpinion(r)));
+}
+
+export function opinionGate(
+  kind: string,
+  rules: AdaptationRule[],
+  turns: Turn[]
+): OpinionGate | undefined {
+  const taken = sameKind(kind, rules);
+  if (taken) return { duplicates: taken.id };
+  const corrections = correctionsOfKind(kind, turns);
+  return corrections < MIN_KIND_CORRECTIONS ? { corrections } : undefined;
+}
+
+function opinionAdvice(id: string, effect: OpinionEffect | null): string {
+  if (effect?.verdict === "lower")
+    return `opinion ${id} lowers its kind, so this is a variant; promote ${id} to a lasting principle to free its slot`;
+  if (effect?.verdict === "not-lower")
+    return `opinion ${id} is not lowering its kind; reword ${id} instead of adding another`;
+  return `opinion ${id}'s effect is not measurable yet (${effect?.verdict ?? "no effect"}); held beside it`;
+}
+
+function duplicateAdvice(
+  id: string,
+  rules: AdaptationRule[],
+  turns: Turn[],
+  now: Date
+): string {
+  const target = rules.find((r) => r.id === id);
+  if (target && isOpinion(target))
+    return opinionAdvice(id, opinionEffectOf(target, rules, turns, now));
+  if (target?.status === "draft")
+    return `draft ${id} already offers an opinion for this kind; decide it first`;
+  return `${id} targeted this kind and is no longer active`;
+}
+
+export function gateAdvice(
+  rule: AdaptationRule,
+  rules: AdaptationRule[],
+  turns: Turn[],
+  now: Date = new Date()
+): string | undefined {
+  const gate = rule.status === "draft" ? rule.opinionGate : undefined;
+  if (!gate) return undefined;
+  if ("duplicates" in gate) return duplicateAdvice(gate.duplicates, rules, turns, now);
+  return `${gate.corrections} corrections of its kind so far; an opinion needs ${MIN_KIND_CORRECTIONS}`;
+}

package/src/hooks/lib/rule-drafter.ts

@@ -1,12 +1,14 @@
 /**
  * The rule drafter: after a confirmed correction, the small model decides
- * whether it repeats an earlier one and, if so, drafts a rule that would have
- * prevented them all.
+ * whether it repeats an earlier one and, if so, drafts the instruction that
+ * would have prevented them all: an opinion, or a rule when its optional
+ * trigger proves.
  */
 
 import type { CandidateInput } from "./adaptation-candidates";
-import type { RuleTrigger } from "./adaptation-rules";
+import { isTriggerRule, type RuleTrigger } from "./adaptation-rules";
 import { type RequestedTurn, type Turn, withRequests } from "./adaptation-turns";
+import { hasCurrentKind } from "./correction-kind";
 import { firesOn } from "./rule-proof";
 
 const MIN_CITED = 2;
@@ -18,14 +20,17 @@ type Correction = RequestedTurn;
 export interface KnownRule {
   id: string;
   when: string;
-  trigger: RuleTrigger;
+  trigger?: RuleTrigger;
   steering: string;
   check?: string;
   status: string;
+  delivery?: "always";
   widens?: string;
 }
 
-const DRAFTER_SYSTEM_PROMPT = `You turn an AI assistant's repeated mistakes into one rule that prevents them.
+type TriggeredRule = KnownRule & { trigger: RuleTrigger };
+
+const DRAFTER_SYSTEM_PROMPT = `You turn an AI assistant's repeated mistakes into one instruction that prevents them.
 
 You get the corrections the user made recently, numbered and oldest first. Each has the end of the assistant's reply the user corrected, the user's correcting message, what the reply got wrong, and, when known, the user's request the reply answered. The newest one just happened. Then the known rules; an approved rule shows its trigger and whether that trigger fires on the newest correction.
 
@@ -37,9 +42,9 @@ Otherwise set widens to an empty string and decide whether the newest correction
 
 If it is not, or another known rule already covers it, set recurring to false, say why in reason in one sentence, leave the text fields empty and set cites to [].
 
-If it is, draft one rule:
-- when: the situation, in one sentence.
-- side and pattern: a case-insensitive JavaScript regular expression for that situation. Side "reply" matches the end of the assistant's reply; side "prompt" matches the user's request. It must match the cited corrections, stay general enough to catch the next one, and not match ordinary turns.
+If it is, draft one instruction. It steers every session unless a trigger proves it can fire only when needed:
+- when: the situation, in one sentence, general enough to cover the next time and not tied to these corrections' topics.
+- side and pattern: optional. Leave both empty unless the situation always shows in the same words, in the user's request (side "prompt") or at the end of the assistant's reply (side "reply"). Then give a case-insensitive JavaScript regular expression that matches every cited correction on that side, would match the next one, and does not match ordinary turns. A pattern built from the words of these corrections or of the user's correcting message is worse than none.
 - steering: the instruction to the assistant, imperative, at most two sentences.
 - check: how to tell from a reply whether the instruction was followed, in one sentence.
 - cites: the numbers of the corrections this rule would have prevented, including the newest.
@@ -52,7 +57,7 @@ const DRAFTER_SCHEMA = {
     widens: { type: "string" },
     reason: { type: "string" },
     when: { type: "string" },
-    side: { enum: ["prompt", "reply"] },
+    side: { enum: ["prompt", "reply", ""] },
     pattern: { type: "string" },
     steering: { type: "string" },
     check: { type: "string" },
@@ -80,12 +85,13 @@ export function canRepeat(corrections: Correction[]): boolean {
   return corrections.length >= MIN_CITED;
 }
 
-function missedApprovedRules(corrections: Correction[], known: KnownRule[]): KnownRule[] {
+function missedApprovedRules(
+  corrections: Correction[],
+  known: KnownRule[]
+): TriggeredRule[] {
   const newest = corrections.at(-1);
   if (!newest) return [];
-  return known.filter(
-    (rule) => rule.status === "approved" && !firesOn(rule.trigger, newest)
-  );
+  return known.filter(isTriggerRule).filter((rule) => !firesOn(rule.trigger, newest));
 }
 
 export function canWiden(corrections: Correction[], known: KnownRule[]): boolean {
@@ -99,9 +105,11 @@ function correctionBlock(correction: Correction, n: number, newest: boolean): st
 
 function knownRuleLine(rule: KnownRule, newest: Correction | undefined): string {
   if (rule.widens)
-    return `- draft widening of rule ${rule.widens}: ${rule.trigger.pattern}`;
-  if (rule.status !== "approved")
-    return `- ${rule.status}: ${rule.when}. ${rule.steering}`;
+    return `- draft widening of rule ${rule.widens}: ${rule.trigger?.pattern}`;
+  if (!isTriggerRule(rule)) {
+    const label = rule.delivery === "always" ? `opinion ${rule.id}` : rule.status;
+    return `- ${label}: ${rule.when}. ${rule.steering}`;
+  }
   const fires = newest && firesOn(rule.trigger, newest) ? "yes" : "no";
   return `- approved rule ${rule.id}: ${rule.when}. ${rule.steering} Trigger on the ${rule.trigger.side}: ${rule.trigger.pattern}. Fires on the newest correction: ${fires}.`;
 }
@@ -134,7 +142,7 @@ interface DraftOutput {
   recurring: boolean;
   widens?: string;
   when: string;
-  side: "prompt" | "reply";
+  side: "prompt" | "reply" | "";
   pattern: string;
   steering: string;
   check: string;
@@ -185,23 +193,48 @@ function citedEvidence(cites: number[], corrections: Correction[]): string[] {
   });
 }
 
+function namedKindsOf(cited: Correction[]): string[] {
+  return cited
+    .filter(hasCurrentKind)
+    .map((c) => c.correctionKind.kind)
+    .filter((kind) => kind !== "other");
+}
+
+export function citedKind(
+  cites: number[],
+  corrections: Correction[]
+): string | undefined {
+  const newestFirst = namedKindsOf(cites.map((n) => corrections[n])).reverse();
+  const count = (kind: string) => newestFirst.filter((k) => k === kind).length;
+  const most = Math.max(...newestFirst.map(count));
+  return newestFirst.find((kind) => count(kind) === most);
+}
+
+function withKind<T extends CandidateInput>(candidate: T, kind: string | undefined): T {
+  return kind ? { ...candidate, kind } : candidate;
+}
+
+function optionalTrigger({ side, pattern }: DraftOutput): RuleTrigger | undefined {
+  if ((side !== "prompt" && side !== "reply") || !hasText(pattern)) return undefined;
+  const bare = bareExpression(pattern);
+  return isValidPattern(bare) ? { side, pattern: bare } : undefined;
+}
+
 function parseNewRule(
   draft: DraftOutput,
   corrections: Correction[]
 ): CandidateInput | null {
   const cites = validCites(draft.cites, corrections.length, MIN_CITED);
-  const sideOk = draft.side === "prompt" || draft.side === "reply";
-  if (!cites || !sideOk || !hasText(draft.pattern)) return null;
-  const pattern = bareExpression(draft.pattern);
-  if (!isValidPattern(pattern)) return null;
-  if (!hasText(draft.when, draft.steering, draft.check)) return null;
-  return {
+  if (!cites || !hasText(draft.when, draft.steering, draft.check)) return null;
+  const trigger = optionalTrigger(draft);
+  const candidate = {
     when: draft.when.trim(),
-    trigger: { side: draft.side, pattern },
+    ...(trigger && { trigger }),
     steering: draft.steering.trim(),
     check: draft.check.trim(),
     evidence: citedEvidence(cites, corrections),
   };
+  return withKind(candidate, citedKind(cites, corrections));
 }
 
 function parseWidening(

package/src/hooks/lib/semi-static.ts

@@ -8,8 +8,8 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
+import { opinionsContext } from "./adaptation-rules";
 import { type FailureEntry, readFailures } from "./learning-store";
-import { loadOpinionContext } from "./opinions";
 import { palHome, paths } from "./paths";
 import { type ProjectProgress, readAllProjects, resolveProjectFromCwd } from "./projects";
 import { readFramePrinciples } from "./wisdom";
@@ -148,7 +148,7 @@ export function getSemiStaticSources(): SemiStaticSource[] {
       writesDigest: true,
       load: () => {
         try {
-          return loadOpinionContext();
+          return opinionsContext();
         } catch {
           return "";
         }

package/src/tools/control-room/relationship.ts

@@ -1,8 +1,8 @@
 /**
  * The Relationship tab: the rule drafts waiting on the user, what the approved
  * rules did, the candidates still being proven, and the last 30 days of labelled
- * turns. A decision goes through `decideRule`, the same rule the CLI and the
- * rule-review skill use.
+ * turns. A decision goes through `decideRule` or `retireRule`, the same rules the
+ * CLI and the rule-review skill use.
  */
 
 import { type Candidate, readCandidates } from "../../hooks/lib/adaptation-candidates";
@@ -10,8 +10,16 @@ import {
   type AdaptationRule,
   decideRule,
   readRules,
+  retireRule,
+  type TriggerProof,
 } from "../../hooks/lib/adaptation-rules";
 import { readTurns, type Turn } from "../../hooks/lib/adaptation-turns";
+import {
+  EFFECT_WINDOW_DAYS,
+  type OpinionEffect,
+  opinionEffectOf,
+} from "../../hooks/lib/correction-rates";
+import { gateAdvice } from "../../hooks/lib/opinion-gate";
 import {
   type RuleEffect,
   readRuleEvents,
@@ -25,12 +33,21 @@ const RECENT_CORRECTIONS = 10;
 
 export interface ActiveRule extends AdaptationRule {
   effect: RuleEffect;
+  opinionEffect: OpinionEffect | null;
 }
 
-export interface PipelineCandidate extends Candidate {
-  ordinaryNeeded: number;
+export interface DraftRule extends AdaptationRule {
+  /** Why it cannot be kept as an opinion, and what to do instead. */
+  gateAdvice?: string;
 }
 
+export type PageDecision = "approved" | "denied" | "opinion" | "retired";
+
+export type PipelineCandidate = Candidate & {
+  proof: TriggerProof;
+  ordinaryNeeded: number;
+};
+
 interface TurnStats {
   total: number;
   byReaction: Record<string, number>;
@@ -40,7 +57,7 @@ interface TurnStats {
 
 export interface RelationshipView {
   windowDays: number;
-  drafts: AdaptationRule[];
+  drafts: DraftRule[];
   active: ActiveRule[];
   denied: AdaptationRule[];
   pipeline: PipelineCandidate[];
@@ -69,33 +86,41 @@ export function relationship(now: Date = new Date()): RelationshipView {
   const rules = readRules();
   const turns = readTurns(WINDOW_DAYS, now);
   const effects = ruleEffects(readRuleEvents(WINDOW_DAYS, now), turns);
+  const opinionTurns = readTurns(EFFECT_WINDOW_DAYS, now);
   const withStatus = (status: AdaptationRule["status"]) =>
     rules.filter((rule) => rule.status === status);
   return {
     windowDays: WINDOW_DAYS,
-    drafts: withStatus("draft"),
+    drafts: withStatus("draft").map((rule) => {
+      const advice = gateAdvice(rule, rules, opinionTurns, now);
+      return advice ? { ...rule, gateAdvice: advice } : rule;
+    }),
     active: withStatus("approved").map((rule) => ({
       ...rule,
       effect: effects[rule.id] ?? NO_EFFECT,
+      opinionEffect: opinionEffectOf(rule, rules, opinionTurns, now),
     })),
     denied: withStatus("denied"),
-    pipeline: readCandidates()
-      .filter((candidate) => candidate.verdict !== "passed")
-      .map((candidate) => ({
-        ...candidate,
-        ordinaryNeeded:
-          candidate.verdict === "waiting" ? ordinaryTurnsNeeded(candidate.proof) : 0,
-      })),
+    pipeline: readCandidates().flatMap((candidate) =>
+      candidate.verdict === "passed" || candidate.verdict === "untriggered"
+        ? []
+        : [
+            {
+              ...candidate,
+              ordinaryNeeded:
+                candidate.verdict === "waiting"
+                  ? ordinaryTurnsNeeded(candidate.proof)
+                  : 0,
+            },
+          ]
+    ),
     turns: turnStats(turns),
   };
 }
 
-export function decideFromPage(
-  id: string,
-  decision: "approved" | "denied"
-): WriteOutcome {
+export function decideFromPage(id: string, decision: PageDecision): WriteOutcome {
   const known = readRules().some((rule) => rule.id === id);
-  const result = decideRule(id, decision);
+  const result = decision === "retired" ? retireRule(id) : decideRule(id, decision);
   if (result.ok) return { ok: true, changed: true };
   return { ok: false, status: known ? 409 : 404, error: result.reason };
 }

package/src/tools/control-room/server.ts

@@ -18,7 +18,7 @@ import { agenda, agentsAtWork, board, handoffs, signal, summary } from "./data";
 import { projectDetail } from "./detail";
 import { matrix } from "./matrix";
 import { type PrefUpdate, readPrefs, validatePrefs, writePrefs } from "./prefs";
-import { decideFromPage, relationship } from "./relationship";
+import { decideFromPage, type PageDecision, relationship } from "./relationship";
 import { DEFAULT_PORT, LOOPBACK } from "./server-config";
 import { MAX_SNOOZE_DAYS, setSnooze } from "./snooze";
 import { indexHtml, staticAsset } from "./static";
@@ -290,16 +290,23 @@ async function prefsWrite(request: Request): Promise<Response> {
   return failure ? json({ error: failure }, 400) : json(writePrefs(body as PrefUpdate));
 }
 
-/** Approve or deny a rule draft — the same rule `pal cli rule` reaches. */
+const PAGE_DECISIONS: readonly PageDecision[] = [
+  "approved",
+  "denied",
+  "opinion",
+  "retired",
+];
+
+/** Decide a rule draft or retire a rule — the same rules `pal cli rule` reaches. */
 async function ruleWrite(request: Request): Promise<Response> {
   const body = await readBody(request);
   if (!body) return json({ error: "expected a JSON body" }, 400);
   const { id, decision } = body;
   if (typeof id !== "string" || !id) return json({ error: "id is required" }, 400);
-  if (decision !== "approved" && decision !== "denied") {
-    return json({ error: "decision must be approved or denied" }, 400);
+  if (!PAGE_DECISIONS.includes(decision as PageDecision)) {
+    return json({ error: `decision must be one of ${PAGE_DECISIONS.join(", ")}` }, 400);
   }
-  return answer(decideFromPage(id, decision), { id, decision });
+  return answer(decideFromPage(id, decision as PageDecision), { id, decision });
 }
 
 const WRITES: Record<string, (request: Request) => Promise<Response>> = {