portable-agent-layer 0.36.0 → 0.38.0

package/src/targets/lib.ts

@@ -81,7 +81,11 @@ type Settings = Record<string, unknown> & {
 export function loadSettingsTemplate(templatePath: string, pkgRoot: string): Settings {
   const raw = readFileSync(templatePath, "utf-8");
   const resolved = raw.replaceAll("{{PKG_ROOT}}", pkgRoot);
-  return JSON.parse(resolved) as Settings;
+  try {
+    return JSON.parse(resolved) as Settings;
+  } catch (e) {
+    throw new Error(`Failed to parse settings template at ${templatePath}: ${e}`);
+  }
 }
 
 /**
@@ -95,7 +99,7 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
 
   // Merge hooks (deduplicate by command)
   if (template.hooks) {
-    if (!result.hooks) result.hooks = {};
+    result.hooks ??= {};
     for (const [event, entries] of Object.entries(template.hooks)) {
       const current = result.hooks[event] ?? [];
       for (const entry of entries) {
@@ -110,8 +114,8 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
 
   // Merge permissions.allow (deduplicate)
   if (template.permissions?.allow) {
-    if (!result.permissions) result.permissions = {};
-    if (!result.permissions.allow) result.permissions.allow = [];
+    result.permissions ??= {};
+    result.permissions.allow ??= [];
     for (const perm of template.permissions.allow) {
       if (!result.permissions.allow.includes(perm)) {
         result.permissions.allow.push(perm);
@@ -184,7 +188,11 @@ export function loadCursorHooksTemplate(
 ): CursorHooks {
   const raw = readFileSync(templatePath, "utf-8");
   const resolved = raw.replaceAll("{{PKG_ROOT}}", pkgRoot);
-  return JSON.parse(resolved) as CursorHooks;
+  try {
+    return JSON.parse(resolved) as CursorHooks;
+  } catch (e) {
+    throw new Error(`Failed to parse Cursor hooks template at ${templatePath}: ${e}`);
+  }
 }
 
 /**
@@ -198,7 +206,7 @@ export function mergeCursorHooks(
   const result: CursorHooks = { ...existing, version: existing.version ?? 1 };
 
   if (template.hooks) {
-    if (!result.hooks) result.hooks = {};
+    result.hooks ??= {};
     for (const [event, entries] of Object.entries(template.hooks)) {
       const current = result.hooks[event] ?? [];
       for (const entry of entries) {
@@ -241,6 +249,103 @@ export function unmergeCursorHooks(
   return result;
 }
 
+// --- Codex hooks (nested group format, distinct from Cursor's flat format) ---
+
+type CodexHookCommand = { type: string; command: string; timeout?: number };
+type CodexHookGroup = { matcher?: string; hooks: CodexHookCommand[] };
+type CodexHooks = { hooks?: Record<string, CodexHookGroup[]> };
+
+/** Strip leading env-var assignments so "PAL_AGENT=x bun run ..." → "bun run ..." */
+function canonicalCmd(cmd: string): string {
+  return cmd.replace(/^(?:\w+=\S+\s+)+/, "");
+}
+
+export function loadCodexHooksTemplate(
+  templatePath: string,
+  pkgRoot: string
+): CodexHooks {
+  const raw = readFileSync(templatePath, "utf-8");
+  const resolved = raw.replaceAll("{{PKG_ROOT}}", pkgRoot);
+  try {
+    return JSON.parse(resolved) as CodexHooks;
+  } catch (e) {
+    throw new Error(`Failed to parse Codex hooks template at ${templatePath}: ${e}`);
+  }
+}
+
+/** Merge PAL hooks into an existing Codex hooks.json. Deduplicates by canonical command path. */
+export function mergeCodexHooks(existing: CodexHooks, template: CodexHooks): CodexHooks {
+  const result: CodexHooks = { ...existing };
+  if (!template.hooks) return result;
+  result.hooks ??= {};
+
+  // Collect canonical paths of PAL template commands so we can evict stale variants
+  const palCanonical = new Set(
+    Object.values(template.hooks).flatMap((groups) =>
+      groups.flatMap((g) => g.hooks.map((h) => canonicalCmd(h.command)))
+    )
+  );
+
+  // Strip any existing entries (nested or flat) whose canonical path matches a PAL command
+  for (const event of Object.keys(result.hooks)) {
+    result.hooks[event] = (result.hooks[event] ?? [])
+      .map((g) => {
+        const flat = g as unknown as CodexHookCommand;
+        if (!g.hooks && flat.command && palCanonical.has(canonicalCmd(flat.command))) {
+          return null;
+        }
+        const filtered = (g.hooks ?? []).filter(
+          (h) => !palCanonical.has(canonicalCmd(h.command))
+        );
+        return filtered.length > 0 ? { ...g, hooks: filtered } : null;
+      })
+      .filter((g): g is CodexHookGroup => g !== null);
+    if (result.hooks[event].length === 0) delete result.hooks[event];
+  }
+
+  // Add fresh template entries
+  for (const [event, groups] of Object.entries(template.hooks)) {
+    const current = result.hooks[event] ?? [];
+    for (const group of groups) current.push(group);
+    result.hooks[event] = current;
+  }
+  return result;
+}
+
+/** Remove PAL hooks from an existing Codex hooks.json. Preserves user hooks. */
+export function unmergeCodexHooks(
+  existing: CodexHooks,
+  template: CodexHooks
+): CodexHooks {
+  const result: CodexHooks = { ...existing };
+  if (!template.hooks || !result.hooks) return result;
+
+  // Match by canonical path so prefix variants (PAL_AGENT=codex, etc.) are all removed
+  const palCanonical = new Set(
+    Object.values(template.hooks).flatMap((groups) =>
+      groups.flatMap((g) => g.hooks.map((h) => canonicalCmd(h.command)))
+    )
+  );
+
+  for (const event of Object.keys(result.hooks)) {
+    result.hooks[event] = (result.hooks[event] ?? [])
+      .map((g) => {
+        const flat = g as unknown as CodexHookCommand;
+        if (!g.hooks && flat.command && palCanonical.has(canonicalCmd(flat.command))) {
+          return null;
+        }
+        const filtered = (g.hooks ?? []).filter(
+          (h) => !palCanonical.has(canonicalCmd(h.command))
+        );
+        return filtered.length > 0 ? { ...g, hooks: filtered } : null;
+      })
+      .filter((g): g is CodexHookGroup => g !== null);
+    if (result.hooks[event].length === 0) delete result.hooks[event];
+  }
+  if (Object.keys(result.hooks).length === 0) delete result.hooks;
+  return result;
+}
+
 // --- TELOS scaffolding ---
 
 /** Copy template files into telos/ without overwriting existing ones */
@@ -275,6 +380,21 @@ export function scaffoldPalSettings(): void {
     copyFileSync(src, dst);
     log.info("Created pal-settings.json from template");
   }
+
+  // Strip deprecated loadAtStartup.files entries from existing installs.
+  // mergeSettings only adds, never removes — deprecated entries persist indefinitely otherwise.
+  try {
+    const raw = JSON.parse(readFileSync(dst, "utf-8"));
+    const files: string[] = raw?.loadAtStartup?.files ?? [];
+    const cleaned = files.filter((f: string) => !f.endsWith("PROJECTS.md"));
+    if (cleaned.length !== files.length) {
+      raw.loadAtStartup.files = cleaned;
+      writeFileSync(dst, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+      log.info("Removed deprecated PROJECTS.md from loadAtStartup.files");
+    }
+  } catch {
+    /* non-fatal — malformed settings left as-is */
+  }
 }
 
 // --- PAL docs (modular context routing files) ---
@@ -492,14 +612,14 @@ function extractAgentForPlatform(content: string, platform: AgentPlatform): stri
   for (const line of frontmatter.split("\n")) {
     if (!line.trim()) continue;
 
-    const platformMatch = line.match(/^(claude|opencode|cursor):\s*$/);
+    const platformMatch = new RegExp(/^(claude|opencode|cursor):\s*$/).exec(line);
     if (platformMatch) {
       currentPlatform = platformMatch[1] as AgentPlatform;
       continue;
     }
 
     if (currentPlatform) {
-      if (line.match(/^ {2}/)) {
+      if (new RegExp(/^ {2}/).exec(line)) {
         platformLines[currentPlatform].push(line.slice(2)); // un-indent one level
         continue;
       }
@@ -580,9 +700,15 @@ export function removeAgentsFromCopilot(copilotAgentsDir: string): string[] {
 
 /** Load and resolve the Copilot hooks template, substituting PKG_ROOT */
 export function loadCopilotHooksTemplate(templatePath: string, pkgRoot: string): unknown {
-  return JSON.parse(
-    readFileSync(templatePath, "utf-8").replaceAll("{{PKG_ROOT}}", pkgRoot)
+  const resolved = readFileSync(templatePath, "utf-8").replaceAll(
+    "{{PKG_ROOT}}",
+    pkgRoot
   );
+  try {
+    return JSON.parse(resolved);
+  } catch (e) {
+    throw new Error(`Failed to parse Copilot hooks template at ${templatePath}: ${e}`);
+  }
 }
 
 // --- Skill Index ---
@@ -604,7 +730,7 @@ function extractTriggers(description: string): string[] {
   // Extract "Use when ..." phrases and key terms
   const triggers = new Set<string>();
 
-  const useWhen = description.match(/Use when\s+(.+?)(?:\.|$)/i);
+  const useWhen = new RegExp(/Use when\s+(.+?)(?:\.|$)/i).exec(description);
   if (useWhen) {
     const words = useWhen[1]
       .toLowerCase()
@@ -647,12 +773,12 @@ export function generateSkillIndex(): number {
 
     try {
       const content = readFileSync(skillMd, "utf-8");
-      const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      const fmMatch = new RegExp(/^---\n([\s\S]*?)\n---/).exec(content);
       if (!fmMatch) continue;
 
       const fm = fmMatch[1];
-      const nameMatch = fm.match(/^name:\s*(.+)$/m);
-      const descMatch = fm.match(/^description:\s*"?(.+?)"?\s*$/m);
+      const nameMatch = new RegExp(/^name:\s*(.+)$/m).exec(fm);
+      const descMatch = new RegExp(/^description:\s*"?(.+?)"?\s*$/m).exec(fm);
       if (!nameMatch) continue;
 
       const skillName = nameMatch[1].trim();

package/src/targets/opencode/plugin.ts

@@ -34,6 +34,9 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
   const { captureRating } = await lib<typeof import("../../hooks/handlers/rating")>(
     "../handlers/rating.ts"
   );
+  const { getRetrievalReminder } = await lib<
+    typeof import("../../hooks/handlers/inject-retrieval")
+  >("../handlers/inject-retrieval.ts");
 
   function partsToText(parts: Array<Record<string, unknown>>): string {
     return parts
@@ -120,17 +123,25 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
 
     // --- Capture ratings + session naming from user messages (shared handlers) ---
     "chat.message": async (input, output) => {
-      const text =
-        output.parts
-          ?.filter((p) => p.type === "text")
-          .map((p) => p.text || "")
-          .join(" ") ?? "";
-
-      if (text.trim()) {
-        await Promise.allSettled([
-          captureRating(text, input.sessionID),
-          captureSessionName(text, input.sessionID),
-        ]);
+      const text = partsToText(output.parts ?? []);
+      if (!text.trim()) return;
+
+      const [, , retrievalResult] = await Promise.allSettled([
+        captureRating(text, input.sessionID),
+        captureSessionName(text, input.sessionID),
+        getRetrievalReminder(text),
+      ]);
+
+      if (retrievalResult.status === "fulfilled" && retrievalResult.value) {
+        const injected = {
+          id: `pal-retrieval-${Date.now()}`,
+          sessionID: input.sessionID,
+          messageID: input.messageID ?? `pal-msg-${Date.now()}`,
+          type: "text" as const,
+          text: retrievalResult.value,
+          synthetic: true,
+        };
+        output.parts = [injected, ...(output.parts ?? [])];
       }
     },
 

package/src/tools/agent/algorithm-reflect.ts

@@ -40,7 +40,7 @@ function reflectionsPath(): string {
   return resolve(dir, "algorithm-reflections.jsonl");
 }
 
-export function appendReflection(reflection: AlgorithmReflection): {
+function appendReflection(reflection: AlgorithmReflection): {
   success: boolean;
   message: string;
   path: string;

package/src/tools/agent/analyze.ts

@@ -34,25 +34,26 @@ export function printReport(result: AnalysisResult): void {
 
   if (result.ratings) {
     const r = result.ratings;
-    const avgColor = r.average >= 7 ? c.green : r.average <= 4 ? c.red : c.yellow;
+    const lowOrMid = r.average <= 4 ? c.red : c.yellow;
+    const avgColor = r.average >= 7 ? c.green : lowOrMid;
+    const ratingStr = `${r.average.toFixed(1)}/10`;
+    const lowStr = `Low (≤4): ${r.low.count}`;
+    const highStr = `High (≥7): ${r.high.count}`;
     console.log(
-      `\n  ${c.bold("Ratings:")} ${avgColor(`${r.average.toFixed(1)}/10`)} avg (${r.total} total)`
-    );
-    console.log(
-      `  ${c.red(`Low (≤4): ${r.low.count}`)} | ${c.green(`High (≥7): ${r.high.count}`)}`
+      `\n  ${c.bold("Ratings:")} ${avgColor(ratingStr)} avg (${r.total} total)`
     );
+    console.log(`  ${c.red(lowStr)} | ${c.green(highStr)}`);
   }
 
   if (result.candidates.length > 0) {
-    console.log(
-      `\n  ${c.bold(c.green(`Graduation Report — ${result.candidates.length} pattern(s) detected`))}\n`
-    );
+    const graduationHeader = `Graduation Report — ${result.candidates.length} pattern(s) detected`;
+    console.log(`\n  ${c.bold(c.green(graduationHeader))}\n`);
     console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
 
     for (const candidate of result.candidates) {
-      console.log(
-        `  ${c.cyan(`[${candidate.domain}]`)} ${c.bold(`${candidate.entries.length}x`)} occurrences`
-      );
+      const domain = `[${candidate.domain}]`;
+      const count = `${candidate.entries.length}x`;
+      console.log(`  ${c.cyan(domain)} ${c.bold(count)} occurrences`);
       console.log("");
 
       for (const entry of candidate.entries) {
@@ -72,9 +73,8 @@ export function printReport(result: AnalysisResult): void {
       }
 
       console.log("");
-      console.log(
-        `  Target frame: ${c.magenta(`memory/wisdom/frames/${candidate.domain}.md`)}`
-      );
+      const framePath = `memory/wisdom/frames/${candidate.domain}.md`;
+      console.log(`  Target frame: ${c.magenta(framePath)}`);
       console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
     }
   }
@@ -82,9 +82,9 @@ export function printReport(result: AnalysisResult): void {
   if (result.emerging.length > 0) {
     console.log(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
     for (const group of result.emerging) {
-      console.log(
-        `  ${c.cyan(`[${group.domain}]`)} ${c.bold(`${group.entries.length}x`)}`
-      );
+      const domain = `[${group.domain}]`;
+      const count = `${group.entries.length}x`;
+      console.log(`  ${c.cyan(domain)} ${c.bold(count)}`);
       for (const entry of group.entries) {
         const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
         const tag =
@@ -154,4 +154,4 @@ async function run() {
   printReport(result);
 }
 
-if (import.meta.main) run();
+if (import.meta.main) await run();

package/src/tools/agent/handoff-note.ts

@@ -43,7 +43,7 @@ function writeHandoffs(handoffs: Record<string, HandoffEntry>): void {
   writeFileSync(handoffPath(), JSON.stringify(trimmed, null, 2), "utf-8");
 }
 
-export function writeHandoffNote(
+function writeHandoffNote(
   cwd: string,
   title: string,
   text: string,