portable-agent-layer 0.1.0

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

@@ -0,0 +1,121 @@
+/**
+ * UserPromptSubmit handler: generates a 4-word name for the session.
+ *
+ * Architecture (fast-exit):
+ * - First prompt: instant deterministic name from keywords (<10ms),
+ *   then spawns a detached background process to upgrade via inference.
+ * - Subsequent prompts: no-op (name already set).
+ *
+ * This avoids the 1-5s inference latency that previously blocked every first prompt.
+ */
+
+// import { spawn } from "node:child_process";
+import { inference } from "../lib/inference";
+import { logDebug, logError } from "../lib/log";
+import {
+  extractFallbackName,
+  readSessionNames,
+  writeSessionName,
+} from "../lib/session-names";
+import { logTokenUsage } from "../lib/token-usage";
+
+const NAME_PROMPT =
+  "You generate concise 4-word session titles for AI coding sessions. " +
+  "Output EXACTLY 4 words in Title Case, no punctuation. Describe the specific task. " +
+  'Example: "Fix Session Name Generation", "Debug Auth Token Refresh"';
+
+export async function captureSessionName(
+  message: string,
+  sessionId: string
+): Promise<void> {
+  if (!sessionId) return;
+
+  // Skip if this session is already named
+  const names = readSessionNames();
+  if (names[sessionId]) return;
+
+  // 1. Instant deterministic name from keywords
+  const fallback = extractFallbackName(message);
+  writeSessionName(sessionId, fallback);
+  logDebug("session-name", `Deterministic name: "${fallback}"`);
+
+  // TODO: re-enable when a consumer exists (tab titles, dashboard)
+  // // 2. Spawn detached background process to upgrade with inference
+  // if (!process.env.ANTHROPIC_API_KEY) return;
+  // try {
+  //   const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
+  //   const child = spawn(
+  //     "bun",
+  //     [import.meta.filename, "--upgrade", sessionId, promptB64, fallback],
+  //     {
+  //       detached: true,
+  //       stdio: "ignore",
+  //       env: { ...process.env, CLAUDECODE: undefined },
+  //     }
+  //   );
+  //   child.unref();
+  //   logDebug("session-name", "Spawned background inference upgrade");
+  // } catch {
+  //   // Non-critical — deterministic name is already stored
+  // }
+}
+
+/**
+ * Background upgrade mode: called via --upgrade flag from a detached subprocess.
+ * Runs inference for a better name, writes only if the name hasn't changed since spawn.
+ */
+async function upgradeWithInference(
+  sessionId: string,
+  promptB64: string,
+  expectedName: string
+): Promise<void> {
+  try {
+    // Version guard: if name changed since we were spawned, skip
+    const currentNames = readSessionNames();
+    if (currentNames[sessionId] !== expectedName) return;
+
+    const promptText = Buffer.from(promptB64, "base64").toString("utf-8");
+    const result = await inference({
+      system: NAME_PROMPT,
+      user: `Generate a 4-word title for: "${promptText}"`,
+      maxTokens: 20,
+      timeout: 10000,
+    });
+
+    if (result.usage) logTokenUsage("session-name", result.usage);
+    if (!result.success || !result.output) return;
+
+    let label = result.output
+      .replace(/^["']|["']$/g, "")
+      .replace(/[.!?,;:]/g, "")
+      .trim();
+
+    const words = label.split(/\s+/).slice(0, 4);
+    label = words
+      .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+      .join(" ");
+
+    const allSubstantial = words.every((w) => w.length >= 3);
+    if (!label || words.length !== 4 || !allSubstantial) return;
+
+    // Only write if name hasn't changed (re-read under guard)
+    const freshNames = readSessionNames();
+    if (freshNames[sessionId] !== expectedName) return;
+
+    writeSessionName(sessionId, label);
+    logDebug("session-name", `Background upgrade: "${label}"`);
+  } catch (err) {
+    logError("session-name:upgrade", err);
+  }
+}
+
+// Background upgrade entry point
+if (process.argv[2] === "--upgrade") {
+  const sid = process.argv[3];
+  const prompt = process.argv[4];
+  const expected = process.argv[5];
+  if (sid && prompt && expected !== undefined) {
+    await upgradeWithInference(sid, prompt, expected);
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/synthesis.ts

@@ -0,0 +1,109 @@
+/**
+ * Auto-trigger pattern synthesis on Stop when conditions are met:
+ * - 7+ days since last synthesis report
+ * - 20+ new ratings since last synthesis
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logDebug } from "../lib/log";
+import { palPkg, paths } from "../lib/paths";
+
+const MIN_DAYS_BETWEEN = 7;
+const MIN_NEW_RATINGS = 20;
+
+function getLastSynthesisDate(): Date | null {
+  try {
+    const synthDir = paths.synthesis();
+    if (!existsSync(synthDir)) return null;
+
+    const months = readdirSync(synthDir).sort().reverse();
+    for (const month of months) {
+      const monthDir = resolve(synthDir, month);
+      const files = readdirSync(monthDir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .reverse();
+      if (files.length > 0) {
+        // Filename: YYYY-MM-DD_period-patterns.md
+        const dateStr = files[0].slice(0, 10);
+        const date = new Date(dateStr);
+        if (!Number.isNaN(date.getTime())) return date;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+function countRatingsSince(since: Date | null): number {
+  try {
+    const ratingsFile = resolve(paths.signals(), "ratings.jsonl");
+    if (!existsSync(ratingsFile)) return 0;
+
+    const lines = readFileSync(ratingsFile, "utf-8").trim().split("\n");
+    if (!since) return lines.length;
+
+    let count = 0;
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line) as { ts?: string };
+        if (entry.ts && new Date(entry.ts) > since) count++;
+      } catch {
+        /* skip bad lines */
+      }
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+export async function checkSynthesisTrigger(): Promise<void> {
+  const lastDate = getLastSynthesisDate();
+  const now = new Date();
+
+  // Check days since last synthesis
+  if (lastDate) {
+    const daysSince = (now.getTime() - lastDate.getTime()) / (1000 * 60 * 60 * 24);
+    if (daysSince < MIN_DAYS_BETWEEN) {
+      logDebug(
+        "synthesis",
+        `Skipping: only ${daysSince.toFixed(1)} days since last report`
+      );
+      return;
+    }
+  }
+
+  // Check new rating count
+  const newRatings = countRatingsSince(lastDate);
+  if (newRatings < MIN_NEW_RATINGS) {
+    logDebug(
+      "synthesis",
+      `Skipping: only ${newRatings} new ratings (need ${MIN_NEW_RATINGS})`
+    );
+    return;
+  }
+
+  logDebug(
+    "synthesis",
+    `Triggering: ${newRatings} new ratings, ${lastDate ? `last report: ${lastDate.toISOString().slice(0, 10)}` : "no previous report"}`
+  );
+
+  // Spawn synthesis as a detached process so it doesn't block the Stop handler
+  try {
+    const repoDir = palPkg();
+    const proc = Bun.spawn(["bun", "run", "tool:patterns"], {
+      cwd: repoDir,
+      stdout: "ignore",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    // Don't await — let it run in background
+    proc.unref();
+    logDebug("synthesis", "Spawned pattern synthesis in background");
+  } catch (err) {
+    logDebug("synthesis", `Failed to spawn: ${err}`);
+  }
+}

package/src/hooks/handlers/tab.ts

@@ -0,0 +1,8 @@
+/**
+ * Stop handler: resets terminal tab title to default.
+ */
+
+export async function resetTab(): Promise<void> {
+  // Reset terminal tab title
+  process.stdout.write("\x1b]0;claude\x07");
+}

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

@@ -0,0 +1,151 @@
+/**
+ * Stop handler: writes fresh counts to memory/state/counts.json
+ * so the session-start greeting can read a single file instead of
+ * scanning directories and JSONL files.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { assets, ensureDir, paths } from "../lib/paths";
+
+interface TokenSummary {
+  input: number;
+  output: number;
+}
+
+interface TokenUsage {
+  today: TokenSummary;
+  week: TokenSummary;
+  month: TokenSummary;
+  total: TokenSummary;
+}
+
+interface Counts {
+  signals: number;
+  telos: number;
+  skills: number;
+  sessions: number;
+  tokens: TokenUsage;
+  updatedAt: string;
+}
+
+function countJsonlLines(filepath: string): number {
+  try {
+    if (!existsSync(filepath)) return 0;
+    const content = readFileSync(filepath, "utf-8").trim();
+    return content ? content.split("\n").length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function countMdFiles(dir: string): number {
+  try {
+    if (!existsSync(dir)) return 0;
+    return readdirSync(dir).filter((f) => f.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+
+function getTokenUsage(): TokenUsage {
+  const today: TokenSummary = { input: 0, output: 0 };
+  const week: TokenSummary = { input: 0, output: 0 };
+  const month: TokenSummary = { input: 0, output: 0 };
+  const total: TokenSummary = { input: 0, output: 0 };
+
+  const filepath = resolve(paths.signals(), "token-usage.jsonl");
+  if (!existsSync(filepath)) return { today, week, month, total };
+
+  try {
+    const content = readFileSync(filepath, "utf-8").trim();
+    if (!content) return { today, week, month, total };
+
+    const now = new Date();
+    const todayPrefix = now.toISOString().slice(0, 10);
+    const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const monthAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
+
+    for (const line of content.split("\n")) {
+      try {
+        const entry = JSON.parse(line) as {
+          ts?: string;
+          inputTokens?: number;
+          outputTokens?: number;
+        };
+        const input = entry.inputTokens ?? 0;
+        const output = entry.outputTokens ?? 0;
+        const ts = entry.ts ?? "";
+
+        total.input += input;
+        total.output += output;
+        if (ts >= monthAgo) {
+          month.input += input;
+          month.output += output;
+        }
+        if (ts >= weekAgo) {
+          week.input += input;
+          week.output += output;
+        }
+        if (ts.startsWith(todayPrefix)) {
+          today.input += input;
+          today.output += output;
+        }
+      } catch {
+        /* skip malformed line */
+      }
+    }
+  } catch {
+    /* file read error */
+  }
+
+  return { today, week, month, total };
+}
+
+function getCounts(): Counts {
+  const signalsDir = paths.signals();
+  const signals = countJsonlLines(resolve(signalsDir, "ratings.jsonl"));
+
+  const telos = countMdFiles(paths.telos());
+
+  // Count skills in the PAL skills dir
+  let skills = 0;
+  const skillsDir = assets.skills();
+  try {
+    if (existsSync(skillsDir)) {
+      skills = readdirSync(skillsDir, { withFileTypes: true }).filter((e) =>
+        e.isDirectory()
+      ).length;
+    }
+  } catch {
+    /* skip */
+  }
+
+  // Count named sessions
+  let sessions = 0;
+  try {
+    const namesPath = resolve(paths.state(), "session-names.json");
+    if (existsSync(namesPath)) {
+      sessions = Object.keys(JSON.parse(readFileSync(namesPath, "utf-8"))).length;
+    }
+  } catch {
+    /* skip */
+  }
+
+  const tokens = getTokenUsage();
+
+  return {
+    signals,
+    telos,
+    skills,
+    sessions,
+    tokens,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export async function updateCounts(): Promise<void> {
+  const counts = getCounts();
+  const countsPath = resolve(ensureDir(paths.state()), "counts.json");
+  writeFileSync(countsPath, JSON.stringify(counts, null, 2), "utf-8");
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Stop handler: writes a structured learning file for significant sessions.
+ * Dedup: only writes once per session ID (tracks in a marker file).
+ * Threshold: >2000 chars transcript + at least 6 messages.
+ * Output: memory/learning/session/YYYY-MM/{datetime}_work_{slug}.md
+ */
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { inference } from "../lib/inference";
+import { categorizeLearning } from "../lib/learning-category";
+import { ensureDir, paths } from "../lib/paths";
+import { fileTimestamp, monthPath } from "../lib/time";
+import { logTokenUsage } from "../lib/token-usage";
+import {
+  extractContent,
+  extractLastAssistant,
+  extractLastUser,
+  parseMessages,
+} from "../lib/transcript";
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 4)
+    .join("-");
+}
+
+const MIN_NEW_MESSAGES = 10;
+
+interface CaptureEntry {
+  filepath: string;
+  messageCount: number;
+}
+
+/** Get the previously captured entry for a session, if any */
+function getPreviousCapture(sessionId: string): CaptureEntry | null {
+  const markerPath = resolve(paths.state(), "captured-learnings.json");
+  if (!existsSync(markerPath)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(markerPath, "utf-8"));
+    if (Array.isArray(raw)) return null;
+    const entry = raw[sessionId];
+    if (!entry) return null;
+    // Migrate old string format
+    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 markerPath = resolve(paths.state(), "captured-learnings.json");
+  let data: Record<string, CaptureEntry> = {};
+  try {
+    if (existsSync(markerPath)) {
+      const raw = JSON.parse(readFileSync(markerPath, "utf-8"));
+      if (!Array.isArray(raw) && typeof raw === "object") {
+        for (const [k, v] of Object.entries(raw)) {
+          if (typeof v === "string") {
+            data[k] = { filepath: v, messageCount: 0 };
+          } else {
+            data[k] = v as CaptureEntry;
+          }
+        }
+      }
+    }
+  } catch {
+    /* start fresh */
+  }
+  data[sessionId] = { filepath, messageCount };
+  // Keep last 50
+  const entries = Object.entries(data);
+  if (entries.length > 50) {
+    data = Object.fromEntries(entries.slice(-50));
+  }
+  writeFileSync(markerPath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+export async function captureWorkLearning(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  if (transcript.length < 2000) return;
+
+  const messages = parseMessages(transcript);
+  if (messages.length < 6) return;
+
+  // Skip if not enough new messages since last capture
+  if (sessionId) {
+    const prev = getPreviousCapture(sessionId);
+    if (prev && messages.length - prev.messageCount < MIN_NEW_MESSAGES) return;
+  }
+
+  const lastUser = extractLastUser(messages);
+  const lastAssistant = extractLastAssistant(messages);
+
+  const rawTitle = extractContent(lastUser).slice(0, 80) || "session";
+  const rawSummary = extractContent(lastAssistant).slice(0, 600);
+
+  // Generate title, summary, and insights in a single inference call
+  let title = rawTitle;
+  let summary = rawSummary;
+  let insights = "";
+  try {
+    const userMessages = messages
+      .filter((m) => m.role === "user")
+      .map((m) => extractContent(m).slice(0, 100))
+      .slice(-8)
+      .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).",
+      user: `Human messages:\n${userMessages}\n\nAI response:\n${rawSummary.slice(0, 400)}`,
+      maxTokens: 250,
+      timeout: 8000,
+      jsonSchema: {
+        type: "object" as const,
+        additionalProperties: false,
+        properties: {
+          title: { type: "string" as const },
+          summary: { type: "string" as const },
+          insights: { type: "string" as const },
+        },
+        required: ["title", "summary", "insights"],
+      },
+    });
+    if (result.usage) logTokenUsage("work-learning", result.usage);
+    if (result.success && result.output) {
+      const parsed = JSON.parse(result.output) as {
+        title?: string;
+        summary?: string;
+        insights?: string;
+      };
+      if (parsed.title) title = parsed.title.slice(0, 100);
+      if (parsed.summary) summary = parsed.summary;
+      if (parsed.insights) insights = parsed.insights;
+    }
+  } catch {
+    // Fallback to raw values
+  }
+  const category = categorizeLearning(title, summary);
+
+  const slug = slugify(title);
+  const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
+  const filename = `${fileTimestamp()}_${category}_${slug}.md`;
+
+  const content = [
+    "# Work Completion Learning",
+    `**Title:** ${title}`,
+    `**Category:** ${category.toUpperCase()}`,
+    `**Date:** ${new Date().toISOString().slice(0, 10)}`,
+    ...(sessionId ? [`**Session:** ${sessionId}`] : []),
+    "",
+    "## What Was Done",
+    summary,
+    "",
+    "## Insights",
+    insights || "*No insights captured.*",
+    "",
+  ].join("\n");
+
+  // Remove previous capture for this session (overwrite on continued conversations)
+  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");
+
+  if (sessionId) markCaptured(sessionId, filepath, messages.length);
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Stop handler: captures structured session records.
+ * Replaces the old work.ts handler.
+ */
+
+import { readSessionNames } from "../lib/session-names";
+import { now } from "../lib/time";
+import {
+  extractContent,
+  extractLastAssistant,
+  extractLastUser,
+  parseMessages,
+} from "../lib/transcript";
+import {
+  detectStatus,
+  extractArtifacts,
+  extractHandoff,
+  type SessionRecord,
+  writeSession,
+} from "../lib/work-tracking";
+
+export async function captureWorkSession(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  try {
+    const messages = parseMessages(transcript);
+    if (messages.length < 2) return;
+
+    const id = sessionId || `session-${Date.now()}`;
+
+    // Look up session name
+    const names = readSessionNames();
+    const name = names[id] || "untitled session";
+
+    // Extract content
+    const lastUser = extractLastUser(messages);
+    const lastAssistant = extractLastAssistant(messages);
+    const lastAssistantText = extractContent(lastAssistant);
+    const summary = extractContent(lastUser).slice(0, 300);
+
+    const record: SessionRecord = {
+      sessionId: id,
+      name,
+      ts: now(),
+      cwd: process.cwd(),
+      status: detectStatus(lastAssistantText),
+      summary,
+      artifacts: extractArtifacts(messages),
+      handoff: extractHandoff(lastAssistantText),
+      messageCount: messages.length,
+    };
+
+    writeSession(record);
+  } catch {
+    // Non-critical
+  }
+}