portable-agent-layer 0.1.0

package/src/hooks/lib/signal-trends.ts

@@ -0,0 +1,117 @@
+/**
+ * Compute rating averages from ratings.jsonl, cache in signal-cache.json.
+ * Returns today / this-week / this-month averages + trend direction.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+interface RatingSignal {
+  ts: string;
+  rating: number;
+}
+
+interface SignalCache {
+  computed_at: string;
+  today: number | null;
+  week: number | null;
+  month: number | null;
+  trend: "up" | "down" | "stable" | null;
+}
+
+function cacheFilePath(): string {
+  return resolve(paths.state(), "signal-cache.json");
+}
+
+function avg(nums: number[]): number | null {
+  if (nums.length === 0) return null;
+  return Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 10) / 10;
+}
+
+function trendDirection(
+  week: number | null,
+  month: number | null
+): "up" | "down" | "stable" | null {
+  if (week === null || month === null) return null;
+  if (week > month + 0.5) return "up";
+  if (week < month - 0.5) return "down";
+  return "stable";
+}
+
+/** Read ratings.jsonl and compute trend stats, with 10-minute cache. */
+export function computeSignalTrends(): SignalCache {
+  const cachePath = cacheFilePath();
+
+  // Return cached value if fresh (< 10 minutes old)
+  if (existsSync(cachePath)) {
+    try {
+      const cache = JSON.parse(readFileSync(cachePath, "utf-8")) as SignalCache;
+      const age = Date.now() - new Date(cache.computed_at).getTime();
+      if (age < 10 * 60 * 1000) return cache;
+    } catch {
+      // Recompute
+    }
+  }
+
+  const ratingsPath = resolve(paths.signals(), "ratings.jsonl");
+  if (!existsSync(ratingsPath)) {
+    const empty: SignalCache = {
+      computed_at: new Date().toISOString(),
+      today: null,
+      week: null,
+      month: null,
+      trend: null,
+    };
+    writeFileSync(cachePath, JSON.stringify(empty, null, 2), "utf-8");
+    return empty;
+  }
+
+  const now = new Date();
+  const todayStart = new Date(now.toISOString().slice(0, 10)).getTime();
+  const weekAgo = now.getTime() - 7 * 24 * 60 * 60 * 1000;
+  const monthAgo = now.getTime() - 30 * 24 * 60 * 60 * 1000;
+
+  const todayRatings: number[] = [];
+  const weekRatings: number[] = [];
+  const monthRatings: number[] = [];
+
+  for (const line of readFileSync(ratingsPath, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const signal = JSON.parse(line) as RatingSignal;
+      if (typeof signal.rating !== "number") continue;
+      const ts = new Date(signal.ts).getTime();
+      if (ts >= monthAgo) monthRatings.push(signal.rating);
+      if (ts >= weekAgo) weekRatings.push(signal.rating);
+      if (ts >= todayStart) todayRatings.push(signal.rating);
+    } catch {
+      // Skip malformed lines
+    }
+  }
+
+  const week = avg(weekRatings);
+  const month = avg(monthRatings);
+  const result: SignalCache = {
+    computed_at: new Date().toISOString(),
+    today: avg(todayRatings),
+    week,
+    month,
+    trend: trendDirection(week, month),
+  };
+
+  writeFileSync(cachePath, JSON.stringify(result, null, 2), "utf-8");
+  return result;
+}
+
+/** Format signal trends as a short markdown string for system-reminder injection */
+export function formatTrends(cache: SignalCache): string {
+  if (cache.today === null && cache.week === null) return "";
+
+  const parts: string[] = [];
+  if (cache.today !== null) parts.push(`today: ${cache.today}/10`);
+  if (cache.week !== null) parts.push(`7d avg: ${cache.week}/10`);
+  if (cache.trend) parts.push(`trend: ${cache.trend}`);
+
+  return `**Signal trends** — ${parts.join(" | ")}`;
+}

package/src/hooks/lib/signals.ts

@@ -0,0 +1,37 @@
+import { appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+import { now } from "./time";
+
+export interface Signal {
+  ts: string;
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Append a signal to a JSONL file in the signals directory */
+export function emitSignal(
+  filename: string,
+  data: { type: string; [key: string]: unknown }
+): void {
+  const signal: Signal = { ts: now(), ...data };
+  const filepath = resolve(paths.signals(), filename);
+  appendFileSync(filepath, `${JSON.stringify(signal)}\n`);
+}
+
+/** Append a rating signal */
+export function emitRating(
+  rating: number,
+  context: string,
+  source: string = "explicit",
+  responsePreview?: string
+): void {
+  const data = {
+    type: "rating",
+    rating,
+    context,
+    source,
+    ...(responsePreview ? { response_preview: responsePreview } : {}),
+  };
+  emitSignal("ratings.jsonl", data);
+}

package/src/hooks/lib/stdin.ts

@@ -0,0 +1,18 @@
+/** Read all of stdin as a string */
+export async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/** Read stdin and parse as JSON, returning null on failure */
+export async function readStdinJSON<T = unknown>(): Promise<T | null> {
+  try {
+    const raw = await readStdin();
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}

package/src/hooks/lib/stop.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared stop handlers - runs all stop event logic.
+ * Used by StopOrchestrator.ts (Claude Code) and opencode plugin.
+ */
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { autoBackup } from "../handlers/backup";
+import { captureFailure } from "../handlers/failure";
+import { captureRelationship } from "../handlers/relationship";
+import { checkSynthesisTrigger } from "../handlers/synthesis";
+import { resetTab } from "../handlers/tab";
+import { updateCounts } from "../handlers/update-counts";
+import { captureWorkLearning } from "../handlers/work-learning";
+import { captureWorkSession } from "../handlers/work-session";
+import { logDebug, logError } from "./log";
+import { ensureDir, paths } from "./paths";
+import { extractContent, extractLastAssistant, parseMessages } from "./transcript";
+
+export interface RunStopHandlersOptions {
+  lastAssistantMessage?: string;
+  sessionId?: string;
+}
+
+/** Run all stop handlers with a transcript string */
+export async function runStopHandlers(
+  transcript: string,
+  options: RunStopHandlersOptions = {}
+): Promise<void> {
+  const messages = parseMessages(transcript);
+  if (messages.length < 2) return;
+
+  logDebug("runStopHandlers", `Running handlers (${messages.length} messages)`);
+
+  // Cache last assistant response (session-scoped)
+  cacheLastResponse(messages, options.lastAssistantMessage, options.sessionId);
+
+  // Run all handlers concurrently (manual wisdom extraction only - no automatic extraction)
+  const results = await Promise.allSettled([
+    captureWorkSession(transcript, options.sessionId),
+    resetTab(),
+    captureRelationship(transcript, options.sessionId),
+    captureWorkLearning(transcript, options.sessionId),
+    checkPendingFailure(transcript),
+    updateCounts(),
+    autoBackup(),
+    checkSynthesisTrigger(),
+  ]);
+
+  const handlerNames = [
+    "work-session",
+    "tab",
+    "relationship",
+    "work-learning",
+    "pending-failure",
+    "update-counts",
+    "backup",
+    "synthesis",
+  ];
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    if (r.status === "rejected") {
+      logError(`runStopHandlers:${handlerNames[i]}`, r.reason);
+    }
+  }
+}
+
+/**
+ * Cache the last assistant response per session for RatingCapture.
+ * Stores a map of session_id → { response, ts } in last-responses.json.
+ * Keeps at most MAX_CACHED_SESSIONS entries (evicts oldest by ts).
+ */
+const MAX_CACHED_SESSIONS = 20;
+
+interface CachedResponse {
+  response: string;
+  ts: string;
+}
+
+function cacheLastResponse(
+  msgs: ReturnType<typeof parseMessages>,
+  lastAssistantMessage?: string,
+  sessionId?: string
+): void {
+  if (!sessionId) return; // Can't cache without a session key
+
+  try {
+    let lastResponse = lastAssistantMessage;
+    if (!lastResponse) {
+      const lastAssistant = extractLastAssistant(msgs);
+      lastResponse = extractContent(lastAssistant);
+    }
+    if (!lastResponse) return;
+
+    const cachePath = resolve(ensureDir(paths.state()), "last-responses.json");
+
+    // Read existing cache
+    let cache: Record<string, CachedResponse> = {};
+    if (existsSync(cachePath)) {
+      try {
+        cache = JSON.parse(readFileSync(cachePath, "utf-8"));
+      } catch {
+        cache = {};
+      }
+    }
+
+    // Upsert this session
+    cache[sessionId] = {
+      response: lastResponse.slice(0, 2000),
+      ts: new Date().toISOString(),
+    };
+
+    // Evict oldest if over limit
+    const keys = Object.keys(cache);
+    if (keys.length > MAX_CACHED_SESSIONS) {
+      const sorted = keys.sort((a, b) =>
+        (cache[a].ts ?? "").localeCompare(cache[b].ts ?? "")
+      );
+      for (const key of sorted.slice(0, keys.length - MAX_CACHED_SESSIONS)) {
+        delete cache[key];
+      }
+    }
+
+    writeFileSync(cachePath, JSON.stringify(cache), "utf-8");
+    logDebug("runStopHandlers", "Cached last response for RatingCapture");
+  } catch (err) {
+    logError("runStopHandlers:cacheLastResponse", err);
+  }
+}
+
+async function checkPendingFailure(transcript: string): Promise<void> {
+  const pendingPath = resolve(paths.state(), "pending-failure.json");
+  if (!existsSync(pendingPath)) return;
+
+  try {
+    const pending = JSON.parse(readFileSync(pendingPath, "utf-8")) as {
+      rating: number;
+      context: string;
+      detailedContext?: string;
+      responsePreview?: string;
+      userPreview?: string;
+    };
+    unlinkSync(pendingPath);
+    await captureFailure(
+      pending.rating,
+      pending.context,
+      transcript,
+      pending.detailedContext,
+      pending.responsePreview,
+      pending.userPreview
+    );
+  } catch {
+    // Non-critical
+  }
+}

package/src/hooks/lib/time.ts

@@ -0,0 +1,19 @@
+/** ISO 8601 UTC timestamp */
+export function now(): string {
+  return new Date().toISOString();
+}
+
+/** Date-based path segment: YYYY/MM */
+export function monthPath(): string {
+  const d = new Date();
+  return `${d.getFullYear()}/${String(d.getMonth() + 1).padStart(2, "0")}`;
+}
+
+/** Compact timestamp for filenames: YYYYMMDD-HHmmss */
+export function fileTimestamp(): string {
+  return new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace("T", "-")
+    .replace(/\.\d+Z/, "");
+}

package/src/hooks/lib/token-usage.ts

@@ -0,0 +1,42 @@
+/**
+ * Append-only JSONL logger for Haiku token usage.
+ * Writes to memory/signals/token-usage.jsonl
+ */
+
+import { appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { HAIKU_MODEL } from "./models";
+import { ensureDir, paths } from "./paths";
+
+export type TokenCaller =
+  | "rating"
+  | "failure"
+  | "work-learning"
+  | "session-name"
+  | "relationship";
+
+interface TokenUsageEntry {
+  ts: string;
+  caller: TokenCaller;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export function logTokenUsage(
+  caller: TokenCaller,
+  usage: { inputTokens: number; outputTokens: number },
+  model?: string
+): void {
+  const entry: TokenUsageEntry = {
+    ts: new Date().toISOString(),
+    caller,
+    model: model ?? HAIKU_MODEL,
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+  };
+
+  const dir = ensureDir(paths.signals());
+  const filepath = resolve(dir, "token-usage.jsonl");
+  appendFileSync(filepath, `${JSON.stringify(entry)}\n`, "utf-8");
+}

package/src/hooks/lib/transcript.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared transcript parsing utilities.
+ * Used by Stop handlers and the opencode plugin.
+ */
+
+import { readFileSync } from "node:fs";
+
+export interface Message {
+  role: string;
+  content: string | unknown;
+}
+
+/** Parse raw transcript string into messages array. Returns [] on failure. */
+export function parseMessages(raw: string): Message[] {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read a Claude Code transcript JSONL file and extract user/assistant messages.
+ * Each line is a JSON object; we extract entries with type "user" or "assistant".
+ */
+export function readTranscriptFile(path: string): Message[] {
+  try {
+    const content = readFileSync(path, "utf-8");
+    const messages: Message[] = [];
+
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type === "user" || entry.type === "assistant") {
+          const msg = entry.message ?? {};
+          let text = "";
+          if (typeof msg.content === "string") {
+            text = msg.content;
+          } else if (Array.isArray(msg.content)) {
+            text = msg.content
+              .filter((c: { type: string }) => c.type === "text")
+              .map((c: { text: string }) => c.text)
+              .join(" ");
+          }
+          if (text) {
+            messages.push({ role: entry.type, content: text });
+          }
+        }
+      } catch {
+        /* skip malformed lines */
+      }
+    }
+
+    return messages;
+  } catch {
+    return [];
+  }
+}
+
+/** Extract string content from a message object */
+export function extractContent(msg: Message | undefined): string {
+  if (!msg) return "";
+  return typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+}
+
+/** Get the last assistant message from a messages array */
+export function extractLastAssistant(messages: Message[]): Message | undefined {
+  return messages.filter((m) => m.role === "assistant").pop();
+}
+
+/** Get the last user message from a messages array */
+export function extractLastUser(messages: Message[]): Message | undefined {
+  return messages.filter((m) => m.role === "user").pop();
+}

package/src/hooks/lib/wisdom.ts

@@ -0,0 +1,48 @@
+/**
+ * Wisdom Frames — domain-specific crystallized knowledge that compounds across sessions.
+ *
+ * Frame files live at memory/wisdom/frames/{domain}.md
+ * Principles marked [CRYSTAL: ≥85%] are injected into every session.
+ *
+ * Frames are populated by Claude during conversations (via CLAUDE.md instructions),
+ * not auto-extracted from transcripts.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+/** Extract CRYSTAL principles (≥85% confidence) from all frame files */
+export function readFramePrinciples(): string[] {
+  const framesDir = paths.wisdom();
+  const principles: string[] = [];
+
+  if (!existsSync(framesDir)) return principles;
+
+  for (const file of readdirSync(framesDir).filter((f) => f.endsWith(".md"))) {
+    const domain = file.replace(".md", "");
+    const content = readFileSync(resolve(framesDir, file), "utf-8");
+
+    // v4: headings "### Name [CRYSTAL: N%]"
+    for (const match of content.matchAll(/^### (.+?) \[CRYSTAL:\s*(\d+)%\]/gm)) {
+      const name = match[1]?.trim();
+      const pct = parseInt(match[2] ?? "", 10);
+      if (name && Number.isFinite(pct) && pct >= 85) {
+        principles.push(`[${domain}] ${name} (${pct}%)`);
+      }
+    }
+
+    // legacy fallback: bullet lines "- X [CRYSTAL: N%]"
+    for (const line of content.split("\n")) {
+      const match = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/);
+      if (!match) continue;
+      const name = match[1]?.trim();
+      const pct = parseInt(match[2] ?? "", 10);
+      if (name && Number.isFinite(pct) && pct >= 85) {
+        principles.push(`[${domain}] ${name} (${pct}%)`);
+      }
+    }
+  }
+
+  return principles;
+}