portable-agent-layer 0.10.0 → 0.12.0

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

@@ -17,7 +17,6 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import { loadTelos } from "./context";
 import { assets, ensureDir, palHome, paths, platform } from "./paths";
 import { buildSetupPrompt, readSetupState } from "./setup";
 
@@ -71,54 +70,81 @@ export function needsRebuild(): boolean {
 
   const outputMtime = statSync(outputPath).mtimeMs;
 
-  // Collect source files: template + setup.json + all telos/*.md
+  // Collect source files: template + setup.json + identity + PAL docs
   const sources: string[] = [
     TEMPLATE_PATH,
-    resolve(dirname(TEMPLATE_PATH), "STEERING-RULES.md"),
     resolve(paths.state(), "setup.json"),
+    palSettingsPath(),
   ];
 
-  const telosDir = paths.telos();
-  if (existsSync(telosDir)) {
-    for (const f of readdirSync(telosDir).filter((f) => f.endsWith(".md"))) {
-      sources.push(resolve(telosDir, f));
+  // Track PAL doc sources for rebuild detection
+  const palDocsDir = assets.palDocs();
+  if (existsSync(palDocsDir)) {
+    for (const f of readdirSync(palDocsDir).filter((f) => f.endsWith(".md"))) {
+      sources.push(resolve(palDocsDir, f));
     }
   }
 
   return latestMtime(...sources) > outputMtime;
 }
 
-function memoryPaths(): string {
-  const mem = resolve(palHome(), "memory");
-  return [
-    `- **Wisdom frames**: \`${resolve(mem, "wisdom", "frames")}/\` — crystallized principles per domain (loaded every session)`,
-    `- **Relationship notes**: \`${resolve(mem, "relationship")}/YYYY-MM/YYYY-MM-DD.md\` — daily interaction observations (loaded every session)`,
-    `- **Session learnings**: \`${resolve(mem, "learning", "session")}/YYYY-MM/*.md\` — reusable insights from sessions (loaded every session)`,
-    `- **Failure captures**: \`${resolve(mem, "learning", "failures")}/YYYY-MM/{timestamp}_{slug}/capture.md\` — what went wrong and why`,
-    `- **Signals**: \`${resolve(mem, "signals")}/ratings.jsonl\` — append-only rating signal log (do not edit directly)`,
-  ].join("\n");
+interface Identity {
+  ai: { name: string; displayName: string; catchphrase: string };
+  principal: { name: string };
+}
+
+const IDENTITY_DEFAULTS: Identity = {
+  ai: { name: "Assistant", displayName: "ASSISTANT", catchphrase: "" },
+  principal: { name: "" },
+};
+
+function palSettingsPath(): string {
+  return resolve(palHome(), "memory", "pal-settings.json");
+}
+
+/** Load identity from pal-settings.json */
+export function loadIdentity(): Identity {
+  const p = palSettingsPath();
+  if (!existsSync(p)) return IDENTITY_DEFAULTS;
+
+  try {
+    const data = JSON.parse(readFileSync(p, "utf-8"));
+    const ai = data.identity?.ai ?? {};
+    const principal = data.identity?.principal ?? {};
+    const name = ai.name || IDENTITY_DEFAULTS.ai.name;
+    const catchphrase = (ai.catchphrase || "").replace("{name}", name);
+
+    return {
+      ai: {
+        name,
+        displayName: ai.displayName || IDENTITY_DEFAULTS.ai.displayName,
+        catchphrase,
+      },
+      principal: {
+        name: principal.name || IDENTITY_DEFAULTS.principal.name,
+      },
+    };
+  } catch {
+    return IDENTITY_DEFAULTS;
+  }
 }
 
 /** Render AGENTS.md from the template using current state */
 export function buildClaudeMd(): string {
   const template = existsSync(TEMPLATE_PATH)
     ? readFileSync(TEMPLATE_PATH, "utf-8")
-    : "# PAL Context\n\n{{SETUP_PROMPT}}\n{{TELOS}}\n## Memory\n\n{{MEMORY_PATHS}}\n";
+    : "# PAL Context\n\n{{SETUP_PROMPT}}\n";
 
   const state = readSetupState();
   const setupPrompt = state ? buildSetupPrompt(state) : null;
-  const telos = loadTelos();
-
-  const steeringPath = resolve(dirname(TEMPLATE_PATH), "STEERING-RULES.md");
-  const steeringRules = existsSync(steeringPath)
-    ? readFileSync(steeringPath, "utf-8").trim()
-    : "";
+  const identity = loadIdentity();
 
   return template
     .replace("{{SETUP_PROMPT}}", setupPrompt ? `${setupPrompt}\n` : "")
-    .replace("{{TELOS}}", telos ? `${telos}\n` : "")
-    .replace("{{MEMORY_PATHS}}", memoryPaths())
-    .replace("{{STEERING_RULES}}", steeringRules);
+    .replaceAll("{{IDENTITY_NAME}}", identity.ai.name)
+    .replaceAll("{{IDENTITY_DISPLAY}}", identity.ai.displayName)
+    .replaceAll("{{IDENTITY_CATCHPHRASE}}", identity.ai.catchphrase)
+    .replaceAll("{{PRINCIPAL_NAME}}", identity.principal.name);
 }
 
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */

package/src/hooks/lib/context.ts

@@ -4,6 +4,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { parse } from "./frontmatter";
 import { readFailures, readLearnings } from "./learning-store";
@@ -21,28 +22,44 @@ import {
   staleProjects,
 } from "./work-tracking";
 
-/** Load all populated TELOS files as a single markdown string */
-export function loadTelos(): string {
-  const telosDir = paths.telos();
-  if (!existsSync(telosDir)) return "";
+interface PalSettings {
+  loadAtStartup?: { files?: string[] };
+  dynamicContext?: Record<string, boolean>;
+}
+
+/** Load pal-settings.json from memory/ */
+function loadPalSettings(): PalSettings {
+  const p = resolve(paths.memory(), "pal-settings.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Check if a dynamic context section is enabled (defaults to true) */
+function isEnabled(settings: PalSettings, key: string): boolean {
+  return settings.dynamicContext?.[key] !== false;
+}
 
-  const files = readdirSync(telosDir)
-    .filter((f) => f.endsWith(".md"))
-    .sort();
+/** Load and concatenate loadAtStartup files */
+function loadStartupFiles(settings: PalSettings): string {
+  const files = settings.loadAtStartup?.files;
+  if (!files || files.length === 0) return "";
 
+  const home = homedir();
   const sections: string[] = [];
 
   for (const file of files) {
-    const content = readFileSync(resolve(telosDir, file), "utf-8").trim();
-    // Skip empty templates (only have a heading and comment)
-    const realLines = content
-      .split("\n")
-      .filter(
-        (l) =>
-          !l.startsWith("#") && !l.startsWith("<!--") && !l.startsWith("-->") && l.trim()
-      );
-    if (realLines.length === 0) continue;
-    sections.push(content);
+    const resolved = file.replace("~", home);
+    if (!existsSync(resolved)) continue;
+    try {
+      const content = readFileSync(resolved, "utf-8").trim();
+      if (content) sections.push(content);
+    } catch {
+      /* skip unreadable files */
+    }
   }
 
   return sections.join("\n\n---\n\n");
@@ -348,15 +365,22 @@ export function loadRelationshipContext(): string {
  * things that change per-session and can't live in a static file.
  */
 export function buildSystemReminder(): string {
-  const work = loadActiveWork();
-  const wisdom = loadWisdomContext();
-  const relationship = loadRelationshipContext();
-  const digest = loadLearningDigest();
-  const trends = loadSignalTrends();
-  const failures = loadFailurePatterns();
-  const synthesis = loadSynthesisRecommendations();
-  const opinions = loadOpinionContext();
+  const settings = loadPalSettings();
+  const startup = loadStartupFiles(settings);
+  const work = isEnabled(settings, "activeWork") ? loadActiveWork() : null;
+  const wisdom = isEnabled(settings, "wisdom") ? loadWisdomContext() : "";
+  const relationship = isEnabled(settings, "relationship")
+    ? loadRelationshipContext()
+    : "";
+  const digest = isEnabled(settings, "learningDigest") ? loadLearningDigest() : "";
+  const trends = isEnabled(settings, "signalTrends") ? loadSignalTrends() : "";
+  const failures = isEnabled(settings, "failurePatterns") ? loadFailurePatterns() : "";
+  const synthesis = isEnabled(settings, "synthesis")
+    ? loadSynthesisRecommendations()
+    : "";
+  const opinions = isEnabled(settings, "opinions") ? loadOpinionContext() : "";
   const parts: string[] = [];
+  if (startup) parts.push(startup);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
   if (relationship) parts.push(relationship);

package/src/hooks/lib/paths.ts

@@ -77,4 +77,6 @@ export const assets = {
   hooks: () => pkg("src", "hooks"),
   telosTemplates: () => pkg("assets", "templates", "telos"),
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
+  claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
+  palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/hooks/lib/security.ts

@@ -33,6 +33,7 @@ export const HOOK_MANAGED_FILES = [
   "update-available.json",
   "debug.log.prev",
   "opinions.json",
+  "pal-settings.json",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */
@@ -43,6 +44,7 @@ export const HOOK_MANAGED_DIRS = [
   "memory/learning/synthesis",
   "memory/relationship",
   "memory/wisdom/state",
+  ".agents/PAL",
 ];
 
 /** Escape a string for use in a RegExp */

package/src/hooks/lib/setup.ts

@@ -26,20 +26,8 @@ export interface SetupState {
 const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
   mission: {
     file: "telos/MISSION.md",
-    question: "What's your name and what do you do?",
-    hint: "Write their name, role, and core purpose to telos/MISSION.md",
-  },
-  ai_name: {
-    file: "telos/IDENTITY.md",
-    question:
-      "What would you like to call your AI? (Pick a name — this is how I'll identify myself.)",
-    hint: "Write the chosen AI name and identity to telos/IDENTITY.md with fields: name, fullName (name — Personal AI), displayName (UPPERCASED)",
-  },
-  catchphrase: {
-    file: "telos/IDENTITY.md",
-    question:
-      'What should your AI\'s startup catchphrase be? (e.g. "{name} here, ready to go" — {name} gets replaced with the AI name.)',
-    hint: "Append the catchphrase to telos/IDENTITY.md under a ## Catchphrase heading. Support {name} as a placeholder.",
+    question: "What do you do? What's your role and core purpose?",
+    hint: "Write their role and core purpose to telos/MISSION.md",
   },
   goals: {
     file: "telos/GOALS.md",
@@ -152,8 +140,8 @@ export function buildSetupPrompt(state: SetupState): string | null {
   const lines: string[] = [
     "## IMPORTANT: PAL First-Run Setup Required",
     "",
-    "TELOS files are empty — this user has not been set up yet.",
-    "You MUST start the setup process immediately, regardless of what the user says.",
+    "TELOS files are empty — the user's identity is already configured (via the installer),",
+    "but personal context is still needed. You MUST start the setup process immediately.",
     "Greet them, explain that PAL needs to learn about them to personalize future sessions,",
     "and ask the first remaining question below. Do NOT wait for the user to ask about setup.",
     "",

package/src/targets/claude/install.ts

@@ -1,21 +1,25 @@
 /**
  * PAL — Claude Code target installer (TypeScript)
- * Merges hooks into existing settings.json (never overwrites).
- * Copies skills additively. Generates CLAUDE.md from TELOS.
+ * Merges settings template into existing settings.json (never overwrites).
+ * Copies skills, agents, and PAL docs. Generates CLAUDE.md from TELOS.
  */
 
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
-import { palHome, palPkg, platform } from "../../hooks/lib/paths";
+import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
 import {
   copyAgents,
+  copyPalDocs,
   copySkills,
   countAgents,
   countMd,
   countSkills,
+  loadSettingsTemplate,
   log,
+  mergeSettings,
   readJson,
+  scaffoldPalSettings,
   writeJson,
 } from "../lib";
 
@@ -35,96 +39,13 @@ const backup = `${SETTINGS}.bak.${Date.now()}`;
 copyFileSync(SETTINGS, backup);
 log.info("Backed up settings.json");
 
-// --- Build hooks payload ---
-const hooksPayload = {
-  hooks: {
-    SessionStart: [
-      {
-        matcher: "",
-        hooks: [
-          { type: "command", command: `bun run ${PKG_ROOT}/src/hooks/LoadContext.ts` },
-        ],
-      },
-    ],
-    UserPromptSubmit: [
-      {
-        matcher: "",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/UserPromptOrchestrator.ts`,
-          },
-        ],
-      },
-    ],
-    PreToolUse: [
-      {
-        matcher: "Bash|Write|Edit",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/SecurityValidator.ts`,
-          },
-        ],
-      },
-      {
-        matcher: "Skill",
-        hooks: [
-          { type: "command", command: `bun run ${PKG_ROOT}/src/hooks/SkillGuard.ts` },
-        ],
-      },
-    ],
-    Stop: [
-      {
-        matcher: "",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/StopOrchestrator.ts`,
-          },
-        ],
-      },
-    ],
-  },
-};
+// --- Load template and merge into existing settings ---
+const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(SETTINGS, {});
+const merged = mergeSettings(existing, template);
 
-// --- Merge hooks additively (deduplicate by command) ---
-type HookEntry = { matcher: string; hooks: Array<{ type: string; command: string }> };
-type Settings = { hooks?: Record<string, HookEntry[]>; env?: Record<string, string> };
-
-const settings = readJson<Settings>(SETTINGS, {});
-if (!settings.hooks) settings.hooks = {};
-
-for (const [event, entries] of Object.entries(hooksPayload.hooks)) {
-  const existing = settings.hooks[event] ?? [];
-  for (const entry of entries) {
-    const cmd = entry.hooks[0]?.command;
-    const alreadyPresent = existing.some((e) => e.hooks?.[0]?.command === cmd);
-    if (!alreadyPresent) existing.push(entry);
-  }
-  settings.hooks[event] = existing;
-}
-
-// --- Add PAL tool permissions (auto-allow ai: scripts) ---
-type SettingsWithPermissions = Settings & { permissions?: { allow?: string[] } };
-const s = settings as SettingsWithPermissions;
-if (!s.permissions) s.permissions = {};
-if (!s.permissions.allow) s.permissions.allow = [];
-const aiTools = [
-  "ai:entity-save",
-  "ai:fyzz-api",
-  "ai:pdf-download",
-  "ai:youtube-analyze",
-];
-for (const tool of aiTools) {
-  const perm = `Bash(bun run ${tool} *)`;
-  if (!s.permissions.allow.includes(perm)) {
-    s.permissions.allow.push(perm);
-  }
-}
-
-writeJson(SETTINGS, settings);
-log.success("Merged hooks into settings.json");
+writeJson(SETTINGS, merged);
+log.success("Merged PAL settings into settings.json");
 
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
@@ -133,13 +54,19 @@ copySkills(skillsDir);
 // --- Copy agents ---
 copyAgents();
 
+// --- Copy PAL system docs ---
+const palDocsCount = copyPalDocs();
+log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+
+// --- Scaffold PAL settings ---
+scaffoldPalSettings();
+
 // --- Generate ~/.claude/AGENTS.md and symlink ~/.claude/CLAUDE.md → AGENTS.md ---
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md (→ ~/.claude/CLAUDE.md symlink)");
 
 log.success("Claude Code installation complete");
 console.log("");
-log.info(`Hooks: 5 (SessionStart, UserPromptSubmit, PreToolUse×2, Stop)`);
 log.info(`Skills: ${countSkills()}`);
 log.info(`Agents: ${countAgents()}`);
 log.info(`TELOS: ${countMd(resolve(palHome(), "telos"))} files`);

package/src/targets/claude/uninstall.ts

@@ -1,14 +1,23 @@
 /**
  * PAL — Claude Code uninstaller (TypeScript)
- * Removes PAL hooks, skills, and env from settings.json.
+ * Removes exactly what the settings template added, plus skills, agents, and PAL docs.
  */
 
 import { copyFileSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
-import { palPkg, platform } from "../../hooks/lib/paths";
-import { log, readJson, removeAgents, removeSkills, writeJson } from "../lib";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  loadSettingsTemplate,
+  log,
+  readJson,
+  removeAgents,
+  removePalDocs,
+  removeSkills,
+  unmergeSettings,
+  writeJson,
+} from "../lib";
 
-const PKG_ROOT = palPkg();
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CLAUDE_DIR = platform.claudeDir();
 const SETTINGS = resolve(CLAUDE_DIR, "settings.json");
 
@@ -21,50 +30,13 @@ if (!existsSync(SETTINGS)) {
 copyFileSync(SETTINGS, `${SETTINGS}.bak.${Date.now()}`);
 log.info("Backed up settings.json");
 
-// --- Remove PAL hooks ---
-type HookEntry = {
-  matcher?: string;
-  hooks?: Array<{ command?: string }>;
-  command?: string;
-};
-type Settings = { hooks?: Record<string, HookEntry[]>; env?: Record<string, string> };
+// --- Load template and unmerge from existing settings ---
+const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(SETTINGS, {});
+const cleaned = unmergeSettings(existing, template);
 
-const settings = readJson<Settings>(SETTINGS, {});
-
-if (settings.hooks) {
-  for (const [event, entries] of Object.entries(settings.hooks)) {
-    settings.hooks[event] = entries.filter((entry) => {
-      // New format: { matcher, hooks: [{ command }] }
-      if (entry.hooks) return !entry.hooks.some((h) => h.command?.includes(PKG_ROOT));
-      // Old flat format: { type, command }
-      if (entry.command) return !entry.command.includes(PKG_ROOT);
-      return true;
-    });
-    if (settings.hooks[event].length === 0) delete settings.hooks[event];
-  }
-  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-}
-
-// --- Remove env ---
-if (settings.env) {
-  // Clean up env vars
-  delete settings.env.PAL_DIR;
-  if (Object.keys(settings.env).length === 0) delete settings.env;
-}
-
-// --- Remove PAL tool permissions ---
-type SettingsWithPermissions = Settings & { permissions?: { allow?: string[] } };
-const s = settings as SettingsWithPermissions;
-if (s.permissions?.allow) {
-  s.permissions.allow = s.permissions.allow.filter(
-    (p) => !p.includes(PKG_ROOT) && !p.startsWith("Bash(bun run ai:")
-  );
-  if (s.permissions.allow.length === 0) delete s.permissions.allow;
-  if (Object.keys(s.permissions).length === 0) delete s.permissions;
-}
-
-writeJson(SETTINGS, settings);
-log.success("Removed PAL hooks and env from settings.json");
+writeJson(SETTINGS, cleaned);
+log.success("Removed PAL settings from settings.json");
 
 // --- Remove PAL skills ---
 const removed = removeSkills(resolve(CLAUDE_DIR, "skills"));
@@ -82,6 +54,9 @@ if (removedAgents.length > 0) {
   log.info("No PAL agents found");
 }
 
+// --- Remove PAL system docs ---
+removePalDocs();
+
 // --- Remove AGENTS.md and CLAUDE.md symlink ---
 const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
 const claudeMd = resolve(CLAUDE_DIR, "CLAUDE.md");