borgmcp 1.1.14 → 2.0.1

package/src/model-presets.ts

@@ -0,0 +1,22 @@
+/**
+ * Temporary compatibility helpers for the legacy Borg-managed Claude model
+ * selector. Model/provider configuration belongs to the launched agent CLI;
+ * the remaining selector is retired with the assimilation model wire cleanup.
+ */
+
+export const MODEL_DESCRIPTOR_REGEX = /^claude:[A-Za-z0-9._:\/-]+$/;
+
+export function parseModel(descriptor: string): { kind: 'claude'; model: string } {
+  if (!MODEL_DESCRIPTOR_REGEX.test(descriptor)) {
+    throw new Error(`invalid model descriptor: ${descriptor} (expected claude:<model>)`);
+  }
+  return { kind: 'claude', model: descriptor.slice('claude:'.length) };
+}
+
+export function resolveLaunchEnv(
+  descriptor: string | null
+): { set: Record<string, string>; unset: string[] } {
+  if (!descriptor) return { set: {}, unset: [] };
+  const { model } = parseModel(descriptor);
+  return { set: { ANTHROPIC_MODEL: model }, unset: [] };
+}

package/src/name-validator.ts

@@ -0,0 +1,23 @@
+/**
+ * Validates an identifier used in worktree paths and other safety-critical
+ * positions (must survive shell-arg parsing without escaping).
+ *
+ * Allowed: lowercase ASCII letters, digits, hyphens, underscores.
+ * Length 1–48. Anchored. No leading hyphen (would parse as a flag).
+ */
+const NAME_RE = /^[a-z0-9_][a-z0-9_-]{0,47}$/;
+
+export function validateName(name: string): { ok: true } | { ok: false; error: string } {
+  if (name.length === 0) {
+    return { ok: false, error: `name must not be empty` };
+  }
+  if (!NAME_RE.test(name)) {
+    return {
+      ok: false,
+      error:
+        `invalid name "${name}". Use lowercase letters, digits, hyphens, or ` +
+        `underscores; max 48 chars; must not start with a hyphen.`,
+    };
+  }
+  return { ok: true };
+}

package/src/opencode-drone.ts

@@ -0,0 +1,528 @@
+import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { createHash, randomUUID } from 'crypto';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+const LOG_FILE = join(tmpdir(), 'borg-opencode-drone.log');
+function log(msg: string) {
+  const line = `[${new Date().toISOString()}] ${msg}\n`;
+  try { appendFileSync(LOG_FILE, line); } catch {}
+}
+
+interface OpenCodeDroneState {
+  serverUrl: string;
+  sessionId: string | null;
+  sessionCreatedAt: number | null;
+  knownRootSessionIds: string[];
+  directory: string;
+  droneLabel: string;
+  cubeName: string;
+  connected: boolean;
+  totalEntriesInjected: number;
+}
+
+let state: OpenCodeDroneState | null = null;
+
+interface ConnectDeps {
+  serverUrl: string;
+  directory: string;
+  droneLabel: string;
+  cubeName: string;
+}
+
+interface OCSession {
+  id: string;
+  directory: string;
+  time: { created: number };
+  parentID?: string;
+  agent?: string;
+  model?: { providerID: string; modelID: string };
+}
+
+interface OCMessage {
+  info?: {
+    role?: string;
+    time?: { created?: number };
+  };
+  parts?: Array<{
+    type?: string;
+    text?: string;
+  }>;
+}
+
+interface SessionBinding {
+  version: 2;
+  sessionId: string;
+  sessionCreatedAt: number;
+  knownRootSessionIds: string[];
+  serverUrl: string;
+  directory: string;
+  droneLabel: string;
+  cubeName: string;
+}
+
+export interface OpenCodeLaunchKickoff {
+  prompt: string;
+  nonce: string;
+}
+
+// This is correlation metadata, intentionally not an instruction to the
+// launched agent. A markdown comment keeps it benign in the user-visible
+// kickoff while preserving it in OpenCode's stored message text.
+const OPEN_CODE_LAUNCH_NONCE_MARKER = 'borg-opencode-correlation:';
+
+/**
+ * Add a launch-unique identity to the OpenCode-only copy of the shared
+ * kickoff. The prompt is what OpenCode records as its first user message, so
+ * the launcher can later bind the MCP child to this precise launch instead of
+ * guessing from a repeated kickoff's text or timestamp.
+ */
+export function createOpenCodeLaunchKickoff(
+  kickoff: string,
+  nonce: string = randomUUID(),
+): OpenCodeLaunchKickoff {
+  return {
+    prompt: `${kickoff}\n\n<!-- ${OPEN_CODE_LAUNCH_NONCE_MARKER}${nonce} -->`,
+    nonce,
+  };
+}
+
+const bindingPathsForTests = new Set<string>();
+
+export async function connectOpenCodeDrone(deps: ConnectDeps): Promise<void> {
+  state = {
+    serverUrl: deps.serverUrl,
+    sessionId: null,
+    sessionCreatedAt: null,
+    knownRootSessionIds: [],
+    directory: deps.directory,
+    droneLabel: deps.droneLabel,
+    cubeName: deps.cubeName,
+    connected: true,
+    totalEntriesInjected: 0,
+  };
+  log(`connected url=${deps.serverUrl} dir=${deps.directory}`);
+}
+
+// ---------------------------------------------------------------------------
+// Raw fetch wrappers
+// ---------------------------------------------------------------------------
+
+function apiUrl(path: string): string {
+  const base = state!.serverUrl.replace(/\/+$/, '');
+  return `${base}${path}${path.includes('?') ? '&' : '?'}directory=${encodeURIComponent(state!.directory)}`;
+}
+
+const FETCH_TIMEOUT = 10_000;
+
+async function rawGet(path: string): Promise<{ status: number; body: string }> {
+  const url = apiUrl(path);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    const body = await res.text();
+    return { status: res.status, body };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function rawPost(path: string, bodyObj: unknown): Promise<{ status: number; body: string }> {
+  const url = apiUrl(path);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      signal: controller.signal,
+      body: JSON.stringify(bodyObj),
+    });
+    const body = await res.text();
+    return { status: res.status, body };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function listSessions(): Promise<OCSession[]> {
+  const { status, body } = await rawGet('/session');
+  if (status !== 200) throw new Error(`OpenCode sessions request failed (${status})`);
+  return JSON.parse(body);
+}
+
+async function getSession(id: string): Promise<OCSession | null> {
+  try {
+    const { status, body } = await rawGet(`/session/${id}`);
+    if (status !== 200) return null;
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+async function listSessionMessages(id: string): Promise<OCMessage[]> {
+  const { status, body } = await rawGet(`/session/${id}/message`);
+  if (status !== 200) throw new Error(`OpenCode session messages request failed (${status})`);
+  return JSON.parse(body);
+}
+
+async function promptSession(id: string, bodyObj: Record<string, unknown>): Promise<boolean> {
+  const { status } = await rawPost(`/session/${id}/prompt_async`, bodyObj);
+  return status === 200 || status === 204;
+}
+
+// ---------------------------------------------------------------------------
+// Persist the launch-selected session for the separately spawned MCP child.
+// ---------------------------------------------------------------------------
+
+function bindingPath(): string {
+  const current = state!;
+  const key = [current.serverUrl, current.directory, current.cubeName, current.droneLabel].join('\0');
+  const digest = createHash('sha256').update(key).digest('hex').slice(0, 24);
+  const path = join(tmpdir(), `borg-opencode-session-${digest}.json`);
+  bindingPathsForTests.add(path);
+  return path;
+}
+
+function bindingMatchesState(binding: SessionBinding): boolean {
+  const current = state!;
+  return binding.version === 2
+    && binding.serverUrl === current.serverUrl
+    && binding.directory === current.directory
+    && binding.droneLabel === current.droneLabel
+    && binding.cubeName === current.cubeName
+    && typeof binding.sessionId === 'string'
+    && typeof binding.sessionCreatedAt === 'number'
+    && Array.isArray(binding.knownRootSessionIds)
+    && binding.knownRootSessionIds.every((id) => typeof id === 'string');
+}
+
+function readBinding(): SessionBinding | null {
+  try {
+    const path = bindingPath();
+    if (!existsSync(path)) return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as SessionBinding;
+    return bindingMatchesState(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function clearBinding(): void {
+  if (!state) return;
+  const path = bindingPath();
+  state.sessionId = null;
+  state.sessionCreatedAt = null;
+  state.knownRootSessionIds = [];
+  try {
+    unlinkSync(path);
+  } catch {
+    // The file may have already been removed by the launch process.
+  }
+}
+
+function saveBinding(session: OCSession, knownRootSessionIds: string[]): void {
+  const current = state!;
+  const binding: SessionBinding = {
+    version: 2,
+    sessionId: session.id,
+    sessionCreatedAt: session.time.created,
+    knownRootSessionIds,
+    serverUrl: current.serverUrl,
+    directory: current.directory,
+    droneLabel: current.droneLabel,
+    cubeName: current.cubeName,
+  };
+  current.sessionId = binding.sessionId;
+  current.sessionCreatedAt = binding.sessionCreatedAt;
+  current.knownRootSessionIds = binding.knownRootSessionIds;
+
+  try {
+    const path = bindingPath();
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(binding), { mode: 0o600 });
+    renameSync(temporary, path);
+  } catch (err) {
+    log(`session binding write failed: ${err}`);
+  }
+}
+
+function restoreBinding(): SessionBinding | null {
+  if (!state) return null;
+  if (state.sessionId && state.sessionCreatedAt !== null) {
+    return {
+      version: 2,
+      sessionId: state.sessionId,
+      sessionCreatedAt: state.sessionCreatedAt,
+      knownRootSessionIds: state.knownRootSessionIds,
+      serverUrl: state.serverUrl,
+      directory: state.directory,
+      droneLabel: state.droneLabel,
+      cubeName: state.cubeName,
+    };
+  }
+
+  const binding = readBinding();
+  if (!binding) return null;
+  state.sessionId = binding.sessionId;
+  state.sessionCreatedAt = binding.sessionCreatedAt;
+  state.knownRootSessionIds = binding.knownRootSessionIds;
+  return binding;
+}
+
+function isBoundSession(session: OCSession, binding: SessionBinding): boolean {
+  return session.id === binding.sessionId && session.directory === state!.directory;
+}
+
+function isTopLevelSession(session: OCSession): boolean {
+  return !session.parentID;
+}
+
+async function findUnseenTopLevelSession(knownRootSessionIds: string[]): Promise<{
+  session: OCSession;
+  knownRootSessionIds: string[];
+} | null> {
+  try {
+    const sessions = await listSessions();
+    const roots = sessions.filter(
+      (session) => session.directory === state!.directory
+        && isTopLevelSession(session),
+    );
+    const matched = roots.filter((session) => !knownRootSessionIds.includes(session.id));
+    if (matched.length === 0) return null;
+    const best = matched.reduce((a, b) =>
+      a.time.created > b.time.created ? a : b,
+    );
+    return { session: best, knownRootSessionIds: roots.map((session) => session.id) };
+  } catch {
+    return null;
+  }
+}
+
+function kickoffMessageTime(messages: OCMessage[], nonce: string): number | null {
+  let latest: number | null = null;
+  for (const message of messages) {
+    if (message.info?.role && message.info.role !== 'user') continue;
+    const matchesLaunchNonce = message.parts?.some(
+      (part) => part.type === 'text' && part.text?.includes(`${OPEN_CODE_LAUNCH_NONCE_MARKER}${nonce}`),
+    );
+    if (!matchesLaunchNonce) continue;
+    const created = message.info?.time?.created ?? 0;
+    latest = latest === null ? created : Math.max(latest, created);
+  }
+  return latest;
+}
+
+/**
+ * The launch process is the only place allowed to discover a session from the
+ * server. It chooses the session that contains this launch's unique nonce,
+ * rather than choosing by repeated kickoff text or session creation time. A
+ * fork is therefore allowed only when it was explicitly selected for this
+ * launch and received the nonce-bearing kickoff.
+ */
+async function findLaunchSession(nonce: string): Promise<{
+  session: OCSession;
+  knownRootSessionIds: string[];
+} | null> {
+  try {
+    const sessions = (await listSessions()).filter(
+      (session) => session.directory === state!.directory,
+    );
+    const knownRootSessionIds = sessions
+      .filter(isTopLevelSession)
+      .map((session) => session.id);
+    const candidates = await Promise.all(sessions.map(async (session) => {
+      try {
+        const messageTime = kickoffMessageTime(
+          await listSessionMessages(session.id),
+          nonce,
+        );
+        return messageTime === null ? null : { session, messageTime };
+      } catch {
+        return null;
+      }
+    }));
+    const matched = candidates.filter(
+      (candidate): candidate is { session: OCSession; messageTime: number } => candidate !== null,
+    );
+    if (matched.length === 0) return null;
+    const session = matched.reduce((best, candidate) =>
+      candidate.messageTime > best.messageTime ? candidate : best,
+    ).session;
+    return { session, knownRootSessionIds };
+  } catch {
+    return null;
+  }
+}
+
+async function resolveInjectionSession(): Promise<OCSession | null> {
+  const binding = restoreBinding();
+  if (!binding) return null;
+
+  const bound = await getSession(binding.sessionId);
+  if (!bound || !isBoundSession(bound, binding)) {
+    clearBinding();
+    const replacement = await findUnseenTopLevelSession(binding.knownRootSessionIds);
+    if (!replacement) return null;
+    saveBinding(replacement.session, replacement.knownRootSessionIds);
+    return replacement.session;
+  }
+
+  // `/new` creates an unseen top-level session. Keep the launch-time root
+  // snapshot so an old, unrelated root is never mistaken for a user switch.
+  // Children never supersede the bound root.
+  const switched = await findUnseenTopLevelSession(binding.knownRootSessionIds);
+  if (switched) {
+    saveBinding(switched.session, switched.knownRootSessionIds);
+    return switched.session;
+  }
+  return bound;
+}
+
+async function rebindAfterFailure(knownRootSessionIds: string[]): Promise<OCSession | null> {
+  const replacement = await findUnseenTopLevelSession(knownRootSessionIds);
+  if (!replacement) return null;
+  saveBinding(replacement.session, replacement.knownRootSessionIds);
+  return replacement.session;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait for the OpenCode HTTP server, then capture the session that received
+ * this launch's nonce-bearing `--prompt` kickoff. The binding survives the separate
+ * MCP-child process, which must never fall back to a newest-session heuristic.
+ */
+export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promise<boolean> {
+  if (!state?.connected) { log('kickoff: not connected'); return false; }
+
+  try {
+    // Wait for the server.
+    for (let i = 0; i < 30; i++) {
+      try {
+        await listSessions();
+        log(`kickoff: server ready (attempt ${i + 1})`);
+        break;
+      } catch {
+        // not ready yet
+      }
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+
+    // Capture the launch-selected session, including explicit resume/fork
+    // targets. Unrelated sessions do not contain this launch's nonce.
+    for (let i = 0; i < 30; i++) {
+      const binding = await findLaunchSession(launch.nonce);
+      if (binding) {
+        saveBinding(binding.session, binding.knownRootSessionIds);
+        log(`kickoff: bound session ${binding.session.id.slice(0, 8)}…`);
+        return true;
+      }
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+
+    log('kickoff: no session found');
+    return false;
+  } catch (err) {
+    log(`kickoff error: ${err}`);
+    return false;
+  }
+}
+
+/**
+ * Inject a silent context entry (noReply) into our session.
+ * Falls through silently — caller falls back to inbox write.
+ */
+export async function injectOpenCodeEntry(text: string): Promise<boolean> {
+  if (!state?.connected) return false;
+
+  try {
+    const target = await resolveInjectionSession();
+    if (!target) return false;
+
+    const body = {
+      parts: [{ type: 'text', text }],
+    };
+    if (await promptSession(target.id, body)) {
+      state.totalEntriesInjected++;
+      return true;
+    }
+
+    // A failed prompt means the cached target is no longer trustworthy. Clear
+    // it before considering only a newer root created by `/new`; never fall
+    // through to a child or arbitrary newest session.
+    const knownRootSessionIds = [...state.knownRootSessionIds];
+    clearBinding();
+    const replacement = await rebindAfterFailure(knownRootSessionIds);
+    if (!replacement) return false;
+    if (await promptSession(replacement.id, body)) {
+      state.totalEntriesInjected++;
+      return true;
+    }
+    clearBinding();
+    return false;
+  } catch (err) {
+    log(`entry error: ${err}`);
+    clearBinding();
+    return false;
+  }
+}
+
+export async function probeOpenCodeDroneArmed(): Promise<boolean | null> {
+  if (!state?.connected) return null;
+  const binding = restoreBinding();
+  if (!binding) return false;
+
+  try {
+    const session = await getSession(binding.sessionId);
+    if (session && isBoundSession(session, binding)) return true;
+    clearBinding();
+    return false;
+  } catch {
+    clearBinding();
+    return false;
+  }
+}
+
+export function disconnectOpenCodeDrone(): void {
+  state = null;
+}
+
+export function getOpenCodeConnectionState(): {
+  connected: boolean;
+  sessionId: string | null;
+  totalEntriesInjected: number;
+} {
+  return {
+    connected: state?.connected ?? false,
+    sessionId: state?.sessionId ?? null,
+    totalEntriesInjected: state?.totalEntriesInjected ?? 0,
+  };
+}
+
+export function computeOpenCodePort(droneId: string, base: number = 14096): number {
+  let hash = 0;
+  for (let i = 0; i < droneId.length; i++) {
+    const char = droneId.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash |= 0;
+  }
+  return base + (Math.abs(hash) % 1024);
+}
+
+/** Test-only cleanup for module state and the local cross-process binding. */
+export function __resetOpenCodeDroneForTests(): void {
+  state = null;
+  for (const path of bindingPathsForTests) {
+    try {
+      unlinkSync(path);
+    } catch {
+      // Already removed.
+    }
+  }
+  bindingPathsForTests.clear();
+}

package/src/opencode-plugin.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * 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.'
+      );
+    },
+  };
+}
+`;
+
+const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
+
+export function installBorgPlugin(): void {
+  const pluginPath = path.join(os.homedir(), PLUGIN_REL_PATH);
+  try {
+    if (fs.existsSync(pluginPath)) {
+      const existing = fs.readFileSync(pluginPath, 'utf-8');
+      if (existing === BORG_PLUGIN_SOURCE) return;
+    }
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+    fs.writeFileSync(pluginPath, BORG_PLUGIN_SOURCE, 'utf-8');
+  } catch {
+    // Best-effort — plugin is an optimization, not a requirement.
+  }
+}