portable-agent-layer 0.22.0 → 0.23.1

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/failure.ts

@@ -30,7 +30,8 @@ export async function captureFailure(
   rating: number,
   context: string,
   transcript: string,
-  detailedContext?: string
+  detailedContext?: string,
+  principle?: string
 ): Promise<void> {
   const messages = parseMessages(transcript);
 
@@ -55,6 +56,7 @@ export async function captureFailure(
     ts: new Date().toISOString(),
     slug,
   };
+  if (principle) meta.principle = principle;
 
   const body = [
     "## What Happened",

package/src/hooks/handlers/rating.ts

@@ -166,8 +166,16 @@ const SENTIMENT_SCHEMA = {
     confidence: { type: "number" },
     summary: { type: "string" },
     detailed_context: { type: "string" },
+    principle: { type: "string" },
   },
-  required: ["rating", "sentiment", "confidence", "summary", "detailed_context"],
+  required: [
+    "rating",
+    "sentiment",
+    "confidence",
+    "summary",
+    "detailed_context",
+    "principle",
+  ],
   additionalProperties: false,
 } as const;
 
@@ -177,6 +185,7 @@ interface SentimentResult {
   confidence: number;
   summary: string;
   detailed_context: string;
+  principle: string;
 }
 
 const SENTIMENT_SYSTEM_PROMPT = `Analyze the user's message for emotional sentiment toward the AI assistant.
@@ -187,7 +196,8 @@ OUTPUT FORMAT (JSON only):
   "sentiment": "positive" | "negative" | "neutral",
   "confidence": <0.0-1.0>,
   "summary": "<brief explanation, 10 words max>",
-  "detailed_context": "<comprehensive analysis, 50-150 words>"
+  "detailed_context": "<comprehensive analysis, 50-150 words>",
+  "principle": "<one actionable rule the AI should follow to avoid this failure or repeat this success, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>"
 }
 
 DETAILED_CONTEXT REQUIREMENTS:
@@ -240,6 +250,7 @@ function handleRating(
   context: string,
   source: string,
   detailedContext?: string,
+  principle?: string,
   sessionId?: string,
   userMessage?: string
 ): void {
@@ -257,6 +268,7 @@ function handleRating(
           context,
           source,
           detailedContext,
+          principle,
           responsePreview,
           userPreview,
           ts: now(),
@@ -284,6 +296,7 @@ async function handleImplicitSentiment(
       `Direct praise: "${trimmed}"`,
       "implicit",
       undefined,
+      undefined,
       sessionId,
       trimmed
     );
@@ -328,6 +341,7 @@ async function handleImplicitSentiment(
         `${parsed.summary}: ${trimmed.slice(0, 200)}`,
         "implicit",
         parsed.detailed_context,
+        parsed.principle,
         sessionId,
         trimmed
       );
@@ -352,6 +366,7 @@ export async function captureRating(message: string, sessionId?: string): Promis
       explicit.comment || cleaned.slice(0, 200),
       "explicit",
       undefined,
+      undefined,
       sessionId,
       cleaned
     );

package/src/hooks/handlers/reflect-trigger.ts

@@ -1,7 +1,7 @@
 /**
  * Auto-trigger for relationship reflect — runs when conditions are met:
- * - 7+ days since last reflect
- * - 10+ new relationship notes since last reflect
+ * - 1+ days since last reflect
+ * - 5+ new relationship notes since last reflect
  *
  * Spawns `bun run tool:reflect` as a detached background process.
  */
@@ -12,8 +12,8 @@ import { logDebug } from "../lib/log";
 import { getLastReflectDate } from "../lib/opinions";
 import { palPkg, paths } from "../lib/paths";
 
-const MIN_DAYS_BETWEEN = 7;
-const MIN_NEW_NOTES = 10;
+const MIN_DAYS_BETWEEN = 1;
+const MIN_NEW_NOTES = 5;
 
 function countNotesSince(since: string): number {
   const relDir = paths.relationship();

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,