borgmcp 1.1.14 → 2.0.1

package/src/local-server-cursor.ts

@@ -0,0 +1,188 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const CURSOR_FILE = join(homedir(), '.config', 'borgmcp', 'local-server-cursors.json');
+const CURSOR_LOCK = `${CURSOR_FILE}.lock`;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export interface LocalServerCursor {
+  id: string;
+  created_at: string;
+}
+
+export interface LocalServerCursorBinding {
+  origin: string;
+  trustIdentity: string;
+  cubeId: string;
+  droneId: string;
+  /**
+   * client#41: cursor-purpose namespace. Absent (the default) is the UNREAD
+   * WATERMARK — the point `read-log unread_only` reads from and advances only
+   * on an explicit successful drain. `'stream'` is the SSE DELIVERY/RESUME
+   * cursor the live tail advances as it delivers events. Keeping these under
+   * separate keys stops SSE delivery from consuming the unread watermark (a
+   * wake-triggering entry would otherwise disappear from `unread_only` before
+   * the agent drained it — a silent missed wake).
+   */
+  purpose?: 'stream';
+}
+
+interface CursorFile {
+  version: 1;
+  cursors: Record<string, LocalServerCursor>;
+}
+
+function cursorKey(binding: LocalServerCursorBinding): string {
+  if (
+    new URL(binding.origin).origin !== binding.origin ||
+    !UUID_RE.test(binding.cubeId) ||
+    !UUID_RE.test(binding.droneId)
+  ) {
+    throw new Error('invalid local Borg server cursor binding');
+  }
+  const hash = createHash('sha256')
+    .update(binding.origin)
+    .update('\0')
+    .update(binding.trustIdentity)
+    .update('\0')
+    .update(binding.cubeId)
+    .update('\0')
+    .update(binding.droneId);
+  // The purpose component is appended ONLY when present, so the unread-watermark
+  // key (purpose absent) stays byte-identical to the pre-client#41 key — already
+  // persisted watermarks are not orphaned by the upgrade. The 'stream' delivery
+  // cursor gets a distinct key.
+  if (binding.purpose) {
+    hash.update('\0').update(binding.purpose);
+  }
+  return hash.digest('hex');
+}
+
+function validCursor(value: unknown): value is LocalServerCursor {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const cursor = value as Record<string, unknown>;
+  return UUID_RE.test(String(cursor.id ?? '')) &&
+    typeof cursor.created_at === 'string' &&
+    Number.isFinite(Date.parse(cursor.created_at)) &&
+    new Date(cursor.created_at).toISOString() === cursor.created_at;
+}
+
+async function readState(): Promise<CursorFile> {
+  try {
+    const parsed = JSON.parse(await readFile(CURSOR_FILE, 'utf8')) as Partial<CursorFile>;
+    if (
+      parsed.version !== 1 ||
+      typeof parsed.cursors !== 'object' ||
+      parsed.cursors === null ||
+      Array.isArray(parsed.cursors) ||
+      Object.values(parsed.cursors).some((cursor) => !validCursor(cursor))
+    ) {
+      throw new Error('invalid');
+    }
+    return parsed as CursorFile;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { version: 1, cursors: {} };
+    }
+    throw new Error('local Borg server cursor state is corrupt');
+  }
+}
+
+async function writeState(state: CursorFile): Promise<void> {
+  await mkdir(dirname(CURSOR_FILE), { recursive: true });
+  const temporary = `${CURSOR_FILE}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporary, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  await rename(temporary, CURSOR_FILE);
+}
+
+async function withLock<T>(operation: () => Promise<T>): Promise<T> {
+  await mkdir(dirname(CURSOR_LOCK), { recursive: true });
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    let handle;
+    try {
+      handle = await open(CURSOR_LOCK, 'wx', 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      try {
+        const metadata = await stat(CURSOR_LOCK);
+        if (Date.now() - metadata.mtimeMs > 30_000) {
+          await unlink(CURSOR_LOCK);
+          continue;
+        }
+      } catch (inspectionError) {
+        if ((inspectionError as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw inspectionError;
+      }
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+      continue;
+    }
+    try {
+      return await operation();
+    } finally {
+      await handle.close();
+      try {
+        await unlink(CURSOR_LOCK);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+  }
+  throw new Error('local Borg server cursor state is busy');
+}
+
+export async function getLocalServerCursor(
+  binding: LocalServerCursorBinding,
+): Promise<LocalServerCursor | null> {
+  const key = cursorKey(binding);
+  const state = await readState();
+  return state.cursors[key] ?? null;
+}
+
+export async function advanceLocalServerCursor(
+  binding: LocalServerCursorBinding,
+  cursor: LocalServerCursor,
+): Promise<void> {
+  if (!validCursor(cursor)) throw new Error('invalid local Borg server cursor');
+  const key = cursorKey(binding);
+  await withLock(async () => {
+    const state = await readState();
+    const prior = state.cursors[key];
+    if (
+      prior &&
+      (prior.created_at > cursor.created_at ||
+        (prior.created_at === cursor.created_at && prior.id >= cursor.id))
+    ) {
+      return;
+    }
+    state.cursors[key] = cursor;
+    await writeState(state);
+  });
+}
+
+/**
+ * client#42: reset (delete) a persisted cursor for `binding`. Used by the SSE
+ * recovery path when the server returns 410 CURSOR_EXPIRED for the stream's
+ * resume cursor — the pointed-at entry has been pruned server-side, so the
+ * stale cursor can never be resumed and must be cleared, letting the next
+ * stream connect re-establish from a fresh valid point (the current tail)
+ * instead of looping forever on the dead cursor. No-op when no cursor is
+ * stored for the binding.
+ */
+export async function clearLocalServerCursor(
+  binding: LocalServerCursorBinding,
+): Promise<void> {
+  const key = cursorKey(binding);
+  await withLock(async () => {
+    const state = await readState();
+    if (!(key in state.cursors)) return;
+    delete state.cursors[key];
+    await writeState(state);
+  });
+}
+
+export function encodeLocalServerCursor(cursor: LocalServerCursor): string {
+  if (!validCursor(cursor)) throw new Error('invalid local Borg server cursor');
+  return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+}

package/src/log-audit.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * borg-log-audit
+ *
+ * Domain-agnostic nudge: scans the Claude Code transcript and emits a
+ * one-line warning to stdout if the drone has accumulated MATERIAL_THRESHOLD
+ * or more state-changing tool calls (Edit / Write / Bash / etc.) since the
+ * last borg_log post. Wired in as a UserPromptSubmit hook so the warning
+ * becomes additional context for the next turn.
+ *
+ * Two refinements vs the v1 1-tool threshold (per drone-6's review):
+ *   1. Counts material tools across all assistant turns until either the
+ *      threshold is hit OR a borg_log call is found (cooldown). One
+ *      diagnostic Bash no longer triggers; substantive work always does.
+ *   2. Any borg_log in the scanback suppresses the nudge — so the drone
+ *      gets a turn of breathing room after each post.
+ *
+ * Stays generic — knows nothing about git, branches, or any project's
+ * conventions. Only the Anthropic tool name `mcp__borg__borg_log` and a
+ * small set of canonical mutating tool names. If no cube is active in
+ * this project, silently exits.
+ *
+ * Hook input arrives as JSON on stdin (Claude Code's standard hook
+ * contract). The relevant field is `transcript_path`.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { getActiveCube } from './cubes.js';
+import { handleVersionFlag } from './version.js';
+import { gateAllowsActivation } from './launch-gate.js';
+
+const MATERIAL_TOOLS = new Set([
+  'Edit',
+  'Write',
+  'MultiEdit',
+  'NotebookEdit',
+  'Bash',
+  'apply_patch',
+  'exec_command',
+  'functions.exec_command',
+  'functions.apply_patch',
+]);
+
+const LOG_TOOL = 'mcp__borg__borg_log';
+
+// Number of state-changing tool calls since the last borg_log that the
+// drone is allowed before the audit nudges. 1 false-positives on
+// diagnostic Bash (git status, ls, etc.); 3 has been comfortable in
+// dogfooding — any substantive work crosses it within a turn or two.
+const MATERIAL_THRESHOLD = 3;
+
+// Cap on how many transcript entries we scan backwards before giving up.
+// Sessions with thousands of turns still resolve in milliseconds at this
+// bound, and anything truly old is no longer "the last span the drone
+// failed to log."
+const MAX_SCAN = 400;
+
+interface HookInput {
+  transcript_path?: string;
+  cwd?: string;
+}
+
+function isUserPrompt(entry: any): boolean {
+  const type = entry?.type ?? entry?.role;
+  if (type !== 'user') return false;
+  const content = entry?.message?.content ?? entry?.content;
+  if (typeof content === 'string') return content.trim().length > 0;
+  if (!Array.isArray(content)) return false;
+  // A "real" user prompt has at least one text block. A tool_result-only
+  // user message is a continuation of an assistant span, not a prompt.
+  return content.some((b: any) => b?.type === 'text');
+}
+
+function isAssistant(entry: any): boolean {
+  const type = entry?.type ?? entry?.role;
+  return type === 'assistant' || type === 'response_item';
+}
+
+type ScanFinding =
+  | { kind: 'cooldown' } // hit a borg_log before threshold — suppress
+  | { kind: 'over_threshold'; count: number } // accumulated >= threshold
+  | { kind: 'under_threshold'; count: number }; // ran out of transcript
+
+function scanAssistant(entry: any, state: { material: number; loggedRecently: boolean }): void {
+  const payload = entry?.payload;
+  const payloadToolName =
+    payload?.type === 'function_call' || payload?.type === 'custom_tool_call'
+      ? payload.name
+      : null;
+  if (typeof payloadToolName === 'string') {
+    if (payloadToolName === LOG_TOOL) {
+      state.loggedRecently = true;
+      return;
+    }
+    if (MATERIAL_TOOLS.has(payloadToolName)) state.material += 1;
+  }
+
+  const content = entry?.message?.content ?? entry?.content ?? [];
+  if (!Array.isArray(content)) return;
+  // Walk the blocks newest-first WITHIN the entry. The caller already
+  // visits entries newest-first. Counting forward within an entry would
+  // either miss post-log material work (if log is in the same entry as
+  // later material blocks) or inflate the count with pre-log work that
+  // the log already covered. Reversing here keeps "material since the
+  // last log" honest at block granularity.
+  for (let i = content.length - 1; i >= 0; i--) {
+    const block = content[i];
+    if (block?.type !== 'tool_use') continue;
+    if (block.name === LOG_TOOL) {
+      state.loggedRecently = true;
+      return;
+    }
+    if (MATERIAL_TOOLS.has(block.name)) state.material += 1;
+  }
+}
+
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) return '';
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+async function main(): Promise<void> {
+  handleVersionFlag();
+  // gh#673 P1 (WI-4): the log-audit nudge only activates in
+  // borg-launched sessions — vanilla `claude` gets no borg hook output.
+  // Exit-0 no-op (a UserPromptSubmit hook must never block the prompt).
+  // ACTIVATION-only, never a security gate.
+  if (!gateAllowsActivation('borg-log-audit UserPromptSubmit hook')) {
+    return;
+  }
+  const raw = await readStdin();
+  let input: HookInput = {};
+  if (raw.trim()) {
+    try {
+      input = JSON.parse(raw);
+    } catch {
+      // No usable input — silent exit.
+      return;
+    }
+  }
+
+  if (!input.transcript_path || !existsSync(input.transcript_path)) return;
+  if (input.cwd && existsSync(input.cwd)) {
+    try {
+      process.chdir(input.cwd);
+    } catch {
+      // Best-effort only; fall back to the hook process cwd.
+    }
+  }
+
+  // Only nudge if there's an active cube in this project. Otherwise the
+  // hook is fully inert.
+  const active = await getActiveCube();
+  if (!active) return;
+
+  const lines = readFileSync(input.transcript_path, 'utf-8').split('\n').filter(Boolean);
+  if (lines.length === 0) return;
+
+  // Walk the transcript backwards from the end. The trailing entry MAY
+  // be the user prompt that triggered this hook; skip it if so. From
+  // there, accumulate material tool calls until either we hit a borg_log
+  // (cooldown — suppress) or we cross MATERIAL_THRESHOLD (nudge). The
+  // scan stops after MAX_SCAN entries to bound work on huge sessions.
+  let i = lines.length - 1;
+  const tail = safeParse(lines[i]);
+  if (tail && isUserPrompt(tail)) i--;
+
+  const state = { material: 0, loggedRecently: false };
+  let scanned = 0;
+  for (; i >= 0 && scanned < MAX_SCAN; i--, scanned++) {
+    const entry = safeParse(lines[i]);
+    if (!entry) continue;
+    if (isAssistant(entry)) {
+      scanAssistant(entry, state);
+      // Threshold has primacy over cooldown: when both could fire on the
+      // same entry (e.g. an entry containing [log, Bash, Bash, Bash]
+      // where the reversed scan first counts 3 material blocks before
+      // hitting the log), we want the nudge — the post-log material
+      // work hasn't been logged yet.
+      if (state.material >= MATERIAL_THRESHOLD) {
+        process.stdout.write(
+          `Heads up: ${state.material}+ state-changing tool calls since the last \`borg_log\` post. ` +
+          'If that work was a substantive unit (a change that ships, a blocker hit, a finding ' +
+          "worth sharing), post to the cube log per your role's conventions before continuing.\n"
+        );
+        return;
+      }
+      if (state.loggedRecently) return; // cooldown
+    }
+  }
+  // Reached MAX_SCAN or start of transcript without finding either a
+  // log call or enough material work. Silent.
+}
+
+function safeParse(line: string): any | null {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+main().catch(() => {
+  // Never fail a hook — silent on error.
+});