portable-agent-layer 0.9.0 → 0.11.0

package/src/hooks/lib/learning-store.ts

@@ -13,6 +13,7 @@ import { parse } from "./frontmatter";
 
 export interface FailureEntry {
   slug: string;
+  path: string;
   rating: number;
   context: string;
   principle: string;
@@ -22,11 +23,13 @@ export interface FailureEntry {
 
 export interface LearningEntry {
   filename: string;
+  path: string;
   title: string;
   category: string;
   principle: string;
   date: string;
   insights: string;
+  cwd: string;
 }
 
 // ── Shared Directory Walker ──
@@ -79,6 +82,7 @@ export function readFailures(baseDir: string, limit?: number): FailureEntry[] {
 
           entries.push({
             slug: meta.slug || slug,
+            path: capturePath,
             rating: meta.rating ?? 0,
             context: meta.context,
             principle: meta.principle || "",
@@ -119,6 +123,7 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
             category?: string;
             principle?: string;
             date?: string;
+            cwd?: string;
           }>(content);
 
           if (!meta.title) continue;
@@ -127,11 +132,13 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
           entries.push({
             filename: file,
+            path: resolve(monthDir, file),
             title: meta.title,
             category: meta.category || "algorithm",
             principle: meta.principle || "",
             date: meta.date || "",
             insights: insightsMatch?.[1]?.trim() || "",
+            cwd: meta.cwd || "",
           });
 
           if (limit && entries.length >= limit) return entries;
@@ -146,120 +153,3 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
   return entries;
 }
-
-// ── Text Similarity (Jaccard on keywords) ──
-
-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))
-  );
-}
-
-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++;
-  }
-  const union = new Set([...ka, ...kb]).size;
-  return union > 0 ? intersection / union : 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/paths.ts

@@ -77,4 +77,6 @@ export const assets = {
   hooks: () => pkg("src", "hooks"),
   telosTemplates: () => pkg("assets", "templates", "telos"),
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
+  claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
+  palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

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 */
@@ -42,6 +43,7 @@ export const HOOK_MANAGED_DIRS = [
   "memory/learning/synthesis",
   "memory/relationship",
   "memory/wisdom/state",
+  ".agents/PAL",
 ];
 
 /** Escape a string for use in a RegExp */

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);
+}