portable-agent-layer 0.20.0 → 0.22.0

package/assets/skills/research/tools/gemini-search.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env bun
+/**
+ * Gemini Search — CLI tool for grounded search via the Gemini API.
+ *
+ * Uses Gemini's built-in Google Search grounding to fetch real-time,
+ * source-cited information. Optimized for academic and scholarly queries.
+ *
+ * Requires PAL_GEMINI_API_KEY environment variable.
+ *
+ * Usage:
+ *   bun gemini-search.ts -- <query> [--max-tokens 4096]
+ *   bun gemini-search.ts -- "recent advances in transformer architectures"
+ *   bun gemini-search.ts -- "CRISPR gene editing clinical trials 2025"
+ */
+
+import { parseArgs } from "node:util";
+
+const API_BASE = "https://generativelanguage.googleapis.com/v1beta";
+const DEFAULT_MODEL = "gemini-3.1-flash-lite-preview";
+
+interface GroundingChunk {
+  web?: { uri: string; title: string };
+}
+
+interface GroundingSupport {
+  segment?: { startIndex: number; endIndex: number; text: string };
+  groundingChunkIndices?: number[];
+}
+
+interface GroundingMetadata {
+  webSearchQueries?: string[];
+  groundingChunks?: GroundingChunk[];
+  groundingSupports?: GroundingSupport[];
+  searchEntryPoint?: { renderedContent: string };
+}
+
+interface ContentPart {
+  text?: string;
+}
+
+interface Candidate {
+  content?: { parts?: ContentPart[]; role?: string };
+  groundingMetadata?: GroundingMetadata;
+}
+
+interface GeminiResponse {
+  candidates?: Candidate[];
+  error?: { message: string; code: number };
+}
+
+function loadApiKey(): string {
+  const key = process.env.PAL_GEMINI_API_KEY;
+  if (!key) {
+    console.error("Error: PAL_GEMINI_API_KEY environment variable is not set.");
+    console.error("Get an API key at https://aistudio.google.com/apikey");
+    process.exit(1);
+  }
+  return key;
+}
+
+const SYSTEM_PROMPT = `You are an academic research assistant. When searching, prioritize:
+- Peer-reviewed papers, preprints (arXiv, bioRxiv, medRxiv)
+- Official documentation and technical specifications
+- University and research institution publications
+- Conference proceedings (NeurIPS, ICML, ACL, CVPR, etc.)
+- Systematic reviews and meta-analyses
+
+Always include: author names, publication year, journal/venue when available.
+Distinguish between peer-reviewed findings and preprints/working papers.
+Note methodology limitations and sample sizes when relevant.
+Be thorough but concise.`;
+
+export async function geminiSearch(query: string, maxTokens: number): Promise<void> {
+  const apiKey = loadApiKey();
+
+  const body = {
+    system_instruction: {
+      parts: [{ text: SYSTEM_PROMPT }],
+    },
+    contents: [
+      {
+        parts: [{ text: query }],
+      },
+    ],
+    tools: [{ google_search: {} }],
+    generationConfig: {
+      maxOutputTokens: maxTokens,
+    },
+  };
+
+  const url = `${API_BASE}/models/${DEFAULT_MODEL}:generateContent?key=${apiKey}`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text().catch(() => "");
+    console.error(`Error: HTTP ${response.status} — ${err.slice(0, 500)}`);
+    process.exit(1);
+  }
+
+  const data = (await response.json()) as GeminiResponse;
+
+  if (data.error) {
+    console.error(`Error: ${data.error.message}`);
+    process.exit(1);
+  }
+
+  if (!data.candidates || data.candidates.length === 0) {
+    console.error("Error: No candidates in Gemini response.");
+    process.exit(1);
+  }
+
+  const candidate = data.candidates[0];
+
+  // Extract text
+  const textParts: string[] = [];
+  if (candidate.content?.parts) {
+    for (const part of candidate.content.parts) {
+      if (part.text) textParts.push(part.text);
+    }
+  }
+
+  if (textParts.length === 0) {
+    console.error("Error: No text content in Gemini response.");
+    process.exit(1);
+  }
+
+  console.log(textParts.join("\n\n"));
+
+  // Extract grounding metadata
+  const meta = candidate.groundingMetadata;
+  if (meta) {
+    if (meta.webSearchQueries && meta.webSearchQueries.length > 0) {
+      console.log("\n---\n## Search Queries Used\n");
+      for (const q of meta.webSearchQueries) {
+        console.log(`- ${q}`);
+      }
+    }
+
+    if (meta.groundingChunks && meta.groundingChunks.length > 0) {
+      console.log("\n---\n## Sources\n");
+      for (const chunk of meta.groundingChunks) {
+        if (chunk.web) {
+          console.log(`- [${chunk.web.title}](${chunk.web.uri})`);
+        }
+      }
+    }
+  }
+}
+
+async function run() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "max-tokens": { type: "string", short: "m", default: "4096" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    console.log(`Gemini Search — grounded academic search via Gemini API
+
+Usage:
+  bun gemini-search.ts -- <query> [options]
+
+Options:
+  --max-tokens, -m <n>       Max response tokens (default: 4096)
+  --help, -h                 Show this help
+
+Examples:
+  bun gemini-search.ts -- "transformer architecture advances 2025"
+  bun gemini-search.ts -- "CRISPR clinical trials"`);
+    process.exit(0);
+  }
+
+  const query = positionals.join(" ");
+  const maxTokens = Number.parseInt(values["max-tokens"] ?? "4096", 10);
+
+  await geminiSearch(query, maxTokens);
+}
+
+if (import.meta.main) run();

package/assets/skills/research/tools/grok-search.ts

@@ -5,7 +5,7 @@
  * Uses the Grok Responses API with web_search and x_search tools
  * to fetch real-time information from the web and X (Twitter).
  *
- * Requires XAI_API_KEY environment variable.
+ * Requires PAL_XAI_API_KEY environment variable.
  *
  * Usage:
  *   bun grok-search.ts -- <query> [--sources web,x] [--max-tokens 2048]
@@ -45,9 +45,9 @@ interface GrokResponse {
 }
 
 function loadApiKey(): string {
-  const key = process.env.XAI_API_KEY;
+  const key = process.env.PAL_XAI_API_KEY;
   if (!key) {
-    console.error("Error: XAI_API_KEY environment variable is not set.");
+    console.error("Error: PAL_XAI_API_KEY environment variable is not set.");
     console.error("Get an API key at https://console.x.ai/");
     process.exit(1);
   }

package/assets/skills/research/tools/perplexity-search.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env bun
+/**
+ * Perplexity Search — CLI tool for investigative search via the Perplexity Sonar API.
+ *
+ * Uses Perplexity's Sonar model with built-in web search to fetch
+ * source-cited, verified information. Optimized for investigative queries
+ * requiring cross-referenced, credible sources.
+ *
+ * Requires PAL_PERPLEXITY_API_KEY environment variable.
+ *
+ * Usage:
+ *   bun perplexity-search.ts -- <query> [--max-tokens 4096]
+ *   bun perplexity-search.ts -- "corruption allegations against company X"
+ *   bun perplexity-search.ts -- "timeline of event Y with sources"
+ */
+
+import { parseArgs } from "node:util";
+
+const API_BASE = "https://api.perplexity.ai";
+const DEFAULT_MODEL = "sonar-pro";
+
+interface Choice {
+  message?: {
+    role: string;
+    content: string;
+  };
+}
+
+interface PerplexityResponse {
+  choices?: Choice[];
+  citations?: string[];
+  error?: { message: string; code?: number };
+}
+
+function loadApiKey(): string {
+  const key = process.env.PAL_PERPLEXITY_API_KEY;
+  if (!key) {
+    console.error(
+      "Error: PAL_PERPLEXITY_API_KEY environment variable is not set.\n" +
+        "The Perplexity API could not be reached. The researcher agent should fall back to WebSearch.\n" +
+        "To enable Perplexity search, get an API key at https://www.perplexity.ai/settings/api\n" +
+        "and set it: export PAL_PERPLEXITY_API_KEY=pplx-..."
+    );
+    process.exit(1);
+  }
+  return key;
+}
+
+const SYSTEM_PROMPT = `You are an investigative research assistant. When searching, prioritize:
+- Cross-referenced facts verified by 2+ independent sources
+- Primary sources: court filings, official reports, government records, regulatory filings
+- Credible journalism: established outlets with editorial standards
+- Source credibility assessment: note publication reputation, potential bias, date of publication
+- Evidence chains: connect claims to their original sources
+
+Always include: source names, publication dates, and direct quotes when available.
+Distinguish between confirmed facts, single-source claims, and unverified allegations.
+Flag contradictions between sources.
+Be thorough but concise.`;
+
+export async function perplexitySearch(query: string, maxTokens: number): Promise<void> {
+  const apiKey = loadApiKey();
+
+  const body = {
+    model: DEFAULT_MODEL,
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: query },
+    ],
+    max_tokens: maxTokens,
+    return_citations: true,
+    search_recency_filter: "week",
+  };
+
+  const response = await fetch(`${API_BASE}/chat/completions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text().catch(() => "");
+    console.error(`Error: HTTP ${response.status} — ${err.slice(0, 500)}`);
+    process.exit(1);
+  }
+
+  const data = (await response.json()) as PerplexityResponse;
+
+  if (data.error) {
+    console.error(`Error: ${data.error.message}`);
+    process.exit(1);
+  }
+
+  if (!data.choices || data.choices.length === 0) {
+    console.error("Error: No choices in Perplexity response.");
+    process.exit(1);
+  }
+
+  const content = data.choices[0].message?.content;
+  if (!content) {
+    console.error("Error: No text content in Perplexity response.");
+    process.exit(1);
+  }
+
+  console.log(content);
+
+  // Extract citations
+  if (data.citations && data.citations.length > 0) {
+    console.log("\n---\n## Sources\n");
+    for (let i = 0; i < data.citations.length; i++) {
+      console.log(`- [${i + 1}] ${data.citations[i]}`);
+    }
+  }
+}
+
+async function run() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "max-tokens": { type: "string", short: "m", default: "4096" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    console.log(`Perplexity Search — investigative search via Perplexity Sonar API
+
+Usage:
+  bun perplexity-search.ts -- <query> [options]
+
+Options:
+  --max-tokens, -m <n>       Max response tokens (default: 4096)
+  --help, -h                 Show this help
+
+Examples:
+  bun perplexity-search.ts -- "corruption allegations timeline"
+  bun perplexity-search.ts -- "regulatory actions against company X"`);
+    process.exit(0);
+  }
+
+  const query = positionals.join(" ");
+  const maxTokens = Number.parseInt(values["max-tokens"] ?? "4096", 10);
+
+  await perplexitySearch(query, maxTokens);
+}
+
+if (import.meta.main) run();

package/assets/templates/PAL/ALGORITHM.md

@@ -35,13 +35,55 @@ Format:
 
 Include at least one anti-criterion (C-A prefix).
 
-**3. Select capabilities:**
+**3. Capability audit:**
 
-Scan the available skills listing. Select skills and tools you'll invoke during EXECUTE. Selecting a capability = commitment to invoke it via tool call. Don't select what you won't use.
+Scan ALL 14 capabilities below. For each, assign exactly one disposition:
+- **USE** — will invoke during a specific phase. State which.
+- **DECLINE** — would help but not worth it for this task's scope.
+- **N/A** — genuinely irrelevant to this task.
+
+**A: Foundation**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 1 | Task Tool | TaskCreate, TaskUpdate, TaskList |
+| 2 | AskUserQuestion | Built-in tool |
+| 3 | Skills (ACTIVE SCAN) | Read `skill-index.json`, match triggers against task |
+
+**B: Thinking & Analysis**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 4 | Think (analysis router) | `think` skill |
+| 5 | First Principles | `first-principles` skill |
+| 6 | Council (multi-perspective) | `council` skill |
+| 7 | Plan Mode | EnterPlanMode tool |
+
+**C: Agents & Research**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 8 | Research (multi-agent) | `research` skill |
+| 9 | Subagents | Agent tool (Explore, Plan, general-purpose) |
+| 10 | Background agents | Agent tool with `run_in_background: true` |
+
+**D: Execution & Verification**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 11 | Git worktree isolation | `isolation: "worktree"` on Agent |
+| 12 | Test runner | `bun test`, vitest, jest, pytest |
+| 13 | Static analysis | `tsc --noEmit`, biome, eslint |
+| 14 | CLI probes | curl, diff, jq, exit codes |
+
+**Capability #3 (Skills) requires active scanning.** Read `skill-index.json` and match the task against skill triggers. "Skills — N/A" without evidence of scanning is an error.
 
 Output:
 ```
-🏹 CAPABILITIES: [list each selected skill/tool and why]
+🏹 CAPABILITIES (14/14):
+USE: [#, #, #] — [reason (phase: WHICH)]
+DECLINE: [#, #] — [reason]
+N/A: [rest]
 ```
 
 ### ━━━ 🧠 PLAN ━━━ 2/5
@@ -92,11 +134,25 @@ If any criteria failed, fix and re-verify before completing.
 
 Reflect on the work and capture reusable knowledge. Skip this phase when the work was trivial or purely mechanical.
 
-**1. Reflection** (one sentence each):
-- What would I do differently next time?
-- What would a better algorithm have done differently?
+**1. Algorithm Reflection** (one sentence each — reflect on ALGORITHM PERFORMANCE, not task subject matter):
+
+**Q1 — Self:** "What would I have done differently in this Algorithm run?"
+Focus: phase execution, criteria quality, capability selection decisions.
+
+**Q2 — Algorithm:** "What would a smarter algorithm have done differently?"
+Focus: structural improvements — missing phases, better gating, capability triggers, ISC patterns.
+
+**Q3 — AI:** "What would a fundamentally smarter AI have done differently?"
+Focus: reasoning approach, problem decomposition, anticipation, blind spots.
+
+**2. Reflection Log** — record algorithm performance:
+
+```bash
+bun ~/.agents/PAL/tools/algorithm-reflect.ts --task "description" --criteria N --passed N --failed N --sentiment 1-10 \
+  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+```
 
-**2. Wisdom Frame** — if the session produced a genuine, reusable insight:
+**3. Wisdom Frame** — if the session produced a genuine, reusable insight:
 
 ```bash
 bun ~/.agents/PAL/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]
@@ -118,7 +174,10 @@ Only write if the insight is **genuine and reusable** — not every session prod
 📋 CRITERIA:
 [criteria checklist]
 
-🏹 CAPABILITIES: [selected capabilities]
+🏹 CAPABILITIES (14/14):
+USE: [#, #] — [reason]
+DECLINE: [#] — [reason]
+N/A: [rest]
 
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
@@ -136,6 +195,9 @@ Only write if the insight is **genuine and reusable** — not every session prod
 🗣️ {{IDENTITY_NAME}}: [summary]
 
 ━━━ 📚 LEARN ━━━ 5/5
-🪞 REFLECT: [what I'd do differently]
+🪞 Q1 — Self: [what I'd do differently]
+🪞 Q2 — Algorithm: [structural improvement]
+🪞 Q3 — AI: [reasoning blind spot]
+📊 REFLECTION LOG: [appended to algorithm-reflections.jsonl]
 📝 WISDOM: [frame update if genuine insight, or "No new insight"]
 ```

package/assets/templates/PAL/WORK_TRACKING.md

@@ -1,14 +1,7 @@
 # Work Tracking
 
-PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured) and `memory/state/projects.json` (AI-managed).
+PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured).
 
 ## Projects
 
-Update `projects.json` via the work-tracking library when:
-- **Starting sustained multi-session work** → create a project with objectives and an id (slugified, e.g. "pdf-template-engine")
-- **Making a key decision** → add to the project's `decisions` array
-- **Completing a milestone** → add to `completed`, remove from `nextSteps`
-- **Session ends with open work** → update `nextSteps` and `handoff`
-- **Work is done** → set status to "completed"
-
-Do not create projects for one-off questions or quick fixes.
+Projects are managed in `telos/PROJECTS.md` and force-loaded at session startup via `pal-settings.json → loadAtStartup.files`.

package/package.json

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

package/src/cli/index.ts

@@ -377,12 +377,12 @@ function doctor(silent = false): DoctorResult {
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
     // API key checks
-    process.env.ANTHROPIC_API_KEY
-      ? ok("ANTHROPIC_API_KEY is set")
-      : fail("ANTHROPIC_API_KEY — not set (hooks need it for inference)");
-    process.env.GEMINI_API_KEY
-      ? ok("GEMINI_API_KEY is set")
-      : warn("GEMINI_API_KEY — not set (optional, for YouTube analysis)");
+    process.env.PAL_ANTHROPIC_API_KEY
+      ? ok("PAL_ANTHROPIC_API_KEY is set")
+      : fail("PAL_ANTHROPIC_API_KEY — not set (hooks need it for inference)");
+    process.env.PAL_GEMINI_API_KEY
+      ? ok("PAL_GEMINI_API_KEY is set")
+      : warn("PAL_GEMINI_API_KEY — not set (optional, for YouTube analysis)");
 
     // Hook health from debug.log
     const hookHealth = checkHookHealth(home);
@@ -443,6 +443,18 @@ async function init(args: string[]) {
 }
 
 async function install(targets: { claude: boolean; opencode: boolean; cursor: boolean }) {
+  // Ensure dependencies are installed
+  const pkg = palPkg();
+  log.info("Installing dependencies...");
+  const deps = spawnSync("bun", ["install", "--frozen-lockfile"], {
+    cwd: pkg,
+    stdio: "inherit",
+    shell: true,
+  });
+  if (deps.status !== 0) {
+    log.warn("bun install failed — continuing anyway, but hooks may not work");
+  }
+
   // Scaffold TELOS + PAL settings, then prompt for missing identity
   const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");

package/src/hooks/handlers/rating.ts

@@ -358,6 +358,6 @@ export async function captureRating(message: string, sessionId?: string): Promis
     return;
   }
 
-  // Path 2: Implicit sentiment (requires ANTHROPIC_API_KEY — inference silently no-ops without it)
+  // Path 2: Implicit sentiment (requires PAL_ANTHROPIC_API_KEY — inference silently no-ops without it)
   await handleImplicitSentiment(cleaned, sessionId);
 }

package/src/hooks/handlers/relationship.ts

@@ -52,8 +52,8 @@ export async function captureRelationship(
     return;
   }
 
-  if (!process.env.ANTHROPIC_API_KEY) {
-    logDebug("relationship", "Skipped: no ANTHROPIC_API_KEY");
+  if (!process.env.PAL_ANTHROPIC_API_KEY) {
+    logDebug("relationship", "Skipped: no PAL_ANTHROPIC_API_KEY");
     return;
   }
 

package/src/hooks/handlers/session-name.ts

@@ -42,7 +42,7 @@ export async function captureSessionName(
   logDebug("session-name", `Named from prompt: "${name}"`);
 
   // Spawn detached background process to upgrade with Haiku inference
-  if (!process.env.ANTHROPIC_API_KEY) return;
+  if (!process.env.PAL_ANTHROPIC_API_KEY) return;
   try {
     const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
     const child = spawn(

package/src/hooks/handlers/work-learning.ts

@@ -19,6 +19,7 @@ import {
   extractLastUser,
   parseMessages,
 } from "../lib/transcript";
+import { appendProjectHistory } from "../lib/work-tracking";
 
 function slugify(text: string): string {
   return text
@@ -183,5 +184,13 @@ export async function captureWorkLearning(
   const filepath = resolve(dir, filename);
   writeFileSync(filepath, content, "utf-8");
 
+  // Append to per-project history (agent-agnostic recall)
+  appendProjectHistory(process.cwd(), {
+    date: new Date().toISOString().slice(0, 10),
+    title,
+    summary,
+    insights,
+  });
+
   if (sessionId) markCaptured(sessionId, filepath, messages.length);
 }

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

@@ -7,6 +7,7 @@
  */
 
 import {
+  copyFileSync,
   existsSync,
   lstatSync,
   readdirSync,
@@ -48,7 +49,7 @@ function latestMtime(...filePaths: string[]): number {
   return latest;
 }
 
-/** Create or verify a symlink pointing to AGENTS.md */
+/** Create or verify a symlink pointing to AGENTS.md (falls back to copy on Windows EPERM) */
 function ensureOneSymlink(linkPath: string, targetPath: string): void {
   try {
     const stat = lstatSync(linkPath);
@@ -58,8 +59,16 @@ function ensureOneSymlink(linkPath: string, targetPath: string): void {
     // doesn't exist — create it
   }
   ensureDir(dirname(linkPath));
-  const relTarget = relative(dirname(linkPath), targetPath).replaceAll("\\", "/");
-  symlinkSync(relTarget, linkPath);
+  try {
+    const relTarget = relative(dirname(linkPath), targetPath).replaceAll("\\", "/");
+    symlinkSync(relTarget, linkPath);
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code === "EPERM") {
+      copyFileSync(targetPath, linkPath);
+    } else {
+      throw e;
+    }
+  }
 }
 
 /** Ensure all agent symlinks point to the canonical AGENTS.md */
@@ -156,9 +165,12 @@ export function buildClaudeMd(): string {
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
-  ensureSymlinks();
-  if (!needsRebuild()) return false;
+  if (!needsRebuild()) {
+    ensureSymlinks();
+    return false;
+  }
   ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
+  ensureSymlinks();
   return true;
 }