portable-agent-layer 0.36.0 → 0.37.0

package/src/hooks/lib/setup.ts

@@ -5,23 +5,15 @@
  * The AI is instructed to mark steps done after writing each file.
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { ensureDir, palHome, paths } from "./paths";
+import { existsSync, readFileSync } from "node:fs";
 
-export interface SetupStep {
+interface SetupStep {
   done: boolean;
   file: string;
   question: string;
   hint: string;
 }
 
-export interface SetupState {
-  version: number;
-  completed: boolean;
-  steps: Record<string, SetupStep>;
-}
-
 /** Ordered setup steps — defines the wizard flow */
 export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
   mission: {
@@ -50,10 +42,6 @@ export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
 
 export const STEP_ORDER = Object.keys(SETUP_STEPS);
 
-function setupPath(): string {
-  return resolve(ensureDir(paths.state()), "setup.json");
-}
-
 /** Check if a TELOS file has real content (not just template scaffolding) */
 export function hasRealContent(filePath: string): boolean {
   if (!existsSync(filePath)) return false;
@@ -70,49 +58,3 @@ export function hasRealContent(filePath: string): boolean {
     return false;
   }
 }
-
-/** Create initial setup state, auto-detecting already-populated TELOS files */
-export function createInitialState(): SetupState {
-  const steps: Record<string, SetupStep> = {};
-  for (const [key, def] of Object.entries(SETUP_STEPS)) {
-    const populated = hasRealContent(resolve(palHome(), def.file));
-    steps[key] = { done: populated, ...def };
-  }
-  const allDone = Object.values(steps).every((s) => s.done);
-  return { version: 1, completed: allDone, steps };
-}
-
-/** Read setup state, or return null if no setup.json exists */
-export function readSetupState(): SetupState | null {
-  const p = setupPath();
-  if (!existsSync(p)) return null;
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-/** Write setup state to disk */
-export function writeSetupState(state: SetupState): void {
-  writeFileSync(setupPath(), `${JSON.stringify(state, null, 2)}\n`);
-}
-
-/** Seed setup.json if it doesn't exist yet. Returns the state. */
-export function ensureSetupState(): SetupState {
-  const existing = readSetupState();
-  if (existing) return existing;
-  const fresh = createInitialState();
-  writeSetupState(fresh);
-  return fresh;
-}
-
-/** Get the list of remaining (not done) step keys, in order */
-export function remainingSteps(state: SetupState): string[] {
-  return STEP_ORDER.filter((k) => !state.steps[k]?.done);
-}
-
-/** Check if setup is fully completed */
-export function isSetupComplete(state: SetupState): boolean {
-  return state.completed;
-}

package/src/hooks/lib/signals.ts

@@ -3,14 +3,14 @@ import { resolve } from "node:path";
 import { paths } from "./paths";
 import { now } from "./time";
 
-export interface Signal {
+interface Signal {
   ts: string;
   type: string;
   [key: string]: unknown;
 }
 
 /** Append a signal to a JSONL file in the signals directory */
-export function emitSignal(
+function emitSignal(
   filename: string,
   data: { type: string; [key: string]: unknown }
 ): void {

package/src/hooks/lib/stdin.ts

@@ -1,5 +1,5 @@
 /** Read all of stdin as a string */
-export async function readStdin(): Promise<string> {
+async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
   for await (const chunk of Bun.stdin.stream()) {
     chunks.push(Buffer.from(chunk));

package/src/hooks/lib/stop.ts

@@ -3,13 +3,15 @@
  * Used by StopOrchestrator.ts (Claude Code) and opencode plugin.
  */
 
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile, unlink } from "node:fs/promises";
 import { resolve } from "node:path";
 import { autoGraduate } from "../handlers/auto-graduate";
 import { autoBackup } from "../handlers/backup";
 import { writeContextDigests } from "../handlers/context-digests";
 import { notifyDesktop } from "../handlers/desktop-notify";
 import { captureFailure } from "../handlers/failure";
+import { persistLastExchange } from "../handlers/persist-last-exchange";
 import { projectTouch } from "../handlers/project-touch";
 import { checkReflectTrigger } from "../handlers/reflect-trigger";
 import { checkSelfModelTrigger } from "../handlers/self-model-trigger";
@@ -23,7 +25,7 @@ import { logDebug, logError } from "./log";
 import { ensureDir, paths } from "./paths";
 import { extractContent, extractLastAssistant, parseMessages } from "./transcript";
 
-export interface RunStopHandlersOptions {
+interface RunStopHandlersOptions {
   lastAssistantMessage?: string;
   sessionId?: string;
 }
@@ -41,6 +43,9 @@ export async function runStopHandlers(
   // Cache last assistant response (session-scoped)
   cacheLastResponse(messages, options.lastAssistantMessage, options.sessionId);
 
+  // Always persist last exchange — drives CompactRecover + "Pick Up Where You Left Off"
+  if (options.sessionId) persistLastExchange(messages, options.sessionId);
+
   // Run all handlers concurrently. Auto-graduate is idempotent (24h TTL +
   // state-dedup + content-dedup) so it's safe to fire on every Stop.
   // project-touch only fires when cwd resolves to an active registered project.
@@ -151,15 +156,16 @@ async function checkPendingFailure(transcript: string): Promise<void> {
   if (!existsSync(pendingPath)) return;
 
   try {
-    const pending = JSON.parse(readFileSync(pendingPath, "utf-8")) as {
+    const pending = JSON.parse(await readFile(pendingPath, "utf-8")) as {
       rating: number;
       context: string;
       detailedContext?: string;
       principle?: string;
       responsePreview?: string;
       userPreview?: string;
+      cwd?: string;
     };
-    unlinkSync(pendingPath);
+    await unlink(pendingPath);
 
     // Extract principle from full transcript if not already present
     let { principle, detailedContext } = pending;
@@ -199,7 +205,7 @@ Return JSON:
             detailed_context?: string;
           };
           principle = parsed.principle || undefined;
-          if (!detailedContext) detailedContext = parsed.detailed_context || undefined;
+          detailedContext ??= parsed.detailed_context || undefined;
         }
       } catch {
         /* graceful fallback — capture without principle */
@@ -211,7 +217,8 @@ Return JSON:
       pending.context,
       transcript,
       detailedContext,
-      principle
+      principle,
+      pending.cwd
     );
   } catch {
     // Non-critical

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

@@ -8,10 +8,9 @@ import { resolve } from "node:path";
 import { HAIKU_MODEL } from "./models";
 import { ensureDir, paths } from "./paths";
 
-export type TokenCaller =
+type TokenCaller =
   | "rating"
   | "failure"
-  | "work-learning"
   | "session-name"
   | "session-intelligence"
   | "relationship"

package/src/hooks/lib/transcript.ts

@@ -5,7 +5,7 @@
 
 import { readFileSync } from "node:fs";
 
-export interface Message {
+interface Message {
   role: string;
   content: string | unknown;
 }

package/src/hooks/lib/wisdom.ts

@@ -63,13 +63,13 @@ function existingCrystalPrinciples(content: string): string[] {
     if (m[1]) out.push(m[1].trim());
   }
   for (const line of content.split("\n")) {
-    const m = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*\d+%\]\s*$/);
+    const m = new RegExp(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*\d+%\]\s*$/).exec(line);
     if (m?.[1]) out.push(m[1].trim());
   }
   return out;
 }
 
-export interface PromoteCrystalResult {
+interface PromoteCrystalResult {
   domain: string;
   principle: string;
   confidence: number;
@@ -123,7 +123,7 @@ export function promoteCrystal(
   return { domain, principle, confidence, framePath, skipped: null };
 }
 
-export interface FrameDoc {
+interface FrameDoc {
   domain: string;
   principle: string;
   body: string;
@@ -153,7 +153,7 @@ export function readFramesForRetrieval(): FrameDoc[] {
     }
 
     for (const line of content.split("\n")) {
-      const m = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/);
+      const m = new RegExp(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/).exec(line);
       if (!m) continue;
       const name = m[1]?.trim();
       const pct = parseInt(m[2] ?? "", 10);
@@ -188,7 +188,7 @@ export function readFramePrinciples(): string[] {
 
     // legacy fallback: bullet lines "- X [CRYSTAL: N%]"
     for (const line of content.split("\n")) {
-      const match = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/);
+      const match = new RegExp(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/).exec(line);
       if (!match) continue;
       const name = match[1]?.trim();
       const pct = parseInt(match[2] ?? "", 10);

package/src/hooks/lib/work-tracking.ts

@@ -29,7 +29,7 @@ function sessionsPath(): string {
   return resolve(ensureDir(paths.state()), "sessions.json");
 }
 
-export function readSessions(): SessionRecord[] {
+function readSessions(): SessionRecord[] {
   const p = sessionsPath();
   if (!existsSync(p)) return [];
   try {
@@ -54,12 +54,6 @@ export function writeSession(record: SessionRecord): void {
   writeFileSync(sessionsPath(), JSON.stringify(pruned, null, 2), "utf-8");
 }
 
-/** Filter sessions within the last N hours */
-export function recentSessions(hours: number): SessionRecord[] {
-  const cutoff = Date.now() - hours * 60 * 60 * 1000;
-  return readSessions().filter((s) => new Date(s.ts).getTime() > cutoff);
-}
-
 /** Detect session completion status from last assistant message */
 export function detectStatus(lastAssistant: string): SessionRecord["status"] {
   const completionSignals =
@@ -118,15 +112,15 @@ function cleanForHandoff(text: string): string {
 /** Extract handoff notes from last assistant message */
 export function extractHandoff(lastAssistant: string): string {
   // Look for explicit next-steps / TODO / remaining sections
-  const sectionMatch = lastAssistant.match(
+  const sectionMatch = new RegExp(
     /(?:next steps?|todo|remaining|what's left|still need|want me to)[:\s]*\n([\s\S]{10,300}?)(?:\n\n|\n(?=[A-Z#]))/i
-  );
+  ).exec(lastAssistant);
   if (sectionMatch) return cleanForHandoff(sectionMatch[1]);
 
   // Look for closing question/offer (common assistant pattern)
-  const closingMatch = lastAssistant.match(
+  const closingMatch = new RegExp(
     /(?:want (?:me to|to)|shall I|should I|ready to|anything else|let me know)[^\n]*$/im
-  );
+  ).exec(lastAssistant);
 
   const cleaned = cleanForHandoff(lastAssistant);
 
@@ -144,7 +138,7 @@ export function extractHandoff(lastAssistant: string): string {
 
 // ── Per-Project History ──────────────────────────────────────────
 
-export interface ProjectHistoryEntry {
+interface ProjectHistoryEntry {
   date: string;
   title: string;
   summary: string;
@@ -152,8 +146,8 @@ export interface ProjectHistoryEntry {
 }
 
 /** Convert a cwd path to a filesystem-safe slug (last directory segment) */
-export function cwdToSlug(cwd: string): string {
-  const normalized = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+function cwdToSlug(cwd: string): string {
+  const normalized = cwd.replaceAll("\\", "/").replace(/\/+$/, "");
   return normalized.split("/").pop() || "unknown";
 }
 

package/src/targets/codex/install.ts

@@ -0,0 +1,95 @@
+/**
+ * PAL — Codex target installer
+ * Merges PAL hooks into ~/.codex/hooks.json (never overwrites user hooks).
+ * Symlinks skills. Ensures AGENTS.md symlink via regenerateIfNeeded().
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  copySkills,
+  countSkills,
+  generateSkillIndex,
+  loadCodexHooksTemplate,
+  log,
+  mergeCodexHooks,
+  readJson,
+  scaffoldPalSettings,
+  writeJson,
+} from "../lib";
+
+/**
+ * Ensure `features.hooks = true` in config.toml without touching other content.
+ * Appends the setting if missing; skips if already present.
+ */
+function enableCodexHooks(configPath: string): void {
+  let content = "";
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, "utf-8");
+    // Already enabled — nothing to do
+    if (/^\s*hooks\s*=\s*true/m.test(content)) {
+      log.info("Codex hooks already enabled in config.toml");
+      return;
+    }
+    // [features] section exists but no hooks line — insert after the header
+    if (/^\[features\]/m.test(content)) {
+      content = content.replace(/(\[features\][^\n]*\n)/, "$1hooks = true\n");
+      writeFileSync(configPath, content, "utf-8");
+      log.success("Added hooks = true to existing [features] section in config.toml");
+      return;
+    }
+  }
+  // No config.toml, or no [features] section — append the block
+  const block = `${content.endsWith("\n") || content === "" ? "" : "\n"}\n[features]\nhooks = true\n`;
+  writeFileSync(configPath, content + block, "utf-8");
+  log.success("Enabled hooks = true in ~/.codex/config.toml");
+}
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const CODEX_DIR = platform.codexDir();
+const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+
+// --- Ensure ~/.codex/ exists ---
+mkdirSync(CODEX_DIR, { recursive: true });
+
+// --- Merge hooks ---
+if (existsSync(HOOKS_FILE)) {
+  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
+  log.info("Backed up hooks.json");
+}
+
+const template = loadCodexHooksTemplate(assets.codexHooksTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
+const merged = mergeCodexHooks(existing, template);
+
+writeJson(HOOKS_FILE, merged);
+log.success("Merged PAL hooks into ~/.codex/hooks.json");
+
+// --- Symlink skills to ~/.codex/skills/ ---
+const codexSkillsDir = resolve(CODEX_DIR, "skills");
+copySkills(codexSkillsDir);
+generateSkillIndex();
+
+// --- Scaffold PAL settings ---
+scaffoldPalSettings();
+
+// --- Generate / verify AGENTS.md symlink ---
+regenerateIfNeeded();
+log.success("Ensured AGENTS.md symlink at ~/.codex/AGENTS.md");
+
+// --- Enable hooks in config.toml ---
+const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
+enableCodexHooks(CONFIG_FILE);
+
+log.success("Codex installation complete");
+console.log("");
+log.info(`Skills: ${countSkills()}`);
+log.info(`Hooks: ${HOOKS_FILE}`);

package/src/targets/codex/uninstall.ts

@@ -0,0 +1,70 @@
+/**
+ * PAL — Codex uninstaller
+ * Removes only PAL-owned hooks from ~/.codex/hooks.json. Preserves user hooks.
+ * Removes PAL skill symlinks.
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  loadCodexHooksTemplate,
+  log,
+  readJson,
+  removeSkills,
+  unmergeCodexHooks,
+  writeJson,
+} from "../lib";
+
+/**
+ * Remove `hooks = true` from config.toml.
+ * Also removes a now-empty [features] section header.
+ */
+function disableCodexHooks(configPath: string): void {
+  if (!existsSync(configPath)) return;
+  let content = readFileSync(configPath, "utf-8");
+  if (!/^\s*hooks\s*=\s*true/m.test(content)) return;
+
+  // Remove the hooks line
+  content = content.replace(/^[ \t]*hooks\s*=\s*true[ \t]*\n?/m, "");
+
+  // Remove [features] header if it's now empty (nothing between it and next section / EOF)
+  content = content.replace(/\[features\]\n(?=\[|$)/m, "");
+
+  writeFileSync(configPath, content, "utf-8");
+  log.success("Removed hooks from ~/.codex/config.toml");
+}
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const CODEX_DIR = platform.codexDir();
+const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+
+// --- Remove PAL hooks from hooks.json ---
+if (existsSync(HOOKS_FILE)) {
+  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
+  log.info("Backed up hooks.json");
+
+  const template = loadCodexHooksTemplate(assets.codexHooksTemplate(), PKG_ROOT);
+  const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
+  const cleaned = unmergeCodexHooks(existing, template);
+
+  writeJson(HOOKS_FILE, cleaned);
+  log.success("Removed PAL hooks from ~/.codex/hooks.json");
+} else {
+  log.info("No hooks.json found, nothing to do");
+}
+
+// --- Remove PAL skill symlinks ---
+const codexSkillsDir = resolve(CODEX_DIR, "skills");
+const removed = removeSkills(codexSkillsDir);
+if (removed.length > 0) {
+  log.success(`Removed ${removed.length} skill(s): ${removed.join(", ")}`);
+} else {
+  log.info("No PAL skills found");
+}
+
+// --- Disable hooks in config.toml ---
+const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
+disableCodexHooks(CONFIG_FILE);
+
+log.success("Codex uninstall complete");