portable-agent-layer 0.22.0 → 0.23.0

package/src/cli/index.ts

@@ -347,7 +347,6 @@ function doctor(silent = false): DoctorResult {
   const hasAgent = claude.available || opencode.available || cursor.available;
 
   const home = palHome();
-  const isRepo = existsSync(resolve(palPkg(), ".palroot"));
   const telosCount = (() => {
     try {
       return readdirSync(resolve(home, "telos")).filter((f) => f.endsWith(".md")).length;
@@ -373,7 +372,7 @@ function doctor(silent = false): DoctorResult {
     cursor.available
       ? ok(`Cursor ${cursor.version || ""}`.trim())
       : fail("Cursor — not found");
-    ok(`PAL home: ${home} (${isRepo ? "repo" : "package"} mode)`);
+    ok(`PAL home: ${home}`);
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
     // API key checks
@@ -420,13 +419,9 @@ async function init(args: string[]) {
   }
 
   const home = palHome();
-  const isRepo = existsSync(resolve(palPkg(), ".palroot"));
-
-  if (!isRepo) {
-    log.info(`Creating PAL home at ${home}`);
-    mkdirSync(resolve(home, "telos"), { recursive: true });
-    mkdirSync(resolve(home, "memory"), { recursive: true });
-  }
+  log.info(`Creating PAL home at ${home}`);
+  mkdirSync(resolve(home, "telos"), { recursive: true });
+  mkdirSync(resolve(home, "memory"), { recursive: true });
 
   scaffoldTelos();
   ensureSetupState();
@@ -670,13 +665,11 @@ async function update() {
 async function status() {
   const home = palHome();
   const pkg = palPkg();
-  const isRepo = existsSync(resolve(pkg, ".palroot"));
 
   const pkgJson = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8"));
 
   console.log("");
   log.info(`Version:  ${pkgJson.version}`);
-  log.info(`Mode:     ${isRepo ? "repo" : "package"}`);
   log.info(`Package:  ${pkg}`);
   log.info(`Home:     ${home}`);
   console.log("");

package/src/hooks/handlers/relationship.ts

@@ -74,7 +74,7 @@ export async function captureRelationship(
   logDebug("relationship", "Calling inference...");
   const result = await inference({
     system:
-      "You analyze messages from an AI coding session to extract relationship observations. " +
+      "You analyze messages from an AI assistant session to extract relationship observations. " +
       "Types: O=opinions/preferences (how the user likes to work, what they want), " +
       "B=biographical (what the AI accomplished this session, written in first-person), " +
       "W=world facts (user's situation, projects, tools they use). " +

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

@@ -0,0 +1,324 @@
+/**
+ * Stop handler: unified session intelligence capture.
+ *
+ * Merges work-learning + relationship + handoff into a single Haiku call.
+ * Produces: title, summary, insights, handoff, relationship observations.
+ * Writes: session learning file, project history, relationship notes, last-handoff.
+ *
+ * Replaces: work-learning.ts + relationship.ts (both still exist but are bypassed).
+ */
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { stringify } from "../lib/frontmatter";
+import { inference } from "../lib/inference";
+import { categorizeLearning } from "../lib/learning-category";
+import { logDebug, logError } from "../lib/log";
+import { ensureDir, paths } from "../lib/paths";
+import { appendNotes, hasSessionNotes, type RelationshipNote } from "../lib/relationship";
+import { fileTimestamp, monthPath } from "../lib/time";
+import { logTokenUsage } from "../lib/token-usage";
+import {
+  extractContent,
+  extractLastAssistant,
+  extractLastUser,
+  parseMessages,
+} from "../lib/transcript";
+import { appendProjectHistory, detectStatus } from "../lib/work-tracking";
+
+// ── Dedup tracking (same as work-learning) ──
+
+interface CaptureEntry {
+  filepath: string;
+  messageCount: number;
+}
+
+const MIN_NEW_MESSAGES = 10;
+
+function capturedPath(): string {
+  return resolve(paths.state(), "captured-learnings.json");
+}
+
+function getPreviousCapture(sessionId: string): CaptureEntry | null {
+  const p = capturedPath();
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    if (Array.isArray(raw)) return null;
+    const entry = raw[sessionId];
+    if (!entry) return null;
+    if (typeof entry === "string") return { filepath: entry, messageCount: 0 };
+    return entry as CaptureEntry;
+  } catch {
+    return null;
+  }
+}
+
+function markCaptured(sessionId: string, filepath: string, messageCount: number): void {
+  const p = capturedPath();
+  let data: Record<string, CaptureEntry> = {};
+  try {
+    if (existsSync(p)) {
+      const raw = JSON.parse(readFileSync(p, "utf-8"));
+      if (!Array.isArray(raw) && typeof raw === "object") {
+        for (const [k, v] of Object.entries(raw)) {
+          data[k] =
+            typeof v === "string"
+              ? { filepath: v, messageCount: 0 }
+              : (v as CaptureEntry);
+        }
+      }
+    }
+  } catch {
+    /* start fresh */
+  }
+  data[sessionId] = { filepath, messageCount };
+  const entries = Object.entries(data);
+  if (entries.length > 50) data = Object.fromEntries(entries.slice(-50));
+  writeFileSync(p, JSON.stringify(data, null, 2), "utf-8");
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 4)
+    .join("-");
+}
+
+// ── JSON schema for merged Haiku call ──
+
+const INTELLIGENCE_SCHEMA = {
+  type: "object" as const,
+  additionalProperties: false,
+  properties: {
+    title: { type: "string" as const, description: "Short session title, 5-10 words" },
+    summary: {
+      type: "string" as const,
+      description:
+        "What the AI did for the user, 2-4 sentences, AI perspective using 'we'",
+    },
+    insights: {
+      type: "string" as const,
+      description:
+        "What worked, what was surprising, what to do differently, 2-3 bullet points",
+    },
+    handoff: {
+      type: "string" as const,
+      description:
+        "If status is in-progress: what remains to be done, key decisions made, blockers. If completed: empty string.",
+    },
+    observations: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        additionalProperties: false,
+        properties: {
+          type: {
+            type: "string" as const,
+            enum: ["O", "W", "B"],
+            description: "O=preference, W=world fact, B=what AI did",
+          },
+          text: { type: "string" as const },
+          confidence: { type: "number" as const },
+        },
+        required: ["type", "text", "confidence"] as const,
+      },
+    },
+  },
+  required: ["title", "summary", "insights", "handoff", "observations"] as const,
+};
+
+interface IntelligenceOutput {
+  title: string;
+  summary: string;
+  insights: string;
+  handoff: string;
+  observations: Array<{ type: "O" | "W" | "B"; text: string; confidence: number }>;
+}
+
+// ── Main handler ──
+
+export async function captureSessionIntelligence(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  const messages = parseMessages(transcript);
+  if (messages.length < 6 || transcript.length < 2000) return;
+
+  // Dedup check
+  if (sessionId) {
+    const prev = getPreviousCapture(sessionId);
+    if (prev && messages.length - prev.messageCount < MIN_NEW_MESSAGES) return;
+  }
+
+  // Skip if no API key
+  if (!process.env.PAL_ANTHROPIC_API_KEY) {
+    logDebug("session-intelligence", "Skipped: no PAL_ANTHROPIC_API_KEY");
+    return;
+  }
+
+  // Relationship dedup — skip relationship capture if already done for this session
+  const skipRelationship = sessionId ? hasSessionNotes(sessionId) : false;
+
+  // Extract transcript windows
+  const userMessages = messages
+    .filter((m) => m.role === "user")
+    .map((m) => extractContent(m))
+    .filter((t) => t.length > 0);
+
+  const lastAssistant = extractLastAssistant(messages);
+  const lastAssistantText = extractContent(lastAssistant);
+  const lastUser = extractLastUser(messages);
+  const status = detectStatus(lastAssistantText);
+
+  // Wider window: 15 user msgs at 200 chars (relationship needs more context)
+  const userWindow = userMessages.slice(-15).map((t) => t.slice(0, 200));
+  const assistantWindow = lastAssistantText.slice(0, 600);
+
+  if (userWindow.length < 3) return;
+
+  // Single Haiku call
+  logDebug("session-intelligence", "Calling inference...");
+  let output: IntelligenceOutput | null = null;
+  try {
+    const result = await inference({
+      system: [
+        "You analyze a session between a human user and an AI assistant. Sessions may involve coding, research, writing, planning, analysis, or any other task.",
+        `Session status: ${status}.`,
+        "Produce ALL of the following:",
+        "1. title: short title (5-10 words) describing what was accomplished",
+        "2. summary: what the AI did for the user (2-4 sentences, AI perspective using 'we')",
+        "3. insights: what worked, what was surprising, what to do differently (2-3 points, no markdown)",
+        status === "in-progress"
+          ? "4. handoff: what remains unfinished — decisions made so far, next steps, blockers (2-4 sentences)"
+          : "4. handoff: empty string (session completed)",
+        skipRelationship
+          ? "5. observations: empty array (already captured)"
+          : "5. observations: 0-3 relationship observations. O=preference/opinion, W=world fact, B=what AI did this session (first-person). Be concise.",
+      ].join("\n"),
+      user: `User messages:\n${userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n")}\n\nLast AI response:\n${assistantWindow}`,
+      maxTokens: 500,
+      timeout: 15000,
+      jsonSchema: INTELLIGENCE_SCHEMA,
+    });
+
+    if (result.usage) logTokenUsage("session-intelligence", result.usage);
+
+    if (result.success && result.output) {
+      output = JSON.parse(result.output) as IntelligenceOutput;
+    }
+  } catch (err) {
+    logError("session-intelligence", err);
+  }
+
+  // Fallbacks
+  const title = output?.title || extractContent(lastUser).slice(0, 80) || "session";
+  const summary = output?.summary || lastAssistantText.slice(0, 600);
+  const insights = output?.insights || "";
+  const handoff = output?.handoff || "";
+
+  // ── Write session learning file ──
+
+  const category = categorizeLearning(title, summary);
+  const slug = slugify(title);
+  const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
+  const filename = `${fileTimestamp()}_${category}_${slug}.md`;
+
+  const meta: Record<string, unknown> = {
+    title,
+    category,
+    date: new Date().toISOString().slice(0, 10),
+    cwd: process.cwd(),
+  };
+  if (sessionId) meta.session = sessionId;
+
+  const body = [
+    "## What Was Done",
+    summary,
+    "",
+    "## Insights",
+    insights || "*No insights captured.*",
+    ...(handoff ? ["", "## Handoff", handoff] : []),
+  ].join("\n");
+
+  const content = stringify(meta, body);
+
+  // Remove previous capture for this session
+  if (sessionId) {
+    const prev = getPreviousCapture(sessionId);
+    if (prev?.filepath && existsSync(prev.filepath)) {
+      try {
+        unlinkSync(prev.filepath);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  const filepath = resolve(dir, filename);
+  writeFileSync(filepath, content, "utf-8");
+
+  // Append to per-project history
+  appendProjectHistory(process.cwd(), {
+    date: new Date().toISOString().slice(0, 10),
+    title,
+    summary,
+    insights,
+  });
+
+  if (sessionId) markCaptured(sessionId, filepath, messages.length);
+  logDebug("session-intelligence", `Learning captured: ${title}`);
+
+  // ── Write relationship notes ──
+
+  if (!skipRelationship && output?.observations && output.observations.length > 0) {
+    try {
+      const notes: RelationshipNote[] = output.observations.map((o) => ({
+        type: o.type,
+        text: o.text,
+        confidence: o.confidence,
+      }));
+      appendNotes(notes, sessionId);
+      logDebug(
+        "session-intelligence",
+        `${notes.length} relationship observations captured`
+      );
+    } catch (err) {
+      logError("session-intelligence:relationship", err);
+    }
+  }
+
+  // ── Write handoff state ──
+
+  if (handoff && status === "in-progress") {
+    try {
+      const handoffPath = resolve(ensureDir(paths.state()), "last-handoff.json");
+      let handoffs: Record<string, unknown> = {};
+      if (existsSync(handoffPath)) {
+        try {
+          handoffs = JSON.parse(readFileSync(handoffPath, "utf-8"));
+        } catch {
+          /* fresh */
+        }
+      }
+      handoffs[process.cwd()] = {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        title,
+        status,
+        handoff,
+        artifacts: [],
+      };
+      // Keep last 20 projects
+      const entries = Object.entries(handoffs);
+      if (entries.length > 20) handoffs = Object.fromEntries(entries.slice(-20));
+      writeFileSync(handoffPath, JSON.stringify(handoffs, null, 2), "utf-8");
+      logDebug("session-intelligence", "Handoff state written");
+    } catch (err) {
+      logError("session-intelligence:handoff", err);
+    }
+  }
+}

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

@@ -20,9 +20,9 @@ import {
 import { logTokenUsage } from "../lib/token-usage";
 
 const NAME_PROMPT =
-  "You generate concise 4-word session titles for AI coding sessions. " +
+  "You generate concise 4-word session titles for AI assistant sessions. " +
   "Output EXACTLY 4 words in Title Case, no punctuation. Describe the specific task. " +
-  'Example: "Fix Session Name Generation", "Debug Auth Token Refresh"';
+  'Example: "Fix Session Name Generation", "Research Market Entry Strategy"';
 
 export async function captureSessionName(
   message: string,

package/src/hooks/handlers/synthesis.ts

@@ -0,0 +1,36 @@
+/**
+ * Stop handler: Run synthesis if 24h+ since last run.
+ * Imports synthesize logic directly — no subprocess needed.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logDebug } from "../lib/log";
+import { paths } from "../lib/paths";
+
+const SYNTHESIS_TTL_MS = 24 * 60 * 60 * 1000;
+
+export async function runSynthesis(): Promise<void> {
+  const statePath = resolve(paths.state(), "synthesis.json");
+
+  // Check 24h guard
+  if (existsSync(statePath)) {
+    try {
+      const data = JSON.parse(readFileSync(statePath, "utf-8")) as { timestamp: string };
+      if (Date.now() - new Date(data.timestamp).getTime() < SYNTHESIS_TTL_MS) {
+        logDebug("synthesis", "Skipped — last synthesis < 24h ago");
+        return;
+      }
+    } catch {
+      // Corrupted state — run anyway
+    }
+  }
+
+  logDebug("synthesis", "Running synthesis...");
+
+  const { synthesize, writeSynthesis } = await import("../../tools/agent/synthesize");
+  const state = synthesize(7);
+  writeSynthesis(state);
+
+  logDebug("synthesis", "Synthesis complete");
+}

package/src/hooks/handlers/update-check.ts

@@ -1,7 +1,7 @@
 /**
  * Update checker — detects if a newer version of PAL is available.
  *
- * Repo mode (.palroot exists): git fetch + compare HEAD vs origin/main
+ * Repo mode (.git exists next to package): git fetch + compare HEAD vs origin/main
  * Package mode: fetch npm registry for latest version vs installed
  *
  * Caches result in state/update-available.json. Checked at most once per hour.
@@ -47,7 +47,7 @@ function writeCache(cache: UpdateCache): void {
 }
 
 function isRepoMode(): boolean {
-  return existsSync(resolve(palPkg(), ".palroot"));
+  return existsSync(resolve(palPkg(), ".git"));
 }
 
 function getInstalledVersion(): string {

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

@@ -116,7 +116,7 @@ export async function captureWorkLearning(
       .join("\n");
     const result = await inference({
       system:
-        "You summarize AI coding sessions between a human user and an AI assistant. The 'Human messages' are what the user said. The 'AI response' is what the assistant said. Produce: 1) a short title (5-10 words) describing what was accomplished, 2) a summary of what the AI assistant did for the user (2-4 sentences, write from the AI's perspective using 'we'), 3) insights — what worked well, what was surprising, or what should be done differently next time (2-3 bullet points, no markdown).",
+        "You summarize sessions between a human user and an AI assistant. Sessions may involve coding, research, writing, planning, analysis, or any other task. The 'Human messages' are what the user said. The 'AI response' is what the assistant said. Produce: 1) a short title (5-10 words) describing what was accomplished, 2) a summary of what the AI assistant did for the user (2-4 sentences, write from the AI's perspective using 'we'), 3) insights — what worked well, what was surprising, or what should be done differently next time (2-3 bullet points, no markdown).",
       user: `Human messages:\n${userMessages}\n\nAI response:\n${rawSummary.slice(0, 400)}`,
       maxTokens: 300,
       timeout: 15000,

package/src/hooks/lib/context.ts

@@ -333,6 +333,116 @@ export function loadRelationshipContext(): string {
   }
 }
 
+/** Load session intelligence from compact synthesis state */
+export function loadSessionIntelligence(): string {
+  try {
+    const p = resolve(paths.state(), "synthesis.json");
+    if (!existsSync(p)) return "";
+    const state = JSON.parse(readFileSync(p, "utf-8"));
+
+    const lines: string[] = ["## Session Intelligence"];
+
+    // Open Threads — project-specific first, then global
+    if (state.threads?.length > 0) {
+      const cwd = process.cwd();
+      const here = state.threads.filter((t: { cwd?: string }) => t.cwd === cwd);
+      const other = state.threads.filter((t: { cwd?: string }) => t.cwd !== cwd);
+
+      if (here.length > 0) {
+        lines.push("");
+        lines.push(`**Open threads — this project (${here.length}):**`);
+        for (const t of here) {
+          lines.push(`- ${t.title} (opened ${t.opened})`);
+          if (t.context) lines.push(`  ${t.context}`);
+        }
+        lines.push("→ These are directly relevant to your current work.");
+      }
+      if (other.length > 0) {
+        lines.push("");
+        lines.push(`**Open threads — other projects (${other.length}):**`);
+        for (const t of other) {
+          lines.push(`- ${t.title} (opened ${t.opened})`);
+        }
+      }
+    }
+
+    // Rating Trend
+    if (state.ratings?.count > 0) {
+      const r = state.ratings;
+      lines.push("");
+      lines.push(
+        `**Rating trend:** ${r.avg}/10 avg (last 10: ${r.recentAvg}/10, ${r.trend}).${r.lowCount > 0 ? ` ${r.lowCount} low ratings.` : ""}`
+      );
+      if (r.trend === "declining") {
+        lines.push(
+          "→ Trend is declining. Be extra careful with assumptions. Confirm before acting."
+        );
+      } else if (r.trend === "improving") {
+        lines.push("→ Trend is improving. Maintain current approach.");
+      } else if (r.lowCount > 5) {
+        lines.push(
+          "→ Multiple low ratings. Slow down, verify before acting, ask when uncertain."
+        );
+      }
+    }
+
+    // Algorithm Performance
+    if (state.algorithm?.reflectionCount > 0) {
+      const a = state.algorithm;
+      lines.push("");
+      lines.push(
+        `**Algorithm:** ${a.reflectionCount} reflections, ${a.passRate}% criteria pass rate, ${a.avgSentiment}/10 sentiment.`
+      );
+      if (a.passRate < 80) {
+        lines.push(
+          "→ Criteria pass rate is low. Invest more time in OBSERVE and PLAN phases."
+        );
+      }
+      if (a.recentObservations?.length > 0) {
+        const cwd = process.cwd();
+        const relevant = a.recentObservations.filter(
+          (o: { cwd?: string }) => !o.cwd || o.cwd === cwd
+        );
+        if (relevant.length > 0) {
+          lines.push("Recent self-observations (this project):");
+          for (const o of relevant) {
+            lines.push(`- [${o.date}] ${o.task}: "${o.observation}"`);
+          }
+        }
+      }
+    }
+
+    return lines.length > 1 ? lines.join("\n") : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Load handoff state for the current project */
+export function loadHandoff(): string {
+  try {
+    const p = resolve(paths.state(), "last-handoff.json");
+    if (!existsSync(p)) return "";
+    const handoffs = JSON.parse(readFileSync(p, "utf-8"));
+    const cwd = process.cwd();
+    const entry = handoffs[cwd];
+    if (!entry?.handoff || entry.status !== "in-progress") return "";
+
+    const age = Date.now() - new Date(entry.timestamp).getTime();
+    if (age > 7 * 24 * 60 * 60 * 1000) return ""; // stale after 7 days
+
+    return [
+      "## Pick Up Where You Left Off",
+      `*Previous session: ${entry.title}*`,
+      "",
+      entry.handoff,
+      "→ Continue this work or explicitly close it before starting something new.",
+    ].join("\n");
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Build the <system-reminder> content for the AI.
  *
@@ -358,10 +468,16 @@ export function buildSystemReminder(): string {
     ? loadSynthesisRecommendations()
     : "";
   const opinions = isEnabled(settings, "opinions") ? loadOpinionContext() : "";
+  const intelligence = isEnabled(settings, "sessionIntelligence")
+    ? loadSessionIntelligence()
+    : "";
+  const handoff = isEnabled(settings, "handoff") ? loadHandoff() : "";
   const parts: string[] = [];
   if (startup) parts.push(startup);
+  if (handoff) parts.push(handoff);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
+  if (intelligence) parts.push(intelligence);
   if (relationship) parts.push(relationship);
   if (projectHistory) parts.push(projectHistory);
   if (digest) parts.push(digest);

package/src/hooks/lib/paths.ts

@@ -12,20 +12,12 @@ export function palPkg(): string {
 }
 
 /**
- * Root of the user's personal state (telos, memory, etc.).
- * In repo mode: same as palPkg() (the repo root).
- * In package mode: ~/.pal/ (or PAL_HOME override).
- *
- * Repo mode is detected by the presence of .palroot next to the package.
- * This file is not included in the npm package, so it only exists in cloned repos.
+ * Root of the user's personal state (telos, memory, docs, tools, skills).
+ * Always resolves to ~/.pal/ regardless of where the package lives.
+ * Power users who want memory/telos versioned in a repo can override via PAL_HOME.
  */
 export function palHome(): string {
-  if (process.env.PAL_HOME) return process.env.PAL_HOME;
-
-  const pkgRoot = palPkg();
-  if (existsSync(resolve(pkgRoot, ".palroot"))) return pkgRoot;
-
-  return resolve(homedir(), ".pal");
+  return process.env.PAL_HOME || resolve(homedir(), ".pal");
 }
 
 /** Ensure a directory exists, creating it recursively if needed */