portable-agent-layer 0.1.0

package/src/cli/index.ts

@@ -0,0 +1,344 @@
+#!/usr/bin/env bun
+/**
+ * PAL CLI — Portable Agent Layer
+ *
+ * Usage: pal <command> [options]
+ *
+ * Commands:
+ *   init                 Scaffold PAL home, install hooks for all targets
+ *   install              Register hooks/skills for targets
+ *   uninstall            Remove hooks/skills for targets
+ *   export               Export user state (telos, memory) to a zip
+ *   import               Import user state from a zip
+ *   status               Show current PAL configuration
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { palHome, palPkg, platform } from "../hooks/lib/paths";
+import { log } from "../targets/lib";
+
+const [command, ...args] = process.argv.slice(2);
+
+function banner() {
+  console.log("");
+  console.log("  ╔═══════════════════════════════════╗");
+  console.log("  ║  PAL — Portable Agent Layer       ║");
+  console.log("  ║  Non-destructive · Modular        ║");
+  console.log("  ╚═══════════════════════════════════╝");
+  console.log("");
+}
+
+function showHelp() {
+  console.log(`
+  Usage: pal <command> [options]
+
+  Commands:
+    init [--claude] [--opencode] [--all]    Scaffold and install (default: all)
+    install [--claude] [--opencode] [--all]  Register hooks for targets
+    uninstall [--claude] [--opencode] [--all] Remove hooks for targets
+    export [path] [--dry-run]               Export state to zip
+    import [path] [--dry-run]               Import state from zip
+    status                                  Show PAL configuration
+  Environment:
+    PAL_HOME              Override user state directory (default: ~/.pal or repo root)
+    PAL_PKG               Override package root
+    PAL_CLAUDE_DIR        Override Claude config dir (default: ~/.claude)
+    PAL_OPENCODE_DIR      Override opencode config dir (default: ~/.config/opencode)
+    PAL_AGENTS_DIR        Override agents dir (default: ~/.agents)
+`);
+}
+
+function parseTargets(args: string[]): {
+  claude: boolean;
+  opencode: boolean;
+} {
+  if (args.length === 0) return { claude: true, opencode: true };
+
+  let claude = false;
+  let opencode = false;
+  for (const arg of args) {
+    if (arg === "--claude") claude = true;
+    else if (arg === "--opencode") opencode = true;
+    else if (arg === "--all") {
+      claude = true;
+      opencode = true;
+    }
+  }
+  // If no target flags, default to all
+  if (!claude && !opencode) return { claude: true, opencode: true };
+  return { claude, opencode };
+}
+
+// ── Commands ──
+
+async function init() {
+  const { ensureSetupState, isSetupComplete } = await import("../hooks/lib/setup");
+  const { scaffoldTelos } = await import("../targets/lib");
+
+  banner();
+
+  const home = palHome();
+  const isRepo = existsSync(resolve(palPkg(), ".palroot"));
+
+  if (!isRepo) {
+    // Package mode — scaffold ~/.pal/
+    log.info(`Creating PAL home at ${home}`);
+    mkdirSync(resolve(home, "telos"), { recursive: true });
+    mkdirSync(resolve(home, "memory"), { recursive: true });
+  }
+
+  scaffoldTelos();
+  ensureSetupState();
+
+  const targets = parseTargets(args);
+  await install(targets);
+
+  console.log("");
+  const state = ensureSetupState();
+  if (!isSetupComplete(state)) {
+    log.info("Start a session — PAL will guide you through first-run setup");
+  }
+}
+
+async function install(targets?: { claude: boolean; opencode: boolean }) {
+  const t = targets || parseTargets(args);
+
+  if (t.claude) {
+    console.log("━━━ Claude Code ━━━");
+    await import("../targets/claude/install");
+    console.log("");
+  }
+
+  if (t.opencode) {
+    console.log("━━━ opencode ━━━");
+    await import("../targets/opencode/install");
+    console.log("");
+  }
+
+  log.success("Done. Existing config was preserved — only new entries were added.");
+}
+
+async function uninstall() {
+  const targets = parseTargets(args);
+
+  if (targets.claude) {
+    console.log("━━━ Claude Code ━━━");
+    await import("../targets/claude/uninstall");
+    console.log("");
+  }
+
+  if (targets.opencode) {
+    console.log("━━━ opencode ━━━");
+    await import("../targets/opencode/uninstall");
+    console.log("");
+  }
+
+  log.success(
+    `PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`
+  );
+}
+
+async function exportState() {
+  const { collectExportFiles, exportZip, timestamp } = await import(
+    "../hooks/lib/export"
+  );
+
+  const dryRun = args.includes("--dry-run");
+  const pathArg = args.find((a) => !a.startsWith("-") && a !== "export");
+  const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
+
+  if (dryRun) {
+    const files = collectExportFiles();
+    if (files.length === 0) {
+      console.log("Nothing to export.");
+    } else {
+      console.log(`Would export ${files.length} files → ${outputPath}\n`);
+      for (const f of files) console.log(`  ${f}`);
+    }
+  } else {
+    const count = exportZip(outputPath);
+    if (count === 0) {
+      console.log("Nothing to export.");
+    } else {
+      console.log(`Exported ${count} files → ${outputPath}`);
+    }
+  }
+}
+
+async function importState() {
+  const { readdirSync, statSync } = await import("node:fs");
+  const { createInterface } = await import("node:readline");
+  const AdmZip = (await import("adm-zip")).default;
+
+  const home = palHome();
+  const dryRun = args.includes("--dry-run");
+  const pathArg = args.find((a) => !a.startsWith("-") && a !== "import");
+
+  function findLatest(): string | null {
+    const candidates: string[] = [];
+
+    try {
+      candidates.push(
+        ...readdirSync(home)
+          .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
+          .map((f) => resolve(home, f))
+      );
+    } catch {
+      /* empty */
+    }
+
+    try {
+      const backupDir = resolve(home, "backups");
+      candidates.push(
+        ...readdirSync(backupDir)
+          .filter(
+            (f) =>
+              (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
+              f.endsWith(".zip")
+          )
+          .map((f) => resolve(backupDir, f))
+      );
+    } catch {
+      /* empty */
+    }
+
+    if (candidates.length === 0) return null;
+    return candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+  }
+
+  let zipPath: string;
+
+  if (pathArg) {
+    zipPath = resolve(pathArg);
+  } else {
+    const latest = findLatest();
+    if (!latest) {
+      log.error("No export or backup files found. Provide a path: pal import <path>");
+      process.exit(1);
+    }
+    console.log(`Found: ${latest}`);
+    const zip = new AdmZip(latest);
+    console.log(
+      `Contains ${zip.getEntries().length} files, created ${statSync(latest).mtime.toISOString().slice(0, 16).replace("T", " ")}`
+    );
+
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const answer = await new Promise<string>((res) =>
+      rl.question("Import this file? [y/N] ", (a) => {
+        rl.close();
+        res(a);
+      })
+    );
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log("Cancelled.");
+      process.exit(0);
+    }
+    zipPath = latest;
+  }
+
+  const zip = new AdmZip(zipPath);
+  const entries = zip.getEntries();
+
+  if (entries.length === 0) {
+    console.log("Archive is empty.");
+    process.exit(0);
+  }
+
+  if (dryRun) {
+    console.log(`Would import ${entries.length} files → ${home}\n`);
+    for (const e of entries) console.log(`  ${e.entryName}`);
+  } else {
+    zip.extractAllTo(home, true);
+    console.log(`Imported ${entries.length} files → ${home}`);
+    log.info("Run 'pal install' to re-register hooks.");
+  }
+}
+
+async function status() {
+  const { existsSync, readdirSync, readFileSync } = await import("node:fs");
+
+  const home = palHome();
+  const pkg = palPkg();
+  const isRepo = existsSync(resolve(pkg, ".palroot"));
+
+  const pkgJson = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8"));
+
+  console.log("");
+  log.info(`Version:  ${pkgJson.version}`);
+  log.info(`Mode:     ${isRepo ? "repo" : "package"}`);
+  log.info(`Package:  ${pkg}`);
+  log.info(`Home:     ${home}`);
+  console.log("");
+
+  // Platform dirs
+  log.info(`Claude:   ${platform.claudeDir()}`);
+  log.info(`opencode: ${platform.opencodeDir()}`);
+  log.info(`Agents:   ${platform.agentsDir()}`);
+  console.log("");
+
+  // Counts
+  const count = (dir: string, ext?: string) => {
+    try {
+      const files = readdirSync(dir);
+      return ext ? files.filter((f) => f.endsWith(ext)).length : files.length;
+    } catch {
+      return 0;
+    }
+  };
+
+  log.info(`TELOS:    ${count(resolve(home, "telos"), ".md")} files`);
+
+  const skillsDir = resolve(platform.agentsDir(), "skills");
+  log.info(`Skills:   ${count(skillsDir)} installed`);
+
+  const agentsDir = resolve(platform.claudeDir(), "agents");
+  log.info(`Agents:   ${count(agentsDir, ".md")} installed`);
+
+  // Check if hooks are registered
+  const settingsPath = resolve(platform.claudeDir(), "settings.json");
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const hookCount = Object.values(settings.hooks || {}).flat().length;
+    log.info(`Hooks:    ${hookCount} registered`);
+  } catch {
+    log.info(`Hooks:    not configured`);
+  }
+  console.log("");
+}
+
+// ── Dispatch ──
+
+switch (command) {
+  case "init":
+    await init();
+    break;
+  case "install":
+    banner();
+    await install();
+    break;
+  case "uninstall":
+    await uninstall();
+    break;
+  case "export":
+    await exportState();
+    break;
+  case "import":
+    await importState();
+    break;
+  case "status":
+    await status();
+    break;
+  case "--help":
+  case "-h":
+  case "help":
+    showHelp();
+    break;
+  default:
+    if (command) log.error(`Unknown command: ${command}`);
+    showHelp();
+    process.exit(command ? 1 : 0);
+}

package/src/cli/install.ts

@@ -0,0 +1,86 @@
+/**
+ * PAL — main installer entry point (TypeScript)
+ * Usage: bun run install.ts [--claude] [--opencode] [--all]
+ * Default: installs for both targets.
+ */
+
+import { ensureSetupState, isSetupComplete } from "../hooks/lib/setup";
+import { log, scaffoldTelos } from "../targets/lib";
+
+// --- Parse args ---
+const args = process.argv.slice(2);
+let installClaude = false;
+let installOpencode = false;
+
+if (args.length === 0) {
+  installClaude = true;
+  installOpencode = true;
+}
+
+for (const arg of args) {
+  if (arg === "--claude") installClaude = true;
+  else if (arg === "--opencode") installOpencode = true;
+  else if (arg === "--all") {
+    installClaude = true;
+    installOpencode = true;
+  } else if (arg === "--help" || arg === "-h") {
+    console.log("Usage: bun run install.ts [--claude] [--opencode] [--all]");
+    console.log("");
+    console.log("  --claude    Install hooks/skills for Claude Code");
+    console.log("  --opencode  Install context/skills for opencode");
+    console.log("  --all       Install for both (default)");
+    process.exit(0);
+  } else {
+    log.error(`Unknown option: ${arg}`);
+    process.exit(1);
+  }
+}
+
+// --- Check bun ---
+if (installClaude) {
+  try {
+    Bun.version; // always available in bun
+  } catch {
+    log.error("bun is required: curl -fsSL https://bun.sh/install | bash");
+    process.exit(1);
+  }
+}
+
+console.log("");
+console.log("  ╔═══════════════════════════════════╗");
+console.log("  ║  PAL — Portable Agent Layer       ║");
+console.log("  ║  Non-destructive · Modular        ║");
+console.log("  ╚═══════════════════════════════════╝");
+console.log("");
+
+// --- Scaffold TELOS + seed setup state ---
+scaffoldTelos();
+ensureSetupState();
+
+// --- Run target installers ---
+if (installClaude) {
+  console.log("━━━ Claude Code ━━━");
+  await import("../targets/claude/install");
+  console.log("");
+}
+
+if (installOpencode) {
+  console.log("━━━ opencode ━━━");
+  await import("../targets/opencode/install");
+  console.log("");
+}
+
+log.success("Done. Existing config was preserved — only new entries were added.");
+console.log("");
+log.info("Next steps:");
+
+const state = ensureSetupState();
+if (!isSetupComplete(state)) {
+  log.info("  1. Start a session — PAL will guide you through first-run setup");
+  log.info("  2. Or fill in telos/*.md manually, then re-run install.ts");
+} else {
+  log.info("  1. Fill in telos/*.md with your info (if not already done)");
+  log.info("  2. Re-run install.ts to regenerate context files");
+}
+log.info("  3. Add skills by dropping .md files into skills/");
+log.info("  4. Uninstall: bun run uninstall.ts [--claude] [--opencode]");

package/src/cli/uninstall.ts

@@ -0,0 +1,45 @@
+/**
+ * PAL — main uninstaller entry point (TypeScript)
+ * Usage: bun run uninstall.ts [--claude] [--opencode] [--all]
+ */
+
+import { palHome } from "../hooks/lib/paths";
+import { log } from "../targets/lib";
+
+const args = process.argv.slice(2);
+let removeClaude = false;
+let removeOpencode = false;
+
+if (args.length === 0) {
+  removeClaude = true;
+  removeOpencode = true;
+}
+
+for (const arg of args) {
+  if (arg === "--claude") removeClaude = true;
+  else if (arg === "--opencode") removeOpencode = true;
+  else if (arg === "--all") {
+    removeClaude = true;
+    removeOpencode = true;
+  } else if (arg === "--help" || arg === "-h") {
+    console.log("Usage: bun run uninstall.ts [--claude] [--opencode] [--all]");
+    process.exit(0);
+  } else {
+    log.error(`Unknown option: ${arg}`);
+    process.exit(1);
+  }
+}
+
+if (removeClaude) {
+  console.log("━━━ Claude Code ━━━");
+  await import("../targets/claude/uninstall");
+  console.log("");
+}
+
+if (removeOpencode) {
+  console.log("━━━ opencode ━━━");
+  await import("../targets/opencode/uninstall");
+  console.log("");
+}
+
+log.success(`PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`);

package/src/hooks/LoadContext.ts

@@ -0,0 +1,41 @@
+/**
+ * Hook: SessionStart — Injects dynamic context + regenerates AGENTS.md if stale.
+ *
+ * Static context (TELOS, setup prompt) is loaded natively from AGENTS.md / CLAUDE.md.
+ * This hook injects dynamic context only: wisdom principles, relationship notes,
+ * learning digest, signal trends, failure patterns, active work state.
+ */
+
+import { regenerateIfNeeded } from "./lib/claude-md";
+import { buildGreeting, buildSystemReminder } from "./lib/context";
+import { logDebug, logError } from "./lib/log";
+
+// --- Skip heavy context for subagents ---
+const isSubagent =
+  process.env.CLAUDE_PROJECT_DIR?.includes("/.claude/Agents/") ||
+  process.env.CLAUDE_AGENT_TYPE !== undefined;
+
+if (isSubagent) {
+  logDebug("LoadContext", "Subagent session — skipping context loading");
+  process.exit(0);
+}
+
+// --- Regenerate CLAUDE.md if telos or setup changed ---
+try {
+  const rebuilt = regenerateIfNeeded();
+  if (rebuilt) logDebug("LoadContext", "AGENTS.md regenerated");
+} catch (err) {
+  logError("LoadContext:regenerate", err);
+}
+
+// --- Visible greeting to stderr ---
+process.stderr.write(`${buildGreeting().join("\n")}\n`);
+
+// --- Dynamic system-reminder to stdout (empty = nothing injected) ---
+try {
+  const reminder = buildSystemReminder();
+  if (reminder) console.log(reminder);
+  logDebug("LoadContext", `Reminder injected: ${reminder ? reminder.length : 0} chars`);
+} catch (err) {
+  logError("LoadContext:reminder", err);
+}

package/src/hooks/SecurityValidator.ts

@@ -0,0 +1,52 @@
+/**
+ * Hook: PreToolUse — Guards against dangerous commands.
+ * Returns JSON { decision: "block", reason: "..." } to block, or exits silently to allow.
+ *
+ * Fail-open design: if anything goes wrong, the command is allowed through.
+ */
+
+import { checkBashCommand, checkFilePath, WARN_COMMANDS } from "./lib/security";
+import { readStdinJSON } from "./lib/stdin";
+
+interface ToolUseInput {
+  tool_name: string;
+  tool_input: {
+    command?: string;
+    file_path?: string;
+  };
+}
+
+try {
+  const input = await readStdinJSON<ToolUseInput>();
+  if (!input) process.exit(0);
+
+  const { tool_name, tool_input } = input;
+
+  // Check Bash commands
+  if (tool_name === "Bash" && tool_input.command) {
+    const reason = checkBashCommand(tool_input.command);
+    if (reason) {
+      console.log(JSON.stringify({ decision: "block", reason: `Blocked: ${reason}` }));
+      process.exit(0);
+    }
+
+    for (const pattern of WARN_COMMANDS) {
+      if (pattern.test(tool_input.command)) {
+        // Log but don't block — Claude Code's own permission system handles confirmation
+        break;
+      }
+    }
+  }
+
+  // Check file path operations (Write, Edit)
+  if ((tool_name === "Write" || tool_name === "Edit") && tool_input.file_path) {
+    const fileReason = checkFilePath(tool_input.file_path);
+    if (fileReason) {
+      console.log(JSON.stringify({ decision: "block", reason: fileReason }));
+      process.exit(0);
+    }
+  }
+} catch {
+  // Fail open
+  process.exit(0);
+}

package/src/hooks/SkillGuard.ts

@@ -0,0 +1,41 @@
+/**
+ * Hook: PreToolUse (Skill) — Blocks false-positive skill invocations.
+ *
+ * keybindings-help appears first in every skills list and triggers on
+ * virtually any ambiguous prompt due to position bias + the Skill tool's
+ * aggressive "BLOCKING REQUIREMENT" language. This hook blocks it unless
+ * the user explicitly asked for keybinding help.
+ *
+ * Fail-open: on any error, the skill is allowed through.
+ */
+
+import { readStdinJSON } from "./lib/stdin";
+
+const BLOCKED_SKILLS = ["keybindings-help"];
+
+interface SkillInput {
+  tool_name: string;
+  tool_input: {
+    skill?: string;
+  };
+}
+
+try {
+  const input = await readStdinJSON<SkillInput>();
+  if (!input) process.exit(0);
+
+  const skill = (input.tool_input?.skill || "").toLowerCase().trim();
+
+  if (BLOCKED_SKILLS.includes(skill)) {
+    console.log(
+      JSON.stringify({
+        decision: "block",
+        reason:
+          'BLOCKED: "keybindings-help" is a known false-positive triggered by position bias. ' +
+          "The user did NOT ask about keybindings. Continue with their ACTUAL request.",
+      })
+    );
+  }
+} catch {
+  // Fail open
+}

package/src/hooks/StopOrchestrator.ts

@@ -0,0 +1,35 @@
+/**
+ * Hook: Stop — Single entry point for all stop-event handling.
+ * Fans out to independent handlers via Promise.allSettled.
+ *
+ * stdin: JSON object with { session_id, transcript_path, last_assistant_message, ... }
+ * Transcript is read from the file at transcript_path, NOT from stdin.
+ */
+
+import { logError } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+import { runStopHandlers } from "./lib/stop";
+import { readTranscriptFile } from "./lib/transcript";
+
+interface StopHookInput {
+  session_id: string;
+  transcript_path: string;
+  last_assistant_message?: string;
+}
+
+const input = await readStdinJSON<StopHookInput>();
+if (!input?.transcript_path) {
+  logError("StopOrchestrator", "No transcript_path in hook input");
+  process.exit(0);
+}
+
+// Read the actual transcript from the file on disk
+const messages = readTranscriptFile(input.transcript_path);
+if (messages.length < 2) process.exit(0);
+
+// Serialize and run handlers
+const transcript = JSON.stringify(messages);
+await runStopHandlers(transcript, {
+  lastAssistantMessage: input.last_assistant_message,
+  sessionId: input.session_id,
+});

package/src/hooks/UserPromptOrchestrator.ts

@@ -0,0 +1,35 @@
+/**
+ * Hook: UserPromptSubmit — Single entry point for all prompt-event handling.
+ * Fans out to independent handlers via Promise.allSettled.
+ *
+ * Handlers:
+ *  - rating: capture explicit/implicit sentiment ratings
+ *  - session-name: generate 4-word session headline on first prompt
+ */
+
+import { captureRating } from "./handlers/rating";
+import { captureSessionName } from "./handlers/session-name";
+import { logDebug, logError } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+interface PromptSubmitInput {
+  prompt: string;
+  session_id?: string;
+}
+
+const input = await readStdinJSON<PromptSubmitInput>();
+logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)}`);
+if (!input?.prompt) process.exit(0);
+
+const results = await Promise.allSettled([
+  captureRating(input.prompt, input.session_id),
+  captureSessionName(input.prompt, input.session_id ?? ""),
+]);
+
+const handlerNames = ["rating", "session-name"];
+for (let i = 0; i < results.length; i++) {
+  const r = results[i];
+  if (r.status === "rejected") {
+    logError(`UserPromptOrchestrator:${handlerNames[i]}`, r.reason);
+  }
+}