portable-agent-layer 0.89.1 → 0.91.0

package/src/cli/whats-new.ts

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palPkg } from "../hooks/lib/paths";
+
+export interface Release {
+  tag_name: string;
+  body?: string | null;
+}
+
+export interface WhatsNew {
+  items: string[];
+  more: number;
+  url: string;
+}
+
+const SHOWN = 3;
+
+function parts(version: string): number[] {
+  return version.replace(/^v/, "").split(".").map(Number);
+}
+
+export function newer(a: string, b: string): boolean {
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i++) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0);
+  }
+  return false;
+}
+
+/** "* **rating:** confirm corrections ([abc](url))" reads "Confirm corrections". */
+export function noteText(bullet: string): string {
+  const text = bullet
+    .replace(/^\s*[*-]\s*/, "")
+    .replace(/^\*\*[^*]+:\*\*\s*/, "")
+    .replace(/\s*\(\[[^\]]*\]\([^)]*\)\)/g, "")
+    .trim();
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function section(body: string, heading: string): string[] {
+  const start = body.indexOf(`### ${heading}`);
+  if (start < 0) return [];
+  const rest = body.slice(start).split("\n").slice(1);
+  const end = rest.findIndex((line) => line.startsWith("#"));
+  return (end < 0 ? rest : rest.slice(0, end))
+    .filter((line) => /^\s*[*-]\s/.test(line))
+    .map(noteText);
+}
+
+export function releaseNotes(body: string): string[] {
+  return [...section(body, "Features"), ...section(body, "Bug Fixes")];
+}
+
+function repoSlug(pkg = palPkg()): string | null {
+  try {
+    const manifest = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8")) as {
+      repository?: { url?: string };
+    };
+    return (
+      /github\.com\/([^/]+\/[^/.]+)/.exec(manifest.repository?.url ?? "")?.[1] ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+export function summarizeReleases(
+  releases: Release[],
+  from: string,
+  to: string,
+  slug: string
+): WhatsNew | null {
+  const items = releases
+    .filter((r) => newer(r.tag_name, from) && !newer(r.tag_name, to))
+    .flatMap((r) => releaseNotes(r.body ?? ""));
+  if (items.length === 0) return null;
+  return {
+    items: items.slice(0, SHOWN),
+    more: Math.max(0, items.length - SHOWN),
+    url: `github.com/${slug}/releases/tag/v${to}`,
+  };
+}
+
+async function fetchReleases(slug: string): Promise<Release[]> {
+  const response = await fetch(
+    `https://api.github.com/repos/${slug}/releases?per_page=30`,
+    {
+      headers: { accept: "application/vnd.github+json" },
+      signal: AbortSignal.timeout(3000),
+    }
+  );
+  return response.ok ? ((await response.json()) as Release[]) : [];
+}
+
+/** Null when the notes cannot be fetched in time: an update never waits on GitHub. */
+export async function whatsNew(
+  from: string,
+  to: string,
+  fetchAll: (slug: string) => Promise<Release[]> = fetchReleases
+): Promise<WhatsNew | null> {
+  const slug = repoSlug();
+  if (!slug) return null;
+  try {
+    return summarizeReleases(await fetchAll(slug), from, to, slug);
+  } catch {
+    return null;
+  }
+}

package/src/hooks/handlers/rating.ts

@@ -21,14 +21,18 @@ import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
 import { logDebug } from "../lib/log";
+import { HAIKU_5_5_MODEL } from "../lib/models";
 import { paths } from "../lib/paths";
 import { isSystemText, stripInjectedTags } from "../lib/prompt-text";
 import {
-  isCorrectionLabel,
+  correctionCheckRequest,
+  needsCorrectionCheck,
+  parseCorrectionCheck,
   parseReactionLabel,
   ratingContext,
   ratingFromLabels,
   reactionRequest,
+  settledLabel,
   turnFromLabels,
 } from "../lib/reaction-rating";
 import {
@@ -225,6 +229,12 @@ async function labelReaction(reply: string, message: string, sessionId?: string)
   return result.success ? parseReactionLabel(result.output) : null;
 }
 
+async function checkCorrection(reply: string, message: string, sessionId?: string) {
+  const result = await inference(correctionCheckRequest(reply, message, sessionId));
+  if (result.usage) logTokenUsage("rating", result.usage);
+  return result.success ? parseCorrectionCheck(result.output) : null;
+}
+
 function knownRules() {
   const waiting = readCandidates().filter((candidate) => candidate.verdict === "waiting");
   return [
@@ -240,13 +250,13 @@ async function draftRuleCandidate(sessionId?: string): Promise<void> {
   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);
+  if (result.usage) logTokenUsage("rule-drafter", result.usage, HAIKU_5_5_MODEL);
   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. */
+/** Background mode: label the reaction, check a possible correction, store the rating. */
 async function runReactionRatingAndStore(
   message: string,
   reply: string,
@@ -255,17 +265,18 @@ async function runReactionRatingAndStore(
 ): Promise<void> {
   try {
     const first = await labelReaction(reply, message, sessionId);
-    const confirmation = isCorrectionLabel(first)
-      ? await labelReaction(reply, message, sessionId)
+    const check = needsCorrectionCheck(first)
+      ? await checkCorrection(reply, message, sessionId)
       : null;
-    const rating = ratingFromLabels(first, confirmation);
-    if (first && rating !== null) {
-      handleRating(rating, ratingContext(first, message), "implicit", reply, message);
+    const label = settledLabel(first, check);
+    const rating = ratingFromLabels(label, check);
+    if (label && rating !== null) {
+      handleRating(rating, ratingContext(label, message), "implicit", reply, message);
     }
     const turn = turnFromLabels(
       { session: sessionId ?? "", message, replyEnd: reply },
-      first,
-      confirmation
+      label,
+      check
     );
     if (turn) appendTurn(turn, sentAt);
     if (turn?.confirmed) await draftRuleCandidate(sessionId);

package/src/hooks/lib/inference.ts

@@ -74,7 +74,7 @@ interface RoutePreview {
 }
 
 function modelFor(route: FixedModelRoute, opts: InferenceOptions): string {
-  return inferenceModel(route, opts.tier);
+  return inferenceModel(route, opts.tier, opts.caller);
 }
 
 function smallModelOf(route: InferenceRoute): string | undefined {

package/src/hooks/lib/models.ts

@@ -5,6 +5,7 @@
 import type { AgentType } from "./agent";
 
 export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
+export const HAIKU_5_5_MODEL = "claude-haiku-5-5";
 export const SONNET_MODEL = "claude-sonnet-5";
 export const FABLE_MODEL = "claude-fable-5";
 
@@ -54,11 +55,23 @@ 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"]);
+
+function evaluatedModel(models: RouteModels, caller?: string): string | undefined {
+  const onAnthropic = models === ANTHROPIC_MODELS;
+  return onAnthropic && caller && ANTHROPIC_EVALUATED_ON_HAIKU_5_5.has(caller)
+    ? HAIKU_5_5_MODEL
+    : undefined;
+}
+
 export function inferenceModel(
   route: FixedModelRoute,
-  tier: InferenceTier = "small"
+  tier: InferenceTier = "small",
+  caller?: string
 ): string {
-  return INFERENCE_MODELS[route][tier];
+  const models = INFERENCE_MODELS[route];
+  return evaluatedModel(models, caller) ?? models[tier];
 }
 
 const AGENT_SPAWN_ROUTE: Partial<Record<AgentType, FixedModelRoute>> = {
@@ -102,6 +115,14 @@ export const MODEL_PRICING: Record<string, ModelPricing> = {
     cacheWrite1h: 2,
     cacheRead: 0.1,
   },
+  // Rates for prompts up to 100k tokens; longer prompts cost 5x, and PAL's never get there.
+  [HAIKU_5_5_MODEL]: {
+    input: 0.1,
+    output: 0.5,
+    cacheWrite5m: 0.125,
+    cacheWrite1h: 0.2,
+    cacheRead: 0.01,
+  },
   [FABLE_MODEL]: {
     input: 10,
     output: 50,

package/src/hooks/lib/reaction-rating.ts

@@ -57,12 +57,47 @@ const REACTION_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+const CORRECTION_CHECK_PROMPT = `An AI assistant sent a reply and the user answered. A first reader labelled the answer a correction of the reply. Check whether that is right.
+
+It is a correction only when the user says or shows that the reply itself was wrong:
+- something the reply claimed is false;
+- something it said was done is not done;
+- a command or step it gave does not work;
+- a promise it made was not kept;
+- following its advice or steps caused a problem;
+- it missed what the user asked, or is waiting on or asking for something the user had already done;
+- the user still does not understand after its explanation, even when they phrase it as a question.
+
+It is not a correction when the user:
+- wants more, or adds a requirement the reply was not asked to meet. "This needs more" or "it should also do X" is a new requirement unless the reply claimed X was already done;
+- cannot find where or how to do a step the reply described;
+- doubts the reply or asks for a check, without saying it is wrong;
+- reports something that failed later, when the reply never claimed it would work;
+- complains about something other than what the reply claimed;
+- decides to change or drop a feature.`;
+
+const CORRECTION_CHECK_ANSWER = `Answer corrected if it is a correction, otherwise not-corrected. For corrected, set issue to what the reply got wrong, in at most twelve words; otherwise set issue to an empty string.`;
+
+const CORRECTION_CHECK_SCHEMA = {
+  type: "object",
+  properties: {
+    reaction: { enum: ["corrected", "not-corrected"] },
+    issue: { type: "string" },
+  },
+  required: ["reaction", "issue"],
+  additionalProperties: false,
+} as const;
+
 const MESSAGE_MAX = 800;
 
+function reactionPrompt(replyEnd: string, message: string): string {
+  return `The end of the assistant's reply:\n<reply_end>\n${replyEnd}\n</reply_end>\n\nThe user's next message:\n<message>\n${message.slice(0, MESSAGE_MAX)}\n</message>`;
+}
+
 export function reactionRequest(replyEnd: string, message: string, sessionId?: string) {
   return {
     system: REACTION_SYSTEM_PROMPT,
-    user: `The end of the assistant's reply:\n<reply_end>\n${replyEnd}\n</reply_end>\n\nThe user's next message:\n<message>\n${message.slice(0, MESSAGE_MAX)}\n</message>`,
+    user: reactionPrompt(replyEnd, message),
     maxTokens: 200,
     timeout: 90_000,
     jsonSchema: REACTION_SCHEMA,
@@ -71,6 +106,51 @@ export function reactionRequest(replyEnd: string, message: string, sessionId?: s
   };
 }
 
+/**
+ * Asked again with the labelling prompt, a model repeats its own mistake; a
+ * narrower question catches the follow-ups it misreads as corrections, and the
+ * corrections it misreads as follow-ups. The answer instruction follows the
+ * message, the order eval/correction-check measures.
+ */
+export function correctionCheckRequest(
+  replyEnd: string,
+  message: string,
+  sessionId?: string
+) {
+  return {
+    ...reactionRequest(replyEnd, message, sessionId),
+    system: CORRECTION_CHECK_PROMPT,
+    user: `${reactionPrompt(replyEnd, message)}\n\n${CORRECTION_CHECK_ANSWER}`,
+    jsonSchema: CORRECTION_CHECK_SCHEMA,
+  };
+}
+
+export function parseCorrectionCheck(
+  output: string | null | undefined
+): ReactionLabel | null {
+  if (!output) return null;
+  try {
+    const parsed = JSON.parse(output) as { reaction?: unknown; issue?: unknown };
+    if (parsed.reaction !== "corrected") return { reaction: "follow-up", issue: "" };
+    const issue = typeof parsed.issue === "string" ? parsed.issue.trim() : "";
+    return { reaction: "corrected", issue };
+  } catch {
+    return null;
+  }
+}
+
+export function needsCorrectionCheck(first: ReactionLabel | null): boolean {
+  return isCorrectionLabel(first) || first?.reaction === "follow-up";
+}
+
+export function settledLabel(
+  first: ReactionLabel | null,
+  check: ReactionLabel | null
+): ReactionLabel | null {
+  const caughtFollowUp = first?.reaction === "follow-up" && isCorrectionLabel(check);
+  return caughtFollowUp ? check : first;
+}
+
 function isModelReaction(value: unknown): value is ModelReaction {
   return MODEL_REACTIONS.includes(value as ModelReaction);
 }

package/src/targets/lib.ts

@@ -18,6 +18,7 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { createStyle, PALETTE, type Rgb } from "../cli/ui/style";
 import {
   AGENT_NAMES,
   AGENT_REGISTRY,
@@ -45,12 +46,47 @@ function narrate(line: string): void {
   if (narrating) console.log(line);
 }
 
+export type LogLevel = "info" | "success" | "warn" | "error" | "detail";
+type LogSink = (level: LogLevel, message: string) => void;
+
+let sink: LogSink | null = null;
+
+/** Hands every log line to `collect` while `work` runs, so a caller can place it under its own step. */
+export async function capturingLog<T>(
+  collect: LogSink,
+  work: () => Promise<T>
+): Promise<T> {
+  const previous = sink;
+  sink = collect;
+  try {
+    return await work();
+  } finally {
+    sink = previous;
+  }
+}
+
+const LEVEL_COLOR: Record<LogLevel, Rgb> = {
+  info: PALETTE.indigo,
+  success: PALETTE.green,
+  warn: PALETTE.amber,
+  error: PALETTE.rose,
+  detail: PALETTE.indigo,
+};
+
+function tagged(level: LogLevel, message: string): string {
+  return `${createStyle().paint(LEVEL_COLOR[level], "[pal]")} ${message}`;
+}
+
+function emit(level: LogLevel, message: string, write: (line: string) => void): void {
+  if (sink) sink(level, message);
+  else write(tagged(level, message));
+}
+
 export const log = {
-  info: (msg: string) => narrate(`\x1b[34m[pal]\x1b[0m ${msg}`),
-  success: (msg: string) => narrate(`\x1b[32m[pal]\x1b[0m ${msg}`),
-  heading: (label: string) => narrate(`\n━━━ ${label} ━━━`),
-  warn: (msg: string) => console.log(`\x1b[33m[pal]\x1b[0m ${msg}`),
-  error: (msg: string) => console.error(`\x1b[31m[pal]\x1b[0m ${msg}`),
+  info: (msg: string) => emit("info", msg, narrate),
+  success: (msg: string) => emit("success", msg, narrate),
+  warn: (msg: string) => emit("warn", msg, (line) => console.log(line)),
+  error: (msg: string) => emit("error", msg, (line) => console.error(line)),
 
   /**
    * Per-item narration from inside a loop, where the caller already reports the
@@ -61,7 +97,7 @@ export const log = {
    */
   detail: (msg: string) => {
     if (runningUnderTest()) return;
-    narrate(`\x1b[34m[pal]\x1b[0m ${msg}`);
+    emit("detail", msg, narrate);
   },
 };
 
@@ -1152,6 +1188,13 @@ function shippedAgentNames(): Set<string> {
   );
 }
 
+export function installedShippedAgentCount(agent: AgentName): number {
+  const dir = nativeAgentsDir(agent);
+  return [...shippedAgentNames()].filter((name) =>
+    existsSync(resolve(dir, agentFileName(name, agent)))
+  ).length;
+}
+
 /** List the user-authored subagents in ~/.pal/agents/. */
 export function listPersonalSubagents(): string[] {
   if (!existsSync(palAgentsStore())) return [];