portable-agent-layer 0.35.0 → 0.37.0

package/src/hooks/handlers/persist-last-exchange.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared handler: persist the last user/assistant exchange on every Stop and PreCompact.
+ *
+ * Writes two outputs:
+ *  1. last-exchange/{sessionId}.json + last-exchange/latest.json
+ *     → read by CompactRecover to re-inject after compaction
+ *  2. last-handoff.json keyed by cwd
+ *     → read by loadHandoff() to surface "Pick Up Where You Left Off"
+ *
+ * Always overwrites — Stop is the source of truth for both. The LEARN-phase
+ * handoff-note.ts tool may also write to last-handoff.json; whichever runs last wins,
+ * but raw exchange is sufficient for continuity and costs nothing.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logDebug, logError } from "../lib/log";
+import { ensureDir, paths } from "../lib/paths";
+import { extractContent, extractLastAssistant, extractLastUser } from "../lib/transcript";
+import { detectStatus } from "../lib/work-tracking";
+
+type ParsedMessage = { role: string; content: unknown };
+
+export function persistLastExchange(
+  messages: ParsedMessage[],
+  sessionId: string,
+  cwd: string = process.cwd()
+): void {
+  try {
+    const lastUser = extractContent(extractLastUser(messages));
+    const lastAssistant = extractContent(extractLastAssistant(messages));
+    if (!lastUser && !lastAssistant) return;
+
+    // 1. Write last-exchange files for CompactRecover
+    const stateDir = ensureDir(resolve(paths.state(), "last-exchange"));
+    const payload = {
+      sessionId,
+      timestamp: new Date().toISOString(),
+      trigger: null,
+      customInstructions: null,
+      userMessage: lastUser,
+      assistantMessage: lastAssistant,
+    };
+    const json = `${JSON.stringify(payload, null, 2)}\n`;
+    writeFileSync(resolve(stateDir, `${sessionId}.json`), json, "utf-8");
+    writeFileSync(resolve(stateDir, "latest.json"), json, "utf-8");
+
+    // 2. Write last-handoff.json for "Pick Up Where You Left Off"
+    const handoffPath = resolve(paths.state(), "last-handoff.json");
+    const existing: Record<string, unknown> = existsSync(handoffPath)
+      ? JSON.parse(readFileSync(handoffPath, "utf-8"))
+      : {};
+    const title = (lastUser.slice(0, 80).replace(/\n/g, " ") || "Session").trim();
+    const handoff = [
+      lastUser ? `Last user message:\n${lastUser.slice(0, 500)}` : "",
+      lastAssistant ? `\nLast assistant response:\n${lastAssistant.slice(0, 500)}` : "",
+    ]
+      .filter(Boolean)
+      .join("");
+    existing[cwd] = {
+      timestamp: new Date().toISOString(),
+      title,
+      status: detectStatus(lastAssistant),
+      handoff,
+      artifacts: [],
+    };
+    writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
+
+    logDebug(
+      "persist-last-exchange",
+      `Persisted exchange for session ${sessionId} (user=${lastUser.length}ch, assistant=${lastAssistant.length}ch)`
+    );
+  } catch (err) {
+    logError("persist-last-exchange", err);
+  }
+}

package/src/hooks/handlers/rating.ts

@@ -48,7 +48,7 @@ export function parseExplicitRating(
   prompt: string
 ): { rating: number; comment?: string } | null {
   const trimmed = prompt.trim();
-  const match = trimmed.match(/^(10|[1-9])(?:\s*[-:,]\s*|\s+)?(.*)$/);
+  const match = new RegExp(/^(10|[1-9])(?:\s*[-:,]\s*|\s+)?(.*)$/).exec(trimmed);
   if (!match) return null;
 
   const rating = parseInt(match[1], 10);
@@ -271,6 +271,7 @@ function handleRating(
           principle,
           responsePreview,
           userPreview,
+          cwd: process.cwd(),
           ts: now(),
         },
         null,

package/src/hooks/handlers/readme-sync.ts

@@ -33,7 +33,7 @@ function hasDocumentableChanges(): boolean {
   }
 }
 
-export interface ReadmeSyncDecision {
+interface ReadmeSyncDecision {
   decision?: "block";
   reason?: string;
 }
@@ -50,9 +50,10 @@ export function checkReadmeSync(): ReadmeSyncDecision {
 
   if (!result.ok) {
     logDebug("readme-sync", `README out of sync: ${result.issues.join("; ")}`);
+    const issueList = result.issues.map((i) => `- ${i}`).join("\n");
     return {
       decision: "block",
-      reason: `README.md is out of date. Please update it before finishing:\n${result.issues.map((i) => `- ${i}`).join("\n")}`,
+      reason: `README.md is out of date. Please update it before finishing:\n${issueList}`,
     };
   }
 

package/src/hooks/handlers/session-intelligence.ts

@@ -1,21 +1,22 @@
 /**
  * Stop handler: unified session intelligence capture.
  *
- * Merges work-learning + relationship + handoff into a single Haiku call.
- * Produces: title, summary, insights, handoff, relationship observations.
- * Writes: session learning file, project history, relationship notes, last-handoff.
+ * Produces: title, summary, insights via Haiku.
+ * Writes: session learning file, project history.
+ *
+ * Relationship notes → written in ALGORITHM LEARN phase via relationship-note.ts
+ * Handoff notes     → written in ALGORITHM LEARN phase via handoff-note.ts
  *
- * Replaces: work-learning.ts + relationship.ts (both still exist but are bypassed).
  */
 
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { stringify } from "../lib/frontmatter";
-import { inference } from "../lib/inference";
+import { hasApiKey, inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
-import { appendNotes, hasSessionNotes, type RelationshipNote } from "../lib/relationship";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -26,7 +27,7 @@ import {
 } from "../lib/transcript";
 import { appendProjectHistory, detectStatus } from "../lib/work-tracking";
 
-// ── Dedup tracking (same as work-learning) ──
+// ── Dedup tracking ──
 
 interface CaptureEntry {
   filepath: string;
@@ -110,25 +111,8 @@ const INTELLIGENCE_SCHEMA = {
       description:
         "If status is in-progress: what remains to be done, key decisions made, blockers. If completed: empty string.",
     },
-    observations: {
-      type: "array" as const,
-      items: {
-        type: "object" as const,
-        additionalProperties: false,
-        properties: {
-          type: {
-            type: "string" as const,
-            enum: ["O", "W", "B"],
-            description: "O=preference, W=world fact, B=what AI did",
-          },
-          text: { type: "string" as const },
-          confidence: { type: "number" as const },
-        },
-        required: ["type", "text", "confidence"] as const,
-      },
-    },
   },
-  required: ["title", "summary", "insights", "handoff", "observations"] as const,
+  required: ["title", "summary", "insights", "handoff"] as const,
 };
 
 interface IntelligenceOutput {
@@ -136,7 +120,6 @@ interface IntelligenceOutput {
   summary: string;
   insights: string;
   handoff: string;
-  observations: Array<{ type: "O" | "W" | "B"; text: string; confidence: number }>;
 }
 
 // ── Main handler ──
@@ -155,14 +138,11 @@ export async function captureSessionIntelligence(
   }
 
   // Skip if no API key
-  if (!process.env.PAL_ANTHROPIC_API_KEY) {
+  if (!hasApiKey()) {
     logDebug("session-intelligence", "Skipped: no PAL_ANTHROPIC_API_KEY");
     return;
   }
 
-  // Relationship dedup — skip relationship capture if already done for this session
-  const skipRelationship = sessionId ? hasSessionNotes(sessionId) : false;
-
   // Extract transcript windows
   const userMessages = messages
     .filter((m) => m.role === "user")
@@ -174,14 +154,14 @@ export async function captureSessionIntelligence(
   const lastUser = extractLastUser(messages);
   const status = detectStatus(lastAssistantText);
 
-  // Wider window: 15 user msgs at 200 chars (relationship needs more context)
-  const userWindow = userMessages.slice(-15).map((t) => t.slice(0, 200));
+  const userWindow = userMessages.slice(-10).map((t) => t.slice(0, 200));
   const assistantWindow = lastAssistantText.slice(0, 600);
 
   if (userWindow.length < 3) return;
 
   // Single Haiku call
   logDebug("session-intelligence", "Calling inference...");
+  const numberedMessages = userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n");
   let output: IntelligenceOutput | null = null;
   try {
     const result = await inference({
@@ -195,12 +175,9 @@ export async function captureSessionIntelligence(
         status === "in-progress"
           ? "4. handoff: what remains unfinished — decisions made so far, next steps, blockers (2-4 sentences)"
           : "4. handoff: empty string (session completed)",
-        skipRelationship
-          ? "5. observations: empty array (already captured)"
-          : "5. observations: 0-3 relationship observations. O=preference/opinion, W=world fact, B=what AI did this session (first-person). Be concise.",
       ].join("\n"),
-      user: `User messages:\n${userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n")}\n\nLast AI response:\n${assistantWindow}`,
-      maxTokens: 500,
+      user: `User messages:\n${numberedMessages}\n\nLast AI response:\n${assistantWindow}`,
+      maxTokens: 350,
       timeout: 15000,
       jsonSchema: INTELLIGENCE_SCHEMA,
     });
@@ -218,8 +195,6 @@ export async function captureSessionIntelligence(
   const title = output?.title || extractContent(lastUser).slice(0, 80) || "session";
   const summary = output?.summary || lastAssistantText.slice(0, 600);
   const insights = output?.insights || "";
-  const handoff = output?.handoff || "";
-
   // ── Write session learning file ──
 
   const category = categorizeLearning(title, summary);
@@ -241,7 +216,6 @@ export async function captureSessionIntelligence(
     "",
     "## Insights",
     insights || "*No insights captured.*",
-    ...(handoff ? ["", "## Handoff", handoff] : []),
   ].join("\n");
 
   const content = stringify(meta, body);
@@ -251,7 +225,7 @@ export async function captureSessionIntelligence(
     const prev = getPreviousCapture(sessionId);
     if (prev?.filepath && existsSync(prev.filepath)) {
       try {
-        unlinkSync(prev.filepath);
+        await unlink(prev.filepath);
       } catch {
         /* ignore */
       }
@@ -259,7 +233,7 @@ export async function captureSessionIntelligence(
   }
 
   const filepath = resolve(dir, filename);
-  writeFileSync(filepath, content, "utf-8");
+  await writeFile(filepath, content, "utf-8");
 
   // Append to per-project history
   appendProjectHistory(process.cwd(), {
@@ -271,54 +245,4 @@ export async function captureSessionIntelligence(
 
   if (sessionId) markCaptured(sessionId, filepath, messages.length);
   logDebug("session-intelligence", `Learning captured: ${title}`);
-
-  // ── Write relationship notes ──
-
-  if (!skipRelationship && output?.observations && output.observations.length > 0) {
-    try {
-      const notes: RelationshipNote[] = output.observations.map((o) => ({
-        type: o.type,
-        text: o.text,
-        confidence: o.confidence,
-      }));
-      appendNotes(notes, sessionId);
-      logDebug(
-        "session-intelligence",
-        `${notes.length} relationship observations captured`
-      );
-    } catch (err) {
-      logError("session-intelligence:relationship", err);
-    }
-  }
-
-  // ── Write handoff state ──
-
-  if (handoff && status === "in-progress") {
-    try {
-      const handoffPath = resolve(ensureDir(paths.state()), "last-handoff.json");
-      let handoffs: Record<string, unknown> = {};
-      if (existsSync(handoffPath)) {
-        try {
-          handoffs = JSON.parse(readFileSync(handoffPath, "utf-8"));
-        } catch {
-          /* fresh */
-        }
-      }
-      handoffs[process.cwd()] = {
-        timestamp: new Date().toISOString(),
-        sessionId,
-        title,
-        status,
-        handoff,
-        artifacts: [],
-      };
-      // Keep last 20 projects
-      const entries = Object.entries(handoffs);
-      if (entries.length > 20) handoffs = Object.fromEntries(entries.slice(-20));
-      writeFileSync(handoffPath, JSON.stringify(handoffs, null, 2), "utf-8");
-      logDebug("session-intelligence", "Handoff state written");
-    } catch (err) {
-      logError("session-intelligence:handoff", err);
-    }
-  }
 }

package/src/hooks/handlers/session-name.ts

@@ -10,7 +10,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { inference } from "../lib/inference";
+import { hasApiKey, inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
 import {
   extractFallbackName,
@@ -42,7 +42,7 @@ export async function captureSessionName(
   logDebug("session-name", `Named from prompt: "${name}"`);
 
   // Spawn detached background process to upgrade with Haiku inference
-  if (!process.env.PAL_ANTHROPIC_API_KEY) return;
+  if (!hasApiKey()) return;
   try {
     const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
     const child = spawn(

package/src/hooks/handlers/synthesis.ts

@@ -3,7 +3,8 @@
  * Imports synthesize logic directly — no subprocess needed.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { logDebug } from "../lib/log";
 import { paths } from "../lib/paths";
@@ -16,7 +17,9 @@ export async function runSynthesis(): Promise<void> {
   // Check 24h guard
   if (existsSync(statePath)) {
     try {
-      const data = JSON.parse(readFileSync(statePath, "utf-8")) as { timestamp: string };
+      const data = JSON.parse(await readFile(statePath, "utf-8")) as {
+        timestamp: string;
+      };
       if (Date.now() - new Date(data.timestamp).getTime() < SYNTHESIS_TTL_MS) {
         logDebug("synthesis", "Skipped — last synthesis < 24h ago");
         return;

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

@@ -4,7 +4,8 @@
  * scanning directories and JSONL files.
  */
 
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { assets, ensureDir, paths } from "../lib/paths";
 
@@ -147,5 +148,5 @@ function getCounts(): Counts {
 export async function updateCounts(): Promise<void> {
   const counts = getCounts();
   const countsPath = resolve(ensureDir(paths.state()), "counts.json");
-  writeFileSync(countsPath, JSON.stringify(counts, null, 2), "utf-8");
+  await writeFile(countsPath, JSON.stringify(counts, null, 2), "utf-8");
 }

package/src/hooks/lib/agent.ts

@@ -1,40 +1,42 @@
 /**
  * Agent detection and output format adapters.
  *
- * Cursor and Claude Code use different JSON contracts for hook I/O.
+ * Cursor, Codex, and Claude Code use different JSON contracts for hook I/O.
  * These helpers normalize the differences so hook handlers stay clean.
  */
 
-export type AgentType = "claude" | "cursor";
+type AgentType = "claude" | "cursor" | "codex";
 
 /** Detect which agent is running via environment variables */
-export function detectAgent(): AgentType {
+function detectAgent(): AgentType {
+  // PAL_AGENT is set explicitly in hook command prefixes — most reliable signal.
+  // IDE env vars (CURSOR_VERSION, CODEX_CLI_VERSION) are NOT reliably forwarded to
+  // hook subprocesses, so PAL_AGENT is the primary detection mechanism.
+  if (process.env.PAL_AGENT === "cursor") return "cursor";
+  if (process.env.PAL_AGENT === "codex") return "codex";
+  // Fallbacks for environments that do forward IDE env vars
   if (process.env.CURSOR_VERSION) return "cursor";
+  if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
   return "claude";
 }
 
 export const isCursor = () => detectAgent() === "cursor";
+export const isCodex = () => detectAgent() === "codex";
 
 /**
  * Format a "block this action" response for the current agent.
- * Claude Code: { decision: "block", reason }
- * Cursor:      { permission: "deny", user_message }
+ * Claude Code:       { decision: "block", reason }
+ * Cursor preToolUse: { permission: "deny", user_message }
+ * Codex PreToolUse:  { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny" } }
  */
-export function blockResponse(reason: string): string {
+export function blockResponse(reason: string, hookEventName?: string): string {
   if (isCursor()) {
     return JSON.stringify({ permission: "deny", user_message: reason });
   }
-  return JSON.stringify({ decision: "block", reason });
-}
-
-/**
- * Format sessionStart context injection for the current agent.
- * Claude Code: raw text to stdout
- * Cursor:      { additional_context: "..." }
- */
-export function sessionStartOutput(context: string): string {
-  if (isCursor()) {
-    return JSON.stringify({ additional_context: context });
+  if (isCodex() && hookEventName === "PreToolUse") {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny" },
+    });
   }
-  return context;
+  return JSON.stringify({ decision: "block", reason });
 }

package/src/hooks/lib/claude-md.ts

@@ -1,9 +1,10 @@
 /**
- * Dynamic AGENTS.md generation.
+ * Dynamic AGENTS.md / CLAUDE.md generation.
  *
- * AGENTS.md is regenerated when setup.json or any telos file is newer than
- * the existing AGENTS.md. The template lives at AGENTS.md.template.
- * CLAUDE.md is kept as a symlink pointing to AGENTS.md.
+ * AGENTS.md (opencode, codex, copilot) is regenerated when setup.json or any
+ * telos file is newer. CLAUDE.md (Claude Code) is a real file — not a symlink —
+ * and prepends an @import for the self-model so that large static context loads
+ * natively rather than through the hook's stdout.
  */
 
 import {
@@ -19,6 +20,7 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { assets, ensureDir, paths, platform } from "./paths";
+import { getSemiStaticSources } from "./semi-static";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
 
@@ -70,16 +72,12 @@ function ensureOneSymlink(linkPath: string, targetPath: string): void {
   }
 }
 
-/** Ensure all agent symlinks point to the canonical AGENTS.md */
+/** Ensure codex symlink points to the canonical AGENTS.md.
+ *  CLAUDE.md for Claude Code is a real file written by ensureClaudeCodeMd().
+ *  Copilot uses ~/.copilot/instructions/*.instructions.md — no symlink needed. */
 function ensureSymlinks(): void {
-  const { outputPath, symlinkPath } = getOutputPaths();
-  ensureOneSymlink(symlinkPath, outputPath);
+  const { outputPath } = getOutputPaths();
   ensureOneSymlink(resolve(platform.codexDir(), "AGENTS.md"), outputPath);
-  // Copilot instructions — only create if ~/.copilot/ already exists (i.e. Copilot is installed)
-  const copilotDir = platform.copilotDir();
-  if (existsSync(copilotDir)) {
-    ensureOneSymlink(resolve(copilotDir, "copilot-instructions.md"), outputPath);
-  }
 }
 
 /** Returns true if AGENTS.md needs to be regenerated */
@@ -89,11 +87,12 @@ export function needsRebuild(): boolean {
 
   const outputMtime = statSync(outputPath).mtimeMs;
 
-  // Collect source files: template + setup.json + identity + PAL docs
+  // Collect source files: template + setup.json + identity + PAL docs + @import candidates
   const sources: string[] = [
     TEMPLATE_PATH,
     resolve(paths.state(), "setup.json"),
     resolve(paths.memory(), "pal-settings.json"),
+    ...getSemiStaticSources().map((s) => s.path),
   ];
 
   // Track PAL doc sources for rebuild detection
@@ -124,15 +123,71 @@ export function buildClaudeMd(): string {
     .replaceAll("{{PRINCIPAL_NAME}}", id.principal.name);
 }
 
-/** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */
+/** Build @import header lines for CLAUDE.md — one line per semi-static file that exists. */
+function buildClaudeCodeImports(): string {
+  const claudeDir = platform.claudeDir();
+
+  const lines = getSemiStaticSources()
+    .map((s) => s.path)
+    .filter((p) => existsSync(p))
+    .map((p) => `@${relative(claudeDir, p).replaceAll("\\", "/")}`);
+
+  return lines.length > 0 ? `${lines.join("\n")}\n\n` : "";
+}
+
+/** Build CLAUDE.md content for Claude Code — prepends @import for self-model. */
+export function buildClaudeCodeMd(): string {
+  return buildClaudeCodeImports() + buildClaudeMd();
+}
+
+/** Write ~/.claude/CLAUDE.md as a real file (upgrading from symlink if needed).
+ *  Also rewrites if the @import header has changed (new digest files appeared). */
+function ensureClaudeCodeMd(): void {
+  const claudeDir = platform.claudeDir();
+  if (!claudeDir) return;
+  const claudeMdPath = resolve(claudeDir, "CLAUDE.md");
+  const expected = buildClaudeCodeMd();
+  try {
+    if (existsSync(claudeMdPath) && !lstatSync(claudeMdPath).isSymbolicLink()) {
+      const current = readFileSync(claudeMdPath, "utf-8");
+      if (current === expected) return; // no change needed
+      // @imports changed — rewrite
+    } else if (existsSync(claudeMdPath)) {
+      unlinkSync(claudeMdPath); // remove symlink
+    }
+  } catch {
+    /* fall through */
+  }
+  try {
+    ensureDir(claudeDir);
+    writeFileSync(claudeMdPath, expected, "utf-8");
+  } catch {
+    /* ignore write errors — non-fatal */
+  }
+}
+
+/** Regenerate AGENTS.md if any source file is newer, write real CLAUDE.md, ensure other symlinks. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
   if (!needsRebuild()) {
     ensureSymlinks();
+    ensureClaudeCodeMd();
     return false;
   }
   ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
+  // Write Claude Code's CLAUDE.md as a real file (removing any existing symlink)
+  const claudeDir = platform.claudeDir();
+  if (claudeDir) {
+    const claudeMdPath = resolve(claudeDir, "CLAUDE.md");
+    try {
+      if (existsSync(claudeMdPath)) unlinkSync(claudeMdPath);
+      ensureDir(claudeDir);
+      writeFileSync(claudeMdPath, buildClaudeCodeMd(), "utf-8");
+    } catch {
+      /* ignore — CLAUDE.md write failure is non-fatal */
+    }
+  }
   ensureSymlinks();
   return true;
 }