borgmcp 3.3.0 → 3.4.0

package/src/log-audit-core.ts

@@ -0,0 +1,81 @@
+export const LOG_AUDIT_NUDGE = (count: number): string =>
+  `Heads up: ${count}+ 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.";
+
+/**
+ * Pure transcript scan shared by the Claude hook and the OpenCode plugin.
+ * Accepts both Claude JSONL entries and OpenCode SDK message records.
+ */
+export function evaluateLogAudit(
+  entries: readonly any[],
+  renderNudge: (count: number) => string = (count) =>
+    `Heads up: ${count}+ 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.",
+): string | null {
+  const materialTools = new Set([
+    'Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash',
+    'edit', 'write', 'bash', 'apply_patch', 'exec_command',
+    'functions.exec_command', 'functions.apply_patch',
+  ]);
+  const logTools = new Set(['mcp__borg__borg_log', 'borg_borg_log']);
+  const threshold = 3;
+  const maxScan = 400;
+
+  const role = (entry: any): unknown =>
+    entry?.type ?? entry?.role ?? entry?.info?.role;
+  const parts = (entry: any): any[] => {
+    const value = entry?.message?.content ?? entry?.content ?? entry?.parts ?? [];
+    return Array.isArray(value) ? value : [];
+  };
+  const isUserPrompt = (entry: any): boolean => {
+    if (role(entry) !== 'user') return false;
+    const content = entry?.message?.content ?? entry?.content ?? entry?.parts;
+    if (typeof content === 'string') return content.trim().length > 0;
+    return Array.isArray(content) && content.some((part) =>
+      part?.type === 'text' && typeof part.text === 'string' && part.text.trim().length > 0,
+    );
+  };
+  const isAssistant = (entry: any): boolean => {
+    const value = role(entry);
+    return value === 'assistant' || value === 'response_item';
+  };
+  const toolName = (part: any): string | null => {
+    if (part?.type === 'tool_use' && typeof part.name === 'string') return part.name;
+    if ((part?.type === 'tool' || part?.type === 'tool_call') && typeof part.tool === 'string') {
+      return part.tool;
+    }
+    return null;
+  };
+
+  let index = entries.length - 1;
+  if (index >= 0 && isUserPrompt(entries[index])) index--;
+  let material = 0;
+  let scanned = 0;
+  for (; index >= 0 && scanned < maxScan; index--, scanned++) {
+    const entry = entries[index];
+    if (!isAssistant(entry)) continue;
+
+    const payload = entry?.payload;
+    const payloadTool =
+      payload?.type === 'function_call' || payload?.type === 'custom_tool_call'
+        ? payload.name
+        : null;
+    if (typeof payloadTool === 'string') {
+      if (logTools.has(payloadTool)) return material >= threshold ? renderNudge(material) : null;
+      if (materialTools.has(payloadTool)) material++;
+      if (material >= threshold) return renderNudge(material);
+    }
+
+    const content = parts(entry);
+    for (let partIndex = content.length - 1; partIndex >= 0; partIndex--) {
+      const name = toolName(content[partIndex]);
+      if (!name) continue;
+      if (logTools.has(name)) return material >= threshold ? renderNudge(material) : null;
+      if (materialTools.has(name)) material++;
+      if (material >= threshold) return renderNudge(material);
+    }
+  }
+  return null;
+}

package/src/log-audit.ts

@@ -16,9 +16,9 @@
  *      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.
+ * conventions. Its pure scan core recognizes the Borg log tool names used by
+ * Claude/Codex and OpenCode plus 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`.
@@ -28,92 +28,13 @@ 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;
+import { evaluateLogAudit } from './log-audit-core.js';
 
 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[] = [];
@@ -158,40 +79,8 @@ async function main(): Promise<void> {
   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.
+  const nudge = evaluateLogAudit(lines.map(safeParse).filter((entry) => entry !== null));
+  if (nudge) process.stdout.write(`${nudge}\n`);
 }
 
 function safeParse(line: string): any | null {

package/src/opencode-drone.ts

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from 'crypto';
 import { createServer } from 'node:net';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import { OPENCODE_INJECTED_ENTRY_METADATA_KEY } from './opencode-plugin.js';
 
 const LOG_FILE = join(tmpdir(), 'borg-opencode-drone.log');
 function log(msg: string) {
@@ -511,7 +512,11 @@ async function deliverOpenCodeEntry(
     let status: number | null = null;
     try {
       status = await promptSession(target.id, {
-        parts: [{ type: 'text', text: delivery.text }],
+        parts: [{
+          type: 'text',
+          text: delivery.text,
+          metadata: { [OPENCODE_INJECTED_ENTRY_METADATA_KEY]: true },
+        }],
       });
     } catch (err) {
       log(`entry ${delivery.entryId} submission outcome unavailable: ${err}`);

package/src/opencode-plugin.ts

@@ -1,37 +1,231 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { borgHomeRoot } from './private-root.js';
-
-/**
- * Plugin source that preserves borg cube context across session compaction.
- * The initial kickoff and ongoing entry injection are handled by the launcher
- * and MCP client via the SDK, not by the plugin.
- */
-export const BORG_PLUGIN_SOURCE = `
-// Borg MCP context-preservation plugin — installed by borg assimilate
-export default function () {
-  return {
-    'experimental.session.compacting': async (_input, output) => {
-      output.context.push(
-        '## Borg Cube\\nYou are in a Borg MCP multi-agent coordination cube. ' +
-        'Use MCP tool borg_regen to get full context and recent activity.'
+import { evaluateLogAudit } from './log-audit-core.js';
+import { borgHomeRoot, isCanonicalPath } from './private-root.js';
+import { getPackageVersion } from './version.js';
+
+export const OPENCODE_COMPATIBILITY = {
+  // Empirically pinned on 2026-08-09. OpenCode 1.18.15 loads the default
+  // function -> Hooks object shape while the installed SDK uses the 1.17.18
+  // path/query/body client call shape. TextPart.metadata exists, persists
+  // through history/compaction/reload, and is hidden from the TUI and model.
+  // Do not replace either contract without a new live compatibility measurement.
+  opencode: '1.18.15',
+  sdk: '1.17.18',
+} as const;
+
+const COMPACT_FALLBACK =
+  '## Borg Cube\nYou are in a Borg MCP multi-agent coordination cube. ' +
+  'Use MCP tool borg_regen to get full context and recent activity.';
+export const OPENCODE_INJECTED_ENTRY_METADATA_KEY = 'borgOpenCodeInjectedEntry';
+export const OPENCODE_RECOVERY_METADATA_KEY = 'borgOpenCodeSessionOrientation';
+const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
+
+export interface OpenCodePluginCoreDeps {
+  defer(task: () => Promise<void>): void;
+  wait(milliseconds: number): Promise<void>;
+  listMessages(sessionID: string): Promise<any[]>;
+  renderOrientation(source: 'clear' | 'compact'): Promise<string>;
+  submitPrompt(
+    sessionID: string,
+    text: string,
+    recoveryVersion: string,
+    shouldSubmit: () => boolean,
+  ): Promise<boolean>;
+  audit(messages: readonly any[]): string | null;
+}
+
+export interface OpenCodePluginCoreOptions {
+  enabled: boolean;
+  pluginVersion: string;
+  recoveryMetadataKey: string;
+  injectedEntryMetadataKey: string;
+  kickoffPollAttempts: number;
+  confirmationPollAttempts: number;
+  pollDelayMs: number;
+  compactFallback: string;
+}
+
+/** Pure, dependency-injected behavior core. Its emitted JavaScript function
+ * body is also embedded in the installed self-contained plugin. */
+export function createOpenCodePluginCore(
+  deps: OpenCodePluginCoreDeps,
+  options: OpenCodePluginCoreOptions,
+) {
+  const claimedSessions = new Set<string>();
+  const humanPromptSessions = new Set<string>();
+  const textParts = (message: any): any[] => Array.isArray(message?.parts)
+    ? message.parts.filter((part: any) => part?.type === 'text' && typeof part.text === 'string')
+    : [];
+  const isInjectedEntry = (message: any): boolean => {
+    const parts = textParts(message);
+    return message?.info?.role === 'user' &&
+      parts[0]?.metadata?.[options.injectedEntryMetadataKey] === true;
+  };
+  const isOwnedRecovery = (message: any): boolean => {
+    const parts = textParts(message);
+    return message?.info?.role === 'user' &&
+      parts[0]?.metadata?.[options.recoveryMetadataKey] === options.pluginVersion;
+  };
+  const hasRecoveryBlocker = (sessionID: string, messages: readonly any[]): boolean =>
+    humanPromptSessions.has(sessionID) || messages.some((message) =>
+      isOwnedRecovery(message) ||
+      (message?.info?.role === 'user' && !isInjectedEntry(message)));
+
+  const recoverNewSession = async (sessionID: string): Promise<void> => {
+    try {
+      for (let attempt = 0; attempt < options.kickoffPollAttempts; attempt++) {
+        const messages = await deps.listMessages(sessionID);
+        if (hasRecoveryBlocker(sessionID, messages)) return;
+        if (attempt + 1 < options.kickoffPollAttempts) await deps.wait(options.pollDelayMs);
+      }
+
+      const orientation = (await deps.renderOrientation('clear')).trim();
+      if (!orientation) return;
+      const beforeSubmit = await deps.listMessages(sessionID);
+      if (hasRecoveryBlocker(sessionID, beforeSubmit)) return;
+
+      const submitted = await deps.submitPrompt(
+        sessionID,
+        orientation,
+        options.pluginVersion,
+        () => !hasRecoveryBlocker(sessionID, []),
       );
+      if (!submitted) return;
+      // promptAsync is not idempotent. Confirmation may retry, submission may not.
+      for (let attempt = 0; attempt < options.confirmationPollAttempts; attempt++) {
+        const messages = await deps.listMessages(sessionID);
+        if (messages.some(isOwnedRecovery)) return;
+        if (attempt + 1 < options.confirmationPollAttempts) await deps.wait(options.pollDelayMs);
+      }
+    } catch {
+      // The plugin is best-effort. Never block OpenCode session creation.
+    }
+  };
+
+  return {
+    event: async ({ event }: any): Promise<void> => {
+      if (!options.enabled || event?.type !== 'session.created') return;
+      const sessionID = event?.properties?.info?.id;
+      if (typeof sessionID !== 'string' || claimedSessions.has(sessionID)) return;
+      claimedSessions.add(sessionID);
+      deps.defer(() => recoverNewSession(sessionID));
+    },
+    'experimental.session.compacting': async (
+      _input: { sessionID: string },
+      output: { context: string[] },
+    ): Promise<void> => {
+      if (!options.enabled) return;
+      try {
+        const orientation = (await deps.renderOrientation('compact')).trim();
+        output.context.push(orientation || options.compactFallback);
+      } catch {
+        output.context.push(options.compactFallback);
+      }
+    },
+    'chat.message': async (
+      input: { sessionID: string },
+      output: { message: unknown; parts: any[] },
+    ): Promise<void> => {
+      if (!options.enabled) return;
+      const current = { info: { role: 'user' }, parts: [...output.parts] };
+      if (!isInjectedEntry(current) && !isOwnedRecovery(current)) {
+        // chat.message fires before the user message is persisted. Record the
+        // human turn synchronously so recovery cannot race that short gap.
+        humanPromptSessions.add(input.sessionID);
+      }
+      try {
+        const history = await deps.listMessages(input.sessionID);
+        const nudge = deps.audit([...history, current]);
+        if (nudge) output.parts.push({ type: 'text', text: nudge });
+      } catch {
+        // Audit is advisory and must never block a prompt.
+      }
     },
   };
 }
+
+export function buildBorgPluginSource(version: string): string {
+  const marker = `borgmcp-opencode-plugin:${version};opencode=${OPENCODE_COMPATIBILITY.opencode};sdk=${OPENCODE_COMPATIBILITY.sdk};textpart-metadata=exists+persisted+tui-hidden+model-hidden`;
+  return `// ${marker}
+// Generated by borgmcp. Self-contained; do not edit.
+const createCore = ${createOpenCodePluginCore.toString()};
+const evaluateAudit = ${evaluateLogAudit.toString()};
+export default async function (ctx) {
+  const runRegen = async (source) => {
+    const input = JSON.stringify({ source });
+    const result = await ctx.$\`printf '%s' \${input} | borg-regen\`.quiet().nothrow();
+    return result.exitCode === 0 ? result.stdout.toString('utf8') : '';
+  };
+  return createCore({
+    defer: (task) => { setTimeout(() => { void task(); }, 0); },
+    wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    listMessages: async (sessionID) => {
+      const result = await ctx.client.session.messages({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+      });
+      return Array.isArray(result.data) ? result.data : [];
+    },
+    renderOrientation: runRegen,
+    submitPrompt: async (sessionID, text, recoveryVersion, shouldSubmit) => {
+      if (!shouldSubmit()) return false;
+      await ctx.client.session.promptAsync({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+        body: { parts: [{
+          type: 'text',
+          text,
+          metadata: { [${JSON.stringify(OPENCODE_RECOVERY_METADATA_KEY)}]: recoveryVersion },
+        }] },
+      });
+      return true;
+    },
+    audit: (messages) => evaluateAudit(messages),
+  }, {
+    ...${JSON.stringify({
+    pluginVersion: version,
+    recoveryMetadataKey: OPENCODE_RECOVERY_METADATA_KEY,
+    injectedEntryMetadataKey: OPENCODE_INJECTED_ENTRY_METADATA_KEY,
+    kickoffPollAttempts: 6,
+    confirmationPollAttempts: 6,
+    pollDelayMs: 200,
+    compactFallback: COMPACT_FALLBACK,
+  })},
+    enabled: process.env.BORG_SESSION === '1',
+  });
+}
 `;
+}
 
-const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
+export const BORG_PLUGIN_SOURCE = buildBorgPluginSource(getPackageVersion());
 
-export function installBorgPlugin(): void {
-  const pluginPath = path.join(borgHomeRoot(), PLUGIN_REL_PATH);
+export function openCodePluginPath(homeDir: string = borgHomeRoot()): string {
+  return path.join(homeDir, PLUGIN_REL_PATH);
+}
+
+export function installBorgPlugin(options: {
+  homeDir?: string;
+  version?: string;
+} = {}): void {
+  const pluginPath = openCodePluginPath(options.homeDir);
+  const source = buildBorgPluginSource(options.version ?? getPackageVersion());
   try {
-    if (fs.existsSync(pluginPath)) {
-      const existing = fs.readFileSync(pluginPath, 'utf-8');
-      if (existing === BORG_PLUGIN_SOURCE) return;
+    if (!isCanonicalPath(pluginPath)) return;
+    try {
+      if (fs.lstatSync(pluginPath).isSymbolicLink()) return;
+      if (fs.readFileSync(pluginPath, 'utf-8') === source) return;
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) return;
     }
     fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
-    fs.writeFileSync(pluginPath, BORG_PLUGIN_SOURCE, 'utf-8');
+    if (!isCanonicalPath(pluginPath)) return;
+    try {
+      if (fs.lstatSync(pluginPath).isSymbolicLink()) return;
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) return;
+    }
+    fs.writeFileSync(pluginPath, source, 'utf-8');
   } catch {
     // Best-effort — plugin is an optimization, not a requirement.
   }

package/src/regen-format.ts

@@ -190,7 +190,7 @@ export function formatLeanOrientation(args: {
               '\n_(`/clear` cleared Claude\'s conversation — re-arm the inbox Monitor now.)_',
               '_Quiet-clear fallback: if a later turn follows silence, inspect `borg_stream-status` + `borg_roster`; call `borg_regen mode="full"`, drain `borg_read-log unread_only=true`, then re-arm the Monitor._\n',
             ].join('\n')
-          : ''
+          : '\n_(OpenCode started a new session; Borg supplied this orientation automatically.)_\n'
       : '';
   return [
     `# Cube: ${cubeName} — ${droneLabel}`,

package/src/resolved-cli-config.ts

@@ -7,6 +7,7 @@ export interface ResolvedCliConfigDeps {
   addClaudeUserPromptSubmitHook(): void;
   addCodexSessionStartHook(): void;
   addCodexUserPromptSubmitHook(): void;
+  installOpenCodePlugin(): void;
 }
 /**
  * Apply only the integration writes for the CLI the launcher resolved.
@@ -37,4 +38,5 @@ export function configureResolvedCli(
   }
 
   deps.ensureMcp('opencode');
+  deps.installOpenCodePlugin();
 }