portable-agent-layer 0.85.23 → 0.86.0

package/src/targets/codex/uninstall.ts

@@ -1,7 +1,7 @@
 /**
  * PAL — Codex uninstaller
  * Removes only PAL-owned hooks from ~/.codex/hooks.json. Preserves user hooks.
- * Removes PAL skill symlinks.
+ * Removes PAL skill symlinks and PAL agents.
  */
 
 import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -11,6 +11,7 @@ import {
   loadCodexHooksTemplate,
   log,
   readJson,
+  removeAgentsFromCodex,
   removeCodexStatuslineConfig,
   removeSkills,
   unmergeCodexHooks,
@@ -87,6 +88,12 @@ if (removed.length > 0) {
   log.info("No PAL skills found");
 }
 
+// --- Remove PAL agents ---
+const removedAgents = removeAgentsFromCodex(resolve(CODEX_DIR, "agents"));
+if (removedAgents.length > 0) {
+  log.success(`Removed ${removedAgents.length} agent(s): ${removedAgents.join(", ")}`);
+}
+
 // --- Disable hooks in config.toml ---
 const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
 disableCodexHooks(CONFIG_FILE);

package/src/targets/lib.ts

@@ -18,8 +18,10 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { AGENT_PLATFORMS, type AgentPlatform } from "../hooks/lib/agent-definition";
 import { assets, palHome, platform } from "../hooks/lib/paths";
 import { declaredTriggers } from "../hooks/lib/skill-triggers";
+import { agentFileName, renderAgentForPlatform } from "./agent-render";
 
 // --- Colored logging ---
 
@@ -993,7 +995,7 @@ export function removeSkills(claudeSkillsDir: string): string[] {
 
 // --- Agents ---
 
-const claudeAgentsDir = () => resolve(platform.claudeDir(), "agents");
+const claudeAgentsDir = () => nativeAgentsDir("claude");
 
 /**
  * Install PAL agent definitions into ~/.claude/agents/.
@@ -1031,81 +1033,28 @@ export function countAgents(): number {
   }
 }
 
-// --- Agent platform extraction ---
+// --- Agent platform rendering ---
 
-const AGENT_PLATFORMS = ["claude", "opencode", "cursor", "copilot"] as const;
-type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
-
-/**
- * Extract a platform-specific agent file from the unified agent format.
- *
- * Each agent .md defines platform blocks at the top level:
- *   claude:     → fields for Claude Code
- *   opencode:   → fields for opencode
- *   cursor:     → fields for Cursor
- *
- * Global fields (name, description) are always included.
- * The target platform block is un-indented and merged into the root.
- * All other platform blocks are stripped.
- */
-function extractAgentForPlatform(content: string, platform: AgentPlatform): string {
-  const parts = content.split(/^---\s*$/m);
-  if (parts.length < 3) return content;
-
-  const frontmatter = parts[1];
-  const body = parts.slice(2).join("---");
-
-  const globalLines: string[] = [];
-  const platformLines: Record<AgentPlatform, string[]> = {
-    claude: [],
-    opencode: [],
-    cursor: [],
-    copilot: [],
-  };
-  let currentPlatform: AgentPlatform | null = null;
-
-  for (const line of frontmatter.split("\n")) {
-    if (!line.trim()) continue;
-
-    const platformMatch = new RegExp(/^(claude|opencode|cursor|copilot):\s*$/).exec(line);
-    if (platformMatch) {
-      currentPlatform = platformMatch[1] as AgentPlatform;
-      continue;
-    }
-
-    if (currentPlatform) {
-      if (new RegExp(/^ {2}/).exec(line)) {
-        platformLines[currentPlatform].push(line.slice(2)); // un-indent one level
-        continue;
-      }
-      currentPlatform = null; // end of platform block
-    }
-
-    globalLines.push(line);
-  }
-
-  const newFrontmatter = [...globalLines, ...platformLines[platform]]
-    .filter((l) => l.trim())
-    .join("\n");
+const shippedAgentStems = () =>
+  readdirSync(assets.agents())
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""));
 
-  return `---\n${newFrontmatter}\n---\n${body}`;
-}
+const shippedAgentSource = (stem: string) =>
+  readFileSync(resolve(assets.agents(), `${stem}.md`), "utf-8");
 
 /** Install agents for a platform into a target directory. Always overwrites. */
 function installAgents(targetDir: string, platform: AgentPlatform): number {
-  const agentsDir = assets.agents();
-  if (!existsSync(agentsDir)) return 0;
+  if (!existsSync(assets.agents())) return 0;
 
   mkdirSync(targetDir, { recursive: true });
   let count = 0;
 
-  for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-    const name = file.replace(/\.md$/, "");
-    const installed = reportOnlyOnFailure(`${platform} agent ${name}`, () => {
-      const content = readFileSync(resolve(agentsDir, file), "utf-8");
+  for (const stem of shippedAgentStems()) {
+    const installed = reportOnlyOnFailure(`${platform} agent ${stem}`, () => {
       writeFileSync(
-        resolve(targetDir, file),
-        extractAgentForPlatform(content, platform),
+        resolve(targetDir, agentFileName(stem, platform)),
+        renderAgentForPlatform(shippedAgentSource(stem), platform),
         "utf-8"
       );
     });
@@ -1114,18 +1063,31 @@ function installAgents(targetDir: string, platform: AgentPlatform): number {
   return count;
 }
 
+/** Shipped agents in targetDir that differ from what installAgents would write there. */
+export function staleShippedAgents(targetDir: string, agent: AgentPlatform): string[] {
+  if (!existsSync(assets.agents())) return [];
+  const isStale = (stem: string) => {
+    const installed = resolve(targetDir, agentFileName(stem, agent));
+    return (
+      !existsSync(installed) ||
+      readFileSync(installed, "utf-8") !==
+        renderAgentForPlatform(shippedAgentSource(stem), agent)
+    );
+  };
+  return shippedAgentStems().filter(isStale).sort();
+}
+
 /** Remove PAL agents from a directory. */
-function uninstallAgents(targetDir: string, label: string): string[] {
-  const agentsDir = assets.agents();
-  if (!existsSync(agentsDir)) return [];
+function uninstallAgents(targetDir: string, platform: AgentPlatform): string[] {
+  if (!existsSync(assets.agents())) return [];
 
   const removed: string[] = [];
-  for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-    const dst = resolve(targetDir, file);
+  for (const stem of shippedAgentStems()) {
+    const dst = resolve(targetDir, agentFileName(stem, platform));
     if (existsSync(dst)) {
       unlinkSync(dst);
-      removed.push(file.replace(/\.md$/, ""));
-      log.detail(`Removed ${label} agent: ${file.replace(/\.md$/, "")}`);
+      removed.push(stem);
+      log.detail(`Removed ${platform} agent: ${stem}`);
     }
   }
   return removed;
@@ -1147,6 +1109,10 @@ export function copyAgentsForCopilot(copilotAgentsDir: string): number {
   return installAgents(copilotAgentsDir, "copilot");
 }
 
+export function copyAgentsForCodex(codexAgentsDir: string): number {
+  return installAgents(codexAgentsDir, "codex");
+}
+
 export function removeAgentsFromCursor(cursorAgentsDir: string): string[] {
   return uninstallAgents(cursorAgentsDir, "cursor");
 }
@@ -1155,6 +1121,10 @@ export function removeAgentsFromCopilot(copilotAgentsDir: string): string[] {
   return uninstallAgents(copilotAgentsDir, "copilot");
 }
 
+export function removeAgentsFromCodex(codexAgentsDir: string): string[] {
+  return uninstallAgents(codexAgentsDir, "codex");
+}
+
 // --- Personal subagents (user-authored, under ~/.pal/agents/) ---
 
 /**
@@ -1169,12 +1139,19 @@ const palAgentsStore = () => resolve(palHome(), "agents");
  * exists (mirrors linkPersonalSkill's per-agent gate).
  */
 function personalSubagentTargets(): { agent: AgentPlatform; dir: string }[] {
-  return [
-    { agent: "claude", dir: resolve(platform.claudeDir(), "agents") },
-    { agent: "opencode", dir: resolve(platform.opencodeDir(), "agents") },
-    { agent: "cursor", dir: resolve(platform.cursorDir(), "agents") },
-    { agent: "copilot", dir: resolve(platform.copilotDir(), "agents") },
-  ];
+  return AGENT_PLATFORMS.map((agent) => ({ agent, dir: nativeAgentsDir(agent) }));
+}
+
+/** The directory each agent reads its subagent definitions from. */
+export function nativeAgentsDir(agent: AgentPlatform): string {
+  const home = {
+    claude: platform.claudeDir,
+    opencode: platform.opencodeDir,
+    cursor: platform.cursorDir,
+    copilot: platform.copilotDir,
+    codex: platform.codexDir,
+  }[agent];
+  return resolve(home(), "agents");
 }
 
 /** Names of the subagents PAL ships (assets/agents/*.md). */
@@ -1215,17 +1192,23 @@ export function installPersonalSubagent(name: string): string[] {
     );
   }
   const content = readFileSync(src, "utf-8");
-  const installed: string[] = [];
-  for (const { agent, dir } of personalSubagentTargets()) {
-    if (!existsSync(dir)) continue; // agent not installed
-    writeFileSync(
-      resolve(dir, `${name}.md`),
-      extractAgentForPlatform(content, agent),
-      "utf-8"
-    );
-    installed.push(agent);
+  const renders = personalSubagentTargets()
+    .filter(({ dir }) => existsSync(dir))
+    .map(({ agent, dir }) => ({
+      agent,
+      file: resolve(dir, agentFileName(name, agent)),
+      text: renderForPersonalSubagent(content, agent),
+    }));
+  for (const { file, text } of renders) writeFileSync(file, text, "utf-8");
+  return renders.map(({ agent }) => agent);
+}
+
+function renderForPersonalSubagent(content: string, agent: AgentPlatform): string {
+  try {
+    return renderAgentForPlatform(content, agent);
+  } catch (e) {
+    throw new Error(`Cannot build the ${agent} subagent: ${(e as Error).message}`);
   }
-  return installed;
 }
 
 /** Load and resolve the Copilot hooks template, substituting PKG_ROOT */

package/src/tools/control-room/static.ts

@@ -6,7 +6,8 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
+import { isInside } from "../../hooks/lib/paths";
 
 const UI_DIST = resolve(import.meta.dir, "ui", "dist");
 
@@ -57,12 +58,6 @@ export function indexHtml(): Response {
  */
 export function staticAsset(pathname: string): Response | null {
   const target = resolve(UI_DIST, `.${pathname}`);
-  if (!isInsideDist(target)) return null;
+  if (!isInside(UI_DIST, target)) return null;
   return existsSync(target) ? new Response(Bun.file(target)) : null;
 }
-
-/** Compared as paths, not strings — a separator differs by platform. */
-function isInsideDist(target: string): boolean {
-  const rel = relative(UI_DIST, target);
-  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
-}

package/src/tools/lib/skill-doctor.ts

@@ -12,6 +12,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, relative, resolve } from "node:path";
+import { splitFrontmatter } from "../../hooks/lib/frontmatter";
 import { palHome, toPath } from "../../hooks/lib/paths";
 import { declaredTriggers } from "../../hooks/lib/skill-triggers";
 
@@ -90,8 +91,8 @@ export function findAbsolutePaths(skillDir: string): string[] {
 
 /** Split a SKILL.md into frontmatter fields and body. */
 export function parseSkill(content: string): ParsedSkill {
-  const parts = content.split(/^---\s*$/m);
-  if (parts.length < 3) {
+  const split = splitFrontmatter(content);
+  if (!split) {
     return {
       name: null,
       description: null,
@@ -103,8 +104,7 @@ export function parseSkill(content: string): ParsedSkill {
       body: content,
     };
   }
-  const frontmatter = parts[1];
-  const body = parts.slice(2).join("---");
+  const { frontmatter, body } = split;
   const name = /^name:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
   const rawDescription = /^description:[ \t]*(.*?)\s*$/m.exec(frontmatter)?.[1] ?? null;
   const descriptionQuoted =

package/src/tools/self-model.ts

@@ -84,7 +84,7 @@ async function composeSelfModel(days: number): Promise<string> {
   const result = await inference({
     system: buildPrompt(ai.name, principal.name),
     user: inferenceUserContent(rawData, readFileOrEmpty(selfModelPath())),
-    model: SONNET_MODEL,
+    tier: "medium",
     maxTokens: 1500,
     timeout: 90000,
     caller: "self-model",

package/src/tools/subagent-doctor.ts

@@ -2,7 +2,7 @@
  * subagent-doctor — static evaluator for a personal subagent definition
  * (~/.pal/agents/<name>.md) with merged multi-platform frontmatter. Checks only
  * what is mechanically verifiable: name/description constraints, per-platform
- * blocks (claude/opencode/cursor/copilot), model/tools/permission shape, body
+ * blocks (claude/opencode/cursor/copilot/codex), model/tools/permission shape, body
  * length, and absolute-path portability.
  *
  * Library:  import { lintSubagent, formatSubagentReport } from ".../subagent-doctor"
@@ -13,6 +13,11 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
+import {
+  AGENT_PLATFORMS,
+  type AgentPlatform,
+  parseAgentDefinition,
+} from "../hooks/lib/agent-definition";
 import { assets, namesAPath, palHome, toPath } from "../hooks/lib/paths";
 
 type Level = "pass" | "warn" | "error";
@@ -31,9 +36,6 @@ export interface SubagentReport {
   warnings: number;
 }
 
-const AGENT_PLATFORMS = ["claude", "opencode", "cursor", "copilot"] as const;
-type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
-
 interface ParsedSubagent {
   hasFrontmatter: boolean;
   name: string | null;
@@ -53,6 +55,9 @@ const MAX_BODY_LINES = 500;
 const KNOWN_MODELS = ["inherit", "fable", "sonnet", "opus", "haiku"];
 const PERMISSION_VALUES = ["allow", "ask", "deny"];
 const OPENCODE_MODES = ["subagent", "primary", "all"];
+const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"];
+const CODEX_TABLE_KEYS = ["tools", "skills"];
+const SHARED_FIELDS = ["name", "description"];
 
 /** Machine/user-specific absolute paths that will not survive an export. */
 const ABSOLUTE_PATH_RE =
@@ -71,42 +76,11 @@ function shippedAgentNames(): Set<string> {
 
 /** Split a merged subagent .md into global fields, per-platform blocks, and body. */
 function parseSubagent(content: string): ParsedSubagent {
-  const parts = content.split(/^---\s*$/m);
-  if (parts.length < 3) {
-    return {
-      hasFrontmatter: false,
-      name: null,
-      description: null,
-      descriptionQuoted: false,
-      global: [],
-      platforms: {},
-      body: content,
-    };
-  }
-  const frontmatter = parts[1];
-  const body = parts.slice(2).join("---");
-
-  const global: string[] = [];
-  const platforms: Partial<Record<AgentPlatform, string[]>> = {};
-  let current: AgentPlatform | null = null;
-
-  for (const line of frontmatter.split("\n")) {
-    if (!line.trim()) continue;
-    const pm = /^(claude|opencode|cursor|copilot):\s*$/.exec(line);
-    if (pm) {
-      current = pm[1] as AgentPlatform;
-      platforms[current] ??= [];
-      continue;
-    }
-    if (current) {
-      if (/^ {2}/.test(line)) {
-        platforms[current]?.push(line.slice(2));
-        continue;
-      }
-      current = null;
-    }
-    global.push(line);
+  const definition = parseAgentDefinition(content);
+  if (!definition.hasFrontmatter) {
+    return { ...definition, name: null, description: null, descriptionQuoted: false };
   }
+  const { global, platforms, body } = definition;
 
   const globalText = global.join("\n");
   const name = /^name:\s*"?(.+?)"?\s*$/m.exec(globalText)?.[1] ?? null;
@@ -139,6 +113,10 @@ function fieldValue(lines: string[], key: string): string | null {
   return null;
 }
 
+function topLevelKeys(lines: string[]): string[] {
+  return lines.flatMap((line) => /^([A-Za-z0-9_-]+):/.exec(line)?.[1] ?? []);
+}
+
 /** True when a block declares `key:` (with or without an inline value). */
 function hasField(lines: string[], key: string): boolean {
   return lines.some((l) => new RegExp(`^${key}:`).test(l));
@@ -202,6 +180,26 @@ function checkCopilotBlock(lines: string[], add: AddFinding): void {
   if (model) validateModel(model, "copilot", add);
 }
 
+function checkCodexBlock(lines: string[], add: AddFinding): void {
+  const model = fieldValue(lines, "model");
+  if (model) validateModel(model, "codex", add);
+  const sandbox = fieldValue(lines, "sandbox_mode");
+  if (sandbox !== null && !CODEX_SANDBOX_MODES.includes(sandbox)) {
+    add(
+      "warn",
+      "codex.sandbox_mode",
+      `sandbox_mode "${sandbox}" — expected one of ${CODEX_SANDBOX_MODES.join(", ")}`
+    );
+  }
+  for (const key of CODEX_TABLE_KEYS.filter((k) => hasField(lines, k))) {
+    add(
+      "warn",
+      `codex.${key}`,
+      `Codex reads \`${key}\` as a config table, not a list — the agent will not load; name tools or skills in the body instead`
+    );
+  }
+}
+
 function validateModel(model: string, platform: string, add: AddFinding): void {
   const known = KNOWN_MODELS.includes(model) || /^(claude-|gpt-|o\d|gemini-)/.test(model);
   if (!known) {
@@ -311,6 +309,17 @@ export function lintSubagent(file: string): SubagentReport {
         );
   }
 
+  const unmappedGlobals = topLevelKeys(parsed.global).filter(
+    (key) => !SHARED_FIELDS.includes(key)
+  );
+  if (unmappedGlobals.length > 0) {
+    add(
+      "error",
+      "global.fields",
+      `global ${unmappedGlobals.join(", ")} has no Codex key, so linking fails — move it into the platform blocks that use it`
+    );
+  }
+
   // ── platform blocks ──
   const present = AGENT_PLATFORMS.filter((p) => (platforms[p]?.length ?? 0) > 0);
   present.length > 0
@@ -318,13 +327,14 @@ export function lintSubagent(file: string): SubagentReport {
     : add(
         "warn",
         "platforms",
-        "no platform block — the subagent installs with only name/description; add a claude:/opencode:/cursor:/copilot: block to set model, tools, mode"
+        "no platform block — the subagent installs with only name/description; add a claude:/opencode:/cursor:/copilot:/codex: block to set model, tools, mode"
       );
 
   if (platforms.claude) checkClaudeBlock(platforms.claude, add);
   if (platforms.opencode) checkOpencodeBlock(platforms.opencode, add);
   if (platforms.cursor) checkCursorBlock(platforms.cursor, add);
   if (platforms.copilot) checkCopilotBlock(platforms.copilot, add);
+  if (platforms.codex) checkCodexBlock(platforms.codex, add);
 
   // ── skills field: Claude preloads it; the others have no such field ──
   for (const p of ["opencode", "cursor", "copilot"] as const) {