portable-agent-layer 0.20.0 → 0.22.0

package/src/hooks/lib/context.ts

@@ -15,12 +15,7 @@ import { readSessionNames } from "./session-names";
 import { buildSetupPrompt, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
 import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
-import {
-  activeProjects,
-  readSessions,
-  recentSessions,
-  staleProjects,
-} from "./work-tracking";
+import { readProjectHistory, readSessions, recentSessions } from "./work-tracking";
 
 interface PalSettings {
   loadAtStartup?: { files?: string[] };
@@ -82,44 +77,16 @@ export function loadActiveWork(): { text: string; summary: string | null } | nul
   try {
     const cwd = process.cwd();
     const allRecent = recentSessions(48);
-    const projects = activeProjects();
-    const stale = staleProjects(7);
 
-    if (allRecent.length === 0 && projects.length === 0) return null;
+    if (allRecent.length === 0) return null;
 
     const lines: string[] = [];
 
-    if (allRecent.length > 0) {
-      lines.push("## Recent Work (last 48h)");
-      for (const s of allRecent.slice(-10).reverse()) {
-        const ago = formatAgo(s.ts);
-        const here = s.cwd === cwd ? " *" : "";
-        lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
-      }
-    }
-
-    if (projects.length > 0) {
-      lines.push("", "### Active Projects");
-      for (const p of projects) {
-        const sessionCount = p.sessions.length;
-        const ago = formatAgo(p.updated);
-        lines.push(`- **${p.name}** (${sessionCount} sessions, last: ${ago})`);
-        if (p.nextSteps.length > 0) {
-          lines.push(`  Next: ${p.nextSteps[0]}`);
-        }
-        if (p.blockers.length > 0) {
-          lines.push(`  Blockers: ${p.blockers.join(", ")}`);
-        } else {
-          lines.push("  Blockers: None");
-        }
-      }
-    }
-
-    if (stale.length > 0) {
-      lines.push("", "### Stale Projects (>7d inactive)");
-      for (const p of stale) {
-        lines.push(`- **${p.name}** — last active ${formatAgo(p.updated)}`);
-      }
+    lines.push("## Recent Work (last 48h)");
+    for (const s of allRecent.slice(-10).reverse()) {
+      const ago = formatAgo(s.ts);
+      const here = s.cwd === cwd ? " *" : "";
+      lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
     }
 
     // Summary from most recent session
@@ -240,25 +207,15 @@ export function loadLearningDigest(): string {
     const entries = readLearnings(paths.sessionLearning(), 10);
     if (entries.length === 0) return "";
 
-    const thisProject = entries.filter((e) => e.cwd === cwd).slice(0, 4);
-    const other = entries.filter((e) => e.cwd !== cwd).slice(0, 3);
+    // This-project learnings are now in loadProjectHistoryContext(); only show cross-project here
+    const other = entries.filter((e) => e.cwd !== cwd).slice(0, 5);
 
-    if (thisProject.length === 0 && other.length === 0) return "";
+    if (other.length === 0) return "";
 
     const lines: string[] = [];
 
-    if (thisProject.length > 0) {
-      lines.push("## This Project — Recent Sessions");
-      for (const e of thisProject) {
-        lines.push(`- **${e.title}**`);
-        if (e.insights) lines.push(`  ${e.insights.split("\n")[0].slice(0, 150)}`);
-      }
-    }
-
-    if (other.length > 0) {
-      lines.push(thisProject.length > 0 ? "" : "", "## Other Recent Learnings");
-      for (const e of other) lines.push(`- ${e.title}`);
-    }
+    lines.push("## Other Recent Learnings");
+    for (const e of other) lines.push(`- ${e.title}`);
 
     return lines.join("\n");
   } catch {
@@ -346,6 +303,25 @@ export function loadSignalTrends(): string {
   }
 }
 
+/** Load per-project session history for the current working directory */
+export function loadProjectHistoryContext(): string {
+  try {
+    const cwd = process.cwd();
+    const entries = readProjectHistory(cwd, 15);
+    if (entries.length === 0) return "";
+
+    const lines: string[] = ["## This Project — Session History"];
+    for (const e of entries) {
+      lines.push(`- **${e.title}** (${e.date})`);
+      if (e.summary) lines.push(`  ${e.summary.split("\n")[0].slice(0, 150)}`);
+    }
+
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
 /** Load recent relationship notes (today + yesterday) */
 export function loadRelationshipContext(): string {
   try {
@@ -373,6 +349,9 @@ export function buildSystemReminder(): string {
     ? loadRelationshipContext()
     : "";
   const digest = isEnabled(settings, "learningDigest") ? loadLearningDigest() : "";
+  const projectHistory = isEnabled(settings, "projectHistory")
+    ? loadProjectHistoryContext()
+    : "";
   const trends = isEnabled(settings, "signalTrends") ? loadSignalTrends() : "";
   const failures = isEnabled(settings, "failurePatterns") ? loadFailurePatterns() : "";
   const synthesis = isEnabled(settings, "synthesis")
@@ -384,6 +363,7 @@ export function buildSystemReminder(): string {
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
   if (relationship) parts.push(relationship);
+  if (projectHistory) parts.push(projectHistory);
   if (digest) parts.push(digest);
   if (synthesis) parts.push(synthesis);
   if (trends) parts.push(trends);

package/src/hooks/lib/export.ts

@@ -15,7 +15,8 @@ const EXPORT_DIRS = ["telos", "memory"];
 const SKIP_PATTERNS = ["memory/downloads"];
 
 function shouldSkip(relPath: string): boolean {
-  return SKIP_PATTERNS.some((p) => relPath.startsWith(p));
+  const normalized = relPath.replaceAll("\\", "/");
+  return SKIP_PATTERNS.some((p) => normalized.startsWith(p));
 }
 
 /** Recursively collect all files under a directory, returning paths relative to root. */
@@ -32,7 +33,7 @@ function walkDir(dir: string, root: string): string[] {
     if (entry.isDirectory()) {
       files.push(...walkDir(fullPath, root));
     } else if (entry.isFile()) {
-      files.push(relPath);
+      files.push(relPath.replaceAll("\\", "/"));
     }
   }
   return files;

package/src/hooks/lib/graduation.ts

@@ -214,7 +214,7 @@ async function generateRecommendations(
   ratings: RatingsSummary | null
 ): Promise<string[]> {
   if (candidates.length === 0 && !ratings) return [];
-  if (!process.env.ANTHROPIC_API_KEY) {
+  if (!process.env.PAL_ANTHROPIC_API_KEY) {
     return candidates
       .slice(0, 3)
       .map(

package/src/hooks/lib/inference.ts

@@ -21,7 +21,7 @@ export interface InferenceResult {
 }
 
 export async function inference(opts: InferenceOptions): Promise<InferenceResult> {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
+  const apiKey = process.env.PAL_ANTHROPIC_API_KEY;
   if (!apiKey) return { success: false };
 
   const {

package/src/hooks/lib/paths.ts

@@ -57,6 +57,7 @@ export const paths = {
   relationship: () => ensureDir(home("memory", "relationship")),
   entities: () => ensureDir(home("memory", "entities")),
   failures: () => ensureDir(home("memory", "learning", "failures")),
+  projectHistory: () => ensureDir(home("memory", "projects")),
   sessionLearning: () => ensureDir(home("memory", "learning", "session")),
   synthesis: () => ensureDir(home("memory", "learning", "synthesis")),
   backups: () => ensureDir(home("backups")),

package/src/hooks/lib/readme-sync.ts

@@ -58,21 +58,21 @@ function extractEnvVars(): string[] {
     }
   }
 
-  // ANTHROPIC_API_KEY from inference.ts
+  // PAL_ANTHROPIC_API_KEY from inference.ts
   const inferenceFile = resolve(pkg, "src", "hooks", "lib", "inference.ts");
   if (existsSync(inferenceFile)) {
     const content = readFileSync(inferenceFile, "utf-8");
-    if (content.includes("ANTHROPIC_API_KEY")) {
-      vars.add("ANTHROPIC_API_KEY");
+    if (content.includes("PAL_ANTHROPIC_API_KEY")) {
+      vars.add("PAL_ANTHROPIC_API_KEY");
     }
   }
 
-  // GEMINI_API_KEY from youtube-analyze.ts
+  // PAL_GEMINI_API_KEY from youtube-analyze.ts
   const youtubeFile = resolve(pkg, "src", "tools", "youtube-analyze.ts");
   if (existsSync(youtubeFile)) {
     const content = readFileSync(youtubeFile, "utf-8");
-    if (content.includes("GEMINI_API_KEY")) {
-      vars.add("GEMINI_API_KEY");
+    if (content.includes("PAL_GEMINI_API_KEY")) {
+      vars.add("PAL_GEMINI_API_KEY");
     }
   }
 

package/src/hooks/lib/security.ts

@@ -34,6 +34,8 @@ export const HOOK_MANAGED_FILES = [
   "debug.log.prev",
   "opinions.json",
   "pal-settings.json",
+  "skill-index.json",
+  "algorithm-reflections.jsonl",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */
@@ -44,7 +46,9 @@ export const HOOK_MANAGED_DIRS = [
   "memory/learning/synthesis",
   "memory/relationship",
   "memory/wisdom/state",
-  ".agents/PAL",
+  "memory/projects",
+  ".agents/PAL/memory",
+  ".agents/PAL/telos",
 ];
 
 /** Escape a string for use in a RegExp */

package/src/hooks/lib/work-tracking.ts

@@ -1,12 +1,11 @@
 /**
- * Structured work tracking: session history + persistent projects.
+ * Structured work tracking: session history + per-project history.
  * Used by both Claude Code (StopOrchestrator) and opencode (plugin).
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
-import { now } from "./time";
 
 // ── Session Records ──────────────────────────────────────────────
 
@@ -143,51 +142,39 @@ export function extractHandoff(lastAssistant: string): string {
   return cleaned;
 }
 
-// ── Persistent Projects ──────────────────────────────────────────
+// ── Per-Project History ──────────────────────────────────────────
 
-export interface Project {
-  id: string;
-  name: string;
-  created: string;
-  updated: string;
-  status: "active" | "paused" | "completed";
-  objectives: string[];
-  decisions: string[];
-  completed: string[];
-  blockers: string[];
-  nextSteps: string[];
-  handoff: string;
-  sessions: string[];
+export interface ProjectHistoryEntry {
+  date: string;
+  title: string;
+  summary: string;
+  insights: string;
 }
 
-function projectsPath(): string {
-  return resolve(ensureDir(paths.state()), "projects.json");
+/** Convert a cwd path to a filesystem-safe slug (last directory segment) */
+export function cwdToSlug(cwd: string): string {
+  const normalized = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized.split("/").pop() || "unknown";
 }
 
-export function readProjects(): Record<string, Project> {
-  const p = projectsPath();
-  if (!existsSync(p)) return {};
+/** Append a learning entry to the project's history.jsonl */
+export function appendProjectHistory(cwd: string, entry: ProjectHistoryEntry): void {
+  const slug = cwdToSlug(cwd);
+  const dir = ensureDir(resolve(paths.projectHistory(), slug));
+  const historyPath = resolve(dir, "history.jsonl");
+  const line = `${JSON.stringify(entry)}\n`;
+  appendFileSync(historyPath, line, "utf-8");
+}
+
+/** Read the project history for a given cwd */
+export function readProjectHistory(cwd: string, limit = 15): ProjectHistoryEntry[] {
+  const slug = cwdToSlug(cwd);
+  const historyPath = resolve(paths.projectHistory(), slug, "history.jsonl");
+  if (!existsSync(historyPath)) return [];
   try {
-    return JSON.parse(readFileSync(p, "utf-8"));
+    const lines = readFileSync(historyPath, "utf-8").trim().split("\n").filter(Boolean);
+    return lines.slice(-limit).map((line) => JSON.parse(line) as ProjectHistoryEntry);
   } catch {
-    return {};
+    return [];
   }
 }
-
-export function writeProject(project: Project): void {
-  const projects = readProjects();
-  project.updated = now();
-  projects[project.id] = project;
-  writeFileSync(projectsPath(), JSON.stringify(projects, null, 2), "utf-8");
-}
-
-export function activeProjects(): Project[] {
-  return Object.values(readProjects()).filter((p) => p.status === "active");
-}
-
-export function staleProjects(days = 7): Project[] {
-  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
-  return Object.values(readProjects()).filter(
-    (p) => p.status === "active" && new Date(p.updated).getTime() < cutoff
-  );
-}

package/src/targets/claude/install.ts

@@ -15,6 +15,7 @@ import {
   countAgents,
   countMd,
   countSkills,
+  generateSkillIndex,
   loadSettingsTemplate,
   log,
   mergeSettings,
@@ -50,6 +51,7 @@ log.success("Merged PAL settings into settings.json");
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
 copySkills(skillsDir);
+generateSkillIndex();
 
 // --- Copy agents ---
 copyAgents();

package/src/targets/cursor/install.ts

@@ -12,6 +12,7 @@ import {
   copyPalDocs,
   copySkills,
   countSkills,
+  generateSkillIndex,
   loadCursorHooksTemplate,
   log,
   mergeCursorHooks,
@@ -44,6 +45,7 @@ log.success("Merged PAL hooks into hooks.json");
 // --- Symlink skills to ~/.cursor/skills/ ---
 const cursorSkillsDir = resolve(CURSOR_DIR, "skills");
 copySkills(cursorSkillsDir);
+generateSkillIndex();
 
 // --- Copy PAL system docs ---
 const palDocsCount = copyPalDocs();

package/src/targets/lib.ts

@@ -536,6 +536,99 @@ export function removeAgentsFromOpencode(ocAgentsDir: string): string[] {
   return removed;
 }
 
+// --- Skill Index ---
+
+interface SkillIndexEntry {
+  name: string;
+  description: string;
+  triggers: string[];
+}
+
+interface SkillIndex {
+  generated: string;
+  totalSkills: number;
+  skills: Record<string, SkillIndexEntry>;
+}
+
+/** Extract trigger keywords from a skill description */
+function extractTriggers(description: string): string[] {
+  // Extract "Use when ..." phrases and key terms
+  const triggers = new Set<string>();
+
+  const useWhen = description.match(/Use when\s+(.+?)(?:\.|$)/i);
+  if (useWhen) {
+    const words = useWhen[1]
+      .toLowerCase()
+      .split(/[,\s]+/)
+      .filter(
+        (w) =>
+          w.length > 3 &&
+          !["when", "this", "that", "with", "from", "about", "your", "the"].includes(w)
+      );
+    for (const w of words) triggers.add(w);
+  }
+
+  // Extract domain terms from full description
+  const terms = description
+    .toLowerCase()
+    .match(
+      /\b(research|analyze|extract|summarize|review|debug|reflect|council|debate|brainstorm|first.principles|security|pdf|youtube|telos|goals|projects|beliefs|challenges|opinion|skill|create)\b/g
+    );
+  if (terms) for (const t of terms) triggers.add(t);
+
+  return [...triggers];
+}
+
+/**
+ * Generate skill-index.json from installed skills in ~/.agents/skills/.
+ * Called during install after skills are symlinked.
+ */
+export function generateSkillIndex(): number {
+  if (!existsSync(AGENTS_SKILLS_DIR)) return 0;
+
+  const index: SkillIndex = {
+    generated: new Date().toISOString(),
+    totalSkills: 0,
+    skills: {},
+  };
+
+  for (const name of readdirSync(AGENTS_SKILLS_DIR)) {
+    const skillMd = resolve(AGENTS_SKILLS_DIR, name, "SKILL.md");
+    if (!existsSync(skillMd)) continue;
+
+    try {
+      const content = readFileSync(skillMd, "utf-8");
+      const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+
+      const fm = fmMatch[1];
+      const nameMatch = fm.match(/^name:\s*(.+)$/m);
+      const descMatch = fm.match(/^description:\s*"?(.+?)"?\s*$/m);
+      if (!nameMatch) continue;
+
+      const skillName = nameMatch[1].trim();
+      const description = descMatch?.[1]?.trim() ?? "";
+
+      index.skills[skillName] = {
+        name: skillName,
+        description,
+        triggers: extractTriggers(description),
+      };
+      index.totalSkills++;
+    } catch {
+      /* skip unreadable skills */
+    }
+  }
+
+  // Write to state directory
+  const stateDir = resolve(palHome(), "memory", "state");
+  mkdirSync(stateDir, { recursive: true });
+  writeJson(resolve(stateDir, "skill-index.json"), index);
+  log.info(`Skill index: ${index.totalSkills} skills indexed`);
+
+  return index.totalSkills;
+}
+
 /** Count skill subdirectories in ~/.agents/skills/ */
 export function countSkills(): number {
   if (!existsSync(AGENTS_SKILLS_DIR)) return 0;

package/src/targets/opencode/install.ts

@@ -12,6 +12,7 @@ import {
   copyPalDocs,
   copySkills,
   countSkills,
+  generateSkillIndex,
   log,
   writeJson,
 } from "../lib";
@@ -54,6 +55,7 @@ try {
 // --- 3. Install skills into ~/.agents/skills/ ---
 const claudeSkillsDir = resolve(platform.claudeDir(), "skills");
 copySkills(claudeSkillsDir);
+generateSkillIndex();
 log.success("Installed skills to ~/.agents/skills/");
 
 // --- 4. Install agents into ~/.config/opencode/agents/ ---

package/src/tools/agent/algorithm-reflect.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/**
+ * AlgorithmReflect — Append structured algorithm reflections to JSONL.
+ *
+ * Records algorithm performance data after each LEARN phase.
+ * Creates a queryable dataset for improving the algorithm over time.
+ *
+ * Usage:
+ *   bun run tool:algorithm-reflect --task "description" --criteria 5 --passed 4 --failed 1 --sentiment 7 \
+ *     --q1 "Should have read the file before planning" \
+ *     --q2 "Could have parallelized the explore agents" \
+ *     --q3 "Missed the implicit constraint about cross-platform"
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { paths } from "../../hooks/lib/paths";
+
+// ── Types ──
+
+interface AlgorithmReflection {
+  timestamp: string;
+  task: string;
+  criteria_count: number;
+  criteria_passed: number;
+  criteria_failed: number;
+  sentiment: number;
+  q1: string;
+  q2: string;
+  q3: string;
+}
+
+// ── Core ──
+
+function reflectionsPath(): string {
+  const dir = resolve(paths.learning(), "reflections");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return resolve(dir, "algorithm-reflections.jsonl");
+}
+
+export function appendReflection(reflection: AlgorithmReflection): {
+  success: boolean;
+  message: string;
+  path: string;
+} {
+  const p = reflectionsPath();
+  const line = `${JSON.stringify(reflection)}\n`;
+  appendFileSync(p, line, "utf-8");
+
+  return {
+    success: true,
+    message: `Reflection logged: ${reflection.criteria_passed}/${reflection.criteria_count} passed, sentiment ${reflection.sentiment}/10`,
+    path: p,
+  };
+}
+
+// ── CLI ──
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      task: { type: "string" },
+      criteria: { type: "string" },
+      passed: { type: "string" },
+      failed: { type: "string" },
+      sentiment: { type: "string" },
+      q1: { type: "string" },
+      q2: { type: "string" },
+      q3: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+AlgorithmReflect — Log algorithm performance after LEARN phase
+
+Usage:
+  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
+    --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+
+Arguments:
+  --task        Brief task description
+  --criteria    Total criteria count
+  --passed      Criteria passed
+  --failed      Criteria failed
+  --sentiment   Implied satisfaction 1-10
+  --q1          Q1 — Self: what I'd do differently
+  --q2          Q2 — Algorithm: structural improvement
+  --q3          Q3 — AI: reasoning blind spot
+
+Output: algorithm-reflections.jsonl in memory/learning/reflections/
+`);
+    process.exit(0);
+  }
+
+  if (!values.task || !values.q1 || !values.q2 || !values.q3) {
+    console.error("Required: --task, --q1, --q2, --q3");
+    process.exit(1);
+  }
+
+  const reflection: AlgorithmReflection = {
+    timestamp: new Date().toISOString(),
+    task: values.task,
+    criteria_count: parseInt(values.criteria || "0", 10),
+    criteria_passed: parseInt(values.passed || "0", 10),
+    criteria_failed: parseInt(values.failed || "0", 10),
+    sentiment: Math.max(1, Math.min(10, parseInt(values.sentiment || "5", 10))),
+    q1: values.q1,
+    q2: values.q2,
+    q3: values.q3,
+  };
+
+  const result = appendReflection(reflection);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (import.meta.main) run();

package/src/tools/agent/wisdom-frame.ts

@@ -167,8 +167,6 @@ ${type === "anti-pattern" ? `### ${observation}\n- **Severity:** Medium\n- **Fre
         `- ${date()}: Principle candidate — ${observation}`
       );
       break;
-
-    case "evolution":
     default:
       content = appendToSection(content, "## Evolution Log", evolutionEntry);
       break;

package/assets/agents/claude-researcher.md

@@ -1,43 +0,0 @@
----
-name: claude-researcher
-description: Deep research with academic rigor — query decomposition, multi-source synthesis, scholarly depth. Use for research tasks requiring thorough analysis.
-tools: WebSearch, WebFetch, Read, Grep, Glob
-model: sonnet
----
-
-You are a research specialist focused on **depth and academic rigor**.
-
-## Methodology
-
-1. **Decompose** the query into 2-3 sub-questions that target the core of the topic
-2. **Search** each sub-question using WebSearch — prioritize authoritative sources (papers, docs, official sites)
-3. **Read** the most promising results with WebFetch to extract detail
-4. **Synthesize** findings into a structured analysis
-
-## Guidelines
-
-- Prioritize primary sources over summaries
-- Distinguish between established facts, expert consensus, and speculation
-- Note methodology limitations when citing research
-- If a claim has no strong source, say so — do not fabricate citations
-- Keep findings concise but substantive
-
-## Output Format
-
-```markdown
-## Findings
-
-[Numbered list of key discoveries, each with a brief explanation]
-
-## Sources
-
-[Verified URLs with one-line descriptions — only include URLs you actually visited]
-
-## Confidence
-
-[High/Medium/Low rating per finding, with brief justification]
-
-## Gaps
-
-[What couldn't be answered or needs further investigation]
-```