portable-agent-layer 0.2.1 → 0.4.0

package/README.md

@@ -30,7 +30,10 @@ With PAL, you can:
 
 ### Prerequisites
 
+> **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.
+
 - [Bun](https://bun.sh) >= 1.3.0
+- At least one of: [Claude Code](https://claude.ai/code) or [opencode](https://opencode.ai)
 
 ### Package mode (recommended)
 
@@ -77,6 +80,7 @@ pal cli status        # check your setup
 | `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 |
+| `pal cli doctor` | Check prerequisites and system health |
 
 ### Target flags
 
@@ -111,6 +115,27 @@ pal cli install               # both (default)
 
 ---
 
+## Skills
+
+PAL ships with built-in skills that extend your agent's capabilities:
+
+| Skill | Description |
+|-------|-------------|
+| `analyze-pdf` | Download and analyze PDF files |
+| `analyze-youtube` | Analyze YouTube videos using Gemini |
+| `council` | Multi-perspective parallel debate on decisions |
+| `create-skill` | Scaffold a new skill from a description |
+| `extract-entities` | Extract people and companies from content |
+| `extract-wisdom` | Extract structured insights from content |
+| `first-principles` | Break down problems to fundamentals |
+| `fyzz-chat-api` | Query Fyzz Chat conversations via API |
+| `reflect` | Diagnose why a PAL behavior didn't trigger |
+| `research` | Multi-agent parallel research |
+| `review` | Security-focused code review |
+| `summarize` | Structured summarization |
+
+---
+
 ## Core idea
 
 PAL stands for **Portable Agent Layer**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -48,6 +48,7 @@
     "ai:fyzz-api": "bun run src/tools/fyzz-api.ts",
     "ai:pdf-download": "bun run src/tools/pdf-download.ts",
     "ai:youtube-analyze": "bun run src/tools/youtube-analyze.ts",
+    "tool:graduate": "bun run src/tools/graduate.ts",
     "tool:patterns": "bun run src/tools/pattern-synthesis.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
     "tool:export": "bun run src/tools/export.ts",

package/src/cli/index.ts

@@ -13,6 +13,7 @@
  *   export [path] [--dry-run]         Export user state to zip
  *   import [path] [--dry-run]         Import user state from zip
  *   status                            Show current PAL configuration
+ *   doctor                            Check prerequisites and system health
  */
 
 import { spawnSync } from "node:child_process";
@@ -20,6 +21,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
+import { getPendingSuggestions } from "../hooks/lib/tags";
 import { log } from "../targets/lib";
 
 const allArgs = process.argv.slice(2);
@@ -35,18 +37,53 @@ if (allArgs[0] === "cli") {
   await session(allArgs);
 }
 
-// ── Session: pal [claude-args] ──
+// ── Session: pal [args] ──
 
-async function session(claudeArgs: string[]) {
-  // Run claude with all args, inheriting stdio for interactive TTY
-  const result = spawnSync("claude", claudeArgs, {
+interface ToolCheck {
+  name: string;
+  available: boolean;
+  version?: string;
+}
+
+function checkTool(cmd: string, versionArgs: string[] = ["--version"]): ToolCheck {
+  try {
+    const result = spawnSync(cmd, versionArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+      timeout: 5000,
+    });
+    if (result.status === 0) {
+      const version = (result.stdout?.toString() || "").trim().split("\n")[0];
+      return { name: cmd, available: true, version };
+    }
+  } catch {
+    // not found
+  }
+  return { name: cmd, available: false };
+}
+
+function detectAgent(): string | null {
+  if (checkTool("claude").available) return "claude";
+  if (checkTool("opencode").available) return "opencode";
+  return null;
+}
+
+async function session(sessionArgs: string[]) {
+  const agent = detectAgent();
+  if (!agent) {
+    log.error("No supported agent found. Install Claude Code or opencode.");
+    process.exit(1);
+  }
+
+  const result = spawnSync(agent, sessionArgs, {
     stdio: "inherit",
     shell: true,
   });
 
   const exitCode = result.status ?? 1;
 
-  // Find the most recent transcript and extract session ID
+  // Session summary (Claude only)
+  if (agent !== "claude") process.exit(exitCode);
   try {
     const projectsDir = resolve(homedir(), ".claude", "projects");
     if (!existsSync(projectsDir)) process.exit(exitCode);
@@ -98,7 +135,7 @@ async function runCli(command: string | undefined, args: string[]) {
       break;
     case "install":
       banner();
-      await install(parseTargets(args));
+      await install(resolveTargets(args));
       break;
     case "uninstall":
       await uninstall(args);
@@ -112,6 +149,9 @@ async function runCli(command: string | undefined, args: string[]) {
     case "status":
       await status();
       break;
+    case "doctor":
+      doctor();
+      break;
     case "--help":
     case "-h":
     case "help":
@@ -148,6 +188,7 @@ function showHelp() {
     pal cli export [path] [--dry-run]       Export state to zip
     pal cli import [path] [--dry-run]       Import state from zip
     pal cli status                          Show PAL configuration
+    pal cli doctor                          Check prerequisites and health
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
@@ -176,6 +217,172 @@ function parseTargets(args: string[]): {
   return { claude, opencode };
 }
 
+/** Resolve targets against available agents. Errors if explicitly requested but missing. */
+function resolveTargets(
+  args: string[],
+  health?: DoctorResult
+): { claude: boolean; opencode: boolean } {
+  const requested = parseTargets(args);
+  const h = health || doctor(true);
+  const explicit = args.some(
+    (a) => a === "--claude" || a === "--opencode" || a === "--all"
+  );
+
+  if (explicit) {
+    // User explicitly requested — error if not available
+    if (requested.claude && !h.claude.available) {
+      log.error("Claude Code is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
+    if (requested.opencode && !h.opencode.available) {
+      log.error("opencode is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
+    return requested;
+  }
+
+  // Default (no flags) — install for available agents only
+  const targets = {
+    claude: h.claude.available,
+    opencode: h.opencode.available,
+  };
+
+  if (!targets.claude) log.info("Skipping Claude Code (not installed)");
+  if (!targets.opencode) log.info("Skipping opencode (not installed)");
+
+  return targets;
+}
+
+// ── Hook health ──
+
+interface HookHealth {
+  totalErrors: number;
+  lastError: string | null;
+}
+
+function checkHookHealth(home: string): HookHealth {
+  const logPath = resolve(home, "memory", "state", "debug.log");
+
+  try {
+    if (!existsSync(logPath)) return { totalErrors: 0, lastError: null };
+
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.split("\n").filter((l) => l.includes("] ERROR "));
+
+    // Filter to last 24h
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
+    const recentErrors = lines.filter((line) => {
+      const match = line.match(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/);
+      if (!match) return false;
+      return new Date(match[1]) > cutoff;
+    });
+
+    const lastError =
+      recentErrors.length > 0
+        ? recentErrors[recentErrors.length - 1]
+            .replace(/^\[.*?\] ERROR /, "")
+            .slice(0, 120)
+        : null;
+
+    return { totalErrors: recentErrors.length, lastError };
+  } catch {
+    return { totalErrors: 0, lastError: null };
+  }
+}
+
+// ── Doctor ──
+
+interface DoctorResult {
+  bun: ToolCheck;
+  claude: ToolCheck;
+  opencode: ToolCheck;
+  hasAgent: boolean;
+}
+
+function doctor(silent = false): DoctorResult {
+  // Allow CI/tests to skip agent detection
+  if (process.env.PAL_SKIP_DOCTOR === "1") {
+    return {
+      bun: { name: "bun", available: true, version: Bun.version },
+      claude: { name: "claude", available: true },
+      opencode: { name: "opencode", available: true },
+      hasAgent: true,
+    };
+  }
+
+  const bun = { name: "bun", available: true, version: Bun.version };
+  const claude = checkTool("claude");
+  const opencode = checkTool("opencode");
+  const hasAgent = claude.available || opencode.available;
+
+  const home = palHome();
+  const isRepo = existsSync(resolve(palPkg(), ".palroot"));
+  const telosCount = (() => {
+    try {
+      return readdirSync(resolve(home, "telos")).filter((f) => f.endsWith(".md")).length;
+    } catch {
+      return 0;
+    }
+  })();
+
+  if (!silent) {
+    const ok = (msg: string) => console.log(`  \x1b[32m\u2713\x1b[0m ${msg}`);
+    const warn = (msg: string) => console.log(`  \x1b[33m\u26A0\x1b[0m ${msg}`);
+    const fail = (msg: string) => console.log(`  \x1b[31m\u2717\x1b[0m ${msg}`);
+
+    console.log("");
+    log.info("Doctor");
+    ok(`Bun ${bun.version}`);
+    claude.available
+      ? ok(`Claude Code ${claude.version || ""}`.trim())
+      : fail("Claude Code — not found");
+    opencode.available
+      ? ok(`opencode ${opencode.version || ""}`.trim())
+      : fail("opencode — not found");
+    ok(`PAL home: ${home} (${isRepo ? "repo" : "package"} mode)`);
+    telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
+
+    // API key checks
+    process.env.ANTHROPIC_API_KEY
+      ? ok("ANTHROPIC_API_KEY is set")
+      : fail("ANTHROPIC_API_KEY — not set (hooks need it for inference)");
+    process.env.GEMINI_API_KEY
+      ? ok("GEMINI_API_KEY is set")
+      : warn("GEMINI_API_KEY — not set (optional, for YouTube analysis)");
+
+    // Hook health from debug.log
+    const hookHealth = checkHookHealth(home);
+    if (hookHealth.totalErrors === 0) {
+      ok("Hooks: no recent errors");
+    } else {
+      fail(`Hooks: ${hookHealth.totalErrors} error(s) in last 24h`);
+      if (hookHealth.lastError) {
+        log.warn(`    Last: ${hookHealth.lastError}`);
+      }
+    }
+
+    // Pending tag suggestions
+    const pending = getPendingSuggestions();
+    const pendingEntries = Object.entries(pending).sort((a, b) => b[1] - a[1]);
+    if (pendingEntries.length > 0) {
+      warn(`Tags: ${pendingEntries.length} pending suggestion(s)`);
+      for (const [tag, count] of pendingEntries.slice(0, 5)) {
+        log.info(`    "${tag}" (${count}/3 to promote)`);
+      }
+    } else {
+      ok("Tags: no pending suggestions");
+    }
+
+    if (!hasAgent) {
+      console.log("");
+      log.error("No supported agent found. Install Claude Code or opencode.");
+    }
+    console.log("");
+  }
+
+  return { bun, claude, opencode, hasAgent };
+}
+
 // ── Commands ──
 
 async function init(args: string[]) {
@@ -184,6 +391,12 @@ async function init(args: string[]) {
 
   banner();
 
+  // Run doctor first — abort if no agents available
+  const health = doctor(false);
+  if (!health.hasAgent) {
+    process.exit(1);
+  }
+
   const home = palHome();
   const isRepo = existsSync(resolve(palPkg(), ".palroot"));
 
@@ -196,7 +409,9 @@ async function init(args: string[]) {
   scaffoldTelos();
   ensureSetupState();
 
-  await install(parseTargets(args));
+  // Auto-detect available targets
+  const targets = resolveTargets(args, health);
+  await install(targets);
 
   console.log("");
   const state = ensureSetupState();

package/src/hooks/StopOrchestrator.ts

@@ -6,6 +6,7 @@
  * Transcript is read from the file at transcript_path, NOT from stdin.
  */
 
+import { checkReadmeSync } from "./handlers/readme-sync";
 import { logError } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 import { runStopHandlers } from "./lib/stop";
@@ -17,6 +18,17 @@ interface StopHookInput {
   last_assistant_message?: string;
 }
 
+// Check README sync before anything else — may block the session
+try {
+  const decision = checkReadmeSync();
+  if (decision.decision === "block") {
+    console.log(JSON.stringify(decision));
+    process.exit(0);
+  }
+} catch (err) {
+  logError("StopOrchestrator:readme-sync", err);
+}
+
 const input = await readStdinJSON<StopHookInput>();
 if (!input?.transcript_path) {
   logError("StopOrchestrator", "No transcript_path in hook input");

package/src/hooks/handlers/failure.ts

@@ -2,14 +2,16 @@
  * Deep Failure Capture — full context dump for ratings 1–3.
  *
  * Writes to memory/learning/failures/YYYY-MM/{timestamp}_{slug}/
- *   CONTEXT.md    — full failure context with transcript excerpt
- *   sentiment.json — structured rating + metadata
+ *   capture.md     — frontmatter metadata + failure context body
+ *   sentiment.json — DEPRECATED legacy format (kept for backward compat)
  */
 
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { ensureDir, paths } from "../lib/paths";
+import { getVocabulary, recordSuggestedTag } from "../lib/tags";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -53,32 +55,38 @@ export async function captureFailure(
     resolve(paths.failures(), monthPath(), `${fileTimestamp()}_${slug}`)
   );
 
-  // Attempt inference to fill root cause analysis
+  // Attempt inference to fill root cause analysis + tags
   let whatWentWrong = "";
   let whatToDoDifferently = "";
+  let tags: string[] = [];
   try {
+    const vocab = getVocabulary();
     const analysisResult = await inference({
-      system:
-        "You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable.",
+      system: `You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable. Also pick 1-3 tags from this list: [${vocab.join(", ")}]. If none fit, leave tags empty and put your suggested tag in suggested_tag.`,
       user: [
         `Rating: ${rating}/10`,
         `Context: ${context}`,
         detailedContext ? `Analysis: ${detailedContext}` : "",
-        `User said: ${lastUser}`,
-        `Assistant said: ${lastAssistant}`,
+        `Assistant response (what the user reacted to): ${lastAssistant}`,
+        `User reaction (the frustrated message): ${lastUser}`,
       ]
         .filter(Boolean)
         .join("\n"),
-      maxTokens: 300,
-      timeout: 8000,
+      maxTokens: 400,
+      timeout: 15000,
       jsonSchema: {
         type: "object" as const,
         additionalProperties: false,
         properties: {
           what_went_wrong: { type: "string" as const },
           what_to_do_differently: { type: "string" as const },
+          tags: {
+            type: "array" as const,
+            items: { type: "string" as const },
+          },
+          suggested_tag: { type: "string" as const },
         },
-        required: ["what_went_wrong", "what_to_do_differently"],
+        required: ["what_went_wrong", "what_to_do_differently", "tags"],
       },
     });
     if (analysisResult.usage) logTokenUsage("failure", analysisResult.usage);
@@ -86,51 +94,48 @@ export async function captureFailure(
       const parsed = JSON.parse(analysisResult.output) as {
         what_went_wrong?: string;
         what_to_do_differently?: string;
+        tags?: string[];
+        suggested_tag?: string;
       };
       whatWentWrong = parsed.what_went_wrong ?? "";
       whatToDoDifferently = parsed.what_to_do_differently ?? "";
+      if (parsed.tags?.length) tags = parsed.tags;
+      if (parsed.suggested_tag) recordSuggestedTag(parsed.suggested_tag);
     }
   } catch {
     // Graceful fallback — empty sections are still useful with the other context
   }
 
-  const contextMdPath = resolve(dir, "CONTEXT.md");
-  writeFileSync(
-    contextMdPath,
-    [
-      `# Failure Capture — Rating ${rating}/10`,
-      `**Date:** ${new Date().toISOString().slice(0, 10)}`,
-      `**Context:** ${context}`,
-      "",
-      "## Last User Message",
-      lastUser || "*(unavailable)*",
-      "",
-      "## Last Assistant Response",
-      lastAssistant || "*(unavailable)*",
-      "",
-      ...(detailedContext ? ["## AI Response Context", detailedContext, ""] : []),
-      "## What Went Wrong?",
-      whatWentWrong || "",
-      "",
-      "## What Should Be Done Differently?",
-      whatToDoDifferently || "",
-      "",
-    ].join("\n"),
-    "utf-8"
-  );
+  const meta: Record<string, unknown> = {
+    rating,
+    context,
+    date: new Date().toISOString().slice(0, 10),
+    ts: new Date().toISOString(),
+    slug,
+  };
+  if (tags.length > 0) meta.tags = tags;
 
+  const body = [
+    "## Last User Message",
+    lastUser || "*(unavailable)*",
+    "",
+    "## Last Assistant Response",
+    lastAssistant || "*(unavailable)*",
+    "",
+    ...(detailedContext ? ["## AI Response Context", detailedContext, ""] : []),
+    "## What Went Wrong?",
+    whatWentWrong || "",
+    "",
+    "## What Should Be Done Differently?",
+    whatToDoDifferently || "",
+  ].join("\n");
+
+  writeFileSync(resolve(dir, "capture.md"), stringify(meta, body), "utf-8");
+
+  // DEPRECATED: legacy sentiment.json — remove once all readers use capture.md frontmatter
   writeFileSync(
     resolve(dir, "sentiment.json"),
-    JSON.stringify(
-      {
-        rating,
-        context,
-        ts: new Date().toISOString(),
-        slug,
-      },
-      null,
-      2
-    ),
+    JSON.stringify({ rating, context, ts: new Date().toISOString(), slug }, null, 2),
     "utf-8"
   );
 }

package/src/hooks/handlers/rating.ts

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { ensureDir, paths } from "../lib/paths";
@@ -244,24 +245,24 @@ function writeLearningMarkdown(
   const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
   const filename = `${fileTimestamp()}_${source}-rating-${rating}_${category}.md`;
 
-  const content = [
-    `# ${source === "explicit" ? "Low Rating" : "Implicit Low Rating"}: ${rating}/10`,
-    `**Title:** ${context.slice(0, 100) || "(low rating)"}`,
-    `**Date:** ${new Date().toISOString().slice(0, 10)}`,
-    `**Rating:** ${rating}/10`,
-    `**Source:** ${source}`,
-    `**Category:** ${category.toUpperCase()}`,
-    "",
+  const meta: Record<string, unknown> = {
+    title: context.slice(0, 100) || "(low rating)",
+    category,
+    date: new Date().toISOString().slice(0, 10),
+    rating,
+    source,
+  };
+
+  const body = [
     "## Context",
     context || "*(unavailable)*",
     "",
     ...(detailedContext ? ["## Analysis", detailedContext, ""] : []),
     "## Last Response",
     responsePreview || "*(unavailable)*",
-    "",
   ].join("\n");
 
-  writeFileSync(resolve(dir, filename), content, "utf-8");
+  writeFileSync(resolve(dir, filename), stringify(meta, body), "utf-8");
 }
 
 function handleRating(
@@ -295,14 +296,7 @@ function handleRating(
       ),
       "utf-8"
     );
-    // Also write learning markdown
-    writeLearningMarkdown(
-      rating,
-      source,
-      context,
-      detailedContext ?? "",
-      responsePreview
-    );
+    // No learning markdown for ≤3 — failure capture covers it with richer analysis + tags
   } else if (rating < 5) {
     // Low but not critical — write learning markdown
     writeLearningMarkdown(

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

@@ -0,0 +1,61 @@
+/**
+ * Stop handler: check if README.md is out of sync with code.
+ *
+ * Runs git diff to see if documentable files changed in this session.
+ * If they did and README is stale, returns a block decision.
+ */
+
+import { execSync } from "node:child_process";
+import { logDebug } from "../lib/log";
+import { palPkg } from "../lib/paths";
+import { validateReadmeSync, WATCHED_PATHS } from "../lib/readme-sync";
+
+/** Check if any watched files have uncommitted changes. */
+function hasDocumentableChanges(): boolean {
+  try {
+    const diff = execSync("git diff --name-only HEAD", {
+      cwd: palPkg(),
+      encoding: "utf-8",
+    }).trim();
+
+    const staged = execSync("git diff --name-only --cached", {
+      cwd: palPkg(),
+      encoding: "utf-8",
+    }).trim();
+
+    const changed = `${diff}\n${staged}`.split("\n").filter((f) => f.length > 0);
+
+    return changed.some((file) =>
+      WATCHED_PATHS.some((watched) => file === watched || file.startsWith(`${watched}/`))
+    );
+  } catch {
+    return false;
+  }
+}
+
+export interface ReadmeSyncDecision {
+  decision?: "block";
+  reason?: string;
+}
+
+/** Returns a block decision if README is stale, or empty object to allow stop. */
+export function checkReadmeSync(): ReadmeSyncDecision {
+  if (!hasDocumentableChanges()) {
+    logDebug("readme-sync", "No documentable changes detected");
+    return {};
+  }
+
+  logDebug("readme-sync", "Documentable files changed — validating README");
+  const result = validateReadmeSync();
+
+  if (!result.ok) {
+    logDebug("readme-sync", `README out of sync: ${result.issues.join("; ")}`);
+    return {
+      decision: "block",
+      reason: `README.md is out of date. Please update it before finishing:\n${result.issues.map((i) => `- ${i}`).join("\n")}`,
+    };
+  }
+
+  logDebug("readme-sync", "README is in sync");
+  return {};
+}