portable-agent-layer 0.34.0 → 0.36.0

package/src/targets/copilot/uninstall.ts

@@ -1,12 +1,22 @@
 /**
  * PAL — Copilot uninstaller
- * Removes pal-hooks.json, skill symlinks, agents, and copilot-instructions.md symlink.
+ * Removes pal-hooks.json, skill symlinks, agents, instruction files,
+ * and the VS Code chat.instructionsFilesLocations entry.
  */
 
 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";
+import { copilotFilename, getSemiStaticSources } from "../../hooks/lib/semi-static";
+import {
+  log,
+  readJson,
+  removeAgentsFromCopilot,
+  removePalDocs,
+  removeSkills,
+  vscodeSettingsFile,
+  writeJson,
+} from "../lib";
 
 const COPILOT_DIR = platform.copilotDir();
 const HOOKS_FILE = resolve(COPILOT_DIR, "hooks", "pal-hooks.json");
@@ -35,26 +45,57 @@ 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)) {
+// --- Remove PAL docs ---
+removePalDocs();
+
+// --- Remove ~/.copilot/instructions/pal-*.instructions.md ---
+for (const src of getSemiStaticSources()) {
+  try {
+    unlinkSync(resolve(COPILOT_DIR, "instructions", copilotFilename(src)));
+  } catch {
+    /* gone */
+  }
+}
+// pal-session.instructions.md is written by LoadContext (not a semi-static source)
+try {
+  unlinkSync(resolve(COPILOT_DIR, "instructions", "pal-session.instructions.md"));
+} catch {
+  /* gone */
+}
+log.success("Removed ~/.copilot/instructions/pal-*.instructions.md");
+
+// --- Backward compat: remove old copilot-instructions.md symlink if present ---
+const legacyPath = resolve(COPILOT_DIR, "copilot-instructions.md");
+if (existsSync(legacyPath)) {
   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");
-      }
+    if (
+      lstatSync(legacyPath).isSymbolicLink() &&
+      readlinkSync(legacyPath).includes("AGENTS.md")
+    ) {
+      unlinkSync(legacyPath);
+      log.success("Removed legacy copilot-instructions.md symlink");
     }
   } catch {
-    // ignore
+    /* ignore */
   }
 }
 
-// --- Remove PAL docs ---
-removePalDocs();
+// --- Remove ~/.copilot/instructions entry from VS Code settings ---
+const vsSettingsPath = vscodeSettingsFile();
+if (vsSettingsPath && existsSync(vsSettingsPath)) {
+  const settings = readJson<Record<string, unknown>>(vsSettingsPath, {});
+  const locs = settings["chat.instructionsFilesLocations"];
+  if (typeof locs === "object" && locs !== null) {
+    const obj = locs as Record<string, unknown>;
+    delete obj["~/.copilot/instructions"];
+    if (Object.keys(obj).length === 0) {
+      delete settings["chat.instructionsFilesLocations"];
+    } else {
+      settings["chat.instructionsFilesLocations"] = obj;
+    }
+    writeJson(vsSettingsPath, settings);
+    log.success("Removed ~/.copilot/instructions from VS Code settings");
+  }
+}
 
 log.success("Copilot uninstall complete");

package/src/targets/cursor/install.ts

@@ -6,6 +6,7 @@
 
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
+import { writeContextDigests } from "../../hooks/handlers/context-digests";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -64,6 +65,13 @@ scaffoldPalSettings();
 regenerateIfNeeded();
 log.success("Generated AGENTS.md");
 
+// --- Write ~/.cursor/rules/pal-*.mdc ---
+mkdirSync(resolve(CURSOR_DIR, "rules"), { recursive: true });
+writeContextDigests();
+log.success(
+  "Written ~/.cursor/rules/pal-self-model.mdc + pal-wisdom.mdc + pal-opinions.mdc"
+);
+
 log.success("Cursor installation complete");
 console.log("");
 log.info(`Skills: ${countSkills()}`);

package/src/targets/cursor/uninstall.ts

@@ -4,9 +4,10 @@
  * Removes PAL skill symlinks.
  */
 
-import { copyFileSync, existsSync } from "node:fs";
+import { copyFileSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import { cursorFilename, getSemiStaticSources } from "../../hooks/lib/semi-static";
 import {
   loadCursorHooksTemplate,
   log,
@@ -56,4 +57,20 @@ if (removedAgents.length > 0) {
 // --- Remove PAL system docs ---
 removePalDocs();
 
+// --- Remove ~/.cursor/rules/pal-*.mdc ---
+for (const src of getSemiStaticSources()) {
+  try {
+    unlinkSync(resolve(CURSOR_DIR, "rules", cursorFilename(src)));
+  } catch {
+    /* gone */
+  }
+}
+// Backward compat: remove legacy merged file if present
+try {
+  unlinkSync(resolve(CURSOR_DIR, "rules", "pal-context.mdc"));
+} catch {
+  /* gone */
+}
+log.success("Removed ~/.cursor/rules/pal-*.mdc");
+
 log.success("Cursor uninstall complete");

package/src/targets/lib.ts

@@ -14,6 +14,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { assets, palHome, platform } from "../hooks/lib/paths";
 
@@ -41,6 +42,31 @@ export function writeJson(path: string, data: unknown): void {
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 }
 
+/** Resolve the VS Code user settings.json path cross-platform. Returns null on unknown platforms. */
+export function vscodeSettingsFile(): string | null {
+  const h = homedir();
+  if (process.platform === "darwin") {
+    return resolve(h, "Library", "Application Support", "Code", "User", "settings.json");
+  }
+  if (process.platform === "linux") {
+    return resolve(
+      process.env.XDG_CONFIG_HOME ?? resolve(h, ".config"),
+      "Code",
+      "User",
+      "settings.json"
+    );
+  }
+  if (process.platform === "win32") {
+    return resolve(
+      process.env.APPDATA ?? resolve(h, "AppData", "Roaming"),
+      "Code",
+      "User",
+      "settings.json"
+    );
+  }
+  return null;
+}
+
 // --- Settings template merge/unmerge ---
 
 type HookEntry = { matcher?: string; hooks?: Array<{ type: string; command: string }> };

package/src/targets/opencode/install.ts

@@ -3,10 +3,18 @@
  * Deploys plugin, installs skills, generates AGENTS.md.
  */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { palPkg, platform } from "../../hooks/lib/paths";
+import { getSemiStaticSources } from "../../hooks/lib/semi-static";
 import {
   copyAgentsForOpencode,
   copyPalDocs,
@@ -70,6 +78,26 @@ log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md");
 
+// --- 7. Add semi-static digest files to instructions[] in config.json ---
+const configPath = resolve(OC_GLOBAL_DIR, "config.json");
+const staticFiles = getSemiStaticSources().map((s) => s.path);
+let ocConfig: Record<string, unknown> = {};
+if (existsSync(configPath) && statSync(configPath).size > 0) {
+  try {
+    ocConfig = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    /* start fresh */
+  }
+}
+const existingInstructions = Array.isArray(ocConfig.instructions)
+  ? (ocConfig.instructions as string[])
+  : [];
+ocConfig.instructions = [...new Set([...existingInstructions, ...staticFiles])];
+writeFileSync(configPath, `${JSON.stringify(ocConfig, null, 2)}\n`, "utf-8");
+log.success(
+  `Updated config.json: ${(ocConfig.instructions as string[]).length} instructions`
+);
+
 log.success("opencode installation complete");
 console.log("");
 log.info(`Plugin: ${pluginDst}`);

package/src/targets/opencode/plugin.ts

@@ -74,7 +74,7 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
   return {
     // --- Per-message: Inject dynamic system reminder ---
     "experimental.chat.system.transform": async (_input, output) => {
-      const reminder = buildSystemReminder();
+      const reminder = buildSystemReminder({ agent: "opencode" });
       if (reminder) output.system.push(reminder);
     },
 

package/src/targets/opencode/uninstall.ts

@@ -1,11 +1,12 @@
 /**
  * PAL — opencode uninstaller (TypeScript)
- * Removes plugin and AGENTS.md.
+ * Removes plugin, AGENTS.md, and PAL entries from config.json.
  */
 
-import { unlinkSync } from "node:fs";
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { platform } from "../../hooks/lib/paths";
+import { getSemiStaticSources } from "../../hooks/lib/semi-static";
 import { log, removeAgentsFromOpencode, removePalDocs, removeSkills } from "../lib";
 
 const OC_GLOBAL_DIR = platform.opencodeDir() || "";
@@ -41,7 +42,7 @@ if (removedAgents.length > 0)
 // --- Remove PAL system docs ---
 removePalDocs();
 
-// --- Remove AGENTS.md and CLAUDE.md symlink ---
+// --- Remove AGENTS.md and CLAUDE.md ---
 const agentsMd = resolve(OC_GLOBAL_DIR, "AGENTS.md");
 const claudeMd = resolve(PAL_CLAUDE_DIR, "CLAUDE.md");
 try {
@@ -57,4 +58,30 @@ try {
   /* gone */
 }
 
+// --- Remove PAL entries from config.json instructions[] ---
+const configPath = resolve(OC_GLOBAL_DIR, "config.json");
+if (existsSync(configPath) && statSync(configPath).size > 0) {
+  try {
+    const ocConfig = JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+    if (Array.isArray(ocConfig.instructions)) {
+      const palFiles = new Set(getSemiStaticSources().map((s) => s.path));
+      const filtered = (ocConfig.instructions as string[]).filter(
+        (p) => !palFiles.has(p)
+      );
+      if (filtered.length === 0) {
+        delete ocConfig.instructions;
+      } else {
+        ocConfig.instructions = filtered;
+      }
+      writeFileSync(configPath, `${JSON.stringify(ocConfig, null, 2)}\n`, "utf-8");
+      log.success("Removed PAL entries from config.json instructions[]");
+    }
+  } catch {
+    log.warn("Could not clean config.json instructions[] — check manually");
+  }
+}
+
 log.success("opencode uninstall complete");

package/src/tools/agent/handoff-note.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+/**
+ * HandoffNote — Write or clear a handoff note for the current project.
+ *
+ * Called in the ALGORITHM LEARN phase when work is unfinished.
+ * Written by Claude in-session — no inference call needed.
+ *
+ * Usage:
+ *   bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains + next steps"
+ *   bun ~/.pal/tools/handoff-note.ts --done   # mark completed, suppress next-session injection
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { ensureDir, paths } from "../../hooks/lib/paths";
+
+interface HandoffEntry {
+  timestamp: string;
+  title: string;
+  status: "in-progress" | "completed";
+  handoff: string;
+  artifacts: string[];
+}
+
+function handoffPath(): string {
+  return resolve(ensureDir(paths.state()), "last-handoff.json");
+}
+
+function readHandoffs(): Record<string, HandoffEntry> {
+  const p = handoffPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeHandoffs(handoffs: Record<string, HandoffEntry>): void {
+  const entries = Object.entries(handoffs);
+  const trimmed = entries.length > 20 ? Object.fromEntries(entries.slice(-20)) : handoffs;
+  writeFileSync(handoffPath(), JSON.stringify(trimmed, null, 2), "utf-8");
+}
+
+export function writeHandoffNote(
+  cwd: string,
+  title: string,
+  text: string,
+  done: boolean
+): { success: boolean; message: string } {
+  const handoffs = readHandoffs();
+  handoffs[cwd] = {
+    timestamp: new Date().toISOString(),
+    title,
+    status: done ? "completed" : "in-progress",
+    handoff: text,
+    artifacts: [],
+  };
+  writeHandoffs(handoffs);
+  return {
+    success: true,
+    message: done ? "Handoff cleared (marked completed)" : "Handoff note written",
+  };
+}
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      title: { type: "string" },
+      text: { type: "string" },
+      done: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+HandoffNote — Write a handoff note for the current project
+
+Usage:
+  bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains"
+  bun ~/.pal/tools/handoff-note.ts --done    # mark session completed
+
+Arguments:
+  --title   Brief title of what was being worked on (5-10 words)
+  --text    What remains unfinished — decisions made, next steps, blockers
+  --done    Mark as completed; suppresses "pick up where you left off" injection
+
+Output: writes to memory/state/last-handoff.json keyed by cwd
+`);
+    process.exit(0);
+  }
+
+  if (values.done) {
+    const result = writeHandoffNote(
+      process.cwd(),
+      values.title || "session",
+      values.text || "",
+      true
+    );
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  }
+
+  if (!values.title || !values.text) {
+    console.error("Required: --title and --text (or --done to close)");
+    process.exit(1);
+  }
+
+  const result = writeHandoffNote(process.cwd(), values.title, values.text, false);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (import.meta.main) run();

package/src/tools/agent/relationship-note.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/**
+ * RelationshipNote — Write a B entry to today's relationship log.
+ *
+ * Called in the ALGORITHM LEARN phase. Claude writes the B entry directly
+ * from full session context — no inference call needed.
+ *
+ * Usage:
+ *   bun ~/.pal/tools/relationship-note.ts --b "what I did this session"
+ */
+
+import { parseArgs } from "node:util";
+import { appendNotes } from "../../hooks/lib/relationship";
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      b: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+RelationshipNote — Append a B entry to today's relationship log
+
+Usage:
+  bun ~/.pal/tools/relationship-note.ts --b "description"
+
+Arguments:
+  --b   What happened this session (1-2 sentences, first-person, specific)
+
+Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
+`);
+    process.exit(0);
+  }
+
+  if (!values.b) {
+    console.error("Required: --b");
+    process.exit(1);
+  }
+
+  appendNotes([{ type: "Session", text: values.b }]);
+
+  console.log(
+    JSON.stringify({ success: true, message: "Relationship note written" }, null, 2)
+  );
+}
+
+if (import.meta.main) run();

package/src/tools/relationship-reflect.ts

@@ -37,7 +37,7 @@ interface Rating {
 }
 
 interface ParsedNote {
-  type: "W" | "O" | "B";
+  type: "W" | "O" | "Session";
   text: string;
   confidence?: number;
   date: string;
@@ -94,7 +94,7 @@ export function loadNotes(daysBack: number): ParsedNote[] {
           const obMatch = line.match(/^- ([OB])\(c=([\d.]+)\):\s*(.+)$/);
           if (obMatch) {
             notes.push({
-              type: obMatch[1] as "O" | "B",
+              type: obMatch[1] as "O" | "Session",
               confidence: Number.parseFloat(obMatch[2]),
               text: obMatch[3],
               date: dateStr,

package/src/tools/self-model.ts

@@ -71,7 +71,7 @@ interface AlgorithmReflection {
 }
 
 interface RelationshipNote {
-  type: "O" | "W" | "B";
+  type: "O" | "W" | "Session";
   content: string;
   confidence?: number;
   date: string;
@@ -292,9 +292,9 @@ function readRelationshipNotes(since: Date): RelationshipNote[] {
           continue;
         }
 
-        const behaviorMatch = noteContent.match(/^B:\s*(.+)$/);
+        const behaviorMatch = noteContent.match(/^Session:\s*(.+)$/);
         if (behaviorMatch) {
-          notes.push({ type: "B", content: behaviorMatch[1], date: dateStr });
+          notes.push({ type: "Session", content: behaviorMatch[1], date: dateStr });
         }
       }
     }
@@ -376,7 +376,7 @@ function gatherData(days: number): SelfModelData {
     wisdomFrames,
     graduated,
     reflections,
-    behaviorNotes: relNotes.filter((n) => n.type === "B").map((n) => n.content),
+    behaviorNotes: relNotes.filter((n) => n.type === "Session").map((n) => n.content),
     wisdomNotes: relNotes.filter((n) => n.type === "W").map((n) => n.content),
     selfObservations: reflections.map((r) => r.q1).filter(Boolean),
     algorithmObservations: reflections.map((r) => r.q2).filter(Boolean),

package/assets/templates/telos/PROJECTS.md

@@ -1,7 +0,0 @@
-# Projects
-
-<!-- Current projects, their status, and how they relate to each other. -->
-
-| Project | Status | Priority | Notes |
-|---------|--------|----------|-------|
-|         |        |          |       |