@ssm-08/relay 0.4.0

package/hooks/hooks.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "timeout": 2,
+            "statusMessage": "Loading relay memory..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" stop",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" user-prompt-submit",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook.cmd

@@ -0,0 +1,11 @@
+: << 'CMDBLOCK'
+@echo off
+setlocal
+if "%CLAUDE_PLUGIN_ROOT%"=="" set CLAUDE_PLUGIN_ROOT=%~dp0..
+node "%CLAUDE_PLUGIN_ROOT%\hooks\%1.mjs"
+exit /b %ERRORLEVEL%
+CMDBLOCK
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+node "$SCRIPT_DIR/$1.mjs"
+exit $?

package/hooks/session-start.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { readMemory } from '../lib/memory.mjs';
+import { readStdin, isMain } from '../lib/util.mjs';
+import { GitSync } from '../lib/sync.mjs';
+
+// Returns { content: string, skillFiles: string[] }
+export function readBroadcastDir(broadcastDir) {
+  if (!fs.existsSync(broadcastDir)) return { content: '', skillFiles: [] };
+  const files = [];
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name !== '.gitkeep') files.push(full);
+    }
+  }
+  walk(broadcastDir);
+  files.sort();
+  if (files.length === 0) return { content: '', skillFiles: [] };
+
+  const skillsDir = path.join(broadcastDir, 'skills');
+  const skillFiles = files
+    .filter((f) => path.dirname(f) === skillsDir)
+    .map((f) => path.basename(f));
+
+  const MAX_FILE_BYTES = 50_000;
+  const MAX_TOTAL_BYTES = 200_000;
+  let totalBytes = 0;
+  const parts = [];
+  for (const f of files) {
+    const name = path.relative(broadcastDir, f).replace(/\\/g, '/');
+    let body = fs.readFileSync(f, 'utf8');
+    if (Buffer.byteLength(body, 'utf8') > MAX_FILE_BYTES) {
+      body = body.slice(0, MAX_FILE_BYTES) + '\n<!-- relay: truncated — file exceeds 50 KB -->';
+    }
+    const entry = `## broadcast: ${name}\n\n${body.trim()}`;
+    const entryBytes = Buffer.byteLength(entry, 'utf8');
+    if (totalBytes + entryBytes > MAX_TOTAL_BYTES) break; // aggregate cap
+    parts.push(entry);
+    totalBytes += entryBytes;
+  }
+  const content = parts.join('\n\n---\n\n');
+
+  return { content, skillFiles };
+}
+
+export function buildContext(cwd) {
+  const relayDir = path.join(cwd, '.relay');
+  if (!fs.existsSync(relayDir)) return '';
+
+  const memory = readMemory(path.join(relayDir, 'memory.md'));
+  const { content: broadcast, skillFiles } = readBroadcastDir(path.join(relayDir, 'broadcast'));
+
+  const parts = [];
+  if (memory.trim()) parts.push(`# Relay Memory\n\n${memory.trim()}`);
+  if (broadcast.trim()) {
+    let broadcastSection = `# Relay Broadcast\n\n${broadcast.trim()}`;
+    if (skillFiles.length > 0) {
+      const count = skillFiles.length;
+      const names = skillFiles
+        .map((f) => '`' + path.basename(f, path.extname(f)) + '`')
+        .join(', ');
+      broadcastSection +=
+        `\n\n_Relay: ${count} team skill(s) loaded — ${names}.` +
+        ` Acknowledge in your first response with one line: "Loaded ${count} team skill(s): ${names}."_`;
+    }
+    parts.push(broadcastSection);
+  }
+
+  return parts.join('\n\n---\n\n');
+}
+
+function appendLog(cwd, msg) {
+  try {
+    const logPath = path.join(cwd, '.relay', 'log');
+    fs.appendFileSync(logPath, `[${new Date().toISOString()}] ${msg}\n`);
+  } catch {}
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    const input = JSON.parse(raw);
+    const { cwd } = input;
+
+    // Pull latest .relay/ from remote before reading memory (fail-open, 3s cap inside pull)
+    if (fs.existsSync(path.join(cwd, '.relay'))) {
+      try { new GitSync().pull(cwd, { fetchTimeoutMs: 1500, checkoutTimeoutMs: 500 }); } catch {}
+    }
+
+    const context = buildContext(cwd);
+    if (!context) process.exit(0);
+    appendLog(cwd, 'injection: session-start');
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext: context,
+        },
+      }) + '\n'
+    );
+  } catch (e) {
+    process.stderr.write(`[relay] session-start error: ${e.message}\n`);
+    process.exit(0);
+  }
+}
+
+if (isMain(import.meta.url)) main();

package/hooks/stop.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { spawn } from 'node:child_process';
+import { readStdin, isMain } from '../lib/util.mjs';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+const TURNS_THRESHOLD = process.env.RELAY_TURNS_THRESHOLD ? parseInt(process.env.RELAY_TURNS_THRESHOLD, 10) : 5;
+const IDLE_MS = process.env.RELAY_IDLE_MS ? parseInt(process.env.RELAY_IDLE_MS, 10) : 2 * 60 * 1000;
+
+export function writeWatermarkAtomic(watermarkPath, state) {
+  const tmp = `${watermarkPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  let lastErr;
+  for (let i = 0; i < 5; i++) {
+    try { fs.renameSync(tmp, watermarkPath); return; } catch (e) {
+      lastErr = e;
+      if (e.code !== 'EPERM' && e.code !== 'EBUSY' && e.code !== 'EACCES') break;
+      // Staggered busy-wait: reduces concurrent NTFS rename contention on Windows
+      const end = Date.now() + i + 1;
+      while (Date.now() < end) {}
+    }
+  }
+  try { fs.unlinkSync(tmp); } catch {}
+  throw lastErr;
+}
+
+export function updateWatermark(relayDir) {
+  const stateDir = path.join(relayDir, 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+
+  const watermarkPath = path.join(stateDir, 'watermark.json');
+  let state = { turns_since_distill: 0 };
+  try {
+    state = JSON.parse(fs.readFileSync(watermarkPath, 'utf8'));
+  } catch {}
+
+  state.turns_since_distill = (state.turns_since_distill ?? 0) + 1;
+  state.last_turn_at = Date.now();
+
+  writeWatermarkAtomic(watermarkPath, state);
+  return state;
+}
+
+export function shouldDistill(state) {
+  if (state.distiller_running) {
+    // PID liveness check — if the distiller was killed (OOM, forced reboot) the flag would
+    // stick forever. Verify the PID is still alive; only treat as stale on ESRCH (no such process).
+    if (state.distiller_pid) {
+      try {
+        process.kill(state.distiller_pid, 0);
+        return false; // still alive
+      } catch (e) {
+        if (e.code !== 'ESRCH') return false; // EPERM or unknown — conservatively honor flag
+        // ESRCH: process is gone — stale flag, fall through to normal threshold checks
+      }
+    } else {
+      return false; // no PID stored, honor flag
+    }
+  }
+  if (state.turns_since_distill >= TURNS_THRESHOLD) return true;
+  // idle trigger: turns accumulated but not yet at threshold
+  // Use last_turn_at (not last_distilled_at) so idle trigger fires even before first distillation
+  if (
+    state.turns_since_distill > 0 &&
+    state.last_turn_at &&
+    Date.now() - state.last_turn_at > IDLE_MS
+  ) return true;
+  return false;
+}
+
+export function spawnDistiller({ relayDir, transcriptPath, since, cwd }) {
+  const distillerPath =
+    process.env.CLAUDE_PLUGIN_ROOT
+      ? path.join(process.env.CLAUDE_PLUGIN_ROOT, 'distiller.mjs')
+      : path.join(__dirname, '..', 'distiller.mjs');
+
+  const memoryPath = path.join(relayDir, 'memory.md');
+  const logPath = path.join(relayDir, 'log');
+
+  const args = [
+    distillerPath,
+    '--transcript', transcriptPath,
+    '--memory', memoryPath,
+    '--out', memoryPath,
+    '--cwd', cwd,
+  ];
+  if (since) args.push('--since', since);
+
+  let logFd;
+  try {
+    logFd = fs.openSync(logPath, 'a');
+  } catch {
+    logFd = 'ignore';
+  }
+
+  const proc = spawn('node', args, {
+    detached: true,
+    windowsHide: true,
+    stdio: ['ignore', logFd, logFd],
+  });
+  proc.on('error', (e) => {
+    process.stderr.write(`[relay] distiller spawn failed: ${e.message}\n`);
+  });
+  proc.unref();
+  // close parent's copy — child already inherited its own fd
+  if (typeof logFd === 'number') { try { fs.closeSync(logFd); } catch {} }
+  return proc;
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    const input = JSON.parse(raw);
+    const { cwd, transcript_path } = input;
+    const relayDir = path.join(cwd, '.relay');
+    if (!fs.existsSync(relayDir)) process.exit(0);
+
+    const state = updateWatermark(relayDir);
+
+    if (shouldDistill(state) && transcript_path) {
+      // openSync('wx') is atomic — EEXIST if another Stop hook beat us here
+      const triggerLock = path.join(relayDir, 'state', 'distill-trigger.lock');
+      try {
+        fs.closeSync(fs.openSync(triggerLock, 'wx'));
+      } catch {
+        process.exit(0); // another process won the race
+      }
+
+      const watermarkPath = path.join(relayDir, 'state', 'watermark.json');
+
+      const distProc = spawnDistiller({
+        relayDir,
+        transcriptPath: transcript_path,
+        since: state.last_uuid || '',
+        cwd,
+      });
+
+      // Only set distiller_running + reset turns if OS assigned a pid.
+      // If spawn silently failed (pid undefined), don't reset turns — distiller never ran.
+      const pid = distProc?.pid;
+      if (pid) {
+        state.distiller_running = true;
+        state.distiller_pid = pid;
+        state.turns_since_distill = 0;
+      }
+      writeWatermarkAtomic(watermarkPath, state);
+      // Release trigger lock only after distiller_running is written — prevents a second
+      // concurrent Stop hook from passing the lock check before the flag is set.
+      try { fs.unlinkSync(triggerLock); } catch {}
+    }
+  } catch (e) {
+    process.stderr.write(`[relay] stop error: ${e.message}\n`);
+  }
+  process.exit(0);
+}
+
+if (isMain(import.meta.url)) main();

package/hooks/user-prompt-submit.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { readStdin, isMain } from '../lib/util.mjs';
+import { readMemory, writeMemoryAtomic } from '../lib/memory.mjs';
+import { GitSync } from '../lib/sync.mjs';
+import { diffMemory, renderDelta, hashMemory } from '../lib/diff-memory.mjs';
+
+const SNAPSHOT_FILE = 'last-injected-memory.md';
+
+/**
+ * UPS owns its own state file — separate from watermark.json (owned by stop.mjs).
+ * This eliminates the read-modify-write race that existed when both hooks wrote
+ * to the shared watermark.json: UPS only needs last_injected_mtime + last_injected_hash,
+ * Stop only needs turns_since_distill + distiller_running + last_turn_at.
+ * No shared mutable state → no lock needed.
+ */
+const UPS_STATE_FILE = 'ups-state.json';
+
+function appendLog(cwd, msg) {
+  try {
+    const logPath = path.join(cwd, '.relay', 'log');
+    fs.appendFileSync(logPath, `[${new Date().toISOString()}] [ups] ${msg}\n`);
+  } catch {}
+}
+
+function readUpsState(upsStatePath) {
+  try { return JSON.parse(fs.readFileSync(upsStatePath, 'utf8')); } catch { return {}; }
+}
+
+function writeUpsStateAtomic(upsStatePath, state) {
+  const tmp = `${upsStatePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  let lastErr;
+  for (let i = 0; i < 5; i++) {
+    try { fs.renameSync(tmp, upsStatePath); return; } catch (e) {
+      lastErr = e;
+      if (e.code !== 'EPERM' && e.code !== 'EBUSY' && e.code !== 'EACCES') break;
+      // Staggered busy-wait: reduces concurrent NTFS rename contention on Windows
+      const end = Date.now() + i + 1;
+      while (Date.now() < end) {}
+    }
+  }
+  try { fs.unlinkSync(tmp); } catch {}
+  throw lastErr;
+}
+
+function markInjection(cwd, event) {
+  appendLog(cwd, `injection: ${event}`);
+}
+
+/**
+ * Exported for unit testing — all logic with no I/O side effects except reading files.
+ * Returns { delta: string, newUpsState: object, newSnapshot: string } or null (skip).
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.relayDir
+ * @param {string} opts.upsStatePath  - path to ups-state.json (UPS-owned, never written by stop.mjs)
+ * @param {string} opts.snapshotPath
+ * @param {string} opts.memoryPath
+ */
+export function buildInjection({ cwd, relayDir, upsStatePath, snapshotPath, memoryPath }) {
+  // 1. Check memory.md exists
+  if (!fs.existsSync(memoryPath)) return null;
+
+  const st = readUpsState(upsStatePath);
+  let currentMtime;
+  try {
+    const stat = fs.statSync(memoryPath);
+    if (!stat.isFile()) return null;
+    currentMtime = stat.mtimeMs;
+  } catch {
+    return null;
+  }
+
+  // 2. Fast path: mtime unchanged since last injection check
+  if (st.last_injected_mtime === currentMtime) return null;
+
+  // 3. Read current memory content + compute hash
+  const currentContent = readMemory(memoryPath);
+  const currentHash = hashMemory(currentContent);
+
+  // 4. First-run seed: no prior injection → seed without injecting
+  if (!st.last_injected_hash) {
+    return {
+      delta: null,
+      newUpsState: { last_injected_mtime: currentMtime, last_injected_hash: currentHash },
+      newSnapshot: currentContent,
+    };
+  }
+
+  // 5. Hash unchanged (e.g. file re-written with same content) → update mtime only
+  if (currentHash === st.last_injected_hash) {
+    return {
+      delta: null,
+      newUpsState: { ...st, last_injected_mtime: currentMtime },
+      newSnapshot: null,
+    };
+  }
+
+  // 6. Content changed — compute diff against stored snapshot
+  let snapshotContent = '';
+  try {
+    if (fs.existsSync(snapshotPath)) {
+      snapshotContent = fs.readFileSync(snapshotPath, 'utf8');
+    }
+  } catch {
+    // Corrupt/missing snapshot — treat as empty, inject full diff
+  }
+
+  const diff = diffMemory(snapshotContent, currentContent);
+  const delta = renderDelta(diff);
+
+  return {
+    delta: delta || null,
+    newUpsState: { last_injected_mtime: currentMtime, last_injected_hash: currentHash },
+    newSnapshot: currentContent,
+  };
+}
+
+async function main() {
+  let cwd;
+  try {
+    const raw = await readStdin();
+    const input = JSON.parse(raw);
+    cwd = input.cwd;
+
+    const relayDir = path.join(cwd, '.relay');
+    if (!fs.existsSync(relayDir)) { process.exit(0); }
+
+    // Pull latest memory from remote with tight timeout (stay within 2s hook budget)
+    try {
+      new GitSync().pull(cwd, { fetchTimeoutMs: 1500, checkoutTimeoutMs: 500 });
+    } catch (e) {
+      appendLog(cwd, `pull failed: ${e.message}`);
+      // Fail-open: proceed with whatever is on disk
+    }
+
+    const stateDir = path.join(relayDir, 'state');
+    const upsStatePath = path.join(stateDir, UPS_STATE_FILE);
+    const snapshotPath = path.join(stateDir, SNAPSHOT_FILE);
+    const memoryPath = path.join(relayDir, 'memory.md');
+
+    const result = buildInjection({ cwd, relayDir, upsStatePath, snapshotPath, memoryPath });
+
+    if (!result) { process.exit(0); }
+
+    const { delta, newUpsState, newSnapshot } = result;
+
+    // Write state updates — only to UPS-owned files; never touch watermark.json
+    fs.mkdirSync(stateDir, { recursive: true });
+    writeUpsStateAtomic(upsStatePath, newUpsState);
+    if (newSnapshot !== null) {
+      writeMemoryAtomic(snapshotPath, newSnapshot);
+    }
+
+    if (!delta) { process.exit(0); }
+
+    markInjection(cwd, 'user-prompt-submit');
+
+    // Emit additionalContext
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: delta,
+      },
+    }) + '\n');
+  } catch (e) {
+    // Fail-open: log + exit 0, never break the session
+    try { if (cwd) appendLog(cwd, `error: ${e && e.message ? e.message : e}`); } catch {}
+    process.exit(0);
+  }
+}
+
+if (isMain(import.meta.url)) main();

package/lib/diff-memory.mjs

@@ -0,0 +1,97 @@
+import crypto from 'node:crypto';
+
+const SECTION_RE = /^## (.+)$/;
+const BULLET_RE = /^- (.+)$/;
+
+/**
+ * Parse memory.md into a Map of section name → Set of bullet text.
+ * Provenance tags like "[session X, turn N]" are kept as part of the bullet
+ * so they don't cause spurious diffs (section-aware set diff ignores ordering).
+ * Note: content before the first ## header (e.g. a # title line) is intentionally
+ * ignored — the distiller prompt outputs only section-based bullets.
+ */
+export function parseSections(markdown) {
+  const sections = new Map();
+  let current = null;
+  for (const raw of (markdown || '').split('\n')) {
+    const line = raw.trimEnd();
+    const secMatch = line.match(SECTION_RE);
+    if (secMatch) {
+      current = secMatch[1].trim();
+      if (!sections.has(current)) sections.set(current, new Set());
+      continue;
+    }
+    const bulletMatch = line.match(BULLET_RE);
+    if (bulletMatch && current) {
+      sections.get(current).add(bulletMatch[1].trim());
+    }
+  }
+  return sections;
+}
+
+/**
+ * Compute section-aware set diff between two memory.md strings.
+ * Returns { added: Map<section, string[]>, removed: Map<section, string[]> }.
+ * Bullet reordering within a section produces an empty diff.
+ */
+export function diffMemory(oldText, newText) {
+  const oldSec = parseSections(oldText);
+  const newSec = parseSections(newText);
+  const added = new Map();
+  const removed = new Map();
+
+  const allSections = new Set([...oldSec.keys(), ...newSec.keys()]);
+  for (const sec of allSections) {
+    const oldBullets = oldSec.get(sec) || new Set();
+    const newBullets = newSec.get(sec) || new Set();
+
+    const addedBullets = [...newBullets].filter((b) => !oldBullets.has(b));
+    const removedBullets = [...oldBullets].filter((b) => !newBullets.has(b));
+
+    if (addedBullets.length > 0) added.set(sec, addedBullets);
+    if (removedBullets.length > 0) removed.set(sec, removedBullets);
+  }
+
+  return { added, removed };
+}
+
+/**
+ * Render a diff into a compact additionalContext string.
+ * Truncates to maxBytes with a marker so the model knows it's partial.
+ */
+export function renderDelta(diff, { maxBytes = 4096 } = {}) {
+  const { added, removed } = diff;
+  if (added.size === 0 && removed.size === 0) return '';
+
+  const lines = ['## Relay live update'];
+
+  if (added.size > 0) {
+    for (const [sec, bullets] of added) {
+      lines.push(`### New in ${sec}`);
+      for (const b of bullets) lines.push(`- ${b}`);
+    }
+  }
+  if (removed.size > 0) {
+    for (const [sec, bullets] of removed) {
+      lines.push(`### Removed from ${sec}`);
+      for (const b of bullets) lines.push(`- ${b}`);
+    }
+  }
+
+  let result = lines.join('\n');
+  if (Buffer.byteLength(result, 'utf8') > maxBytes) {
+    // Truncate at last newline before the byte limit (avoids splitting UTF-8 multi-byte sequences)
+    const truncated = Buffer.from(result, 'utf8').subarray(0, maxBytes - 60).toString('utf8');
+    const lastNL = truncated.lastIndexOf('\n');
+    result = (lastNL > 0 ? truncated.slice(0, lastNL) : truncated) +
+      '\n_…truncated, see .relay/memory.md for full context…_';
+  }
+  return result;
+}
+
+/**
+ * 12-char SHA-256 prefix of the memory text. Fast change detection.
+ */
+export function hashMemory(text) {
+  return crypto.createHash('sha256').update(text || '').digest('hex').slice(0, 12);
+}