portable-agent-layer 0.1.0

package/src/hooks/lib/relationship.ts

@@ -0,0 +1,135 @@
+/**
+ * Relationship Memory — daily interaction notes tracking preferences,
+ * frustrations, positive signals, and milestones.
+ *
+ * Notes live at memory/relationship/YYYY-MM/YYYY-MM-DD.md
+ * W = world (facts about user's situation)
+ * O = opinion (preference with confidence)
+ *
+ * Extraction is handled by the relationship handler via Haiku inference.
+ * This lib provides storage and reading utilities only.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+
+export type NoteType = "W" | "O";
+
+export interface RelationshipNote {
+  type: NoteType;
+  text: string;
+  confidence?: number;
+}
+
+function dailyFilePath(date: Date): string {
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  const monthDir = ensureDir(resolve(paths.relationship(), `${yyyy}-${mm}`));
+  return resolve(monthDir, `${yyyy}-${mm}-${dd}.md`);
+}
+
+/** Check if a session already has notes in today's file */
+export function hasSessionNotes(sessionId: string): boolean {
+  const filepath = dailyFilePath(new Date());
+  if (!existsSync(filepath)) return false;
+  try {
+    const content = readFileSync(filepath, "utf-8");
+    return content.includes(`<!-- session:${sessionId} -->`);
+  } catch {
+    return false;
+  }
+}
+
+/** Deduplicate notes against what's already in today's file */
+function dedup(notes: RelationshipNote[], filepath: string): RelationshipNote[] {
+  if (!existsSync(filepath)) return notes;
+  try {
+    const existing = readFileSync(filepath, "utf-8").toLowerCase();
+    return notes.filter((n) => {
+      // Check if a substantially similar line already exists
+      const key = n.text.slice(0, 80).toLowerCase();
+      return !existing.includes(key);
+    });
+  } catch {
+    return notes;
+  }
+}
+
+/** Append notes to today's relationship file */
+export function appendNotes(notes: RelationshipNote[], sessionId?: string): void {
+  if (notes.length === 0) return;
+
+  const filepath = dailyFilePath(new Date());
+  const today = new Date().toISOString().slice(0, 10);
+
+  // Deduplicate against existing content
+  const fresh = dedup(notes, filepath);
+  if (fresh.length === 0) return;
+
+  const lines: string[] = [];
+
+  if (!existsSync(filepath)) {
+    lines.push(`# Relationship Notes — ${today}`, "");
+  }
+
+  const timestamp = new Date().toTimeString().slice(0, 5);
+  lines.push(`## ${timestamp}`);
+  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}`);
+    } else {
+      lines.push(`- ${note.type}: ${note.text}`);
+    }
+  }
+
+  lines.push("");
+
+  const existing = existsSync(filepath) ? readFileSync(filepath, "utf-8") : "";
+  writeFileSync(filepath, existing + lines.join("\n"), "utf-8");
+}
+
+/** Load notes from the last N days as a single string */
+export function loadRecentNotes(days: number = 2): string {
+  const relDir = paths.relationship();
+  if (!existsSync(relDir)) return "";
+
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+
+  const sections: string[] = [];
+
+  for (const monthDir of readdirSync(relDir).sort().reverse()) {
+    const monthPath = resolve(relDir, monthDir);
+    if (!existsSync(monthPath)) continue;
+
+    let files: string[];
+    try {
+      files = readdirSync(monthPath)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .reverse();
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      const dateStr = file.replace(".md", "");
+      if (new Date(dateStr) < cutoff) continue;
+
+      try {
+        const content = readFileSync(resolve(monthPath, file), "utf-8").trim();
+        if (content) sections.push(content);
+      } catch {
+        // skip unreadable files
+      }
+    }
+
+    if (sections.length > 0) break; // only go back one month at most
+  }
+
+  return sections.join("\n\n---\n\n");
+}

package/src/hooks/lib/security.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared security definitions and validation logic.
+ * Used by SecurityValidator.ts (Claude Code) and the opencode plugin.
+ */
+
+/** Dangerous command patterns — always blocked */
+export const BLOCKED_COMMANDS: [RegExp, string][] = [
+  [/rm\s+-rf\s+[/~]/, "Recursive delete of root or home"],
+  [/mkfs\./, "Filesystem format"],
+  [/dd\s+if=.*of=\/dev\//, "Raw disk write"],
+  [/>\s*\/dev\/sd/, "Direct device write"],
+  [/chmod\s+-R\s+777\s+\//, "Recursive world-writable root"],
+  [/:\(\)\{\s*:\|:&\s*\};:/, "Fork bomb"],
+  [/curl.*\|\s*(?:ba)?sh/, "Pipe to shell"],
+  [/wget.*\|\s*(?:ba)?sh/, "Pipe to shell"],
+];
+
+/** Hook-managed files — single source of truth */
+export const HOOK_MANAGED_FILES = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  "ratings.jsonl",
+  "sessions.json",
+  "captured-learnings.json",
+  "counts.json",
+  "session-names.json",
+  "debug.log",
+  "last-responses.json",
+  "signal-cache.json",
+  "pending-failure.json",
+  "token-usage.jsonl",
+];
+
+/** Hook-managed directories — AI must not write to or delete from these */
+export const HOOK_MANAGED_DIRS = [
+  "memory/signals",
+  "memory/learning/failures",
+  "memory/learning/session",
+  "memory/learning/synthesis",
+  "memory/relationship",
+];
+
+/** Escape a string for use in a RegExp */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Paths that should never be written to */
+export const PROTECTED_PATHS: RegExp[] = [
+  /^\/etc\//,
+  /^\/boot\//,
+  /^\/System\//,
+  /\.ssh\/(?!config)/,
+  /\.gnupg\//,
+  // Derived from HOOK_MANAGED_FILES
+  ...HOOK_MANAGED_FILES.map((name) => new RegExp(`[/\\\\]${escapeRegExp(name)}$`)),
+];
+
+/** Patterns that warrant a warning (logged but not blocked) */
+export const WARN_COMMANDS: RegExp[] = [
+  /git\s+push\s+.*--force/,
+  /git\s+reset\s+--hard/,
+  /drop\s+(?:table|database)/i,
+  /truncate\s+table/i,
+];
+
+/** Read-only commands allowed to reference protected files */
+const READ_ONLY_COMMANDS =
+  /^\s*(?:cat|head|tail|less|more|grep|rg|wc|diff|stat|file|ls|dir|git\s+(?:log|diff|blame|show|status)|bat)\b/;
+
+/** Check a bash command against blocked patterns. Returns reason string or null. */
+export function checkBashCommand(cmd: string): string | null {
+  for (const [pattern, reason] of BLOCKED_COMMANDS) {
+    if (pattern.test(cmd)) return reason;
+  }
+  // If command mentions a protected file, block unless it's read-only
+  for (const name of HOOK_MANAGED_FILES) {
+    if (cmd.includes(name)) {
+      // Check each piped segment — if any segment is not read-only, block
+      const segments = cmd.split(/[|;&&]/).map((s) => s.trim());
+      const allReadOnly = segments
+        .filter((s) => s.includes(name))
+        .every((s) => READ_ONLY_COMMANDS.test(s));
+      if (!allReadOnly) {
+        return `${name} is managed automatically by hooks — do not edit directly`;
+      }
+    }
+  }
+  // If command mentions a hook-managed directory, block unless it's read-only
+  for (const dir of HOOK_MANAGED_DIRS) {
+    if (cmd.includes(dir)) {
+      const segments = cmd.split(/[|;&&]/).map((s) => s.trim());
+      const allReadOnly = segments
+        .filter((s) => s.includes(dir))
+        .every((s) => READ_ONLY_COMMANDS.test(s));
+      if (!allReadOnly) {
+        return `${dir} is managed automatically by hooks — do not edit directly`;
+      }
+    }
+  }
+  return null;
+}
+
+/** Check a file path against protected patterns. Returns a reason string or null. */
+export function checkFilePath(filePath: string): string | null {
+  const normalized = filePath.replace(/\\/g, "/");
+  // Check hook-managed files first (more specific message)
+  const matchedFile = HOOK_MANAGED_FILES.find((name) => normalized.endsWith(`/${name}`));
+  if (matchedFile) {
+    return `${matchedFile} is managed automatically by hooks — do not edit directly`;
+  }
+  // Check hook-managed directories
+  const matchedDir = HOOK_MANAGED_DIRS.find((dir) => normalized.includes(`/${dir}/`));
+  if (matchedDir) {
+    return `${matchedDir}/ is managed automatically by hooks — do not edit directly`;
+  }
+  // Check system-protected paths
+  if (PROTECTED_PATHS.some((pattern) => pattern.test(filePath))) {
+    return `Protected path: ${filePath}`;
+  }
+  return null;
+}

package/src/hooks/lib/session-names.ts

@@ -0,0 +1,247 @@
+/**
+ * Session naming utilities — 4-word headline per session, stored in session-names.json.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+export interface SessionNames {
+  [sessionId: string]: string;
+}
+
+// Noise words that produce garbage session names — extended from original PAI
+const NOISE_WORDS = new Set([
+  // Articles, pronouns, prepositions
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "from",
+  "by",
+  "as",
+  "is",
+  "it",
+  "its",
+  "this",
+  "that",
+  "i",
+  "you",
+  "we",
+  "my",
+  "me",
+  "your",
+  "our",
+  "they",
+  "them",
+  "those",
+  "these",
+  // Common verbs (too generic for names)
+  "can",
+  "do",
+  "not",
+  "be",
+  "are",
+  "was",
+  "were",
+  "just",
+  "so",
+  "if",
+  "how",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "have",
+  "has",
+  "had",
+  "will",
+  "would",
+  "could",
+  "should",
+  "been",
+  "being",
+  "having",
+  "getting",
+  "making",
+  // Filler words
+  "there",
+  "here",
+  "some",
+  "all",
+  "any",
+  "each",
+  "every",
+  "both",
+  "more",
+  "most",
+  "less",
+  "much",
+  "many",
+  "few",
+  "really",
+  "actually",
+  "basically",
+  "pretty",
+  "very",
+  "quite",
+  "super",
+  "totally",
+  "completely",
+  "okay",
+  "yeah",
+  "yes",
+  "sure",
+  "fine",
+  "good",
+  "bad",
+  "great",
+  "nice",
+  "hey",
+  "well",
+  "now",
+  "then",
+  "still",
+  "even",
+  "already",
+  "yet",
+  "ago",
+  // Generic task words (too vague)
+  "thing",
+  "things",
+  "something",
+  "nothing",
+  "anything",
+  "everything",
+  "stuff",
+  "way",
+  "kind",
+  "sort",
+  "type",
+  "part",
+  "whole",
+  "point",
+  // Common non-topic words
+  "need",
+  "want",
+  "please",
+  "help",
+  "work",
+  "working",
+  "doing",
+  "going",
+  "like",
+  "know",
+  "think",
+  "right",
+  "look",
+  "see",
+  "try",
+  "let",
+  "get",
+  "set",
+  "put",
+  "use",
+  "run",
+  "make",
+  "tell",
+  "show",
+  "give",
+  "keep",
+  "start",
+  "stop",
+  "move",
+  "turn",
+  "pull",
+  "push",
+  "open",
+  "close",
+  "guess",
+  "maybe",
+  "probably",
+  "mean",
+  "means",
+  "called",
+  "used",
+  "using",
+  // Tool/system artifacts
+  "output",
+  "file",
+  "result",
+  "tool",
+  "input",
+  "content",
+  "contents",
+  "invoke",
+]);
+
+/** Strip system-injected artifacts from prompt before naming */
+function sanitizePrompt(prompt: string): string {
+  return prompt
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, " ")
+    .replace(/<task-notification>[\s\S]*?<\/task-notification>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, " ")
+    .replace(/\b[0-9a-f]{7,}\b/gi, " ")
+    .replace(/(?:\/[\w.-]+){2,}/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Deterministic fallback: extract up to 4 meaningful keywords, Title Case */
+export function extractFallbackName(prompt: string): string {
+  const sanitized = sanitizePrompt(prompt);
+  const words = sanitized
+    .replace(/[^a-zA-Z\s]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length >= 3 && !NOISE_WORDS.has(w.toLowerCase()));
+
+  // Deduplicate while preserving order
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const w of words) {
+    const lower = w.toLowerCase();
+    if (!seen.has(lower)) {
+      seen.add(lower);
+      unique.push(w);
+    }
+    if (unique.length >= 4) break;
+  }
+
+  if (unique.length === 0) return "untitled session";
+
+  return unique
+    .slice(0, 4)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function namesFilePath(): string {
+  return resolve(paths.state(), "session-names.json");
+}
+
+export function readSessionNames(): SessionNames {
+  const filepath = namesFilePath();
+  if (!existsSync(filepath)) return {};
+  try {
+    return JSON.parse(readFileSync(filepath, "utf-8")) as SessionNames;
+  } catch {
+    return {};
+  }
+}
+
+export function writeSessionName(sessionId: string, name: string): void {
+  const names = readSessionNames();
+  names[sessionId] = name;
+  writeFileSync(namesFilePath(), JSON.stringify(names, null, 2), "utf-8");
+}

package/src/hooks/lib/setup.ts

@@ -0,0 +1,189 @@
+/**
+ * Setup state management for PAL first-run wizard.
+ *
+ * State lives in memory/state/setup.json. Each step maps to a TELOS file.
+ * The AI is instructed to mark steps done after writing each file.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, palHome, paths } from "./paths";
+
+export interface SetupStep {
+  done: boolean;
+  file: string;
+  question: string;
+  hint: string;
+}
+
+export interface SetupState {
+  version: number;
+  completed: boolean;
+  steps: Record<string, SetupStep>;
+}
+
+/** Ordered setup steps — defines the wizard flow */
+const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
+  mission: {
+    file: "telos/MISSION.md",
+    question: "What's your name and what do you do?",
+    hint: "Write their name, role, and core purpose to telos/MISSION.md",
+  },
+  ai_name: {
+    file: "telos/IDENTITY.md",
+    question:
+      "What would you like to call your AI? (Pick a name — this is how I'll identify myself.)",
+    hint: "Write the chosen AI name and identity to telos/IDENTITY.md with fields: name, fullName (name — Personal AI), displayName (UPPERCASED)",
+  },
+  catchphrase: {
+    file: "telos/IDENTITY.md",
+    question:
+      'What should your AI\'s startup catchphrase be? (e.g. "{name} here, ready to go" — {name} gets replaced with the AI name.)',
+    hint: "Append the catchphrase to telos/IDENTITY.md under a ## Catchphrase heading. Support {name} as a placeholder.",
+  },
+  goals: {
+    file: "telos/GOALS.md",
+    question: "What are your current goals? (short-term, medium-term, long-term)",
+    hint: "Write goals organized by timeframe to telos/GOALS.md",
+  },
+  projects: {
+    file: "telos/PROJECTS.md",
+    question: "What projects are you currently working on?",
+    hint: "Write to telos/PROJECTS.md using table format: | Project | Status | Priority | Notes |",
+  },
+  beliefs: {
+    file: "telos/BELIEFS.md",
+    question: "What principles or values guide your work?",
+    hint: "Write their values and principles to telos/BELIEFS.md",
+  },
+  challenges: {
+    file: "telos/CHALLENGES.md",
+    question: "What are your biggest current challenges?",
+    hint: "Write their challenges and obstacles to telos/CHALLENGES.md",
+  },
+};
+
+export const STEP_ORDER = Object.keys(SETUP_STEPS);
+
+function setupPath(): string {
+  return resolve(ensureDir(paths.state()), "setup.json");
+}
+
+/** Check if a TELOS file has real content (not just template scaffolding) */
+function hasRealContent(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const content = readFileSync(filePath, "utf-8").trim();
+    return content
+      .split("\n")
+      .some(
+        (l) =>
+          !l.startsWith("#") &&
+          !l.startsWith("<!--") &&
+          !l.startsWith("-->") &&
+          l.trim() &&
+          !/^\s*-\s*$/.test(l) &&
+          !/^\s*\|/.test(l)
+      );
+  } catch {
+    return false;
+  }
+}
+
+/** Create initial setup state, auto-detecting already-populated TELOS files */
+export function createInitialState(): SetupState {
+  const steps: Record<string, SetupStep> = {};
+  for (const [key, def] of Object.entries(SETUP_STEPS)) {
+    const populated = hasRealContent(resolve(palHome(), def.file));
+    steps[key] = { done: populated, ...def };
+  }
+  const allDone = Object.values(steps).every((s) => s.done);
+  return { version: 1, completed: allDone, steps };
+}
+
+/** Read setup state, or return null if no setup.json exists */
+export function readSetupState(): SetupState | null {
+  const p = setupPath();
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Write setup state to disk */
+export function writeSetupState(state: SetupState): void {
+  writeFileSync(setupPath(), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/** Seed setup.json if it doesn't exist yet. Returns the state. */
+export function ensureSetupState(): SetupState {
+  const existing = readSetupState();
+  if (existing) return existing;
+  const fresh = createInitialState();
+  writeSetupState(fresh);
+  return fresh;
+}
+
+/** Get the list of remaining (not done) step keys, in order */
+export function remainingSteps(state: SetupState): string[] {
+  return STEP_ORDER.filter((k) => !state.steps[k]?.done);
+}
+
+/** Check if setup is fully completed */
+export function isSetupComplete(state: SetupState): boolean {
+  return state.completed;
+}
+
+/**
+ * Build the system-prompt instructions for the current setup state.
+ * Returns null if setup is already complete.
+ */
+export function buildSetupPrompt(state: SetupState): string | null {
+  if (state.completed) return null;
+
+  const remaining = remainingSteps(state);
+  if (remaining.length === 0) return null;
+
+  const completedSteps = STEP_ORDER.filter((k) => state.steps[k]?.done);
+  const totalSteps = STEP_ORDER.length;
+
+  const lines: string[] = [
+    "## IMPORTANT: PAL First-Run Setup Required",
+    "",
+    "TELOS files are empty — this user has not been set up yet.",
+    "You MUST start the setup process immediately, regardless of what the user says.",
+    "Greet them, explain that PAL needs to learn about them to personalize future sessions,",
+    "and ask the first remaining question below. Do NOT wait for the user to ask about setup.",
+    "",
+  ];
+
+  if (completedSteps.length > 0) {
+    lines.push(
+      `Setup in progress — ${completedSteps.length}/${totalSteps} steps complete. Continue from the next remaining step.`,
+      ""
+    );
+  }
+
+  lines.push("### Steps to complete (ask one at a time):", "");
+
+  for (const key of remaining) {
+    const step = state.steps[key];
+    lines.push(`- **${key}** — Ask: "${step.question}" → ${step.hint}`);
+  }
+
+  lines.push(
+    "",
+    "### After each answer:",
+    "1. Write the user's answer to the corresponding TELOS file.",
+    `2. Read \`memory/state/setup.json\`, set \`steps.<key>.done = true\`, and write it back.`,
+    "3. Ask the next remaining question.",
+    "",
+    `When all steps are done (or the user wants to skip), set \`completed: true\` in setup.json.`,
+    "",
+    "Keep it conversational and natural. If the user wants to skip a step, mark it done and move on."
+  );
+
+  return lines.join("\n");
+}