portable-agent-layer 0.86.3 → 0.87.0

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

@@ -0,0 +1,87 @@
+/**
+ * What an approved rule did: how often it fired, and whether the user still
+ * corrected the reply it steered. A turn is stamped with when its message was
+ * sent, so the first turn in a session after a fire judges the steered reply.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { RuleTrigger } from "./adaptation-rules";
+import type { Turn } from "./adaptation-turns";
+import { paths } from "./paths";
+
+const WINDOW_DAYS = 30;
+const DAY_MS = 86_400_000;
+
+export interface RuleEvent {
+  ts: string;
+  rule: string;
+  side: RuleTrigger["side"];
+  session: string;
+  sentBack?: boolean;
+}
+
+export interface RuleEffect {
+  fired: number;
+  sentBack: number;
+  /** Fires followed by a labelled turn in the same session. */
+  judged: number;
+  correctedAfter: number;
+}
+
+export function ruleEventsPath(): string {
+  return resolve(paths.adaptation(), "rule-events.jsonl");
+}
+
+function parseLine(line: string): RuleEvent | null {
+  try {
+    const parsed = JSON.parse(line) as RuleEvent;
+    return typeof parsed.ts === "string" && typeof parsed.rule === "string"
+      ? parsed
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readRuleEvents(days = WINDOW_DAYS, now = new Date()): RuleEvent[] {
+  const path = ruleEventsPath();
+  if (!existsSync(path)) return [];
+  const cutoff = now.getTime() - days * DAY_MS;
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .map(parseLine)
+    .filter((e): e is RuleEvent => e !== null && Date.parse(e.ts) >= cutoff);
+}
+
+function turnAfter(event: RuleEvent, turns: Turn[]): Turn | undefined {
+  return turns.find((t) => t.session === event.session && t.ts > event.ts);
+}
+
+function isConfirmedCorrection(turn: Turn | undefined): boolean {
+  return turn?.confirmed === true;
+}
+
+const emptyEffect = (): RuleEffect => ({
+  fired: 0,
+  sentBack: 0,
+  judged: 0,
+  correctedAfter: 0,
+});
+
+export function ruleEffects(
+  events: RuleEvent[],
+  turns: Turn[]
+): Record<string, RuleEffect> {
+  const effects: Record<string, RuleEffect> = {};
+  for (const event of events) {
+    const effect = effects[event.rule] ?? emptyEffect();
+    const judge = turnAfter(event, turns);
+    effect.fired += 1;
+    if (event.sentBack) effect.sentBack += 1;
+    if (judge) effect.judged += 1;
+    if (isConfirmedCorrection(judge)) effect.correctedAfter += 1;
+    effects[event.rule] = effect;
+  }
+  return effects;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * The proof: replay a candidate's trigger over the turn log. A trigger earns a
+ * draft when it fires on repeated corrections and stays quiet on ordinary turns.
+ */
+
+import type { RuleTrigger, TriggerProof } from "./adaptation-rules";
+import type { RequestedTurn } from "./adaptation-turns";
+
+const MIN_FIRED_CORRECTIONS = 2;
+const MAX_ORDINARY_FIRE_RATE = 0.1;
+const MIN_ORDINARY_TURNS = 20;
+
+export type ProofVerdict = "passed" | "failed" | "waiting";
+
+const CORRECTION_REACTIONS = new Set(["corrected", "repeated"]);
+
+function isConfirmedCorrection(turn: RequestedTurn): boolean {
+  return CORRECTION_REACTIONS.has(turn.reaction) && turn.confirmed === true;
+}
+
+function isOrdinary(turn: RequestedTurn): boolean {
+  return !CORRECTION_REACTIONS.has(turn.reaction);
+}
+
+function triggerText(trigger: RuleTrigger, turn: RequestedTurn): string {
+  return trigger.side === "reply" ? turn.replyEnd : turn.prompt;
+}
+
+export function proveTrigger(trigger: RuleTrigger, turns: RequestedTurn[]): TriggerProof {
+  const pattern = new RegExp(trigger.pattern, "i");
+  const testable = turns.filter((turn) => triggerText(trigger, turn) !== "");
+  const fires = (turn: RequestedTurn) => pattern.test(triggerText(trigger, turn));
+  const corrections = testable.filter(isConfirmedCorrection);
+  const ordinary = testable.filter(isOrdinary);
+  return {
+    firedCorrections: corrections.filter(fires).length,
+    corrections: corrections.length,
+    firedOrdinary: ordinary.filter(fires).length,
+    ordinary: ordinary.length,
+  };
+}
+
+export function ordinaryTurnsNeeded(proof: TriggerProof): number {
+  return Math.max(0, MIN_ORDINARY_TURNS - proof.ordinary);
+}
+
+export function proofVerdict(proof: TriggerProof): ProofVerdict {
+  if (proof.firedCorrections < MIN_FIRED_CORRECTIONS) return "failed";
+  if (proof.ordinary < MIN_ORDINARY_TURNS) return "waiting";
+  return proof.firedOrdinary <= proof.ordinary * MAX_ORDINARY_FIRE_RATE
+    ? "passed"
+    : "failed";
+}

package/src/hooks/lib/token-usage.ts

@@ -10,6 +10,7 @@ import { ensureDir, paths } from "./paths";
 
 type TokenCaller =
   | "rating"
+  | "rule-drafter"
   | "failure"
   | "session-name"
   | "session-intelligence"

package/src/targets/opencode/plugin.ts

@@ -179,11 +179,12 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       const text = partsToText(output.parts ?? []);
       if (!text.trim()) return;
 
+      const sentAt = new Date();
       const injectedText = (await getPromptContext(text, input.sessionID)) ?? "";
       logPromptSnapshot(text, injectedText || null);
 
       await Promise.allSettled([
-        captureRating(text, input.sessionID),
+        captureRating(text, input.sessionID, sentAt),
         captureSessionName(text, input.sessionID),
       ]);
 

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

@@ -9,6 +9,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { readRules } from "../../hooks/lib/adaptation-rules";
 import { ensureDir, paths } from "../../hooks/lib/paths";
 import { readAllProjects } from "../../hooks/lib/projects";
 import { queryLedger } from "../ledger/query";
@@ -127,10 +128,27 @@ function unranked(): AttentionItem[] {
     }));
 }
 
+function ruleDrafts(): AttentionItem[] {
+  return readRules()
+    .filter((rule) => rule.status === "draft")
+    .map((rule) => ({
+      id: `rule:${rule.id}`,
+      source: "rules" as const,
+      severity: "waiting" as const,
+      title: `Rule draft waiting: ${rule.when}`,
+      detail: rule.steering,
+      at: rule.createdAt,
+      project: null,
+      href: "/relationship",
+      read: false,
+    }));
+}
+
 const SOURCES: Record<AttentionSource, (now: Date) => AttentionItem[]> = {
   refusals,
   waiting,
   unranked: () => unranked(),
+  rules: () => ruleDrafts(),
 };
 
 export function attention(now: Date = new Date()): AttentionView {

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

@@ -14,7 +14,7 @@ import {
   write as writeSettings,
 } from "../../hooks/lib/settings";
 
-const ATTENTION_SOURCES = ["refusals", "waiting", "unranked"] as const;
+const ATTENTION_SOURCES = ["refusals", "waiting", "unranked", "rules"] as const;
 export type AttentionSource = (typeof ATTENTION_SOURCES)[number];
 
 export interface ControlRoomPrefs {
@@ -28,7 +28,7 @@ const PREF_DEFAULTS: ControlRoomPrefs = {
   quietAfterDays: PROJECT_STALE_DAYS_DEFAULT,
   urgentWithinDays: 14,
   rankGoals: true,
-  attention: { refusals: true, waiting: true, unranked: true },
+  attention: { refusals: true, waiting: true, unranked: true, rules: true },
 };
 
 const DAY_LIMIT = 365;

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

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+
+import { type Candidate, readCandidates } from "../../hooks/lib/adaptation-candidates";
+import {
+  type AdaptationRule,
+  decideRule,
+  readRules,
+} from "../../hooks/lib/adaptation-rules";
+import { readTurns, type Turn } from "../../hooks/lib/adaptation-turns";
+import {
+  type RuleEffect,
+  readRuleEvents,
+  ruleEffects,
+} from "../../hooks/lib/rule-effect";
+import { ordinaryTurnsNeeded } from "../../hooks/lib/rule-proof";
+import type { WriteOutcome } from "./writes";
+
+const WINDOW_DAYS = 30;
+const RECENT_CORRECTIONS = 10;
+
+export interface ActiveRule extends AdaptationRule {
+  effect: RuleEffect;
+}
+
+export interface PipelineCandidate extends Candidate {
+  ordinaryNeeded: number;
+}
+
+interface TurnStats {
+  total: number;
+  byReaction: Record<string, number>;
+  confirmedCorrections: number;
+  recentCorrections: { ts: string; issue: string; message: string }[];
+}
+
+export interface RelationshipView {
+  windowDays: number;
+  drafts: AdaptationRule[];
+  active: ActiveRule[];
+  denied: AdaptationRule[];
+  pipeline: PipelineCandidate[];
+  turns: TurnStats;
+}
+
+function turnStats(turns: Turn[]): TurnStats {
+  const byReaction: Record<string, number> = {};
+  for (const turn of turns)
+    byReaction[turn.reaction] = (byReaction[turn.reaction] ?? 0) + 1;
+  const confirmed = turns.filter((turn) => turn.confirmed === true);
+  return {
+    total: turns.length,
+    byReaction,
+    confirmedCorrections: confirmed.length,
+    recentCorrections: confirmed
+      .slice(-RECENT_CORRECTIONS)
+      .reverse()
+      .map(({ ts, issue, message }) => ({ ts, issue, message })),
+  };
+}
+
+const NO_EFFECT: RuleEffect = { fired: 0, sentBack: 0, judged: 0, correctedAfter: 0 };
+
+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 withStatus = (status: AdaptationRule["status"]) =>
+    rules.filter((rule) => rule.status === status);
+  return {
+    windowDays: WINDOW_DAYS,
+    drafts: withStatus("draft"),
+    active: withStatus("approved").map((rule) => ({
+      ...rule,
+      effect: effects[rule.id] ?? NO_EFFECT,
+    })),
+    denied: withStatus("denied"),
+    pipeline: readCandidates()
+      .filter((candidate) => candidate.verdict !== "passed")
+      .map((candidate) => ({
+        ...candidate,
+        ordinaryNeeded:
+          candidate.verdict === "waiting" ? ordinaryTurnsNeeded(candidate.proof) : 0,
+      })),
+    turns: turnStats(turns),
+  };
+}
+
+export function decideFromPage(
+  id: string,
+  decision: "approved" | "denied"
+): WriteOutcome {
+  const known = readRules().some((rule) => rule.id === id);
+  const result = 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,6 +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 { DEFAULT_PORT, LOOPBACK } from "./server-config";
 import { MAX_SNOOZE_DAYS, setSnooze } from "./snooze";
 import { indexHtml, staticAsset } from "./static";
@@ -39,7 +40,14 @@ export { DEFAULT_PORT, LOOPBACK };
  * Every path the single-page app owns. Listed rather than wildcarded, because a
  * blanket "/*" outranks the fetch handler and would swallow /api as well.
  */
-const PAGE_ROUTES = ["/", "/projects", "/projects/:slug", "/log", "/settings"];
+const PAGE_ROUTES = [
+  "/",
+  "/projects",
+  "/projects/:slug",
+  "/log",
+  "/relationship",
+  "/settings",
+];
 
 export interface ServerStatus {
   pid: number;
@@ -284,7 +292,20 @@ 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. */
+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);
+  }
+  return answer(decideFromPage(id, decision), { id, decision });
+}
+
 const WRITES: Record<string, (request: Request) => Promise<Response>> = {
+  "/api/rule": ruleWrite,
   "/api/serves": overrideServes,
   "/api/isc": iscWrite,
   "/api/placement": placementWrite,
@@ -340,6 +361,8 @@ export function startControlRoom(port: number = DEFAULT_PORT) {
           return json(autoUpdateStatus());
         case "/api/attention":
           return json(attention());
+        case "/api/relationship":
+          return json(relationship());
         case "/api/status":
           return status(server.port ?? port, startedAt);
         default:

package/src/tools/control-room/ui/app.tsx

@@ -22,6 +22,7 @@ import {
   STATUS_FILTERS,
   type StatusFilter,
 } from "./screens/projects";
+import { Relationship } from "./screens/relationship";
 import { Settings } from "./screens/settings";
 import { isLayout, LAYOUTS, type Layout, Today } from "./screens/today";
 
@@ -126,6 +127,23 @@ function LogRoute() {
   );
 }
 
+function RelationshipRoute() {
+  return (
+    <Screen
+      title="Relationship"
+      aside={
+        <span className="text-[12px] text-neutral-700">
+          rules drafted from your corrections, and what they did
+        </span>
+      }
+    >
+      <Scroller className={MARK_ROOM}>
+        <Relationship />
+      </Scroller>
+    </Screen>
+  );
+}
+
 function SettingsRoute() {
   return (
     <Screen title="Settings">
@@ -140,6 +158,7 @@ const TABS = [
   { to: "/", label: "Today", end: true },
   { to: "/projects", label: "Projects", end: false },
   { to: "/log", label: "Action log", end: false },
+  { to: "/relationship", label: "Relationship", end: false },
   { to: "/settings", label: "Settings", end: false },
 ] as const;
 
@@ -194,6 +213,7 @@ function App() {
             <Route path="/projects" element={<ProjectsRoute />} />
             <Route path="/projects/:slug" element={<ProjectDetailRoute />} />
             <Route path="/log" element={<LogRoute />} />
+            <Route path="/relationship" element={<RelationshipRoute />} />
             <Route path="/settings" element={<SettingsRoute />} />
             <Route path="*" element={<Navigate to="/" replace />} />
           </Routes>