portable-agent-layer 0.2.1 → 0.4.0

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

@@ -7,9 +7,11 @@
 
 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 { ensureDir, paths } from "../lib/paths";
+import { getVocabulary, recordSuggestedTag } from "../lib/tags";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -106,18 +108,19 @@ export async function captureWorkLearning(
   let title = rawTitle;
   let summary = rawSummary;
   let insights = "";
+  let tags: string[] = [];
   try {
+    const vocab = getVocabulary();
     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).",
+      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), 4) tags — pick 1-3 from this list: [${vocab.join(", ")}]. If none fit, leave tags empty and put your suggested tag in suggested_tag.`,
       user: `Human messages:\n${userMessages}\n\nAI response:\n${rawSummary.slice(0, 400)}`,
-      maxTokens: 250,
-      timeout: 8000,
+      maxTokens: 350,
+      timeout: 15000,
       jsonSchema: {
         type: "object" as const,
         additionalProperties: false,
@@ -125,8 +128,13 @@ export async function captureWorkLearning(
           title: { type: "string" as const },
           summary: { type: "string" as const },
           insights: { type: "string" as const },
+          tags: {
+            type: "array" as const,
+            items: { type: "string" as const },
+          },
+          suggested_tag: { type: "string" as const },
         },
-        required: ["title", "summary", "insights"],
+        required: ["title", "summary", "insights", "tags"],
       },
     });
     if (result.usage) logTokenUsage("work-learning", result.usage);
@@ -135,10 +143,14 @@ export async function captureWorkLearning(
         title?: string;
         summary?: string;
         insights?: string;
+        tags?: string[];
+        suggested_tag?: string;
       };
       if (parsed.title) title = parsed.title.slice(0, 100);
       if (parsed.summary) summary = parsed.summary;
       if (parsed.insights) insights = parsed.insights;
+      if (parsed.tags?.length) tags = parsed.tags;
+      if (parsed.suggested_tag) recordSuggestedTag(parsed.suggested_tag);
     }
   } catch {
     // Fallback to raw values
@@ -149,21 +161,24 @@ export async function captureWorkLearning(
   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}`] : []),
-    "",
+  const meta: Record<string, unknown> = {
+    title,
+    category,
+    date: new Date().toISOString().slice(0, 10),
+  };
+  if (tags.length > 0) meta.tags = tags;
+  if (sessionId) meta.session = sessionId;
+
+  const body = [
     "## What Was Done",
     summary,
     "",
     "## Insights",
     insights || "*No insights captured.*",
-    "",
   ].join("\n");
 
+  const content = stringify(meta, body);
+
   // Remove previous capture for this session (overwrite on continued conversations)
   if (sessionId) {
     const prev = getPreviousCapture(sessionId);

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

@@ -18,7 +18,7 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { loadTelos } from "./context";
-import { assets, palHome, paths, platform } from "./paths";
+import { assets, ensureDir, palHome, paths, platform } from "./paths";
 import { buildSetupPrompt, readSetupState } from "./setup";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
@@ -116,6 +116,7 @@ export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
   ensureSymlink();
   if (!needsRebuild()) return false;
+  ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
   return true;
 }

package/src/hooks/lib/context.ts

@@ -5,6 +5,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { hasFrontmatter, parse } from "./frontmatter";
 import { paths } from "./paths";
 import { loadRecentNotes } from "./relationship";
 import { readSessionNames } from "./session-names";
@@ -247,28 +248,53 @@ export function loadLearningDigest(): string {
       if (files.length >= 6) break;
     }
 
-    function extractTitle(filePath: string): string {
+    function extractMeta(filePath: string): {
+      title: string;
+      category: string;
+    } {
       const content = readFileSync(filePath, "utf-8").trim();
+
+      // Frontmatter format (new)
+      if (hasFrontmatter(content)) {
+        const { meta } = parse<{ title?: string; category?: string }>(content);
+        return {
+          title: meta.title ? `**Title:** ${meta.title}` : content.slice(0, 80),
+          category: meta.category || "algorithm",
+        };
+      }
+
+      // DEPRECATED: legacy **Title:** inline format — remove once old learning files are migrated
       const titleLine = content.split("\n").find((l) => l.startsWith("**Title:**"));
-      if (titleLine) return titleLine;
-      // Fallback: first non-heading, non-empty line
       const fallback = content.split("\n").find((l) => l.trim() && !l.startsWith("#"));
-      return fallback?.slice(0, 100) ?? content.slice(0, 80);
+      return {
+        title: titleLine ?? fallback?.slice(0, 100) ?? content.slice(0, 80),
+        category: "algorithm", // legacy files use filename for category
+      };
     }
 
-    const algorithm = files.filter((f) => f.category === "algorithm").slice(0, 2);
-    const system = files.filter((f) => f.category === "system").slice(0, 2);
+    // Extract metadata, preferring frontmatter over filename for category
+    const enriched = files.map((f) => {
+      const meta = extractMeta(f.path);
+      return {
+        ...f,
+        title: meta.title,
+        category: meta.category !== "algorithm" ? meta.category : f.category,
+      };
+    });
+
+    const algorithm = enriched.filter((f) => f.category === "algorithm").slice(0, 2);
+    const system = enriched.filter((f) => f.category === "system").slice(0, 2);
 
     if (algorithm.length === 0 && system.length === 0) return "";
 
     const lines: string[] = ["## Recent Session Learnings"];
     if (algorithm.length > 0) {
       lines.push("### Approach");
-      for (const f of algorithm) lines.push(`- ${extractTitle(f.path)}`);
+      for (const f of algorithm) lines.push(`- ${f.title}`);
     }
     if (system.length > 0) {
       lines.push("### System");
-      for (const f of system) lines.push(`- ${extractTitle(f.path)}`);
+      for (const f of system) lines.push(`- ${f.title}`);
     }
     return lines.join("\n");
   } catch {
@@ -292,22 +318,38 @@ export function loadFailurePatterns(): string {
           const dirs = readdirSync(monthPath).sort().reverse();
           for (const dir of dirs) {
             if (!/^\d{8}-\d{6}_/.test(dir)) continue;
-            // Read context from sentiment.json for a meaningful description
+            // Try capture.md (new format), fall back to sentiment.json (legacy)
+            const capturePath = resolve(monthPath, dir, "capture.md");
             const sentimentPath = resolve(monthPath, dir, "sentiment.json");
-            if (existsSync(sentimentPath)) {
+
+            let rating: number | undefined;
+            let ctx: string | undefined;
+
+            if (existsSync(capturePath)) {
+              try {
+                const content = readFileSync(capturePath, "utf-8");
+                const { meta } = parse<{ rating?: number; context?: string }>(content);
+                rating = meta.rating;
+                ctx = meta.context;
+              } catch {
+                /* fallback below */
+              }
+            }
+
+            // DEPRECATED: legacy sentiment.json fallback — remove once old failures have capture.md
+            if (!ctx && existsSync(sentimentPath)) {
               try {
-                const data = JSON.parse(readFileSync(sentimentPath, "utf-8")) as {
-                  rating?: number;
-                  context?: string;
-                };
-                if (data.context) {
-                  const label = data.rating ? `[${data.rating}/10]` : "";
-                  failures.push(`${label} ${data.context}`.trim());
-                }
+                const data = JSON.parse(readFileSync(sentimentPath, "utf-8"));
+                rating = data.rating;
+                ctx = data.context;
               } catch {
-                // Fall back to slug from directory name
-                failures.push(dir.replace(/^\d{8}-\d{6}_/, ""));
+                /* skip */
               }
+            }
+
+            if (ctx) {
+              const label = rating ? `[${rating}/10]` : "";
+              failures.push(`${label} ${ctx}`.trim());
             } else {
               failures.push(dir.replace(/^\d{8}-\d{6}_/, ""));
             }
@@ -361,12 +403,28 @@ export function loadSynthesisRecommendations(): string {
 
         if (recs.length === 0) continue;
 
-        // Extract metadata
-        const periodMatch = content.match(/\*\*Period:\*\* (.+)/);
-        const avgMatch = content.match(/\*\*Average Rating:\*\* (.+)/);
+        // Extract metadata — frontmatter or legacy
+        let period = "";
+        let avgRating = "";
+
+        if (hasFrontmatter(content)) {
+          const { meta } = parse<{
+            period?: string;
+            average_rating?: string;
+          }>(content);
+          period = meta.period || "";
+          avgRating = meta.average_rating ? `${meta.average_rating}/10` : "";
+        } else {
+          // DEPRECATED: legacy **Key:** format
+          const periodMatch = content.match(/\*\*Period:\*\* (.+)/);
+          const avgMatch = content.match(/\*\*Average Rating:\*\* (.+)/);
+          period = periodMatch?.[1] || "";
+          avgRating = avgMatch?.[1] || "";
+        }
+
         const header = [
           "## Pattern Synthesis",
-          periodMatch ? `*${periodMatch[1]} — ${avgMatch?.[1] ?? ""}*` : "",
+          period ? `*${period} — ${avgRating}*` : "",
         ]
           .filter(Boolean)
           .join("\n");

package/src/hooks/lib/frontmatter.ts

@@ -0,0 +1,95 @@
+/**
+ * Lightweight YAML frontmatter parser/serializer.
+ *
+ * No external dependencies — parses simple key: value YAML between --- delimiters.
+ * Supports strings, numbers, booleans, and inline JSON arrays.
+ */
+
+export interface Parsed<T = Record<string, string>> {
+  meta: T;
+  body: string;
+}
+
+const DELIMITER = /^---\s*$/m;
+
+/**
+ * Parse frontmatter from a markdown string.
+ * Returns typed meta + body. If no frontmatter found, meta is empty and body is the full content.
+ */
+export function parse<T = Record<string, string>>(content: string): Parsed<T> {
+  const parts = content.split(DELIMITER);
+
+  // Need at least 3 parts: before --- | frontmatter | after ---
+  // parts[0] should be empty (content starts with ---)
+  if (parts.length < 3 || parts[0].trim() !== "") {
+    return { meta: {} as T, body: content };
+  }
+
+  const rawMeta = parts[1];
+  const body = parts.slice(2).join("---").trim();
+
+  const meta: Record<string, unknown> = {};
+  for (const line of rawMeta.split("\n")) {
+    const match = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+
+    // Inline JSON array
+    if (value.startsWith("[") && value.endsWith("]")) {
+      try {
+        meta[key] = JSON.parse(value);
+        continue;
+      } catch {
+        // Fall through to string handling
+      }
+    }
+
+    // Strip quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      meta[key] = value.slice(1, -1).replace(/\\"/g, '"');
+      continue;
+    }
+
+    // Type coercion
+    if (value === "true") meta[key] = true;
+    else if (value === "false") meta[key] = false;
+    else if (/^\d+$/.test(value)) meta[key] = Number.parseInt(value, 10);
+    else if (/^\d+\.\d+$/.test(value)) meta[key] = Number.parseFloat(value);
+    else meta[key] = value;
+  }
+
+  return { meta: meta as T, body };
+}
+
+/**
+ * Serialize metadata and body into a frontmatter string.
+ * Skips undefined/null values.
+ */
+export function stringify(meta: Record<string, unknown>, body: string): string {
+  const lines: string[] = ["---"];
+
+  for (const [key, value] of Object.entries(meta)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+    } else if (typeof value === "string") {
+      lines.push(`${key}: "${value.replace(/"/g, '\\"')}"`);
+    } else {
+      lines.push(`${key}: ${String(value)}`);
+    }
+  }
+
+  lines.push("---");
+  return `${lines.join("\n")}\n\n${body.trim()}\n`;
+}
+
+/**
+ * Check if content has frontmatter (starts with ---).
+ */
+export function hasFrontmatter(content: string): boolean {
+  return content.trimStart().startsWith("---");
+}