portable-agent-layer 0.61.4 → 0.62.1

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

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/assets/schema/pal-settings.schema.json",
+  "title": "PAL settings",
+  "description": "Configuration for the Portable Agent Layer. Lives at ~/.pal/memory/pal-settings.json. All sections are optional; PAL falls back to defaults for anything absent.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference — enables editor autocomplete, validation, and hover docs."
+    },
+    "identity": {
+      "type": "object",
+      "description": "Who the assistant is and who it serves.",
+      "additionalProperties": false,
+      "properties": {
+        "ai": {
+          "type": "object",
+          "description": "The assistant's persona.",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "description": "Short name (e.g. the name you call the assistant)." },
+            "fullName": { "type": "string", "description": "Full/formal name." },
+            "displayName": { "type": "string", "description": "Uppercase label used in headers." },
+            "catchphrase": { "type": "string", "description": "Greeting line. '{name}' is substituted with the ai.name value." }
+          }
+        },
+        "principal": {
+          "type": "object",
+          "description": "The human the assistant works for.",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "description": "The principal's name." },
+            "timezone": { "type": "string", "description": "IANA timezone (e.g. Europe/Budapest)." }
+          }
+        }
+      }
+    },
+    "loadAtStartup": {
+      "type": "object",
+      "description": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
+      "additionalProperties": false,
+      "properties": {
+        "files": {
+          "type": "array",
+          "description": "Absolute or PAL-relative file paths to inject at session start.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "dynamicContext": {
+      "type": "object",
+      "description": "Dynamic context sections injected at session start. Set any key to false to disable it; absent keys default to enabled.",
+      "additionalProperties": { "type": "boolean" },
+      "properties": {
+        "wisdom": { "type": "boolean", "description": "Crystallized wisdom principles." },
+        "opinions": { "type": "boolean", "description": "Tracked user opinions." },
+        "relationship": { "type": "boolean", "description": "Recent relationship notes." },
+        "learningDigest": { "type": "boolean", "description": "Lessons-from-failures digest." },
+        "failurePatterns": { "type": "boolean", "description": "Recurring failure patterns." },
+        "projectHistory": { "type": "boolean", "description": "Per-project session history." },
+        "projects": { "type": "boolean", "description": "Active projects list." },
+        "sessionIntelligence": { "type": "boolean", "description": "Rating trends and session signals." },
+        "handoff": { "type": "boolean", "description": "Handoff note from the previous session." },
+        "selfModel": { "type": "boolean", "description": "The assistant's self-model synthesis." },
+        "contextualSteering": { "type": "boolean", "description": "Prompt-time steering self-checks (see the steering section)." },
+        "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
+      }
+    },
+    "attribution": {
+      "type": "object",
+      "description": "Git co-author attribution opt-in.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Add the PAL co-author trailer to commits." },
+        "decided": { "type": "boolean", "description": "Gates the one-time attribution prompt." }
+      }
+    },
+    "steering": {
+      "type": "object",
+      "description": "Contextual steering: PAL injects a short self-check into your prompt when it matches a task type. Toggle the whole feature via dynamicContext.contextualSteering.",
+      "additionalProperties": false,
+      "properties": {
+        "disable": {
+          "type": "array",
+          "description": "Shipped steering rules to suppress, by tag.",
+          "items": {
+            "type": "string",
+            "enum": ["debugging", "destructive", "refactor", "planning", "testing", "committing", "secrets"]
+          },
+          "uniqueItems": true
+        },
+        "rules": {
+          "type": "array",
+          "description": "Personal steering rules appended to the shipped set. A malformed entry (missing field or bad regex) is skipped, never fatal.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["tag", "pattern", "snippet"],
+            "properties": {
+              "tag": { "type": "string", "description": "Short identifier for this rule (also used to dedupe matches)." },
+              "pattern": { "type": "string", "description": "JavaScript regex source, matched case-insensitively against the prompt." },
+              "snippet": { "type": "string", "description": "The self-check text injected when the pattern matches." }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/assets/templates/hooks.copilot.json

@@ -21,6 +21,10 @@
       {
         "type": "command",
         "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      },
+      {
+        "type": "command",
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "agentStop": [

package/assets/templates/hooks.cursor.json

@@ -21,6 +21,10 @@
       {
         "type": "command",
         "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      },
+      {
+        "type": "command",
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "beforeShellExecution": [

package/assets/templates/pal-settings.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/assets/schema/pal-settings.schema.json",
   "identity": {
     "ai": {
       "name": "",
@@ -12,11 +13,9 @@
     }
   },
   "loadAtStartup": {
-    "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
     "files": []
   },
   "dynamicContext": {
-    "_docs": "Dynamic context sections injected at session start. Set to false to disable.",
     "wisdom": true,
     "opinions": true,
     "relationship": true,
@@ -26,6 +25,12 @@
     "projects": true,
     "sessionIntelligence": true,
     "handoff": true,
-    "selfModel": true
+    "selfModel": true,
+    "contextualSteering": true,
+    "steeringTestReport": false
+  },
+  "steering": {
+    "disable": [],
+    "rules": []
   }
 }

package/assets/templates/settings.claude.json

@@ -18,6 +18,20 @@
       "Bash(stat //*)",
       "Bash(readlink //*)",
       "Bash(lsof *)",
+      "Bash(rtk read *)",
+      "Bash(rtk ls *)",
+      "Bash(rtk tree *)",
+      "Bash(rtk find *)",
+      "Bash(rtk grep *)",
+      "Bash(rtk rg *)",
+      "Bash(rtk wc *)",
+      "Bash(rtk diff *)",
+      "Bash(rtk json *)",
+      "Bash(rtk log *)",
+      "Bash(rtk deps *)",
+      "Bash(rtk env *)",
+      "Bash(rtk smart *)",
+      "Bash(rtk gain *)",
       "Bash(bun ~/.pal/skills/*/tools/*.ts *)",
       "Bash(bun ~/.pal/tools/*.ts *)",
       "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)"
@@ -108,6 +122,15 @@
             "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

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

package/src/cli/index.ts

@@ -622,6 +622,13 @@ function nodeInstallHint(): string {
   return "install Node ≥ 22.6 (see https://nodejs.org or your package manager)";
 }
 
+function rtkInstallHint(): string {
+  if (process.platform === "win32")
+    return "download rtk.exe from https://github.com/rtk-ai/rtk/releases and add it to PATH";
+  if (process.platform === "darwin") return "`brew install rtk`";
+  return "`curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh`";
+}
+
 function checkHookHealth(home: string): HookHealth {
   const stateDir = resolve(home, "memory", "state");
   // Read current + all rotated logs (`.1`..`.5`) + legacy `.prev` so a recent
@@ -671,6 +678,7 @@ interface DoctorResult {
   cursor: ToolCheck;
   copilot: ToolCheck;
   codex: ToolCheck;
+  rtk: ToolCheck;
   hasAgent: boolean;
 }
 
@@ -684,6 +692,7 @@ function doctor(silent = false): DoctorResult {
       cursor: { name: "cursor", available: true },
       copilot: { name: "copilot", available: true },
       codex: { name: "codex", available: true },
+      rtk: { name: "rtk", available: true },
       hasAgent: true,
     };
   }
@@ -694,6 +703,7 @@ function doctor(silent = false): DoctorResult {
   const cursor = checkTool("cursor");
   const copilot = checkTool("copilot", ["version"]);
   const codex = checkTool("codex");
+  const rtk = checkTool("rtk");
   const hasAgent =
     claude.available ||
     opencode.available ||
@@ -751,6 +761,11 @@ function doctor(silent = false): DoctorResult {
       : fail(
           "Playwright Chromium — not found (run 'pal cli install' or 'bunx playwright install chromium')"
         );
+    rtk.available
+      ? ok(rtk.version || "rtk")
+      : info(
+          `rtk — not installed (optional; enables Bash output compression — ${rtkInstallHint()})`
+        );
 
     console.log("");
     log.info("PAL state");
@@ -1023,7 +1038,7 @@ function doctor(silent = false): DoctorResult {
     console.log("");
   }
 
-  return { bun, claude, opencode, cursor, copilot, codex, hasAgent };
+  return { bun, claude, opencode, cursor, copilot, codex, rtk, hasAgent };
 }
 
 // ── Commands ──

package/src/hooks/RtkWrap.ts

@@ -0,0 +1,52 @@
+/**
+ * Hook: PreToolUse — transparently wraps Bash commands in `rtk` to compress
+ * tool output before it reaches the model's context.
+ *
+ * PAL owns the wiring + presence-gating; rtk owns the rewrite. We do NOT
+ * reimplement rtk's selectivity or per-agent JSON shape — we forward the hook's
+ * stdin to `rtk hook <agent>` and pass its stdout straight back. rtk emits the
+ * correct rewrite object for each agent (Claude/Cursor/Copilot all differ), or
+ * nothing when a command isn't worth rewriting.
+ *
+ * Fail-open by construction: if rtk isn't installed, the agent can't rewrite,
+ * or anything throws, we emit nothing and exit 0 — the original command runs
+ * unchanged. rtk absent must never block or alter a Bash call.
+ *
+ * Codex (allow/deny only) and opencode (plugin path) have no `rtk hook`
+ * subcommand and are handled elsewhere — this hook no-ops for them.
+ */
+
+import { getActiveAgent } from "./lib/agent";
+import { findBinaryOnPath } from "./lib/which";
+
+const RTK_HOOK_SUBCOMMAND: Partial<Record<ReturnType<typeof getActiveAgent>, string>> = {
+  claude: "claude",
+  cursor: "cursor",
+  copilot: "copilot",
+};
+
+async function run(): Promise<void> {
+  const subcommand = RTK_HOOK_SUBCOMMAND[getActiveAgent()];
+  if (!subcommand) return; // codex/opencode — no rtk hook processor
+
+  const rtk = findBinaryOnPath("rtk");
+  if (!rtk) return; // fail-open: rtk not installed → command runs unchanged
+
+  const stdin = await Bun.stdin.text();
+  const proc = Bun.spawn([rtk, "hook", subcommand], {
+    stdin: Buffer.from(stdin),
+    stdout: "pipe",
+    stderr: "ignore", // drop rtk's "no hook installed" stderr nag
+  });
+  const out = await new Response(proc.stdout).text();
+  await proc.exited;
+  if (proc.exitCode === 0 && out) {
+    process.stdout.write(out);
+  }
+}
+
+try {
+  await run();
+} catch {
+  // Fail open — emit nothing, allow the original command.
+}

package/src/hooks/UserPromptOrchestrator.ts

@@ -7,7 +7,7 @@
  *  - session-name: generate 4-word session headline on first prompt
  */
 
-import { injectRetrieval } from "./handlers/inject-retrieval";
+import { injectPromptContext } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
 import { logDebug, logError, logPromptSnapshot } from "./lib/log";
@@ -30,8 +30,8 @@ logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)
 if (!input?.prompt) process.exit(0);
 
 const sessionId = input.session_id ?? input.sessionId ?? input.conversation_id;
-const retrieval = await injectRetrieval(input.prompt);
-logPromptSnapshot(input.prompt, retrieval);
+const injected = await injectPromptContext(input.prompt);
+logPromptSnapshot(input.prompt, injected);
 
 const results = await Promise.allSettled([
   captureRating(input.prompt, sessionId),

package/src/hooks/handlers/inject-retrieval.ts

@@ -12,6 +12,7 @@ import { logDebug, logError } from "../lib/log";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
+import { getSteeringReminder } from "../lib/steering";
 
 const TIMEOUT_MS = 250;
 
@@ -51,12 +52,11 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
   return result.reminder;
 }
 
-/** Write retrieval reminder to stdout in the correct format for the current agent.
+/** Write a reminder to stdout in the correct format for the current agent.
  *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON.
- *  Returns the reminder string that was injected, or null if nothing was injected. */
-export async function injectRetrieval(prompt: string): Promise<string | null> {
-  const reminder = await getRetrievalReminder(prompt);
-  if (!reminder) return null;
+ *  MUST be called at most once per hook run — Cursor/Codex expect a single JSON
+ *  object on stdout, so all prompt-time context is merged before this call. */
+function writeForAgent(reminder: string): void {
   if (isCursor()) {
     process.stdout.write(JSON.stringify({ additional_context: reminder }));
   } else if (isCodex()) {
@@ -71,5 +71,17 @@ export async function injectRetrieval(prompt: string): Promise<string | null> {
   } else {
     process.stdout.write(`${reminder}\n`);
   }
-  return reminder;
+}
+
+/** Gather all prompt-time context — prior-lesson retrieval + contextual steering —
+ *  merge into a single payload, and do the one per-agent write. Returns the combined
+ *  reminder that was injected, or null if there was nothing to inject. */
+export async function injectPromptContext(prompt: string): Promise<string | null> {
+  const retrieval = await getRetrievalReminder(prompt);
+  const steering = getSteeringReminder(prompt);
+  const parts = [steering, retrieval].filter((p): p is string => Boolean(p));
+  if (parts.length === 0) return null;
+  const combined = parts.join("\n\n");
+  writeForAgent(combined);
+  return combined;
 }

package/src/hooks/lib/inference.ts

@@ -20,8 +20,7 @@
  * yet wired and currently fall through to the API path.
  */
 
-import { accessSync, constants, existsSync } from "node:fs";
-import { basename, delimiter, resolve as resolvePath } from "node:path";
+import { basename } from "node:path";
 import {
   getActiveAgent,
   isClaude,
@@ -33,6 +32,7 @@ import {
 import { logDebug } from "./log";
 import { HAIKU_MODEL } from "./models";
 import { buildSpawnGuardEnv, getInferenceDepth, SPAWN_GUARD_ENV } from "./spawn-guard";
+import { findBinaryOnPath } from "./which";
 
 export function hasApiKey(): boolean {
   return !!process.env.PAL_ANTHROPIC_API_KEY;
@@ -213,45 +213,6 @@ let opencodeBinaryCache: string | null | undefined;
 let copilotBinaryCache: string | null | undefined;
 let cursorBinaryCache: string | null | undefined;
 
-/**
- * Resolve a binary on PATH to its full absolute path.
- *
- * Manual PATH walk (instead of Bun.which / `which` subprocess) because:
- * 1. Ubuntu 24.04 dropped the `which` binary entirely.
- * 2. Windows has no `which` at all.
- * 3. Bun.which snapshots PATH at startup and ignores mid-test mutations.
- * 4. Bun.spawn on Windows is inconsistent at resolving PATHEXT for bare
- *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
- *
- * Returns the resolved absolute path or null.
- */
-function findBinaryOnPath(name: string): string | null {
-  const PATH = process.env.PATH;
-  if (!PATH) return null;
-  const exts =
-    process.platform === "win32"
-      ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
-      : [""];
-  for (const dir of PATH.split(delimiter)) {
-    if (!dir) continue;
-    for (const ext of exts) {
-      const candidate = resolvePath(dir, name + ext);
-      try {
-        if (process.platform === "win32") {
-          // Windows has no executable bit — existence in PATHEXT is enough.
-          if (existsSync(candidate)) return candidate;
-        } else {
-          accessSync(candidate, constants.X_OK);
-          return candidate;
-        }
-      } catch {
-        /* not here — try next */
-      }
-    }
-  }
-  return null;
-}
-
 function getClaudeBinary(): string | null {
   if (claudeBinaryCache !== undefined) return claudeBinaryCache;
   claudeBinaryCache = findBinaryOnPath("claude");

package/src/hooks/lib/models.ts

@@ -26,17 +26,24 @@ export function flagshipAuthorModel(agent: AgentType): string | undefined {
   return FLAGSHIP_AUTHOR_MODEL[agent];
 }
 
+export interface ModelPricing {
+  input: number;
+  output: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+}
+
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+}
+
 /** Pricing per million tokens (USD) — from https://platform.claude.com/docs/en/about-claude/pricing */
-export const MODEL_PRICING: Record<
-  string,
-  {
-    input: number;
-    output: number;
-    cacheWrite5m: number;
-    cacheWrite1h: number;
-    cacheRead: number;
-  }
-> = {
+export const MODEL_PRICING: Record<string, ModelPricing> = {
   [HAIKU_MODEL]: {
     input: 1,
     output: 5,
@@ -51,6 +58,13 @@ export const MODEL_PRICING: Record<
     cacheWrite1h: 20,
     cacheRead: 1,
   },
+  "claude-opus-5": {
+    input: 5,
+    output: 25,
+    cacheWrite5m: 6.25,
+    cacheWrite1h: 10,
+    cacheRead: 0.5,
+  },
   "claude-opus-4-8": {
     input: 5,
     output: 25,
@@ -72,6 +86,13 @@ export const MODEL_PRICING: Record<
     cacheWrite1h: 10,
     cacheRead: 0.5,
   },
+  "claude-opus-4-5": {
+    input: 5,
+    output: 25,
+    cacheWrite5m: 6.25,
+    cacheWrite1h: 10,
+    cacheRead: 0.5,
+  },
   // Claude Sonnet 5 — introductory pricing through 2026-08-31; standard (3/15/3.75/6/0.30) applies from 2026-09-01.
   "claude-sonnet-5": {
     input: 2,
@@ -95,3 +116,37 @@ export const MODEL_PRICING: Record<
     cacheRead: 0.3,
   },
 };
+
+function longestPrefixKey(model: string): string | null {
+  let best: string | null = null;
+  for (const key of Object.keys(MODEL_PRICING)) {
+    if (model.startsWith(key) && (best === null || key.length > best.length)) best = key;
+  }
+  return best;
+}
+
+/**
+ * Rates for a model ID. Transcripts carry variants of the same model — dated
+ * (`claude-opus-5-20260115`) and context-tagged (`claude-opus-5[1m]`) — so an
+ * exact miss falls back to the longest table key the ID starts with.
+ */
+export function pricingFor(model: string): ModelPricing | null {
+  const exact = MODEL_PRICING[model];
+  if (exact) return exact;
+  const prefix = longestPrefixKey(model);
+  return prefix ? MODEL_PRICING[prefix] : null;
+}
+
+/** USD cost of a token usage record. Unpriced models bill as 0. */
+export function costOfUsage(model: string, usage: TokenUsage): number {
+  const p = pricingFor(model);
+  if (!p) return 0;
+  return (
+    (usage.input * p.input +
+      usage.output * p.output +
+      usage.cacheWrite5m * p.cacheWrite5m +
+      usage.cacheWrite1h * p.cacheWrite1h +
+      usage.cacheRead * p.cacheRead) /
+    1_000_000
+  );
+}

package/src/hooks/lib/settings.ts

@@ -25,6 +25,11 @@ export interface PalSettingsData {
   dynamicContext?: Record<string, boolean>;
   /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
   attribution?: { enabled?: boolean; decided?: boolean };
+  /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
+  steering?: {
+    disable?: string[];
+    rules?: Array<{ tag: string; pattern: string; snippet: string }>;
+  };
   [key: string]: unknown;
 }