portable-agent-layer 0.1.0

package/src/hooks/handlers/backup.ts

@@ -0,0 +1,41 @@
+/**
+ * Stop handler: automatic weekly backup.
+ * Creates a zip of all gitignored personal files if the last backup
+ * is older than 7 days, or if no backup exists yet.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { exportZip, timestamp } from "../lib/export";
+import { logDebug } from "../lib/log";
+import { paths } from "../lib/paths";
+
+const BACKUP_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+export async function autoBackup(): Promise<void> {
+  const backupDir = paths.backups();
+
+  // Check most recent backup
+  const existing = readdirSync(backupDir)
+    .filter((f) => f.startsWith("pal-backup-") && f.endsWith(".zip"))
+    .sort()
+    .reverse();
+
+  if (existing.length > 0) {
+    const latestPath = resolve(backupDir, existing[0]);
+    const latestMtime = statSync(latestPath).mtimeMs;
+    if (Date.now() - latestMtime < BACKUP_INTERVAL_MS) {
+      logDebug("backup", "Skipping — last backup is less than 7 days old");
+      return;
+    }
+  }
+
+  const outputPath = resolve(backupDir, `pal-backup-${timestamp()}.zip`);
+  const count = exportZip(outputPath);
+
+  if (count === 0) {
+    logDebug("backup", "Nothing to back up");
+  } else {
+    logDebug("backup", `Backed up ${count} files → ${outputPath}`);
+  }
+}

package/src/hooks/handlers/failure.ts

@@ -0,0 +1,136 @@
+/**
+ * Deep Failure Capture — full context dump for ratings 1–3.
+ *
+ * Writes to memory/learning/failures/YYYY-MM/{timestamp}_{slug}/
+ *   CONTEXT.md    — full failure context with transcript excerpt
+ *   sentiment.json — structured rating + metadata
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { inference } from "../lib/inference";
+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, 8)
+      .join("-") || "failure"
+  );
+}
+
+export async function captureFailure(
+  rating: number,
+  context: string,
+  transcript: string,
+  detailedContext?: string,
+  savedResponse?: string,
+  savedUserMessage?: string
+): Promise<void> {
+  const messages = parseMessages(transcript);
+  // Prefer messages saved at rating time (before the AI replied to the rating)
+  const lastUser =
+    savedUserMessage?.slice(0, 400) ||
+    extractContent(extractLastUser(messages)).slice(0, 400);
+  const lastAssistant =
+    savedResponse?.slice(0, 600) ||
+    extractContent(extractLastAssistant(messages)).slice(0, 600);
+
+  const slug = slugify(context);
+  const dir = ensureDir(
+    resolve(paths.failures(), monthPath(), `${fileTimestamp()}_${slug}`)
+  );
+
+  // Attempt inference to fill root cause analysis
+  let whatWentWrong = "";
+  let whatToDoDifferently = "";
+  try {
+    const analysisResult = await inference({
+      system:
+        "You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable.",
+      user: [
+        `Rating: ${rating}/10`,
+        `Context: ${context}`,
+        detailedContext ? `Analysis: ${detailedContext}` : "",
+        `User said: ${lastUser}`,
+        `Assistant said: ${lastAssistant}`,
+      ]
+        .filter(Boolean)
+        .join("\n"),
+      maxTokens: 300,
+      timeout: 8000,
+      jsonSchema: {
+        type: "object" as const,
+        additionalProperties: false,
+        properties: {
+          what_went_wrong: { type: "string" as const },
+          what_to_do_differently: { type: "string" as const },
+        },
+        required: ["what_went_wrong", "what_to_do_differently"],
+      },
+    });
+    if (analysisResult.usage) logTokenUsage("failure", analysisResult.usage);
+    if (analysisResult.success && analysisResult.output) {
+      const parsed = JSON.parse(analysisResult.output) as {
+        what_went_wrong?: string;
+        what_to_do_differently?: string;
+      };
+      whatWentWrong = parsed.what_went_wrong ?? "";
+      whatToDoDifferently = parsed.what_to_do_differently ?? "";
+    }
+  } catch {
+    // Graceful fallback — empty sections are still useful with the other context
+  }
+
+  const contextMdPath = resolve(dir, "CONTEXT.md");
+  writeFileSync(
+    contextMdPath,
+    [
+      `# Failure Capture — Rating ${rating}/10`,
+      `**Date:** ${new Date().toISOString().slice(0, 10)}`,
+      `**Context:** ${context}`,
+      "",
+      "## Last User Message",
+      lastUser || "*(unavailable)*",
+      "",
+      "## Last Assistant Response",
+      lastAssistant || "*(unavailable)*",
+      "",
+      ...(detailedContext ? ["## AI Response Context", detailedContext, ""] : []),
+      "## What Went Wrong?",
+      whatWentWrong || "",
+      "",
+      "## What Should Be Done Differently?",
+      whatToDoDifferently || "",
+      "",
+    ].join("\n"),
+    "utf-8"
+  );
+
+  writeFileSync(
+    resolve(dir, "sentiment.json"),
+    JSON.stringify(
+      {
+        rating,
+        context,
+        ts: new Date().toISOString(),
+        slug,
+      },
+      null,
+      2
+    ),
+    "utf-8"
+  );
+}

package/src/hooks/handlers/rating.ts

@@ -0,0 +1,409 @@
+/**
+ * UserPromptSubmit handler: detects explicit and implicit ratings.
+ * Ported from original PAI's RatingCapture.hook.ts with rich sentiment analysis.
+ *
+ * - Explicit: "7", "8 - great work", "rating: 8"
+ * - Implicit: Haiku-powered sentiment inference on every user message
+ * - Low ratings (<5) write detailed learning markdown
+ * - Very low ratings (<=3) write pending-failure.json for Stop handler
+ */
+
+import { existsSync, readFileSync, 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 { emitRating } from "../lib/signals";
+import { fileTimestamp, monthPath, now } from "../lib/time";
+import { logTokenUsage } from "../lib/token-usage";
+
+/** Read cached last assistant response (written by StopOrchestrator), looked up by session */
+function getLastResponse(sessionId?: string): string {
+  try {
+    const cachePath = resolve(paths.state(), "last-responses.json");
+    if (!existsSync(cachePath)) return "";
+    const cache = JSON.parse(readFileSync(cachePath, "utf-8")) as Record<
+      string,
+      { response?: string }
+    >;
+    // Look up by session, or fall back to most recent entry
+    if (sessionId && cache[sessionId]) {
+      return cache[sessionId].response ?? "";
+    }
+    // No session match — return empty rather than wrong context
+    return "";
+  } catch {
+    /* non-critical */
+  }
+  return "";
+}
+
+// ── Explicit Rating Detection ──
+
+/**
+ * Parse explicit rating pattern from prompt.
+ * Matches: "7", "8 - good work", "6: needs work", "9 excellent", "10!"
+ * Rejects: "3 items", "5 things to fix", "7th thing", "10/10"
+ */
+function parseExplicitRating(
+  prompt: string
+): { rating: number; comment?: string } | null {
+  const trimmed = prompt.trim();
+  const match = trimmed.match(/^(10|[1-9])(?:\s*[-:]\s*|\s+)?(.*)$/);
+  if (!match) return null;
+
+  const rating = parseInt(match[1], 10);
+  if (rating < 1 || rating > 10) return null;
+
+  // Reject if char after number is not a separator (catches "10/10", "3.5", "7th")
+  const afterNumber = trimmed.slice(match[1].length);
+  if (afterNumber.length > 0 && /^[/.\dA-Za-z]/.test(afterNumber)) return null;
+
+  const rest = match[2]?.trim() || undefined;
+
+  // Reject if rest starts with words indicating a sentence, not a rating
+  if (rest) {
+    const sentenceStarters =
+      /^(items?|things?|steps?|files?|lines?|bugs?|issues?|errors?|times?|minutes?|hours?|days?|seconds?|percent|%|th\b|st\b|nd\b|rd\b|of\b|in\b|at\b|to\b|the\b|a\b|an\b)/i;
+    if (sentenceStarters.test(rest)) return null;
+  }
+
+  return { rating, comment: rest };
+}
+
+// ── Praise Fast-Path ──
+
+const POSITIVE_PRAISE_WORDS = new Set([
+  "excellent",
+  "amazing",
+  "brilliant",
+  "fantastic",
+  "wonderful",
+  "incredible",
+  "awesome",
+  "perfect",
+  "great",
+  "nice",
+  "superb",
+  "outstanding",
+  "stellar",
+  "phenomenal",
+  "remarkable",
+  "terrific",
+  "splendid",
+]);
+
+const POSITIVE_PHRASES = new Set([
+  "great job",
+  "good job",
+  "nice work",
+  "well done",
+  "nice job",
+  "good work",
+  "love it",
+  "nailed it",
+  "looks great",
+  "looks good",
+  "rock solid",
+  "thats great",
+  "that works",
+  "thank you",
+  "thanks",
+]);
+
+function isPraise(prompt: string): boolean {
+  const normalized = prompt
+    .trim()
+    .toLowerCase()
+    .replace(/[.!?,'"]/g, "");
+  const words = normalized.split(/\s+/);
+  if (words.length > 3) return false;
+  return (
+    POSITIVE_PRAISE_WORDS.has(normalized) ||
+    POSITIVE_PHRASES.has(normalized) ||
+    (words.length === 2 && words.every((w) => POSITIVE_PRAISE_WORDS.has(w)))
+  );
+}
+
+// ── System-Injected Tag Stripping ──
+
+/**
+ * Strip IDE/system-injected XML tags from the prompt to recover the raw user text.
+ * Claude Code VSCode extension prepends tags like <ide_opened_file>...</ide_opened_file>
+ * and <ide_selection>...</ide_selection> to the prompt field in hooks.
+ */
+const INJECTED_TAG_RE =
+  /<(?:ide_opened_file|ide_selection|system-reminder|task-notification)[^>]*>[\s\S]*?<\/(?:ide_opened_file|ide_selection|system-reminder|task-notification)>/gi;
+
+function stripInjectedTags(prompt: string): string {
+  return prompt.replace(INJECTED_TAG_RE, "").trim();
+}
+
+// ── System Text Filters ──
+
+const SYSTEM_TEXT_PATTERNS = [
+  /^<task-notification>/i,
+  /^<system-reminder>/i,
+  /^This session is being continued from a previous conversation/i,
+  /^Please continue the conversation/i,
+  /^Note:.*was read before/i,
+];
+
+function isSystemText(prompt: string): boolean {
+  const trimmed = prompt.trim();
+  return SYSTEM_TEXT_PATTERNS.some((re) => re.test(trimmed));
+}
+
+// ── Sentiment Analysis ──
+
+const SENTIMENT_SCHEMA = {
+  type: "object",
+  properties: {
+    rating: { type: ["number", "null"] },
+    sentiment: { enum: ["positive", "negative", "neutral"] },
+    confidence: { type: "number" },
+    summary: { type: "string" },
+    detailed_context: { type: "string" },
+  },
+  required: ["rating", "sentiment", "confidence", "summary", "detailed_context"],
+  additionalProperties: false,
+} as const;
+
+interface SentimentResult {
+  rating: number | null;
+  sentiment: "positive" | "negative" | "neutral";
+  confidence: number;
+  summary: string;
+  detailed_context: string;
+}
+
+const SENTIMENT_SYSTEM_PROMPT = `Analyze the user's message for emotional sentiment toward the AI assistant.
+
+OUTPUT FORMAT (JSON only):
+{
+  "rating": <1-10 or null>,
+  "sentiment": "positive" | "negative" | "neutral",
+  "confidence": <0.0-1.0>,
+  "summary": "<brief explanation, 10 words max>",
+  "detailed_context": "<comprehensive analysis, 50-150 words>"
+}
+
+DETAILED_CONTEXT REQUIREMENTS:
+1. What the user was trying to accomplish
+2. What the AI did (or failed to do)
+3. Why the user reacted this way (root cause)
+4. What specific behavior triggered this reaction
+5. What the AI should do differently (negative) or what worked (positive)
+
+RATING SCALE:
+- 1-2: Strong frustration, anger, disappointment
+- 3-4: Mild frustration, dissatisfaction
+- 5: Neutral
+- 6-7: Satisfaction, approval
+- 8-9: Strong approval, impressed
+- 10: Extraordinary enthusiasm
+
+CRITICAL DISTINCTIONS:
+- Profanity can indicate EITHER frustration OR excitement — use context
+- Sarcasm: "Oh great, another error" = negative despite "great"
+- Short praise ("great job", "nice") = STRONG APPROVAL (8-9), not mild
+
+IMPLIED SENTIMENT (most feedback is implied, not explicit):
+
+Implied NEGATIVE (rate 2-4):
+- CORRECTIONS: "No, I meant..." / "That's not what I said" -> 3-4
+- REPEATED REQUESTS: Having to ask the same thing twice -> 2-3
+- BEHAVIORAL CORRECTIONS: "Don't do that" / "Stop doing X" -> 3
+- EXASPERATED QUESTIONS: "Why is this still broken?" -> 2-3
+- SHORT DISMISSALS: "whatever" / "fine" / "just do it" -> 3-4
+- POINTING OUT OMISSIONS: "What about X?" (obviously required) -> 4
+
+Implied POSITIVE (rate 6-8):
+- TRUST SIGNALS: "Alright, fix all of it" / "Go ahead" -> 7
+- BUILDING ON WORK: "Now also add..." / "Next, do..." -> 6-7
+- ENGAGED FOLLOW-UPS: "What about X?" (exploring, not correcting) -> 6
+- MOVING FORWARD: Accepting output and giving next task -> 6
+
+WHEN TO RETURN null FOR RATING:
+- Neutral technical questions ("Can you check the logs?")
+- Simple commands ("Do it", "Yes", "Continue")
+- No emotional indicators present`;
+
+const MIN_CONFIDENCE = 0.5;
+
+// ── Rating Handling ──
+
+function writeLearningMarkdown(
+  rating: number,
+  source: string,
+  context: string,
+  detailedContext: string,
+  responsePreview: string
+): void {
+  const category = categorizeLearning(context, detailedContext);
+  const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
+  const filename = `${fileTimestamp()}_${source}-rating-${rating}_${category}.md`;
+
+  const content = [
+    `# ${source === "explicit" ? "Low Rating" : "Implicit Low Rating"}: ${rating}/10`,
+    `**Title:** ${context.slice(0, 100) || "(low rating)"}`,
+    `**Date:** ${new Date().toISOString().slice(0, 10)}`,
+    `**Rating:** ${rating}/10`,
+    `**Source:** ${source}`,
+    `**Category:** ${category.toUpperCase()}`,
+    "",
+    "## Context",
+    context || "*(unavailable)*",
+    "",
+    ...(detailedContext ? ["## Analysis", detailedContext, ""] : []),
+    "## Last Response",
+    responsePreview || "*(unavailable)*",
+    "",
+  ].join("\n");
+
+  writeFileSync(resolve(dir, filename), content, "utf-8");
+}
+
+function handleRating(
+  rating: number,
+  context: string,
+  source: string,
+  detailedContext?: string,
+  sessionId?: string,
+  userMessage?: string
+): void {
+  const responsePreview = getLastResponse(sessionId).slice(0, 500);
+  emitRating(rating, context, source, responsePreview);
+
+  if (rating <= 3) {
+    // Deep failure — write pending file for Stop handler with full transcript
+    const userPreview = userMessage?.slice(0, 400);
+    writeFileSync(
+      resolve(paths.state(), "pending-failure.json"),
+      JSON.stringify(
+        {
+          rating,
+          context,
+          source,
+          detailedContext,
+          responsePreview,
+          userPreview,
+          ts: now(),
+        },
+        null,
+        2
+      ),
+      "utf-8"
+    );
+    // Also write learning markdown
+    writeLearningMarkdown(
+      rating,
+      source,
+      context,
+      detailedContext ?? "",
+      responsePreview
+    );
+  } else if (rating < 5) {
+    // Low but not critical — write learning markdown
+    writeLearningMarkdown(
+      rating,
+      source,
+      context,
+      detailedContext ?? "",
+      responsePreview
+    );
+  }
+}
+
+// ── Implicit Sentiment ──
+
+async function handleImplicitSentiment(
+  message: string,
+  sessionId?: string
+): Promise<void> {
+  const trimmed = message.trim();
+
+  // Fast-path: short praise -> rating 8
+  if (isPraise(trimmed)) {
+    handleRating(
+      8,
+      `Direct praise: "${trimmed}"`,
+      "implicit",
+      undefined,
+      sessionId,
+      trimmed
+    );
+    return;
+  }
+
+  // Skip system-injected text
+  if (isSystemText(trimmed)) return;
+
+  // Skip very short, very long, or code-like messages
+  if (trimmed.length < 5 || trimmed.length > 500) return;
+  if (/^[/$`{]/.test(trimmed) || trimmed.includes("\n\n")) return;
+
+  const lastResponse = getLastResponse(sessionId).slice(0, 300);
+  const contextBlock = lastResponse
+    ? `CONTEXT (last AI response excerpt):\n${lastResponse}\n\nCURRENT USER MESSAGE:\n${trimmed.slice(0, 300)}`
+    : trimmed.slice(0, 300);
+
+  const result = await inference({
+    system: SENTIMENT_SYSTEM_PROMPT,
+    user: contextBlock,
+    maxTokens: 500,
+    timeout: 8000,
+    jsonSchema: SENTIMENT_SCHEMA,
+  });
+
+  if (result.usage) logTokenUsage("rating", result.usage);
+
+  if (!result.success || !result.output) return;
+
+  try {
+    const parsed = JSON.parse(result.output) as SentimentResult;
+
+    // Skip if no sentiment detected or low confidence
+    if (parsed.rating === null) return;
+    if (parsed.confidence < MIN_CONFIDENCE) return;
+
+    const rating = parsed.rating;
+    if (typeof rating === "number" && rating >= 1 && rating <= 10 && rating !== 5) {
+      handleRating(
+        rating,
+        `${parsed.summary}: ${trimmed.slice(0, 150)}`,
+        "implicit",
+        parsed.detailed_context,
+        sessionId,
+        trimmed
+      );
+    }
+  } catch (err) {
+    const { logError } = await import("../lib/log");
+    logError("rating:implicit", err);
+  }
+}
+
+// ── Main Export ──
+
+export async function captureRating(message: string, sessionId?: string): Promise<void> {
+  // Strip IDE/system-injected tags to recover raw user text
+  const cleaned = stripInjectedTags(message);
+
+  // Path 1: Explicit rating
+  const explicit = parseExplicitRating(cleaned);
+  if (explicit) {
+    handleRating(
+      explicit.rating,
+      explicit.comment || cleaned.slice(0, 200),
+      "explicit",
+      undefined,
+      sessionId,
+      cleaned
+    );
+    return;
+  }
+
+  // Path 2: Implicit sentiment (requires ANTHROPIC_API_KEY — inference silently no-ops without it)
+  await handleImplicitSentiment(cleaned, sessionId);
+}

package/src/hooks/handlers/relationship.ts

@@ -0,0 +1,113 @@
+/**
+ * Stop handler: extracts relationship observations via Haiku inference.
+ * Only runs on substantial sessions (≥10 messages).
+ * Dedup: skips if this session already has notes in today's file.
+ */
+
+import { inference } from "../lib/inference";
+import { logDebug, logError } from "../lib/log";
+import { appendNotes, hasSessionNotes, type RelationshipNote } from "../lib/relationship";
+import { logTokenUsage } from "../lib/token-usage";
+import { extractContent, parseMessages } from "../lib/transcript";
+
+const OBSERVATION_SCHEMA = {
+  type: "object",
+  properties: {
+    observations: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["O", "W"],
+            description: "O=opinion/preference, W=factual observation",
+          },
+          text: { type: "string" },
+          confidence: { type: "number" },
+        },
+        required: ["type", "text", "confidence"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["observations"],
+  additionalProperties: false,
+} as const;
+
+export async function captureRelationship(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  if (sessionId && hasSessionNotes(sessionId)) {
+    logDebug("relationship", "Skipped: session already has notes");
+    return;
+  }
+
+  const messages = parseMessages(transcript);
+  logDebug("relationship", `Messages: ${messages.length}`);
+  if (messages.length < 10) {
+    logDebug("relationship", "Skipped: < 10 messages");
+    return;
+  }
+
+  if (!process.env.ANTHROPIC_API_KEY) {
+    logDebug("relationship", "Skipped: no ANTHROPIC_API_KEY");
+    return;
+  }
+
+  // Collect user messages for analysis
+  const userMessages = messages
+    .filter((m) => m.role === "user")
+    .map((m) => extractContent(m))
+    .filter((t) => t.length > 0)
+    .slice(-15)
+    .map((t) => t.slice(0, 200));
+
+  logDebug("relationship", `User messages: ${userMessages.length}`);
+  if (userMessages.length < 3) {
+    logDebug("relationship", "Skipped: < 3 user messages");
+    return;
+  }
+
+  logDebug("relationship", "Calling inference...");
+  const result = await inference({
+    system:
+      "You analyze user messages from an AI coding session to extract relationship observations. " +
+      "Focus on: preferences (how they like to work), corrections (what they pushed back on), " +
+      "frustrations, positive reactions, communication style patterns. " +
+      "Return 0-3 observations. If nothing notable, return empty observations array. Be concise.",
+    user: `User messages from this session:\n${userMessages.map((m, i) => `${i + 1}. ${m}`).join("\n")}`,
+    maxTokens: 300,
+    timeout: 8000,
+    jsonSchema: OBSERVATION_SCHEMA,
+  });
+
+  if (result.usage) logTokenUsage("relationship", result.usage);
+
+  logDebug("relationship", `Inference result: success=${result.success}`);
+  if (!result.success || !result.output) {
+    logDebug("relationship", "Skipped: inference failed or empty output");
+    return;
+  }
+
+  try {
+    const parsed = JSON.parse(result.output) as {
+      observations: Array<{ type: "O" | "W"; text: string; confidence: number }>;
+    };
+
+    logDebug("relationship", `Parsed ${parsed.observations?.length ?? 0} observations`);
+    if (!parsed.observations || parsed.observations.length === 0) return;
+
+    const notes: RelationshipNote[] = parsed.observations.map((o) => ({
+      type: o.type,
+      text: o.text,
+      confidence: o.confidence,
+    }));
+
+    appendNotes(notes, sessionId);
+    logDebug("relationship", `Captured ${notes.length} observations via inference`);
+  } catch (err) {
+    logError("relationship", err);
+  }
+}