borgmcp 1.1.14 → 2.0.1

package/src/debug.ts

@@ -0,0 +1,73 @@
+/**
+ * Opt-in debug logging for the borg CLI (Queen observability ask — surface
+ * exactly what failed on errors like the cross-account assimilate 404).
+ *
+ * Enabled by `--debug` on the command line OR a truthy `BORG_DEBUG` env var,
+ * wired at the CLI entry points (top-level `borg` dispatcher + `borg setup`
+ * + `borg assimilate`). When on, `authedFetch` (remote-client.ts) emits one
+ * line per HTTP request + the server error body on failure.
+ *
+ * Output goes to STDERR with a `[borg:debug]` prefix so it never contaminates
+ * STDOUT (the MCP / tool output stream a drone session proxies).
+ *
+ * HARD INVARIANT: debug output must NEVER contain token material — no
+ * Authorization header, id_token, or refresh_token. Call sites log only
+ * method / path / status / server-error-body; the Bearer token is omitted.
+ */
+
+let debugEnabled = false;
+
+/** Enable or disable debug logging for the lifetime of the process. */
+export function setDebug(on: boolean): void {
+  debugEnabled = on;
+}
+
+/** Whether debug logging is currently enabled. */
+export function isDebug(): boolean {
+  return debugEnabled;
+}
+
+/**
+ * Emit a debug line to STDERR with the `[borg:debug]` prefix. No-op when
+ * debug is disabled, so call sites need not guard. STDOUT is left clean for
+ * MCP / tool output.
+ */
+export function debugLog(...args: unknown[]): void {
+  if (!debugEnabled) return;
+  if (args.length > 0 && typeof args[0] === 'string') {
+    console.error(`[borg:debug] ${args[0]}`, ...args.slice(1));
+  } else {
+    console.error('[borg:debug]', ...args);
+  }
+}
+
+/**
+ * Resolve debug state from a process argv array + `BORG_DEBUG` at a CLI entry
+ * point. Enables debug when `--debug` is present OR `BORG_DEBUG` is truthy,
+ * then STRIPS every `--debug` token from the array IN PLACE so downstream
+ * subcommand parsers (which reject unknown flags) never see it. Idempotent —
+ * safe to call from more than one entry point in the same process.
+ */
+export function initDebugFromArgv(argv: string[]): void {
+  const hasFlag = argv.includes('--debug');
+  if (hasFlag || isTruthyEnv(process.env.BORG_DEBUG)) {
+    setDebug(true);
+  }
+  if (hasFlag) {
+    for (let i = argv.length - 1; i >= 0; i -= 1) {
+      if (argv[i] === '--debug') argv.splice(i, 1);
+    }
+  }
+}
+
+/** A non-empty env value other than the common falsy spellings is truthy. */
+function isTruthyEnv(value: string | undefined): boolean {
+  if (!value) return false;
+  const v = value.trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+
+/** Test hook: reset module-level debug state between tests. */
+export function _resetDebugForTests(): void {
+  debugEnabled = false;
+}

package/src/direct-log.ts

@@ -0,0 +1,9 @@
+export function normalizeDirectLogRecipients(value: unknown): string[] {
+  if (value == null) return [];
+  const raw = Array.isArray(value) ? value : [value];
+  const recipients = raw
+    .filter((item): item is string => typeof item === 'string')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+  return [...new Set(recipients)];
+}

package/src/docs-sections.ts

@@ -0,0 +1,129 @@
+/**
+ * The single source for the in-product docs index.
+ *
+ * `borg_docs` (index.ts) returns these sections so an agent can route a "how
+ * does borgmcp work / setup / concept / tool" question to the right
+ * repository-local document, then WebFetch the URL for the content. Pure data +
+ * a lazy keyword match — NO server-side fetch, NO RAG/embeddings.
+ *
+ * This is a local-only client: every URL points at the public source repository
+ * (its README + `docs/`), never a hosted product site.
+ *
+ * `page` is the repository-local file each section maps to (anti-drift anchor).
+ */
+
+export const DOCS_BASE_URL = "https://github.com/Byte-Ventures/borg-mcp-client";
+
+const README_URL = `${DOCS_BASE_URL}#readme`;
+const LOCAL_SERVER_URL = `${DOCS_BASE_URL}/blob/main/docs/LOCAL_SERVER.md`;
+
+export interface DocsSection {
+  /** logical topic key */
+  slug: string;
+  title: string;
+  /** repository-local document URL the agent should WebFetch */
+  url: string;
+  /** the repository file this section maps to (anti-drift anchor) */
+  page: string;
+  summary: string;
+  /** extra match terms for the topic lookup */
+  keywords: string[];
+}
+
+export const DOCS_SECTIONS: DocsSection[] = [
+  {
+    slug: "overview",
+    title: "Overview",
+    url: README_URL,
+    page: "README.md",
+    summary: "What Borg MCP is + the cube / drone / role / log mental model.",
+    keywords: ["overview", "what is", "intro", "mental model", "how it works", "start"],
+  },
+  {
+    slug: "concepts",
+    title: "Core concepts",
+    url: README_URL,
+    page: "README.md",
+    summary: "Cubes, drones, roles, the activity log + signals, claims, decisions.",
+    keywords: ["cube", "drone", "role", "log", "signal", "claim", "decision", "coordinate", "coordination"],
+  },
+  {
+    slug: "install",
+    title: "Install client",
+    url: README_URL,
+    page: "README.md",
+    summary: "Install the published Borg MCP client and verify the borg CLI.",
+    keywords: ["install", "installation", "npm", "client", "borgmcp", "borg help", "claude code", "codex", "opencode"],
+  },
+  {
+    slug: "run-server",
+    title: "Run server",
+    url: LOCAL_SERVER_URL,
+    page: "docs/LOCAL_SERVER.md",
+    summary: "Run a self-hosted borgmcp-server: setup, start, endpoint, network configuration.",
+    keywords: ["server", "self-hosted", "borgmcp-server", "borg-mcp-server", "setup", "start", "listen port", "7091", "local server", "--lan", "tls"],
+  },
+  {
+    slug: "enroll",
+    title: "Enroll",
+    url: LOCAL_SERVER_URL,
+    page: "docs/LOCAL_SERVER.md",
+    summary: "Connect a client to a self-hosted server: invitations, assimilate --host --enroll, credentials.",
+    keywords: ["enroll", "enrollment", "invitation", "invite", "assimilate", "--host", "credential", "credentials", "owner", "join server"],
+  },
+  {
+    slug: "self-hosting",
+    title: "Self-hosting operations",
+    url: LOCAL_SERVER_URL,
+    page: "docs/LOCAL_SERVER.md",
+    summary: "Operate a self-hosted server: data directory, credential rotation and grants, capacity, backup, upgrades.",
+    keywords: ["self-hosting", "operations", "operate", "backup", "restore", "upgrade", "rotate", "revoke", "grant", "capacity", "data directory", "license"],
+  },
+  {
+    slug: "cli",
+    title: "CLI commands",
+    url: README_URL,
+    page: "README.md",
+    summary: "Client launch, sync, cleanup, worktree maintenance, and launch-all reference.",
+    keywords: ["cli", "command", "sync", "cleanup", "worktree", "launch", "launch-all", "terminal", "maintenance", "prune"],
+  },
+  {
+    slug: "tools",
+    title: "Tool reference",
+    url: README_URL,
+    page: "README.md",
+    summary: "Every borg_* tool — name, description, params.",
+    keywords: ["tool", "tools", "api", "reference", "param", "borg_"],
+  },
+  {
+    slug: "faq",
+    title: "FAQ",
+    url: README_URL,
+    page: "README.md",
+    summary: "Common questions — agents, coordination, worktrees, docs maturity, security.",
+    keywords: ["faq", "question", "agent", "claude", "codex", "opencode", "coordination", "worktree", "security", "reporting", "second agent"],
+  },
+];
+
+/**
+ * Lazy topic match: a section matches when the topic shares a whitespace token
+ * with the section's slug / title / summary / keywords (case-insensitive,
+ * substring both ways so "price"↔"pricing"). Returns matches ranked by hit
+ * count; empty when nothing matches (the caller then shows the full index).
+ */
+export function matchDocsSections(topic: string): DocsSection[] {
+  const tokens = topic.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length >= 2);
+  if (tokens.length === 0) return [];
+  const scored = DOCS_SECTIONS.map((s) => {
+    const haystack = [s.slug, s.title, s.summary, ...s.keywords].join(" ").toLowerCase();
+    const hits = tokens.filter((t) => haystack.includes(t) || s.keywords.some((k) => t.includes(k))).length;
+    return { s, hits };
+  }).filter((x) => x.hits > 0);
+  scored.sort((a, b) => b.hits - a.hits);
+  return scored.map((x) => x.s);
+}
+
+/** Render sections as a plain-text index (title — summary — URL per line). */
+export function formatDocsIndex(sections: DocsSection[]): string {
+  return sections.map((s) => `- ${s.title} — ${s.summary}\n  ${s.url}`).join("\n");
+}

package/src/drone-lifecycle.ts

@@ -0,0 +1,62 @@
+/**
+ * gh#877: drone-lifecycle signals shared across the client wire layers
+ * (log-stream SSE + remote-client authedFetch + index tool funnel).
+ *
+ * Two distinct, NON-conflated outcomes when a drone's session stops resolving:
+ *
+ *  - DroneEvictedError (server 410 / code DRONE_EVICTED) — TERMINAL. The seat is
+ *    gone. The client emits one harness-neutral stop-session recovery path. This
+ *    is the SOLE authoritative
+ *    teardown trigger (SEC R2): an SSE eviction frame or inbox sentinel is only
+ *    a WAKE HINT — the agent confirms via an authed call returning this code.
+ */
+
+export const DRONE_EVICTED_CODE = 'DRONE_EVICTED';
+
+export class DroneEvictedError extends Error {
+  constructor(
+    message = 'This seat was removed from the cube.'
+  ) {
+    super(message);
+    this.name = 'DroneEvictedError';
+  }
+}
+
+/**
+ * Marker the agent's /loop + role playbook branch on. Single-sourced so the
+ * SSE wake sentinel (log-stream) and the tool-result funnel (index) agree.
+ */
+export const EVICTED_RESULT_MARKER = '[CUBE-EVICTED]';
+
+/**
+ * The recognizable tool RESULT the agent sees when an authed call returns the
+ * AUTHORITATIVE 410 DRONE_EVICTED. Spells out the sanctioned graceful-shutdown
+ * sequence so the agent acts on it deterministically.
+ */
+export function formatEvictedToolResult(cubeName?: string): string {
+  const cube = cubeName ?? 'the selected cube';
+  return (
+    `${EVICTED_RESULT_MARKER} This seat was removed from cube ${cube}.\n\n` +
+    'Borg has stopped listening for activity for this seat. Do not retry this request or restart the loop.\n\n' +
+    'Your worktree and project files are unchanged. Finish any local file safety checks, then end this agent session.\n\n' +
+    'To rejoin later, start a new session and use a new invitation from the server operator. Do not re-assimilate from this evicted session.'
+  );
+}
+
+/**
+ * Extract the structured error code from a worker error body. The worker error
+ * funnel (sanitizeError → createHttpError) emits `{ code, message }`; some
+ * legacy/nested shapes use `{ error: { code } }`. Returns null when absent or
+ * unparseable — callers must NOT treat a bare status (410) as authoritative
+ * without the matching code (SEC R2/R4: spoof + ambiguity resistance).
+ */
+export function errorCodeFromBody(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as any;
+    if (typeof parsed?.code === 'string') return parsed.code;
+    if (typeof parsed?.error?.code === 'string') return parsed.error.code;
+  } catch {
+    // not JSON
+  }
+  return null;
+}

package/src/drone-management.ts

@@ -0,0 +1,162 @@
+import type { EvictDroneResult, ReassignDroneResult } from 'borgmcp-shared/protocol';
+import {
+  activeCubeWithFreshRegenIdentity,
+  getActiveCube,
+  refreshActiveCubeMetadata,
+  type ActiveCube,
+} from './cubes.js';
+import {
+  assertUuidShape,
+  formatEvictDroneSuccess,
+  formatReassignDroneSuccess,
+  resolveDroneIdByLabel,
+} from './evict-drone.js';
+import {
+  evictDrone,
+  getCubeForManagement,
+  reassignDrone,
+  type LocalManageOperation,
+} from './remote-client.js';
+
+interface ManagedCube {
+  id: string;
+  name: string;
+  roles: any[];
+  drones: any[];
+}
+
+export interface DroneManagementDeps {
+  getActiveCube: () => Promise<ActiveCube | null>;
+  getCubeForManagement: (
+    cubeId: string,
+    operation: LocalManageOperation,
+    active: ActiveCube,
+  ) => Promise<ManagedCube>;
+  reassignDrone: (droneId: string, roleId: string, active: ActiveCube) => Promise<ReassignDroneResult>;
+  evictDrone: (
+    droneId: string,
+    options: { cubeId: string; cubeName: string; targetReference: string; active: ActiveCube },
+  ) => Promise<EvictDroneResult>;
+  refreshActiveCubeMetadata: (active: ActiveCube) => Promise<boolean>;
+}
+
+const defaultDeps: DroneManagementDeps = {
+  getActiveCube,
+  getCubeForManagement,
+  reassignDrone,
+  evictDrone,
+  refreshActiveCubeMetadata,
+};
+
+export const STALE_ROLE_DISPLAY_WARNING =
+  'Local display warning: The server committed this change, but Borg could not refresh this worktree\'s saved seat metadata. Local role details may be stale. Do not retry the reassignment.\n\n' +
+  'Run `borg_regen` to refresh the server-authoritative role. If this session still shows the previous role, restart this agent session once. Do not re-assimilate or repeat the management request.';
+
+function opaqueNotFound(): never {
+  throw new Error('Borg server request failed (HTTP 404)');
+}
+
+async function requireActiveCube(deps: DroneManagementDeps): Promise<ActiveCube> {
+  const active = await deps.getActiveCube();
+  if (!active) throw new Error('Not assimilated to a cube. Use borg_assimilate <cube-name> first.');
+  return active;
+}
+
+export async function runReassignDroneTool(
+  input: { droneId: unknown; roleId: unknown },
+  deps: DroneManagementDeps = defaultDeps,
+): Promise<string> {
+  if (typeof input.droneId !== 'string' || input.droneId.length === 0) {
+    throw new Error('drone_id is required');
+  }
+  if (typeof input.roleId !== 'string' || input.roleId.length === 0) {
+    throw new Error('role_id is required');
+  }
+  assertUuidShape(input.droneId, 'drone_id');
+  assertUuidShape(input.roleId, 'role_id');
+
+  const active = await requireActiveCube(deps);
+  const operation = {
+    operation: `reassign drone ${JSON.stringify(input.droneId)} to role ${JSON.stringify(input.roleId)} in cube ${JSON.stringify(active.name)}`,
+    cubeName: active.name,
+    noMutation: 'No drone was reassigned.',
+  };
+  const cube = await deps.getCubeForManagement(active.cubeId, operation, active);
+  const priorDrone = cube.drones.find((candidate) => candidate.id === input.droneId);
+  const role = cube.roles.find((candidate) => candidate.id === input.roleId);
+  if (!priorDrone || !role) opaqueNotFound();
+
+  const { drone } = await deps.reassignDrone(input.droneId, input.roleId, active);
+  if (drone.id !== input.droneId || drone.cube_id !== cube.id || drone.role_id !== input.roleId) {
+    throw new Error(
+      '[LOCAL-MANAGE-COMMIT-UNCONFIRMED] The server returned a successful reassignment response for unexpected identifiers. The reassignment may already be committed. Do not retry blindly; inspect the cube roster first.',
+    );
+  }
+
+  let warning = '';
+  if (drone.id === active.droneId) {
+    try {
+      const refreshed = await deps.refreshActiveCubeMetadata(activeCubeWithFreshRegenIdentity(active, {
+        cube,
+        drone,
+        role,
+      }));
+      if (!refreshed) warning = `\n\n${STALE_ROLE_DISPLAY_WARNING}`;
+    } catch {
+      warning = `\n\n${STALE_ROLE_DISPLAY_WARNING}`;
+    }
+  }
+
+  return formatReassignDroneSuccess({
+    droneLabel: drone.label,
+    cubeName: cube.name,
+    roleName: role.name,
+    droneId: drone.id,
+    roleId: drone.role_id,
+  }) + warning;
+}
+
+export async function runEvictDroneTool(
+  args: Record<string, unknown> | undefined,
+  deps: DroneManagementDeps = defaultDeps,
+): Promise<string> {
+  const droneIdInput = typeof args?.drone_id === 'string' ? args.drone_id : undefined;
+  const labelInput = typeof args?.label === 'string' ? args.label.trim() : undefined;
+  const cubeIdInput = typeof args?.cube_id === 'string' ? args.cube_id : undefined;
+  if (droneIdInput !== undefined && (labelInput !== undefined || cubeIdInput !== undefined)) {
+    throw new Error('Provide drone_id OR label with cube_id, not both.');
+  }
+  if (droneIdInput === undefined && (!labelInput || !cubeIdInput)) {
+    throw new Error('Provide drone_id OR both label and cube_id.');
+  }
+  if (droneIdInput !== undefined) assertUuidShape(droneIdInput, 'drone_id');
+  if (cubeIdInput !== undefined) assertUuidShape(cubeIdInput, 'cube_id');
+
+  const active = await requireActiveCube(deps);
+  const cubeId = droneIdInput === undefined ? cubeIdInput! : active.cubeId;
+  const targetReference = labelInput ?? droneIdInput!;
+  const fallbackCubeName = cubeId === active.cubeId ? active.name : cubeId;
+  const operation = {
+    operation: `remove ${JSON.stringify(targetReference)} from cube ${JSON.stringify(fallbackCubeName)}`,
+    cubeName: fallbackCubeName,
+    noMutation: 'No drone was removed.',
+  };
+  const cube = await deps.getCubeForManagement(cubeId, operation, active);
+  const priorDrone = labelInput === undefined
+    ? cube.drones.find((candidate) => candidate.id === droneIdInput)
+    : resolveDroneIdByLabel(cube.drones, labelInput);
+  if (!priorDrone) opaqueNotFound();
+
+  const result = await deps.evictDrone(priorDrone.id, {
+    cubeId,
+    cubeName: cube.name,
+    targetReference,
+    active,
+  });
+  if (result.drone_id !== priorDrone.id || result.evicted !== true) {
+    throw new Error(
+      '[LOCAL-MANAGE-COMMIT-UNCONFIRMED] The server returned a successful eviction response for an unexpected drone. The eviction may already be committed. Do not retry blindly; inspect the cube roster first.',
+    );
+  }
+  return formatEvictDroneSuccess(priorDrone.label, cube.name);
+}

package/src/ensure-mcp-config.ts

@@ -0,0 +1,54 @@
+import type { BorgCli } from './cubes.js';
+import {
+  addCodexMcpServer,
+  addMcpServer,
+  addOpenCodeMcpServer,
+  isCodexMcpServerConfigured,
+  isMcpServerConfigured,
+  isOpenCodeMcpServerConfigured,
+} from './config-utils.js';
+
+export interface EnsureMcpConfigDeps {
+  isClaudeConfigured: () => boolean;
+  addClaude: () => void;
+  isCodexConfigured: () => boolean;
+  addCodex: () => void;
+  isOpenCodeConfigured: () => boolean;
+  addOpenCode: () => void;
+}
+
+const defaultDeps: EnsureMcpConfigDeps = {
+  isClaudeConfigured: isMcpServerConfigured,
+  addClaude: addMcpServer,
+  isCodexConfigured: isCodexMcpServerConfigured,
+  addCodex: addCodexMcpServer,
+  isOpenCodeConfigured: isOpenCodeMcpServerConfigured,
+  addOpenCode: addOpenCodeMcpServer,
+};
+
+/**
+ * Ensure borg is registered as an MCP server for one selected agent CLI.
+ *
+ * Returns true when this call added the registration and false when it was
+ * already present. Errors from an adder intentionally propagate so callers
+ * can fail the launch with the CLI-specific remediation message.
+ */
+export function ensureCliMcpConfigured(
+  cli: BorgCli,
+  deps: EnsureMcpConfigDeps = defaultDeps,
+): boolean {
+  switch (cli) {
+    case 'claude':
+      if (deps.isClaudeConfigured()) return false;
+      deps.addClaude();
+      return true;
+    case 'codex':
+      if (deps.isCodexConfigured()) return false;
+      deps.addCodex();
+      return true;
+    case 'opencode':
+      if (deps.isOpenCodeConfigured()) return false;
+      deps.addOpenCode();
+      return true;
+  }
+}

package/src/evict-drone.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure label→id resolution for the `borg_evict-drone` tool (gh#718).
+ *
+ * the local drone-management route
+ * both take a drone UUID. Coordinators, however, see drone LABELS everywhere
+ * (roster, regen, cube log) and rarely the UUIDs. This helper lets the tool
+ * accept a label and resolve it to the drone id client-side, against the
+ * cube-grant-scoped detail returned by `getCube` (the same id+label pairs
+ * `borg_list-drones` renders). No I/O here — a pure function so it can be
+ * unit-tested in isolation; the handler in index.ts owns the network calls.
+ */
+
+export interface EvictableDrone {
+  id: string;
+  label: string;
+}
+
+/**
+ * Strict whole-string UUID shape check for the `drone_id` input (gh#782).
+ * The handler rejects non-UUID values before building the DELETE URL: a
+ * label passed as drone_id gets a clear "use label + cube_id" hint instead
+ * of a confusing 404, and a path-shaped value ("../cubes/<uuid>") is never
+ * interpolated into a request path. Case-insensitive; anchored so embedded
+ * or suffixed UUIDs do not pass.
+ */
+export function isUuidShape(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+
+/**
+ * Assert-style wrapper around isUuidShape (gh#782, reassign half). Called
+ * by the remote-client functions that interpolate a drone id into the
+ * request path (reassignDrone PATCH, evictDrone DELETE) — FIRST, before
+ * any token fetch or network I/O, so a path-shaped value like
+ * "../cubes/<uuid>" can never reach URL construction. The `label` names
+ * the offending input in the caller-facing error.
+ */
+export function assertUuidShape(value: string, label: string): void {
+  if (!isUuidShape(value)) {
+    throw new Error(`${label} "${value}" is not a UUID`);
+  }
+}
+
+/**
+ * Resolve an exact drone label to its `{ id, label }` within a single cube's
+ * drone list. Labels are unique per cube, so an exact match is unambiguous.
+ * Returns null when no drone carries the label (the handler turns that into a
+ * caller-facing error). Matching is exact (not substring) and label-only — a
+ * UUID passed here never resolves, because the handler routes UUIDs through the
+ * explicit `drone_id` input instead.
+ */
+export function resolveDroneIdByLabel(
+  drones: ReadonlyArray<EvictableDrone>,
+  label: string
+): EvictableDrone | null {
+  const target = label.trim();
+  const match = drones.find((d) => d.label === target);
+  return match ? { id: match.id, label: match.label } : null;
+}
+
+export function formatReassignDroneSuccess(input: {
+  droneLabel: string;
+  cubeName: string;
+  roleName: string;
+  droneId: string;
+  roleId: string;
+}): string {
+  return (
+    `Reassigned ${input.droneLabel} in cube ${input.cubeName} to role ${input.roleName}.\n` +
+    `Drone id: ${input.droneId}\n` +
+    `Role id: ${input.roleId}`
+  );
+}
+
+export function formatEvictDroneSuccess(droneLabel: string, cubeName: string): string {
+  return (
+    `Removed ${droneLabel} from cube ${cubeName}.\n` +
+    'The seat credential is revoked. The session will stop after its next Borg request.\n' +
+    'The worktree and project files were not deleted. Activity history remains attributed to the removed seat.\n' +
+    'After its work is merged, run `borg cleanup` to review whether the worktree can be pruned.'
+  );
+}