portable-agent-layer 0.1.0

package/src/hooks/lib/entities.ts

@@ -0,0 +1,304 @@
+/**
+ * Entity Collision Detection — deduplicates people, companies, links,
+ * and sources across extracted content, assigning stable UUIDs and
+ * tracking occurrences to build a knowledge graph.
+ *
+ * Ported from ~/git/Personal_AI_Infrastructure/Packs/Utilities/src/Parser/Utils/collision-detection.ts
+ */
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+
+// --- Types ---
+
+export interface PersonEntity {
+  id: string;
+  name: string;
+  first_seen: string;
+  occurrences: number;
+  source_ids: string[];
+}
+
+export interface CompanyEntity {
+  id: string;
+  name: string;
+  domain: string | null;
+  first_seen: string;
+  occurrences: number;
+  source_ids: string[];
+}
+
+export interface LinkEntity {
+  id: string;
+  url: string;
+  first_seen: string;
+  occurrences: number;
+  source_ids: string[];
+}
+
+export interface SourceEntity {
+  id: string;
+  url: string | null;
+  author: string | null;
+  publication: string | null;
+  first_seen: string;
+  occurrences: number;
+  source_ids: string[];
+}
+
+export interface EntityIndex {
+  version: string;
+  last_updated: string;
+  people: Record<string, PersonEntity>;
+  companies: Record<string, CompanyEntity>;
+  links: Record<string, LinkEntity>;
+  sources: Record<string, SourceEntity>;
+}
+
+// --- Normalization ---
+
+export function normalizeName(name: string): string {
+  return name.toLowerCase().trim();
+}
+
+export function normalizeCompanyKey(name: string, domain: string | null): string {
+  return domain ? domain.toLowerCase().trim() : normalizeName(name);
+}
+
+export function normalizeUrl(url: string): string {
+  return url.toLowerCase().trim().replace(/\/$/, "");
+}
+
+export function normalizeSourceKey(
+  url: string | null,
+  author: string | null,
+  publication: string | null
+): string {
+  if (url) return normalizeUrl(url);
+  const a = author ? normalizeName(author) : "";
+  const p = publication ? normalizeName(publication) : "";
+  return `${a}|${p}`;
+}
+
+// --- Index I/O ---
+
+function defaultIndexPath(): string {
+  return resolve(ensureDir(paths.entities()), "entity-index.json");
+}
+
+function emptyIndex(): EntityIndex {
+  return {
+    version: "1.1.0",
+    last_updated: new Date().toISOString(),
+    people: {},
+    companies: {},
+    links: {},
+    sources: {},
+  };
+}
+
+/** Migrate older indexes that lack links/sources. */
+function ensureShape(index: EntityIndex): EntityIndex {
+  if (!index.links) index.links = {};
+  if (!index.sources) index.sources = {};
+  return index;
+}
+
+export function loadEntityIndex(filepath?: string): EntityIndex {
+  const p = filepath ?? defaultIndexPath();
+  if (!existsSync(p)) return emptyIndex();
+  try {
+    return ensureShape(JSON.parse(readFileSync(p, "utf-8")));
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function saveEntityIndex(index: EntityIndex, filepath?: string): void {
+  const p = filepath ?? defaultIndexPath();
+  const tempPath = `${p}.tmp`;
+  index.last_updated = new Date().toISOString();
+  writeFileSync(tempPath, JSON.stringify(index, null, 2), "utf-8");
+  renameSync(tempPath, p);
+}
+
+// --- Deduplication ---
+
+export function getOrCreatePerson(
+  person: { name: string },
+  index: EntityIndex,
+  sourceId: string
+): string {
+  const key = normalizeName(person.name);
+  const existing = index.people[key];
+
+  if (existing) {
+    if (!existing.source_ids.includes(sourceId)) {
+      existing.occurrences++;
+      existing.source_ids.push(sourceId);
+    }
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  index.people[key] = {
+    id,
+    name: person.name,
+    first_seen: new Date().toISOString(),
+    occurrences: 1,
+    source_ids: [sourceId],
+  };
+  return id;
+}
+
+export function getOrCreateCompany(
+  company: { name: string; domain: string | null },
+  index: EntityIndex,
+  sourceId: string
+): string {
+  const key = normalizeCompanyKey(company.name, company.domain);
+  const existing = index.companies[key];
+
+  if (existing) {
+    if (!existing.source_ids.includes(sourceId)) {
+      existing.occurrences++;
+      existing.source_ids.push(sourceId);
+    }
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  index.companies[key] = {
+    id,
+    name: company.name,
+    domain: company.domain,
+    first_seen: new Date().toISOString(),
+    occurrences: 1,
+    source_ids: [sourceId],
+  };
+  return id;
+}
+
+export function getOrCreateLink(
+  link: { url: string },
+  index: EntityIndex,
+  sourceId: string
+): string {
+  const key = normalizeUrl(link.url);
+  const existing = index.links[key];
+
+  if (existing) {
+    if (!existing.source_ids.includes(sourceId)) {
+      existing.occurrences++;
+      existing.source_ids.push(sourceId);
+    }
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  index.links[key] = {
+    id,
+    url: link.url,
+    first_seen: new Date().toISOString(),
+    occurrences: 1,
+    source_ids: [sourceId],
+  };
+  return id;
+}
+
+export function getOrCreateSource(
+  source: { url: string | null; author: string | null; publication: string | null },
+  index: EntityIndex,
+  sourceId: string
+): string {
+  const key = normalizeSourceKey(source.url, source.author, source.publication);
+  const existing = index.sources[key];
+
+  if (existing) {
+    if (!existing.source_ids.includes(sourceId)) {
+      existing.occurrences++;
+      existing.source_ids.push(sourceId);
+    }
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  index.sources[key] = {
+    id,
+    url: source.url,
+    author: source.author,
+    publication: source.publication,
+    first_seen: new Date().toISOString(),
+    occurrences: 1,
+    source_ids: [sourceId],
+  };
+  return id;
+}
+
+/** Check if a URL has already been parsed (exists in the links index). */
+export function isUrlAlreadyParsed(url: string, index: EntityIndex): boolean {
+  const key = normalizeUrl(url);
+  const link = index.links[key];
+  return !!link && link.source_ids.length > 0;
+}
+
+/** Get the first source_id that referenced this URL, or null. */
+export function getExistingContentId(url: string, index: EntityIndex): string | null {
+  const key = normalizeUrl(url);
+  const link = index.links[key];
+  return link?.source_ids[0] ?? null;
+}
+
+// --- Batch processing ---
+
+export function processEntities(
+  extractedData: {
+    people: Array<{ name: string; [key: string]: unknown }>;
+    companies: Array<{
+      name: string;
+      domain: string | null;
+      [key: string]: unknown;
+    }>;
+    links?: Array<{ url: string; [key: string]: unknown }>;
+    sources?: Array<{
+      url: string | null;
+      author: string | null;
+      publication: string | null;
+      [key: string]: unknown;
+    }>;
+  },
+  sourceId: string,
+  indexPath?: string
+): {
+  people: Array<{ id: string; [key: string]: unknown }>;
+  companies: Array<{ id: string; [key: string]: unknown }>;
+  links: Array<{ id: string; [key: string]: unknown }>;
+  sources: Array<{ id: string; [key: string]: unknown }>;
+} {
+  const index = loadEntityIndex(indexPath);
+
+  const people = extractedData.people.map((person) => ({
+    ...person,
+    id: getOrCreatePerson(person, index, sourceId),
+  }));
+
+  const companies = extractedData.companies.map((company) => ({
+    ...company,
+    id: getOrCreateCompany(company, index, sourceId),
+  }));
+
+  const links = (extractedData.links ?? []).map((link) => ({
+    ...link,
+    id: getOrCreateLink(link, index, sourceId),
+  }));
+
+  const sources = (extractedData.sources ?? []).map((source) => ({
+    ...source,
+    id: getOrCreateSource(source, index, sourceId),
+  }));
+
+  saveEntityIndex(index, indexPath);
+
+  return { people, companies, links, sources };
+}

package/src/hooks/lib/export.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared export logic — zips user state directories.
+ * Used by tools/export.ts (manual) and handlers/backup.ts (automatic).
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import AdmZip from "adm-zip";
+import { palHome } from "./paths";
+
+/** Directories within PAL_HOME that contain user state worth exporting. */
+const EXPORT_DIRS = ["telos", "memory"];
+
+/** Subdirectories/files to skip during export. */
+const SKIP_PATTERNS = ["memory/downloads"];
+
+function shouldSkip(relPath: string): boolean {
+  return SKIP_PATTERNS.some((p) => relPath.startsWith(p));
+}
+
+/** Recursively collect all files under a directory, returning paths relative to root. */
+function walkDir(dir: string, root: string): string[] {
+  const files: string[] = [];
+  if (!existsSync(dir)) return files;
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = resolve(dir, entry.name);
+    const relPath = relative(root, fullPath);
+
+    if (shouldSkip(relPath)) continue;
+
+    if (entry.isDirectory()) {
+      files.push(...walkDir(fullPath, root));
+    } else if (entry.isFile()) {
+      files.push(relPath);
+    }
+  }
+  return files;
+}
+
+/** Collect the list of user state files to export. */
+export function collectExportFiles(): string[] {
+  const root = palHome();
+  const files: string[] = [];
+
+  for (const dir of EXPORT_DIRS) {
+    files.push(...walkDir(resolve(root, dir), root));
+  }
+
+  return files;
+}
+
+/** Zip the given files and write to outputPath. Returns file count. */
+export function exportZip(outputPath: string): number {
+  const root = palHome();
+  const files = collectExportFiles();
+  if (files.length === 0) return 0;
+
+  const zip = new AdmZip();
+  for (const file of files) {
+    const fullPath = resolve(root, file);
+    const dir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "";
+    zip.addLocalFile(fullPath, dir);
+  }
+
+  zip.writeZip(outputPath);
+  return files.length;
+}
+
+/** Generate a timestamped filename prefix. */
+export function timestamp(): string {
+  return new Date()
+    .toISOString()
+    .replace(/[-:T.]/g, "")
+    .slice(0, 14);
+}

package/src/hooks/lib/inference.ts

@@ -0,0 +1,91 @@
+/**
+ * Lightweight Anthropic API wrapper used by session naming, failure capture, etc.
+ */
+
+import { HAIKU_MODEL } from "./models";
+
+export interface InferenceOptions {
+  system?: string;
+  user: string;
+  model?: string;
+  maxTokens?: number;
+  timeout?: number;
+  /** JSON schema for structured output — guarantees valid JSON matching the schema */
+  jsonSchema?: Record<string, unknown>;
+}
+
+export interface InferenceResult {
+  success: boolean;
+  output?: string;
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+export async function inference(opts: InferenceOptions): Promise<InferenceResult> {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return { success: false };
+
+  const {
+    system,
+    user,
+    model = HAIKU_MODEL,
+    maxTokens = 200,
+    timeout = 5000,
+    jsonSchema,
+  } = opts;
+
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+
+    const body: Record<string, unknown> = {
+      model,
+      max_tokens: maxTokens,
+      messages: [{ role: "user", content: user }],
+    };
+    if (system) body.system = system;
+    if (jsonSchema) {
+      body.output_config = {
+        format: { type: "json_schema", schema: jsonSchema },
+      };
+    }
+
+    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(body),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+
+    if (!response.ok) {
+      const { logError } = await import("./log");
+      const errBody = await response.text().catch(() => "");
+      logError("inference", `HTTP ${response.status}: ${errBody.slice(0, 200)}`);
+      return { success: false };
+    }
+
+    const data = (await response.json()) as Record<string, unknown>;
+    const rawUsage = data?.usage as
+      | { input_tokens?: number; output_tokens?: number }
+      | undefined;
+    const usage =
+      rawUsage?.input_tokens != null && rawUsage?.output_tokens != null
+        ? { inputTokens: rawUsage.input_tokens, outputTokens: rawUsage.output_tokens }
+        : undefined;
+
+    const content = data?.content as Array<{ text?: string }> | undefined;
+    const text = content?.[0]?.text?.trim();
+    if (!text) return { success: false, usage };
+
+    return { success: true, output: text, usage };
+  } catch (err) {
+    const { logError } = await import("./log");
+    logError("inference", err);
+    return { success: false };
+  }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Learning categorization: SYSTEM (tooling/infra) vs ALGORITHM (approach/design).
+ * Used by both learning.ts and work-learning.ts handlers.
+ */
+
+export type LearningCategory = "system" | "algorithm";
+
+const SYSTEM_KEYWORDS =
+  /\b(config|setting|install|deploy|build|lint|format|biome|typescript|tsc|hook|plugin|ci|cd|pipeline|docker|package|dependency|migration|schema|database|env|permission|security|git|commit|branch|merge)\b/i;
+
+/** Classify a learning based on title and summary content */
+export function categorizeLearning(...texts: string[]): LearningCategory {
+  return SYSTEM_KEYWORDS.test(texts.join(" ")) ? "system" : "algorithm";
+}

package/src/hooks/lib/log.ts

@@ -0,0 +1,53 @@
+/**
+ * Simple file-based debug logger for PAL hooks.
+ * Writes to memory/state/debug.log — rotated on each session start.
+ *
+ * Only writes when PAL_DEBUG=1 or when called via logError (always logged).
+ */
+
+import { appendFileSync, existsSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+const LOG_FILE = resolve(paths.state(), "debug.log");
+const MAX_LOG_SIZE = 50_000; // ~50KB, then rotate
+
+function timestamp(): string {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+function rotateIfNeeded(): void {
+  try {
+    if (existsSync(LOG_FILE) && statSync(LOG_FILE).size > MAX_LOG_SIZE) {
+      const prev = `${LOG_FILE}.prev`;
+      writeFileSync(prev, "");
+      // Swap: current → prev, start fresh
+      const { renameSync } = require("node:fs");
+      renameSync(LOG_FILE, prev);
+    }
+  } catch {
+    /* non-critical */
+  }
+}
+
+/** Log a debug message (only when PAL_DEBUG=1) */
+export function logDebug(source: string, message: string): void {
+  if (process.env.PAL_DEBUG !== "1") return;
+  rotateIfNeeded();
+  try {
+    appendFileSync(LOG_FILE, `[${timestamp()}] DEBUG ${source}: ${message}\n`);
+  } catch {
+    /* non-critical */
+  }
+}
+
+/** Log an error (always written, regardless of PAL_DEBUG) */
+export function logError(source: string, error: unknown): void {
+  rotateIfNeeded();
+  const msg = error instanceof Error ? `${error.message}\n${error.stack}` : String(error);
+  try {
+    appendFileSync(LOG_FILE, `[${timestamp()}] ERROR ${source}: ${msg}\n`);
+  } catch {
+    /* non-critical */
+  }
+}

package/src/hooks/lib/models.ts

@@ -0,0 +1,16 @@
+/**
+ * Single source of truth for model IDs and pricing.
+ */
+
+export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
+
+/** Pricing per million tokens (USD) — from https://platform.claude.com/docs/en/about-claude/pricing */
+export const MODEL_PRICING: Record<
+  string,
+  { input: number; output: number; cacheWrite: number; cacheRead: number }
+> = {
+  [HAIKU_MODEL]: { input: 1.0, output: 5.0, cacheWrite: 1.25, cacheRead: 0.1 },
+  "claude-opus-4-6": { input: 5.0, output: 25.0, cacheWrite: 6.25, cacheRead: 0.5 },
+  "claude-sonnet-4-6": { input: 3.0, output: 15.0, cacheWrite: 3.75, cacheRead: 0.3 },
+  "claude-sonnet-4-5": { input: 3.0, output: 15.0, cacheWrite: 3.75, cacheRead: 0.3 },
+};

package/src/hooks/lib/paths.ts

@@ -0,0 +1,80 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+/**
+ * Root of the PAL package (engine code + shipped assets).
+ * In repo mode: the repo root.
+ * In package mode: the global node_modules package directory.
+ */
+export function palPkg(): string {
+  return process.env.PAL_PKG || resolve(import.meta.dir, "..", "..", "..");
+}
+
+/**
+ * Root of the user's personal state (telos, memory, etc.).
+ * In repo mode: same as palPkg() (the repo root).
+ * In package mode: ~/.pal/ (or PAL_HOME override).
+ *
+ * Repo mode is detected by the presence of .palroot next to the package.
+ * This file is not included in the npm package, so it only exists in cloned repos.
+ */
+export function palHome(): string {
+  if (process.env.PAL_HOME) return process.env.PAL_HOME;
+
+  const pkgRoot = palPkg();
+  if (existsSync(resolve(pkgRoot, ".palroot"))) return pkgRoot;
+
+  return resolve(homedir(), ".pal");
+}
+
+/** Ensure a directory exists, creating it recursively if needed */
+export function ensureDir(path: string): string {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+  return path;
+}
+
+/** Resolve a path relative to the user's home */
+function home(...segments: string[]): string {
+  return resolve(palHome(), ...segments);
+}
+
+/** Resolve a path relative to the package root */
+function pkg(...segments: string[]): string {
+  return resolve(palPkg(), ...segments);
+}
+
+// User state paths (in PAL_HOME / repo root)
+export const paths = {
+  telos: () => home("telos"),
+  memory: () => home("memory"),
+  learning: () => ensureDir(home("memory", "learning")),
+  signals: () => ensureDir(home("memory", "signals")),
+  state: () => ensureDir(home("memory", "state")),
+  research: () => ensureDir(home("memory", "research")),
+  wisdom: () => ensureDir(home("memory", "wisdom", "frames")),
+  wisdomState: () => ensureDir(home("memory", "wisdom", "state")),
+  relationship: () => ensureDir(home("memory", "relationship")),
+  entities: () => ensureDir(home("memory", "entities")),
+  failures: () => ensureDir(home("memory", "learning", "failures")),
+  sessionLearning: () => ensureDir(home("memory", "learning", "session")),
+  synthesis: () => ensureDir(home("memory", "learning", "synthesis")),
+  backups: () => ensureDir(home("backups")),
+} as const;
+
+// Platform directories (env override or cross-platform defaults)
+const h = homedir();
+export const platform = {
+  claudeDir: () => process.env.PAL_CLAUDE_DIR || resolve(h, ".claude"),
+  opencodeDir: () => process.env.PAL_OPENCODE_DIR || resolve(h, ".config", "opencode"),
+  agentsDir: () => process.env.PAL_AGENTS_DIR || resolve(h, ".agents"),
+} as const;
+
+// Engine/asset paths (in PAL_PKG / repo root)
+export const assets = {
+  skills: () => pkg("assets", "skills"),
+  agents: () => pkg("assets", "agents"),
+  hooks: () => pkg("src", "hooks"),
+  telosTemplates: () => pkg("assets", "templates", "telos"),
+  agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
+} as const;