portable-agent-layer 0.24.2 → 0.25.0

package/README.md

@@ -101,6 +101,7 @@ pal cli install               # all available (default)
 | Claude Code | Full | Yes | Yes | Yes | Yes |
 | opencode | Full | Yes | Yes (plugin) | Yes | Yes |
 | Cursor | Full | Yes | Yes | Yes (injected via hook) | Yes |
+| GitHub Copilot | Full | Yes | Yes | Yes (via copilot-instructions.md) | Yes |
 | Codex | Partial | Yes | No | Yes | No |
 
 ---
@@ -125,6 +126,7 @@ pal cli install               # all available (default)
 | `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |
 | `PAL_OPENCODE_DIR` | Override opencode config dir (default: `~/.config/opencode`) |
 | `PAL_CURSOR_DIR` | Override Cursor config dir (default: `~/.cursor`) |
+| `PAL_COPILOT_DIR` | Override Copilot config dir (default: `~/.copilot`) |
 | `PAL_CODEX_DIR` | Override Codex config dir (default: `~/.codex`) |
 | `PAL_AGENTS_DIR` | Override agents dir (default: `~/.agents`) |
 

package/assets/templates/hooks.copilot.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+      },
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      }
+    ],
+    "agentStop": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -212,46 +212,49 @@ function showHelp() {
     PAL_CLAUDE_DIR        Override Claude config dir (default: ~/.claude)
     PAL_OPENCODE_DIR      Override opencode config dir (default: ~/.config/opencode)
     PAL_CURSOR_DIR        Override Cursor config dir (default: ~/.cursor)
+    PAL_COPILOT_DIR       Override Copilot config dir (default: ~/.copilot)
     PAL_AGENTS_DIR        Override agents dir (default: ~/.agents)
 `);
 }
 
-function parseTargets(args: string[]): {
-  claude: boolean;
-  opencode: boolean;
-  cursor: boolean;
-} {
+type Targets = { claude: boolean; opencode: boolean; cursor: boolean; copilot: boolean };
+
+function parseTargets(args: string[]): Targets {
   let claude = false;
   let opencode = false;
   let cursor = false;
+  let copilot = false;
   for (const arg of args) {
     if (arg === "--claude") claude = true;
     else if (arg === "--opencode") opencode = true;
     else if (arg === "--cursor") cursor = true;
+    else if (arg === "--copilot") copilot = true;
     else if (arg === "--all") {
       claude = true;
       opencode = true;
       cursor = true;
+      copilot = true;
     }
   }
-  if (!claude && !opencode && !cursor)
-    return { claude: true, opencode: true, cursor: true };
-  return { claude, opencode, cursor };
+  if (!claude && !opencode && !cursor && !copilot)
+    return { claude: true, opencode: true, cursor: true, copilot: true };
+  return { claude, opencode, cursor, copilot };
 }
 
 /** Resolve targets against available agents. Errors if explicitly requested but missing. */
-function resolveTargets(
-  args: string[],
-  health?: DoctorResult
-): { claude: boolean; opencode: boolean; cursor: boolean } {
+function resolveTargets(args: string[], health?: DoctorResult): Targets {
   const requested = parseTargets(args);
   const h = health || doctor(true);
   const explicit = args.some(
-    (a) => a === "--claude" || a === "--opencode" || a === "--cursor" || a === "--all"
+    (a) =>
+      a === "--claude" ||
+      a === "--opencode" ||
+      a === "--cursor" ||
+      a === "--copilot" ||
+      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);
@@ -264,19 +267,25 @@ function resolveTargets(
       log.error("Cursor is not installed. Run 'pal cli doctor' for details.");
       process.exit(1);
     }
+    if (requested.copilot && !h.copilot.available) {
+      log.error("Copilot is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
     return requested;
   }
 
   // Default (no flags) — install for available agents only
-  const targets = {
+  const targets: Targets = {
     claude: h.claude.available,
     opencode: h.opencode.available,
     cursor: h.cursor.available,
+    copilot: h.copilot.available,
   };
 
   if (!targets.claude) log.info("Skipping Claude Code (not installed)");
   if (!targets.opencode) log.info("Skipping opencode (not installed)");
   if (!targets.cursor) log.info("Skipping Cursor (not installed)");
+  if (!targets.copilot) log.info("Skipping Copilot (not installed)");
 
   return targets;
 }
@@ -320,6 +329,14 @@ function checkOpencodePluginInstalled(): boolean {
   return existsSync(resolve(platform.opencodeDir(), "plugins", "pal-plugin.ts"));
 }
 
+function checkCopilotHooksRegistered(): boolean {
+  return existsSync(resolve(platform.copilotDir(), "hooks", "pal-hooks.json"));
+}
+
+function checkCopilotInstructionsPresent(): boolean {
+  return existsSync(resolve(platform.copilotDir(), "copilot-instructions.md"));
+}
+
 function checkHookHealth(home: string): HookHealth {
   const logPath = resolve(home, "memory", "state", "debug.log");
 
@@ -357,6 +374,7 @@ interface DoctorResult {
   claude: ToolCheck;
   opencode: ToolCheck;
   cursor: ToolCheck;
+  copilot: ToolCheck;
   hasAgent: boolean;
 }
 
@@ -368,6 +386,7 @@ function doctor(silent = false): DoctorResult {
       claude: { name: "claude", available: true },
       opencode: { name: "opencode", available: true },
       cursor: { name: "cursor", available: true },
+      copilot: { name: "copilot", available: true },
       hasAgent: true,
     };
   }
@@ -376,7 +395,9 @@ function doctor(silent = false): DoctorResult {
   const claude = checkTool("claude");
   const opencode = checkTool("opencode");
   const cursor = checkTool("cursor");
-  const hasAgent = claude.available || opencode.available || cursor.available;
+  const copilot = checkTool("copilot", ["version"]);
+  const hasAgent =
+    claude.available || opencode.available || cursor.available || copilot.available;
 
   const home = palHome();
   const telosCount = (() => {
@@ -404,6 +425,9 @@ function doctor(silent = false): DoctorResult {
     cursor.available
       ? ok(`Cursor ${cursor.version || ""}`.trim())
       : fail("Cursor — not found");
+    copilot.available
+      ? ok(`Copilot ${copilot.version || ""}`.trim())
+      : fail("Copilot — not found");
     ok(`PAL home: ${home}`);
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
@@ -474,6 +498,12 @@ function doctor(silent = false): DoctorResult {
         ? ok(`Cursor skills: ${n}`)
         : warn("Cursor skills — none found (run 'pal cli install --cursor')");
     }
+    if (copilot.available) {
+      const n = countSkillsIn(resolve(platform.copilotDir(), "skills"));
+      n > 0
+        ? ok(`Copilot skills: ${n}`)
+        : warn("Copilot skills — none found (run 'pal cli install --copilot')");
+    }
 
     // Dependencies
     const nodeModulesPath = resolve(palPkg(), "node_modules");
@@ -497,6 +527,14 @@ function doctor(silent = false): DoctorResult {
         ? ok("Cursor hooks registered")
         : fail("Cursor hooks — not registered (run 'pal cli install --cursor')");
     }
+    if (copilot.available) {
+      checkCopilotHooksRegistered()
+        ? ok("Copilot hooks registered")
+        : fail("Copilot hooks — not registered (run 'pal cli install --copilot')");
+      checkCopilotInstructionsPresent()
+        ? ok("copilot-instructions.md present")
+        : warn("copilot-instructions.md missing (run 'pal cli install --copilot')");
+    }
 
     // API key checks
     process.env.PAL_ANTHROPIC_API_KEY
@@ -530,7 +568,7 @@ function doctor(silent = false): DoctorResult {
     console.log("");
   }
 
-  return { bun, claude, opencode, cursor, hasAgent };
+  return { bun, claude, opencode, cursor, copilot, hasAgent };
 }
 
 // ── Commands ──
@@ -566,7 +604,7 @@ async function init(args: string[]) {
   }
 }
 
-async function install(targets: { claude: boolean; opencode: boolean; cursor: boolean }) {
+async function install(targets: Targets) {
   // Ensure dependencies are installed
   const pkg = palPkg();
   log.info("Installing dependencies...");
@@ -604,6 +642,12 @@ async function install(targets: { claude: boolean; opencode: boolean; cursor: bo
     console.log("");
   }
 
+  if (targets.copilot) {
+    console.log("━━━ Copilot ━━━");
+    await import("../targets/copilot/install");
+    console.log("");
+  }
+
   log.success("Done. Existing config was preserved — only new entries were added.");
 }
 
@@ -628,6 +672,12 @@ async function uninstall(args: string[]) {
     console.log("");
   }
 
+  if (targets.copilot) {
+    console.log("━━━ Copilot ━━━");
+    await import("../targets/copilot/uninstall");
+    console.log("");
+  }
+
   log.success(
     `PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`
   );

package/src/hooks/LoadContext.ts

@@ -4,11 +4,17 @@
  * 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.
+ *
+ * Copilot: sessionStart output is ignored by the runtime. Instead, we write the merged
+ * context directly to ~/.copilot/copilot-instructions.md so it is picked up on load.
  */
 
+import { existsSync, lstatSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { buildSystemReminder } from "./lib/context";
 import { logDebug, logError } from "./lib/log";
+import { platform } from "./lib/paths";
 
 // --- Skip heavy context for subagents ---
 const isSubagent =
@@ -28,21 +34,32 @@ try {
   logError("LoadContext:regenerate", err);
 }
 
-// --- Context to stdout ---
+// --- Context to stdout (or file for Copilot) ---
 try {
   const reminder = buildSystemReminder();
   if (!reminder) process.exit(0);
 
-  if (process.env.CURSOR_VERSION) {
+  if (process.env.PAL_AGENT === "copilot") {
+    // Copilot: sessionStart output is ignored — write merged context to copilot-instructions.md
+    const instructionsPath = resolve(platform.copilotDir(), "copilot-instructions.md");
+    const agentsMd = buildClaudeMd();
+    const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
+    if (existsSync(instructionsPath) && lstatSync(instructionsPath).isSymbolicLink()) {
+      unlinkSync(instructionsPath);
+    }
+    writeFileSync(instructionsPath, context, "utf-8");
+    logDebug("LoadContext", `Copilot instructions written: ${context.length} chars`);
+  } else if (process.env.CURSOR_VERSION) {
     // Cursor: no native user-level rules — inject AGENTS.md + dynamic context
     const agentsMd = buildClaudeMd();
     const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
     process.stdout.write(JSON.stringify({ additional_context: context }));
+    logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
   } else {
     // Claude Code: raw text
     console.log(reminder);
+    logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
   }
-  logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
 } catch (err) {
   logError("LoadContext:reminder", err);
 }

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

@@ -76,6 +76,11 @@ function ensureSymlinks(): void {
   const { outputPath, symlinkPath } = getOutputPaths();
   ensureOneSymlink(symlinkPath, outputPath);
   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 */

package/src/hooks/lib/paths.ts

@@ -61,6 +61,7 @@ export const platform = {
   claudeDir: () => process.env.PAL_CLAUDE_DIR || resolve(h, ".claude"),
   opencodeDir: () => process.env.PAL_OPENCODE_DIR || resolve(h, ".config", "opencode"),
   cursorDir: () => process.env.PAL_CURSOR_DIR || resolve(h, ".cursor"),
+  copilotDir: () => process.env.PAL_COPILOT_DIR || resolve(h, ".copilot"),
   codexDir: () => process.env.PAL_CODEX_DIR || resolve(h, ".codex"),
   agentsDir: () => process.env.PAL_AGENTS_DIR || resolve(h, ".agents"),
 } as const;
@@ -74,6 +75,7 @@ export const assets = {
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
   claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
   cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
+  copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
   agentTools: () => pkg("src", "tools", "agent"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/targets/copilot/install.ts

@@ -0,0 +1,66 @@
+/**
+ * PAL — Copilot target installer
+ * Writes hooks to ~/.copilot/hooks/pal-hooks.json.
+ * Copies skills and agents. Symlinks copilot-instructions.md to AGENTS.md.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  copyAgentsForCopilot,
+  copyPalDocs,
+  copySkills,
+  countSkills,
+  generateSkillIndex,
+  loadCopilotHooksTemplate,
+  log,
+  scaffoldPalSettings,
+} from "../lib";
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const COPILOT_DIR = platform.copilotDir();
+const HOOKS_DIR = resolve(COPILOT_DIR, "hooks");
+const HOOKS_FILE = resolve(HOOKS_DIR, "pal-hooks.json");
+
+// --- Ensure dirs ---
+mkdirSync(HOOKS_DIR, { recursive: true });
+
+// --- Write hooks file ---
+const template = loadCopilotHooksTemplate(assets.copilotHooksTemplate(), PKG_ROOT);
+writeFileSync(HOOKS_FILE, `${JSON.stringify(template, null, 2)}\n`, "utf-8");
+log.success(`Written hooks to ${HOOKS_FILE}`);
+
+// --- Install skills ---
+const copilotSkillsDir = resolve(COPILOT_DIR, "skills");
+copySkills(copilotSkillsDir);
+generateSkillIndex();
+log.success("Installed skills to ~/.copilot/skills/");
+
+// --- Install agents ---
+const copilotAgentsDir = resolve(COPILOT_DIR, "agents");
+const agentCount = copyAgentsForCopilot(copilotAgentsDir);
+if (agentCount > 0) log.success(`Installed ${agentCount} agents to ~/.copilot/agents/`);
+
+// --- Copy PAL docs ---
+const palDocsCount = copyPalDocs();
+log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
+
+// --- Scaffold PAL settings ---
+scaffoldPalSettings();
+
+// --- Generate AGENTS.md + copilot-instructions.md symlink ---
+// ensureSymlinks() inside regenerateIfNeeded() handles the symlink once ~/.copilot/ exists
+regenerateIfNeeded();
+const instructionsPath = resolve(COPILOT_DIR, "copilot-instructions.md");
+log.success(
+  existsSync(instructionsPath)
+    ? "copilot-instructions.md symlink present"
+    : "Generated AGENTS.md (copilot-instructions.md symlink will be created on next session)"
+);
+
+log.success("Copilot installation complete");
+console.log("");
+log.info(`Skills: ${countSkills()}`);
+log.info(`Hooks: ${HOOKS_FILE}`);

package/src/targets/copilot/uninstall.ts

@@ -0,0 +1,60 @@
+/**
+ * PAL — Copilot uninstaller
+ * Removes pal-hooks.json, skill symlinks, agents, and copilot-instructions.md symlink.
+ */
+
+import { copyFileSync, existsSync, lstatSync, readlinkSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { platform } from "../../hooks/lib/paths";
+import { log, removeAgentsFromCopilot, removePalDocs, removeSkills } from "../lib";
+
+const COPILOT_DIR = platform.copilotDir();
+const HOOKS_FILE = resolve(COPILOT_DIR, "hooks", "pal-hooks.json");
+
+// --- Remove hooks file ---
+if (existsSync(HOOKS_FILE)) {
+  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
+  unlinkSync(HOOKS_FILE);
+  log.success("Removed pal-hooks.json");
+} else {
+  log.info("No pal-hooks.json found, nothing to do");
+}
+
+// --- Remove skill symlinks ---
+const copilotSkillsDir = resolve(COPILOT_DIR, "skills");
+const removed = removeSkills(copilotSkillsDir);
+if (removed.length > 0) {
+  log.success(`Removed ${removed.length} skill(s): ${removed.join(", ")}`);
+} else {
+  log.info("No PAL skills found");
+}
+
+// --- Remove agents ---
+const removedAgents = removeAgentsFromCopilot(resolve(COPILOT_DIR, "agents"));
+if (removedAgents.length > 0) {
+  log.success(`Removed ${removedAgents.length} agent(s): ${removedAgents.join(", ")}`);
+}
+
+// --- Remove copilot-instructions.md symlink (only if it points to AGENTS.md) ---
+const instructionsPath = resolve(COPILOT_DIR, "copilot-instructions.md");
+if (existsSync(instructionsPath)) {
+  try {
+    const stat = lstatSync(instructionsPath);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(instructionsPath);
+      if (target.includes("AGENTS.md")) {
+        unlinkSync(instructionsPath);
+        log.success("Removed copilot-instructions.md symlink");
+      } else {
+        log.info("copilot-instructions.md is not a PAL symlink — leaving it");
+      }
+    }
+  } catch {
+    // ignore
+  }
+}
+
+// --- Remove PAL docs ---
+removePalDocs();
+
+log.success("Copilot uninstall complete");

package/src/targets/lib.ts

@@ -432,7 +432,7 @@ export function countAgents(): number {
 
 // --- Agent platform extraction ---
 
-const AGENT_PLATFORMS = ["claude", "opencode", "cursor"] as const;
+const AGENT_PLATFORMS = ["claude", "opencode", "cursor", "copilot"] as const;
 type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
 
 /**
@@ -462,6 +462,7 @@ export function extractAgentForPlatform(
     claude: [],
     opencode: [],
     cursor: [],
+    copilot: [],
   };
   let currentPlatform: AgentPlatform | null = null;
 
@@ -542,10 +543,25 @@ export function copyAgentsForCursor(cursorAgentsDir: string): number {
   return installAgents(cursorAgentsDir, "cursor");
 }
 
+export function copyAgentsForCopilot(copilotAgentsDir: string): number {
+  return installAgents(copilotAgentsDir, "copilot");
+}
+
 export function removeAgentsFromCursor(cursorAgentsDir: string): string[] {
   return uninstallAgents(cursorAgentsDir, "cursor");
 }
 
+export function removeAgentsFromCopilot(copilotAgentsDir: string): string[] {
+  return uninstallAgents(copilotAgentsDir, "copilot");
+}
+
+/** Load and resolve the Copilot hooks template, substituting PKG_ROOT */
+export function loadCopilotHooksTemplate(templatePath: string, pkgRoot: string): unknown {
+  return JSON.parse(
+    readFileSync(templatePath, "utf-8").replaceAll("{{PKG_ROOT}}", pkgRoot)
+  );
+}
+
 // --- Skill Index ---
 
 interface SkillIndexEntry {