portable-agent-layer 0.9.0 → 0.10.0

package/src/hooks/lib/opinions.ts

@@ -0,0 +1,191 @@
+/**
+ * Opinion store — persistent confidence-tracked opinions about the user.
+ *
+ * Opinions are promoted from recurring relationship notes (O/B types) by the
+ * reflect tool. Confidence evolves with evidence over time.
+ * High-confidence opinions (≥85%) are injected into every session context.
+ *
+ * Storage: memory/relationship/opinions.json
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+import { similarity } from "./text-similarity";
+
+// ── Types ──
+
+export type EvidenceType = "supporting" | "counter" | "confirmation" | "contradiction";
+export type OpinionCategory = "communication" | "technical" | "workflow" | "general";
+
+export interface Evidence {
+  date: string;
+  type: EvidenceType;
+  source: string;
+}
+
+export interface Opinion {
+  id: string;
+  statement: string;
+  confidence: number;
+  category: OpinionCategory;
+  evidence: Evidence[];
+  created: string;
+  updated: string;
+}
+
+// ── Confidence Deltas (matching original PAI) ──
+
+const CONFIDENCE_DELTAS: Record<EvidenceType, number> = {
+  supporting: 0.02,
+  counter: -0.05,
+  confirmation: 0.1,
+  contradiction: -0.2,
+};
+
+const MIN_CONFIDENCE = 0.01;
+const MAX_CONFIDENCE = 0.99;
+const HIGH_CONFIDENCE_THRESHOLD = 0.85;
+
+// ── Category Classification ──
+
+const CATEGORY_MAP: [RegExp, OpinionCategory][] = [
+  [/tone|format|response|verbose|brief|concise|explain|direct|style/i, "communication"],
+  [/code|test|build|deploy|function|type|lint|debug|refactor/i, "technical"],
+  [/commit|git|release|workflow|process|approach|iterative|step/i, "workflow"],
+];
+
+function classifyCategory(text: string): OpinionCategory {
+  for (const [pattern, category] of CATEGORY_MAP) {
+    if (pattern.test(text)) return category;
+  }
+  return "general";
+}
+
+// ── File Path ──
+
+function opinionsPath(): string {
+  return resolve(paths.relationship(), "opinions.json");
+}
+
+// ── Store Format ──
+
+interface OpinionStore {
+  lastReflect: string;
+  opinions: Opinion[];
+}
+
+// ── CRUD ──
+
+function readStore(): OpinionStore {
+  const fp = opinionsPath();
+  if (!existsSync(fp)) return { lastReflect: "", opinions: [] };
+  try {
+    const raw = JSON.parse(readFileSync(fp, "utf-8"));
+    // Migrate from plain array format
+    if (Array.isArray(raw)) return { lastReflect: "", opinions: raw };
+    return raw as OpinionStore;
+  } catch {
+    return { lastReflect: "", opinions: [] };
+  }
+}
+
+function writeStore(store: OpinionStore): void {
+  writeFileSync(opinionsPath(), JSON.stringify(store, null, 2), "utf-8");
+}
+
+export function readOpinions(): Opinion[] {
+  return readStore().opinions;
+}
+
+export function getLastReflectDate(): string {
+  return readStore().lastReflect;
+}
+
+export function setLastReflectDate(date: string): void {
+  const store = readStore();
+  store.lastReflect = date;
+  writeStore(store);
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 6)
+    .join("-");
+}
+
+/** Find an existing opinion similar to the given text. Returns the opinion or null. */
+export function findSimilarOpinion(
+  text: string,
+  opinions: Opinion[],
+  threshold = 0.3
+): Opinion | null {
+  for (const op of opinions) {
+    if (similarity(text, op.statement) >= threshold) return op;
+  }
+  return null;
+}
+
+/** Create a new opinion from a recurring note. Starts at confidence 0.50. */
+export function createOpinion(statement: string, source: string): Opinion {
+  const now = new Date().toISOString().slice(0, 10);
+  return {
+    id: slugify(statement),
+    statement,
+    confidence: 0.5,
+    category: classifyCategory(statement),
+    evidence: [{ date: now, type: "supporting", source }],
+    created: now,
+    updated: now,
+  };
+}
+
+/** Add evidence to an opinion and adjust its confidence. */
+export function addEvidence(
+  opinion: Opinion,
+  type: EvidenceType,
+  source: string
+): Opinion {
+  const now = new Date().toISOString().slice(0, 10);
+  const delta = CONFIDENCE_DELTAS[type];
+  const newConfidence = Math.min(
+    MAX_CONFIDENCE,
+    Math.max(MIN_CONFIDENCE, opinion.confidence + delta)
+  );
+
+  return {
+    ...opinion,
+    confidence: Math.round(newConfidence * 100) / 100,
+    evidence: [...opinion.evidence, { date: now, type, source }],
+    updated: now,
+  };
+}
+
+/** Upsert an opinion into the store. */
+export function saveOpinion(opinion: Opinion): void {
+  const store = readStore();
+  const idx = store.opinions.findIndex((o) => o.id === opinion.id);
+  if (idx >= 0) {
+    store.opinions[idx] = opinion;
+  } else {
+    store.opinions.push(opinion);
+  }
+  writeStore(store);
+}
+
+// ── Context Loading ──
+
+/** Load high-confidence opinions formatted for system-reminder injection. */
+export function loadOpinionContext(threshold = HIGH_CONFIDENCE_THRESHOLD): string {
+  const opinions = readOpinions().filter((o) => o.confidence >= threshold);
+  if (opinions.length === 0) return "";
+
+  const lines = opinions.map(
+    (o) => `- [${o.category}] ${o.statement} (${Math.round(o.confidence * 100)}%)`
+  );
+  return ["## Tracked Opinions", ...lines].join("\n");
+}

package/src/hooks/lib/relationship.ts

@@ -5,6 +5,7 @@
  * Notes live at memory/relationship/YYYY-MM/YYYY-MM-DD.md
  * W = world (facts about user's situation)
  * O = opinion (preference with confidence)
+ * B = belief (behavioral pattern with confidence)
  *
  * Extraction is handled by the relationship handler via Haiku inference.
  * This lib provides storage and reading utilities only.
@@ -14,7 +15,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
 
-export type NoteType = "W" | "O";
+export type NoteType = "W" | "O" | "B";
 
 export interface RelationshipNote {
   type: NoteType;
@@ -79,8 +80,8 @@ export function appendNotes(notes: RelationshipNote[], sessionId?: string): void
   if (sessionId) lines.push(`<!-- session:${sessionId} -->`);
 
   for (const note of fresh) {
-    if (note.type === "O" && note.confidence !== undefined) {
-      lines.push(`- O(c=${note.confidence}): ${note.text}`);
+    if ((note.type === "O" || note.type === "B") && note.confidence !== undefined) {
+      lines.push(`- ${note.type}(c=${note.confidence}): ${note.text}`);
     } else {
       lines.push(`- ${note.type}: ${note.text}`);
     }
@@ -103,8 +104,8 @@ export function loadRecentNotes(days: number = 2): string {
   const sections: string[] = [];
 
   for (const monthDir of readdirSync(relDir).sort().reverse()) {
+    if (!/^\d{4}-\d{2}$/.test(monthDir)) continue;
     const monthPath = resolve(relDir, monthDir);
-    if (!existsSync(monthPath)) continue;
 
     let files: string[];
     try {

package/src/hooks/lib/security.ts

@@ -32,6 +32,7 @@ export const HOOK_MANAGED_FILES = [
   "graduated.json",
   "update-available.json",
   "debug.log.prev",
+  "opinions.json",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */

package/src/hooks/lib/stop.ts

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { autoBackup } from "../handlers/backup";
 import { captureFailure } from "../handlers/failure";
+import { checkReflectTrigger } from "../handlers/reflect-trigger";
 import { captureRelationship } from "../handlers/relationship";
 import { resetTab } from "../handlers/tab";
 import { updateCounts } from "../handlers/update-counts";
@@ -43,6 +44,7 @@ export async function runStopHandlers(
     checkPendingFailure(transcript),
     updateCounts(),
     autoBackup(),
+    checkReflectTrigger(),
   ]);
 
   const handlerNames = [
@@ -53,6 +55,7 @@ export async function runStopHandlers(
     "pending-failure",
     "update-counts",
     "backup",
+    "reflect-trigger",
   ];
   for (let i = 0; i < results.length; i++) {
     const r = results[i];

package/src/hooks/lib/text-similarity.ts

@@ -0,0 +1,125 @@
+/**
+ * Text similarity using Dice coefficient on keyword sets.
+ *
+ * Dice is more generous than Jaccard for short, variable-length texts
+ * (like chatbot messages and failure contexts) because it divides by
+ * average set size instead of union:
+ *
+ *   Dice = 2 * |intersection| / (|A| + |B|)
+ */
+
+const STOP_WORDS = new Set([
+  "the",
+  "a",
+  "an",
+  "is",
+  "was",
+  "are",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "shall",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "and",
+  "but",
+  "or",
+  "nor",
+  "not",
+  "no",
+  "so",
+  "if",
+  "then",
+  "than",
+  "that",
+  "this",
+  "it",
+  "its",
+  "i",
+  "you",
+  "he",
+  "she",
+  "we",
+  "they",
+  "my",
+  "your",
+  "his",
+  "her",
+  "our",
+  "their",
+  "what",
+  "which",
+  "who",
+  "when",
+  "where",
+  "how",
+  "all",
+  "each",
+  "both",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "up",
+  "out",
+  "about",
+  "just",
+  "also",
+  "very",
+  "too",
+  "only",
+  "own",
+]);
+
+export function extractKeywords(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 2 && !STOP_WORDS.has(w))
+  );
+}
+
+/** Dice coefficient on keyword sets. Returns 0-1. */
+export function similarity(a: string, b: string): number {
+  const ka = extractKeywords(a);
+  const kb = extractKeywords(b);
+  if (ka.size === 0 || kb.size === 0) return 0;
+
+  let intersection = 0;
+  for (const w of ka) {
+    if (kb.has(w)) intersection++;
+  }
+
+  return (2 * intersection) / (ka.size + kb.size);
+}

package/src/tools/analyze.ts

@@ -11,6 +11,18 @@
 import { parseArgs } from "node:util";
 import { analyze } from "../hooks/lib/graduation";
 
+// ── ANSI Colors ──
+
+const c = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+};
+
 const { values } = parseArgs({
   args: Bun.argv.slice(2),
   options: {
@@ -24,7 +36,7 @@ if (values.help) {
   PAL Learning Analysis — unified graduation + ratings report
 
   Reads all captured failures (rating ≤3) and session learnings,
-  groups recurring patterns via Jaccard similarity on context text,
+  groups recurring patterns via Dice similarity on context text,
   and summarizes rating trends.
 
   Sections:
@@ -57,47 +69,69 @@ if (!hasPatterns && !hasRatings) {
 
 if (result.ratings) {
   const r = result.ratings;
-  console.log(`\n  Ratings: ${r.average.toFixed(1)}/10 avg (${r.total} total)`);
-  console.log(`  Low (≤4): ${r.low.count} | High (≥7): ${r.high.count}`);
+  const avgColor = r.average >= 7 ? c.green : r.average <= 4 ? c.red : c.yellow;
+  console.log(
+    `\n  ${c.bold("Ratings:")} ${avgColor(`${r.average.toFixed(1)}/10`)} avg (${r.total} total)`
+  );
+  console.log(
+    `  ${c.red(`Low (≤4): ${r.low.count}`)} | ${c.green(`High (≥7): ${r.high.count}`)}`
+  );
 }
 
 // ── Graduation Candidates ──
 
 if (result.candidates.length > 0) {
   console.log(
-    `\n  Graduation Report — ${result.candidates.length} pattern(s) detected\n`
+    `\n  ${c.bold(c.green(`Graduation Report — ${result.candidates.length} pattern(s) detected`))}\n`
   );
-  console.log("  ─────────────────────────────────────────────────\n");
+  console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
 
   for (const candidate of result.candidates) {
-    console.log(`  [${candidate.domain}] ${candidate.entries.length}x occurrences`);
+    console.log(
+      `  ${c.cyan(`[${candidate.domain}]`)} ${c.bold(`${candidate.entries.length}x`)} occurrences`
+    );
     console.log("");
 
     for (const entry of candidate.entries) {
       const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+      const tag =
+        sourceType === "failure" ? c.red(`[${sourceType}]`) : c.yellow(`[${sourceType}]`);
       console.log(
-        `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 100)}`
+        `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 100)}`
       );
     }
 
+    console.log(`\n  ${c.dim("Files:")}`);
+    for (const entry of candidate.entries) {
+      console.log(`    ${c.dim(entry.path)}`);
+    }
+
     console.log("");
-    console.log("  Target frame:", `memory/wisdom/frames/${candidate.domain}.md`);
-    console.log("  ─────────────────────────────────────────────────\n");
+    console.log(
+      `  Target frame: ${c.magenta(`memory/wisdom/frames/${candidate.domain}.md`)}`
+    );
+    console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
   }
 }
 
 // ── Emerging Patterns ──
 
 if (result.emerging.length > 0) {
-  console.log(`  Emerging (2x — one more to graduate)\n`);
+  console.log(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
   for (const group of result.emerging) {
-    console.log(`  [${group.domain}] ${group.entries.length}x`);
+    console.log(`  ${c.cyan(`[${group.domain}]`)} ${c.bold(`${group.entries.length}x`)}`);
     for (const entry of group.entries) {
       const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+      const tag =
+        sourceType === "failure" ? c.red(`[${sourceType}]`) : c.yellow(`[${sourceType}]`);
       console.log(
-        `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 80)}`
+        `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 80)}`
       );
     }
+    console.log("  Files:");
+    for (const entry of group.entries) {
+      console.log(`    ${c.dim(entry.path)}`);
+    }
     console.log("");
   }
 }
@@ -105,7 +139,7 @@ if (result.emerging.length > 0) {
 // ── Recommendations ──
 
 if (result.recommendations.length > 0) {
-  console.log("  Recommendations:\n");
+  console.log(`  ${c.bold("Recommendations:")}\n`);
   for (const rec of result.recommendations) {
     console.log(`    ${rec}`);
   }
@@ -113,6 +147,6 @@ if (result.recommendations.length > 0) {
 }
 
 if (result.candidates.length > 0) {
-  console.log("  To crystallize: add a line to the wisdom frame file.");
-  console.log("  Format: - Your principle here [CRYSTAL: 85%]\n");
+  console.log(`  To crystallize: add a line to the wisdom frame file.`);
+  console.log(`  Format: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`);
 }