portable-agent-layer 0.1.0

package/src/tools/import.ts

@@ -0,0 +1,123 @@
+/**
+ * PAL Import — Extracts a PAL export archive into the repo,
+ * restoring personal files (memory, telos, state).
+ *
+ * Usage: bun run tool:import [path-to-zip] [--dry-run]
+ * If no path is given, finds the latest pal-export-*.zip and asks for confirmation.
+ * Then run: bun run install:all to re-create symlinks and hooks.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import AdmZip from "adm-zip";
+import { palHome } from "../hooks/lib/paths";
+
+const repoRoot = palHome();
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const pathArg = args.find((a) => a !== "--dry-run");
+
+async function confirm(message: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => {
+    rl.question(`${message} [y/N] `, (answer) => {
+      rl.close();
+      res(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+
+function findLatestExport(): string | null {
+  const files = readdirSync(repoRoot)
+    .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
+    .sort()
+    .reverse();
+
+  // Also check backups/
+  try {
+    const backupDir = resolve(repoRoot, "backups");
+    const backups = readdirSync(backupDir)
+      .filter(
+        (f) =>
+          (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
+          f.endsWith(".zip")
+      )
+      .map((f) => ({ name: f, path: resolve(backupDir, f) }))
+      .sort((a, b) => b.name.localeCompare(a.name));
+    if (backups.length > 0) files.push(backups[0].name);
+  } catch {
+    // No backups dir
+  }
+
+  if (files.length === 0) return null;
+
+  // Find the most recent by mtime across both locations
+  const candidates = [
+    ...readdirSync(repoRoot)
+      .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
+      .map((f) => resolve(repoRoot, f)),
+  ];
+  try {
+    const backupDir = resolve(repoRoot, "backups");
+    candidates.push(
+      ...readdirSync(backupDir)
+        .filter(
+          (f) =>
+            (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
+            f.endsWith(".zip")
+        )
+        .map((f) => resolve(backupDir, f))
+    );
+  } catch {
+    // No backups dir
+  }
+
+  if (candidates.length === 0) return null;
+  return candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+}
+
+// Resolve zip path
+let zipPath: string;
+
+if (pathArg) {
+  zipPath = resolve(pathArg);
+} else {
+  const latest = findLatestExport();
+  if (!latest) {
+    console.error(
+      "No export or backup files found. Provide a path: bun run tool:import <path-to-zip>"
+    );
+    process.exit(1);
+  }
+  console.log(`Found: ${latest}`);
+  const zip = new AdmZip(latest);
+  const entries = zip.getEntries();
+  console.log(
+    `Contains ${entries.length} files, created ${statSync(latest).mtime.toISOString().slice(0, 16).replace("T", " ")}`
+  );
+
+  if (!(await confirm("Import this file?"))) {
+    console.log("Cancelled.");
+    process.exit(0);
+  }
+  zipPath = latest;
+}
+
+// Import
+const zip = new AdmZip(zipPath);
+const entries = zip.getEntries();
+
+if (entries.length === 0) {
+  console.log("Archive is empty — nothing to import.");
+  process.exit(0);
+}
+
+if (dryRun) {
+  console.log(`Would import ${entries.length} files → ${repoRoot}\n`);
+  for (const e of entries) console.log(`  ${e.entryName}`);
+} else {
+  zip.extractAllTo(repoRoot, true);
+  console.log(`Imported ${entries.length} files → ${repoRoot}`);
+  console.log("\nRun 'bun run install:all' to re-create symlinks and hooks.");
+}

package/src/tools/pattern-synthesis.ts

@@ -0,0 +1,435 @@
+#!/usr/bin/env bun
+/**
+ * LearningPatternSynthesis — Aggregate ratings into actionable patterns.
+ *
+ * Analyzes memory/signals/ratings.jsonl to find recurring frustration/success
+ * patterns and generates synthesis reports.
+ *
+ * Usage:
+ *   bun run tool:patterns              # Analyze last 7 days (default)
+ *   bun run tool:patterns -- --month   # Analyze last 30 days
+ *   bun run tool:patterns -- --all     # Analyze all ratings
+ *   bun run tool:patterns -- --dry-run # Preview without writing
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { HAIKU_MODEL } from "../hooks/lib/models";
+import { palHome } from "../hooks/lib/paths";
+
+// ── Paths ──
+
+const RATINGS_FILE = resolve(palHome(), "memory", "signals", "ratings.jsonl");
+const SYNTHESIS_DIR = resolve(palHome(), "memory", "learning", "synthesis");
+
+// ── Types ──
+
+interface Rating {
+  ts: string;
+  rating: number;
+  context: string;
+  source: "explicit" | "implicit";
+  response_preview?: string;
+}
+
+interface PatternGroup {
+  pattern: string;
+  count: number;
+  avgRating: number;
+  examples: string[];
+}
+
+interface SynthesisResult {
+  period: string;
+  totalRatings: number;
+  avgRating: number;
+  frustrations: PatternGroup[];
+  successes: PatternGroup[];
+  topIssues: string[];
+  recommendations: string[];
+}
+
+// ── Pattern Detection ──
+
+const FRUSTRATION_PATTERNS: Record<string, RegExp> = {
+  "Time/Performance Issues": /time|slow|delay|hang|wait|long|minutes|hours/i,
+  "Incomplete Work": /incomplete|missing|partial|didn't finish|not done/i,
+  "Wrong Approach": /wrong|incorrect|not what|misunderstand|mistake/i,
+  "Over-engineering": /over-?engineer|too complex|unnecessary|bloat/i,
+  "Tool/System Failures": /fail|error|broken|crash|bug|issue/i,
+  "Communication Problems": /unclear|confus|didn't ask|should have asked/i,
+  "Repetitive Issues": /again|repeat|still|same problem/i,
+};
+
+const SUCCESS_PATTERNS: Record<string, RegExp> = {
+  "Quick Resolution": /quick|fast|efficient|smooth/i,
+  "Good Understanding": /understood|clear|exactly|perfect/i,
+  "Proactive Help": /proactive|anticipat|helpful|above and beyond/i,
+  "Clean Implementation": /clean|simple|elegant|well done/i,
+};
+
+function detectPatterns(
+  summaries: string[],
+  patterns: Record<string, RegExp>
+): Map<string, string[]> {
+  const results = new Map<string, string[]>();
+  for (const summary of summaries) {
+    for (const [name, pattern] of Object.entries(patterns)) {
+      if (pattern.test(summary)) {
+        const arr = results.get(name) ?? [];
+        arr.push(summary);
+        results.set(name, arr);
+      }
+    }
+  }
+  return results;
+}
+
+function toPatternGroups(
+  grouped: Map<string, string[]>,
+  ratings: Rating[]
+): PatternGroup[] {
+  const groups: PatternGroup[] = [];
+
+  for (const [pattern, examples] of grouped.entries()) {
+    const matching = ratings.filter((r) => examples.some((e) => e === r.context));
+    const avgRating =
+      matching.length > 0
+        ? matching.reduce((sum, r) => sum + r.rating, 0) / matching.length
+        : 5;
+
+    groups.push({
+      pattern,
+      count: examples.length,
+      avgRating,
+      examples: examples.slice(0, 3),
+    });
+  }
+
+  return groups.sort((a, b) => b.count - a.count);
+}
+
+// ── Analysis ──
+
+async function generateRecommendations(
+  frustrations: PatternGroup[],
+  successes: PatternGroup[],
+  avgRating: number
+): Promise<string[]> {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey || frustrations.length === 0) {
+    // Fallback: generic recommendations
+    if (frustrations.length === 0)
+      return ["Continue current patterns - no major issues detected"];
+    return frustrations
+      .slice(0, 3)
+      .map(
+        (f) =>
+          `Address "${f.pattern}" (${f.count} occurrences, avg ${f.avgRating.toFixed(1)}/10)`
+      );
+  }
+
+  try {
+    const context = [
+      `Average rating: ${avgRating.toFixed(1)}/10`,
+      "",
+      "Top frustration patterns:",
+      ...frustrations
+        .slice(0, 5)
+        .map(
+          (f) =>
+            `- ${f.pattern} (${f.count}x, avg ${f.avgRating.toFixed(1)}): ${f.examples.slice(0, 2).join("; ")}`
+        ),
+      "",
+      successes.length > 0 ? "Success patterns:" : "",
+      ...successes
+        .slice(0, 3)
+        .map((s) => `- ${s.pattern} (${s.count}x, avg ${s.avgRating.toFixed(1)})`),
+    ]
+      .filter(Boolean)
+      .join("\n");
+
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model: HAIKU_MODEL,
+        max_tokens: 300,
+        messages: [{ role: "user", content: context }],
+        system:
+          "You analyze AI assistant interaction patterns. Given frustration and success patterns from user ratings, generate 3-5 recommendations. Each MUST reference a specific example from the data — no generic advice like 'ask clarifying questions' or 'communicate better'. Every recommendation should name the concrete situation and the concrete fix. One sentence each. Return a JSON array of strings.",
+        output_config: {
+          format: {
+            type: "json_schema",
+            schema: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                recommendations: {
+                  type: "array",
+                  items: { type: "string" },
+                },
+              },
+              required: ["recommendations"],
+            },
+          },
+        },
+      }),
+      signal: AbortSignal.timeout(15000),
+    });
+
+    if (response.ok) {
+      const data = (await response.json()) as { content?: Array<{ text?: string }> };
+      const text = data?.content?.[0]?.text?.trim();
+      if (text) {
+        const parsed = JSON.parse(text) as { recommendations: string[] };
+        if (parsed.recommendations?.length > 0) return parsed.recommendations.slice(0, 5);
+      }
+    }
+  } catch {
+    // Fallback silently
+  }
+
+  return frustrations
+    .slice(0, 3)
+    .map((f) => `Address "${f.pattern}" (${f.count} occurrences)`);
+}
+
+async function analyzeRatings(
+  ratings: Rating[],
+  period: string
+): Promise<SynthesisResult> {
+  if (ratings.length === 0) {
+    return {
+      period,
+      totalRatings: 0,
+      avgRating: 0,
+      frustrations: [],
+      successes: [],
+      topIssues: [],
+      recommendations: [],
+    };
+  }
+
+  const avgRating = ratings.reduce((sum, r) => sum + r.rating, 0) / ratings.length;
+
+  const frustrationRatings = ratings.filter((r) => r.rating <= 4);
+  const successRatings = ratings.filter((r) => r.rating >= 7);
+
+  const frustrationGroups = detectPatterns(
+    frustrationRatings.map((r) => r.context),
+    FRUSTRATION_PATTERNS
+  );
+  const successGroups = detectPatterns(
+    successRatings.map((r) => r.context),
+    SUCCESS_PATTERNS
+  );
+
+  const frustrations = toPatternGroups(frustrationGroups, frustrationRatings);
+  const successes = toPatternGroups(successGroups, successRatings);
+
+  const topIssues = frustrations
+    .slice(0, 3)
+    .map(
+      (f) => `${f.pattern} (${f.count} occurrences, avg rating ${f.avgRating.toFixed(1)})`
+    );
+
+  const recommendations = await generateRecommendations(
+    frustrations,
+    successes,
+    avgRating
+  );
+
+  return {
+    period,
+    totalRatings: ratings.length,
+    avgRating,
+    frustrations,
+    successes,
+    topIssues,
+    recommendations,
+  };
+}
+
+// ── Report ──
+
+function formatReport(result: SynthesisResult): string {
+  const date = new Date().toISOString().slice(0, 10);
+  const lines: string[] = [
+    "# Learning Pattern Synthesis",
+    "",
+    `**Period:** ${result.period}`,
+    `**Generated:** ${date}`,
+    `**Total Ratings:** ${result.totalRatings}`,
+    `**Average Rating:** ${result.avgRating.toFixed(1)}/10`,
+    "",
+    "---",
+    "",
+    "## Top Issues",
+    "",
+  ];
+
+  if (result.topIssues.length > 0) {
+    for (let i = 0; i < result.topIssues.length; i++) {
+      lines.push(`${i + 1}. ${result.topIssues[i]}`);
+    }
+  } else {
+    lines.push("No significant issues detected");
+  }
+
+  lines.push("", "## Frustration Patterns", "");
+  if (result.frustrations.length === 0) {
+    lines.push("*No frustration patterns detected*");
+  } else {
+    for (const f of result.frustrations) {
+      lines.push(
+        `### ${f.pattern}`,
+        "",
+        `- **Occurrences:** ${f.count}`,
+        `- **Avg Rating:** ${f.avgRating.toFixed(1)}`,
+        `- **Examples:**`,
+        ...f.examples.map((e) => `  - "${e}"`),
+        ""
+      );
+    }
+  }
+
+  lines.push("", "## Success Patterns", "");
+  if (result.successes.length === 0) {
+    lines.push("*No success patterns detected*");
+  } else {
+    for (const s of result.successes) {
+      lines.push(
+        `### ${s.pattern}`,
+        "",
+        `- **Occurrences:** ${s.count}`,
+        `- **Avg Rating:** ${s.avgRating.toFixed(1)}`,
+        `- **Examples:**`,
+        ...s.examples.map((e) => `  - "${e}"`),
+        ""
+      );
+    }
+  }
+
+  lines.push(
+    "",
+    "## Recommendations",
+    "",
+    ...result.recommendations.map((r, i) => `${i + 1}. ${r}`),
+    ""
+  );
+
+  return lines.join("\n");
+}
+
+function writeReport(result: SynthesisResult, period: string): string {
+  const date = new Date().toISOString().slice(0, 10);
+  const monthDir = resolve(SYNTHESIS_DIR, date.slice(0, 7));
+  if (!existsSync(monthDir)) mkdirSync(monthDir, { recursive: true });
+
+  const slug = period.toLowerCase().replace(/\s+/g, "-");
+  const filename = `${date}_${slug}-patterns.md`;
+  const filepath = resolve(monthDir, filename);
+
+  writeFileSync(filepath, formatReport(result), "utf-8");
+  return filepath;
+}
+
+// ── CLI ──
+
+const { values } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    week: { type: "boolean" },
+    month: { type: "boolean" },
+    all: { type: "boolean" },
+    "dry-run": { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+
+if (values.help) {
+  console.log(`
+LearningPatternSynthesis — Aggregate ratings into actionable patterns
+
+Usage:
+  bun run tool:patterns              Analyze last 7 days (default)
+  bun run tool:patterns -- --month   Analyze last 30 days
+  bun run tool:patterns -- --all     Analyze all ratings
+  bun run tool:patterns -- --dry-run Preview without writing
+
+Output: Creates synthesis report in memory/learning/synthesis/YYYY-MM/
+`);
+  process.exit(0);
+}
+
+if (!existsSync(RATINGS_FILE)) {
+  console.log("No ratings file found at:", RATINGS_FILE);
+  process.exit(0);
+}
+
+// Read ratings
+const allRatings: Rating[] = readFileSync(RATINGS_FILE, "utf-8")
+  .split("\n")
+  .filter((l) => l.trim())
+  .map((l) => {
+    try {
+      return JSON.parse(l);
+    } catch {
+      return null;
+    }
+  })
+  .filter((r): r is Rating => r !== null);
+
+console.log(`Loaded ${allRatings.length} total ratings`);
+
+// Determine period
+let period = "Weekly";
+const cutoff = new Date();
+
+if (values.month) {
+  period = "Monthly";
+  cutoff.setDate(cutoff.getDate() - 30);
+} else if (values.all) {
+  period = "All Time";
+  cutoff.setTime(0);
+} else {
+  cutoff.setDate(cutoff.getDate() - 7);
+}
+
+const filtered = allRatings.filter((r) => new Date(r.ts).getTime() >= cutoff.getTime());
+console.log(`Analyzing ${filtered.length} ratings for ${period.toLowerCase()} period`);
+
+if (filtered.length === 0) {
+  console.log("No ratings in this period");
+  process.exit(0);
+}
+
+const result = await analyzeRatings(filtered, period);
+
+console.log(`\nAverage Rating: ${result.avgRating.toFixed(1)}/10`);
+console.log(`Frustration Patterns: ${result.frustrations.length}`);
+console.log(`Success Patterns: ${result.successes.length}`);
+
+if (result.topIssues.length > 0) {
+  console.log("\nTop Issues:");
+  for (const issue of result.topIssues) {
+    console.log(`  - ${issue}`);
+  }
+}
+
+if (values["dry-run"]) {
+  console.log("\n[DRY RUN] Would write synthesis report");
+  console.log("\nRecommendations:");
+  for (const rec of result.recommendations) {
+    console.log(`  - ${rec}`);
+  }
+} else {
+  const filepath = writeReport(result, period);
+  console.log(`\nCreated synthesis report: ${filepath}`);
+}

package/src/tools/pdf-download.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+
+/**
+ * PDF Download — Downloads a PDF from a URL and saves it to an organized local archive.
+ *
+ * Saves to: {PAL_ROOT}/memory/downloads/{YYYY}/{MM}/{DD}/{filename}.pdf
+ *
+ * Usage:
+ *   bun run ai:pdf-download -- <url> [--filename <name.pdf>]
+ *
+ * Returns JSON with the saved file path for downstream reading.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parseArgs } from "node:util";
+import { palHome } from "../hooks/lib/paths";
+
+const DOWNLOADS_DIR = join(palHome(), "memory", "downloads");
+
+function buildDatePath(): string {
+  const now = new Date();
+  const yyyy = now.getFullYear().toString();
+  const mm = (now.getMonth() + 1).toString().padStart(2, "0");
+  const dd = now.getDate().toString().padStart(2, "0");
+  return join(yyyy, mm, dd);
+}
+
+function extractFilename(url: string, override?: string): string {
+  if (override) {
+    return override.endsWith(".pdf") ? override : `${override}.pdf`;
+  }
+  const urlPath = new URL(url).pathname;
+  const name = basename(urlPath);
+  return name.endsWith(".pdf") ? name : `${name}.pdf`;
+}
+
+async function main() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      filename: { type: "string", short: "f" },
+    },
+  });
+
+  const url = positionals[0];
+  if (!url) {
+    console.error("Usage: bun run ai:pdf-download -- <url> [--filename <name.pdf>]");
+    process.exit(1);
+  }
+
+  // Validate URL
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    console.error(`Error: Invalid URL: ${url}`);
+    process.exit(1);
+  }
+
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    console.error(`Error: Only HTTP/HTTPS URLs are supported.`);
+    process.exit(1);
+  }
+
+  // Download
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.error(`Error: HTTP ${response.status} ${response.statusText}`);
+    process.exit(1);
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("pdf") && !url.endsWith(".pdf")) {
+    console.error(`Warning: Content-Type is "${contentType}", may not be a PDF.`);
+  }
+
+  const buffer = await response.arrayBuffer();
+
+  // Build destination path
+  const datePath = buildDatePath();
+  const dir = join(DOWNLOADS_DIR, datePath);
+  await mkdir(dir, { recursive: true });
+
+  const filename = extractFilename(url, values.filename);
+  const filePath = join(dir, filename);
+
+  // Write file
+  await Bun.write(filePath, buffer);
+
+  const result = {
+    path: filePath,
+    filename,
+    size: buffer.byteLength,
+    url,
+    downloadedAt: new Date().toISOString(),
+  };
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main();