portable-agent-layer 0.112.0 → 0.114.0-canary.1

package/README.md

@@ -77,7 +77,7 @@ pal cli status        # check your setup
 | `pal cli init` | Scaffold PAL home directory and install hooks |
 | `pal cli install` | Register hooks/skills for targets |
 | `pal cli uninstall` | Remove hooks/skills for targets |
-| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes |
+| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes. `--canary` installs the latest prerelease from the `canary` branch instead; auto-update always follows the stable release |
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |

package/assets/schema/pal-settings.schema.json

@@ -82,6 +82,10 @@
           "type": "boolean",
           "description": "Opt-in, off by default until 1.0. Send a turn back when it committed, made a branch, opened a PR or published an artifact without recording it in the work tree (pal cli work). Needs workTree."
         },
+        "workTreeDecisionGate": {
+          "type": "boolean",
+          "description": "Opt-in, off by default until 1.0. Send a turn back when a small-model check finds it settled a decision that no pal cli work decide recorded. One small-model call at the end of every turn. Needs workTree."
+        },
         "dueReminders": {
           "type": "boolean",
           "description": "Opt-in, off by default until 1.0. Due maintenance reminders (learning analysis, relationship reflect) with every prompt until a reply names their command; then quiet until the next day."

package/assets/templates/pal-settings.json

@@ -29,6 +29,7 @@
     "repoState": true,
     "workTree": false,
     "workTreeGate": false,
+    "workTreeDecisionGate": false,
     "dueReminders": false,
     "interactionAwareness": true,
     "reactionSampling": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.112.0",
+  "version": "0.114.0-canary.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -74,7 +74,9 @@
     "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"
+    "eval:rule-drafter:test": "bun eval/rule-drafter/test-set.ts",
+    "eval:decision": "bun eval/decision/score.ts validation",
+    "eval:decision:test": "bun eval/decision/score.ts test"
   },
   "lint-staged": {
     "*.ts": [

package/src/cli/index.ts

@@ -49,7 +49,7 @@ const tree = cliTree({
     process.exit(await install(resolveTargets(argv), argv));
   },
   uninstall: ({ argv }) => uninstall(argv),
-  update: () => update(),
+  update: ({ values }) => update(values.canary === true),
   export: ({ argv }) => exportState(argv),
   import: ({ argv }) => importState(argv),
   status: () => status(),
@@ -553,15 +553,23 @@ async function importState(args: string[]) {
   log.info("Run 'pal cli install' to re-register hooks.");
 }
 
-async function update() {
-  const { checkForUpdate, clearUpdateCache } = await import(
+async function update(canary: boolean) {
+  const { checkCanary, checkForUpdate, clearUpdateCache, isRepoMode } = await import(
     "../hooks/handlers/update-check"
   );
   const { reinstallInFreshProcess } = await import("./reinstall");
-  const { runUpdate } = await import("./update-flow");
+  const { CANARY_NEEDS_PACKAGE, runUpdate, updateCheck } = await import("./update-flow");
+  const check = updateCheck(canary, isRepoMode(), {
+    stable: () => checkForUpdate(true),
+    canary: checkCanary,
+  });
+  if (!check) {
+    log.error(CANARY_NEEDS_PACKAGE);
+    process.exit(1);
+  }
   process.exit(
     await runUpdate({
-      check: () => checkForUpdate(true),
+      check,
       reinstall: (env) => {
         clearUpdateCache();
         return reinstallInFreshProcess(process.argv[1], env);

package/src/cli/tree.ts

@@ -109,7 +109,17 @@ function adminCommands(admin: AdminHandlers): Record<string, Leaf | Group> {
       options: agentOptions("Uninstall from"),
       run: admin.uninstall,
     }),
-    update: leaf({ summary: "Update PAL (git pull or bun add -g)", run: admin.update }),
+    update: leaf({
+      summary: "Update PAL (git pull or bun add -g)",
+      options: {
+        canary: {
+          type: "boolean",
+          description:
+            "Install the latest canary prerelease instead of the stable release",
+        },
+      },
+      run: admin.update,
+    }),
     export: leaf({
       summary: "Export your state to a zip",
       args: "[path]",

package/src/cli/update-flow.ts

@@ -33,6 +33,21 @@ export interface UpdateSteps {
   run?: Run;
 }
 
+export const CANARY_NEEDS_PACKAGE =
+  "--canary installs from npm. A repo install follows its git checkout: check out the canary branch there instead.";
+
+type Check = UpdateSteps["check"];
+
+/** Null when --canary is asked of a repo install, which has no npm channel to follow. */
+export function updateCheck(
+  canary: boolean,
+  repoMode: boolean,
+  checks: { stable: Check; canary: Check }
+): Check | null {
+  if (!canary) return checks.stable;
+  return repoMode ? null : checks.canary;
+}
+
 /** `bun update -g` keeps the caret range, and on 0.x a caret allows only patch bumps. */
 export function downloadCommand(
   update: UpdateCache

package/src/cli/whats-new.ts

@@ -15,16 +15,22 @@ export interface WhatsNew {
 
 const SHOWN = 3;
 
-function parts(version: string): number[] {
-  return version.replace(/^v/, "").split(".").map(Number);
+function bare(version: string): string {
+  return version.replace(/^v/, "");
 }
 
 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;
+  return Bun.semver.order(bare(a), bare(b)) === 1;
+}
+
+function isPrerelease(version: string): boolean {
+  return bare(version).includes("-");
+}
+
+/** A stable release's notes already cover the canaries before it, so a stable update skips them. */
+function inRange(tag: string, from: string, to: string): boolean {
+  if (isPrerelease(tag) && !isPrerelease(to)) return false;
+  return newer(tag, from) && !newer(tag, to);
 }
 
 /** "* **rating:** confirm corrections ([abc](url))" reads "Confirm corrections". */
@@ -71,7 +77,7 @@ export function summarizeReleases(
   slug: string
 ): WhatsNew | null {
   const items = releases
-    .filter((r) => newer(r.tag_name, from) && !newer(r.tag_name, to))
+    .filter((r) => inRange(r.tag_name, from, to))
     .flatMap((r) => releaseNotes(r.body ?? ""));
   if (items.length === 0) return null;
   return {

package/src/hooks/StopOrchestrator.ts

@@ -64,7 +64,7 @@ try {
   logError("StopOrchestrator:adaptation-rules", err);
 }
 try {
-  const sendBack = stopWorkTree(payload);
+  const sendBack = await stopWorkTree(payload);
   if (sendBack) {
     process.stdout.write(stopBlockResponse(sendBack));
     process.exit(0);

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

@@ -139,12 +139,18 @@ export function isNewerRelease(latest: string, current: string): boolean {
   return Bun.semver.order(latest, current) === 1;
 }
 
-async function checkNpm(): Promise<UpdateCache> {
+/** latest is the stable release from main; canary is the prerelease from the canary branch. */
+export type Channel = "latest" | "canary";
+
+export async function checkNpm(
+  channel: Channel = "latest",
+  fetchImpl: typeof fetch = fetch
+): Promise<UpdateCache> {
   const current = getInstalledVersion();
 
   try {
-    const response = await fetch(
-      "https://registry.npmjs.org/portable-agent-layer/latest",
+    const response = await fetchImpl(
+      `https://registry.npmjs.org/portable-agent-layer/${channel}`,
       { signal: AbortSignal.timeout(5000) }
     );
 
@@ -170,6 +176,11 @@ async function checkNpm(): Promise<UpdateCache> {
   }
 }
 
+/** The canary check is never cached: the cache feeds the stable update notice. */
+export function checkCanary(fetchImpl: typeof fetch = fetch): Promise<UpdateCache> {
+  return checkNpm("canary", fetchImpl);
+}
+
 /** Run update check. Caches result. Use force=true to skip cache (e.g. for `pal cli update`). */
 export async function checkForUpdate(force = false): Promise<UpdateCache> {
   if (!force) {

package/src/hooks/lib/claim-check.ts

@@ -137,6 +137,14 @@ function isUserPrompt(entry: TranscriptLine): boolean {
   return text !== null && !isSystemText(text) && !isCodexInjectedContext(text);
 }
 
+export function promptThisTurn(lines: string[]): string | null {
+  const prompts = lines
+    .map(parsed)
+    .filter((e): e is TranscriptLine => e !== null && isUserPrompt(e));
+  const last = prompts.at(-1);
+  return last ? promptText(last) : null;
+}
+
 const ran = (input: unknown) => JSON.stringify(input ?? {});
 
 function callsIn(entry: TranscriptLine, tools: ReadonlySet<string>): string[] {

package/src/hooks/lib/decision-label.ts

@@ -0,0 +1,70 @@
+/**
+ * Whether a turn settled a decision. Code can see that a turn committed or
+ * opened a PR, but a decision is only words, so the work-tree gate asks the
+ * small model and sends the turn back when nothing was recorded.
+ */
+
+export interface DecisionLabel {
+  decision: boolean;
+  what: string;
+}
+
+const DECISION_SYSTEM = `You read one turn of a working session between a user and an AI assistant: the user's message and the end of the assistant's reply. Say whether the turn settled a decision.
+
+A decision is a choice between alternatives about the work that holds beyond this turn: a policy, a design, a direction, a scope (what is in, out, parked or dropped), or a standing way of working. Examples: "make them opt in for now", "we only track new posts, not past ones", "we don't need the predictor", "PRs go to canary from now on".
+
+A decision is often a few words that answer something open earlier: picking one of the options the assistant offered, keeping something where it is, saying something is not needed or should wait, changing how a thing behaves. Read the reply to see what the user's words settled; a short message can still be a decision.
+
+These are not decisions:
+- a go-ahead or approval of a plan or of the assistant's proposals as they stand ("go", "yes pls", "build all of them", "ok to both, build it"), unless it also picks between alternatives or changes the plan;
+- where the work goes (which branch or PR) and other bookkeeping the assistant handles;
+- a plain request for work ("fix CI", "push and open a PR", "plan it", "list our tasks"), including which step comes first;
+- a question, even one about what to decide or what was decided before;
+- a fact, a status report, or an idea floated for discussion;
+- a recommendation or proposal from the assistant that the user has not accepted;
+- small implementation choices the assistant makes while working.
+
+Most turns settle no decision. When unsure, answer false.
+
+Set what to the decision in under fifteen words, or to an empty string when there is none.`;
+
+const DECISION_SCHEMA = {
+  type: "object",
+  properties: {
+    decision: { type: "boolean" },
+    what: { type: "string" },
+  },
+  required: ["decision", "what"],
+  additionalProperties: false,
+} as const;
+
+const MESSAGE_MAX = 1500;
+const REPLY_END_MAX = 1500;
+
+export function decisionUser(message: string, reply: string) {
+  return `The user's message:\n<message>\n${message.slice(0, MESSAGE_MAX)}\n</message>\n\nThe end of the assistant's reply:\n<reply_end>\n${reply.slice(-REPLY_END_MAX)}\n</reply_end>`;
+}
+
+export function decisionRequest(message: string, reply: string, sessionId?: string) {
+  return {
+    system: DECISION_SYSTEM,
+    user: decisionUser(message, reply),
+    maxTokens: 100,
+    timeout: 60_000,
+    jsonSchema: DECISION_SCHEMA,
+    caller: "decision-label",
+    sessionId,
+  };
+}
+
+export function parseDecision(output: string | null | undefined): DecisionLabel | null {
+  if (!output) return null;
+  try {
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+    if (typeof parsed.decision !== "boolean") return null;
+    const what = typeof parsed.what === "string" ? parsed.what.trim() : "";
+    return { decision: parsed.decision, what: parsed.decision ? what : "" };
+  } catch {
+    return null;
+  }
+}

package/src/hooks/lib/models.ts

@@ -76,7 +76,11 @@ export function isFixedModelRoute(route: string): route is FixedModelRoute {
  * 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"]);
+const ANTHROPIC_ON_HAIKU_5_5 = new Set([
+  "rule-drafter",
+  "correction-kind",
+  "decision-label",
+]);
 
 function evaluatedModel(
   models: RouteModels,

package/src/hooks/lib/work-tree-gate.ts

@@ -4,8 +4,11 @@
  * nothing in the tree is sent back once to record it.
  */
 
-import { callsThisTurn, commandsThisTurn } from "./claim-check";
+import { callsThisTurn, commandsThisTurn, promptThisTurn } from "./claim-check";
 import { alreadySentBack, transcriptLines } from "./claim-log";
+import { type DecisionLabel, decisionRequest, parseDecision } from "./decision-label";
+import { hookFinalReply } from "./hook-turn";
+import { inference } from "./inference";
 import { sessionDir } from "./session-dir";
 import { isOptedIn } from "./settings";
 import type { StopTurnPayload } from "./stop";
@@ -14,6 +17,7 @@ import { attachGitProgress } from "./work-tree-git";
 import { renderPromptLine } from "./work-tree-render";
 
 const RECORDS_WORK_RE = /\bpal\s+cli\s+work\b/;
+const RECORDS_DECISION_RE = /\bpal\s+cli\s+work\s+decide\b/;
 
 const PRODUCERS: { what: string; re: RegExp }[] = [
   { what: "committed", re: /\bgit\s+commit\b/ },
@@ -34,8 +38,12 @@ function producedThisTurn(commands: string[], lines: string[]): string[] {
   return produced;
 }
 
+function whereWorkStands(scope: string): string {
+  return renderPromptLine(readTree(scope), false) ?? "Work: nothing recorded yet";
+}
+
 function sendBackReason(produced: string[], scope: string): string {
-  const where = renderPromptLine(readTree(scope), false) ?? "Work: nothing recorded yet";
+  const where = whereWorkStands(scope);
   return [
     `This turn ${produced.join(", ")} but recorded nothing in the work tree (${where}).`,
     'Record where the work stands with `pal cli work stopped "…"`, plus `decide` or `attach` where they fit;',
@@ -56,11 +64,47 @@ export function workTreeSendBack(
   return produced.length > 0 ? sendBackReason(produced, scopeOf(cwd)) : null;
 }
 
+type LabelDecision = (message: string, reply: string) => Promise<DecisionLabel | null>;
+
+async function labelWithInference(message: string, reply: string) {
+  const result = await inference(decisionRequest(message, reply));
+  return result.success ? parseDecision(result.output) : null;
+}
+
+function decisionReason(what: string, scope: string): string {
+  return [
+    `This turn settled a decision (${what}) but recorded none in the work tree (${whereWorkStands(scope)}).`,
+    'Record it with `pal cli work decide "…"`; if no node fits, open one first with `pal cli work open "…"`.',
+  ].join(" ");
+}
+
+export async function decisionSendBack(
+  payload: StopTurnPayload,
+  lines: string[],
+  cwd: string,
+  label: LabelDecision = labelWithInference
+): Promise<string | null> {
+  if (!isOptedIn("workTree") || !isOptedIn("workTreeDecisionGate")) return null;
+  if (alreadySentBack(payload)) return null;
+  const commands = commandsThisTurn(lines);
+  if (commands === null || commands.some((c) => RECORDS_DECISION_RE.test(c))) return null;
+  const message = promptThisTurn(lines);
+  const reply = hookFinalReply(payload);
+  if (!message || !reply) return null;
+  const decided = await label(message, reply);
+  return decided?.decision ? decisionReason(decided.what, scopeOf(cwd)) : null;
+}
+
 /** The reason to send the turn back with, or null after attaching what git moved. */
-export function stopWorkTree(payload: StopTurnPayload | null): string | null {
+export async function stopWorkTree(
+  payload: StopTurnPayload | null
+): Promise<string | null> {
   if (!payload || !isOptedIn("workTree")) return null;
   const cwd = sessionDir();
-  const sendBack = workTreeSendBack(payload, transcriptLines(payload), cwd);
+  const lines = transcriptLines(payload);
+  const sendBack =
+    workTreeSendBack(payload, lines, cwd) ??
+    (await decisionSendBack(payload, lines, cwd));
   if (sendBack) return sendBack;
   attachGitProgress(cwd);
   return null;