borgmcp 2.12.1 → 2.13.0

package/src/index.ts

@@ -41,6 +41,7 @@ import {
   createRole,
   updateRole,
   patchRoleSection,
+  sanitizeServerAdvisory,
   patchTaxonomyClass,
   deleteRole,
   getCube,
@@ -132,7 +133,9 @@ import { resolveReportableSessionAgentKind } from './agent-runtime.js';
 import {
   connectOpenCodeDrone,
   injectOpenCodeEntry,
-  computeOpenCodePort,
+  configuredOpenCodePort,
+  OPEN_CODE_PORT_MISSING_DIAGNOSTIC,
+  openCodeLaunchBinding,
 } from './opencode-drone.js';
 import { installBorgPlugin } from './opencode-plugin.js';
 import { setModuleInjectOpenCode } from './log-stream.js';
@@ -216,6 +219,57 @@ async function requireActiveCube() {
   return active;
 }
 
+export function appendServerAdvisory(text: string, advisory: unknown): string {
+  const sanitized = sanitizeServerAdvisory(advisory);
+  return sanitized === undefined ? text : `${text}\n\nAdvisory: ${sanitized}`;
+}
+
+export function formatUpdatedCubeResult(cube: { name: string; id: string }, advisory?: unknown): string {
+  return appendServerAdvisory(`Updated cube **${cube.name}** (id: ${cube.id}).`, advisory);
+}
+
+export function formatUpdatedRoleResult(role: { name: string; id: string; role_class?: string; is_human_seat?: boolean; is_default?: boolean; is_mandatory?: boolean }, advisory?: unknown): string {
+  const tags = [
+    role.role_class === 'queen' ? 'Queen' : null,
+    role.is_human_seat ? 'human-seat' : null,
+    role.is_default ? 'default' : null,
+    role.is_mandatory ? 'mandatory' : null,
+  ].filter(Boolean).join(', ');
+  const tag = tags ? ` (${tags})` : '';
+  return appendServerAdvisory(`Updated role **${role.name}**${tag} (id: ${role.id}).`, advisory);
+}
+
+export function formatPatchedRoleSectionResult(action: 'replace' | 'insert' | 'delete', heading: string, role: { name: string; id: string }, advisory?: unknown): string {
+  const verb = action === 'replace' ? 'Replaced' : action === 'insert' ? 'Inserted' : 'Deleted';
+  return appendServerAdvisory(`${verb} section **${heading}** in role **${role.name}** (id: ${role.id}).`, advisory);
+}
+
+export async function connectOpenCodeRuntime(
+  active: {
+    worktree?: string;
+    droneLabel: string;
+    name: string;
+  },
+  env: NodeJS.ProcessEnv = process.env,
+  deps: {
+    connect?: typeof connectOpenCodeDrone;
+  } = {},
+): Promise<boolean> {
+  const configuredPort = configuredOpenCodePort(env);
+  if (configuredPort === null) {
+    console.error(OPEN_CODE_PORT_MISSING_DIAGNOSTIC);
+    return false;
+  }
+  const binding = openCodeLaunchBinding(configuredPort);
+  await (deps.connect ?? connectOpenCodeDrone)({
+    serverUrl: binding.serverUrl,
+    directory: active.worktree ?? findProjectRoot(),
+    droneLabel: active.droneLabel,
+    cubeName: active.name,
+  });
+  return true;
+}
+
 /**
  * Main entry point - MCP stdio server
  */
@@ -266,15 +320,7 @@ export async function main() {
       installBorgPlugin();
       const active = await getActiveCube();
       if (active && openCodeRuntime) {
-        const port = computeOpenCodePort(active.droneId);
-        const serverUrl = `http://127.0.0.1:${port}`;
-        await connectOpenCodeDrone({
-          serverUrl,
-          directory: active.worktree ?? findProjectRoot(),
-          droneLabel: active.droneLabel,
-          cubeName: active.name,
-        });
-        setModuleInjectOpenCode(injectOpenCodeEntry);
+        if (await connectOpenCodeRuntime(active)) setModuleInjectOpenCode(injectOpenCodeEntry);
       }
     },
   };
@@ -1018,8 +1064,8 @@ export async function main() {
           if (typeof args?.cube_directive === 'string') updates.cube_directive = args.cube_directive as string;
           if (Array.isArray(args?.message_taxonomy)) updates.message_taxonomy = args.message_taxonomy as MessageTaxonomy;
           if (Object.keys(updates).length === 0) throw new Error('Pass at least one of: cube_directive, message_taxonomy.');
-          const { cube } = await updateCube(cubeId, updates);
-          return { content: [{ type: 'text', text: `Updated cube **${cube.name}** (id: ${cube.id}).` }] };
+          const { cube, advisory } = await updateCube(cubeId, updates);
+          return { content: [{ type: 'text', text: formatUpdatedCubeResult(cube, advisory) }] };
         }
 
         case 'borg_patch-taxonomy-class': {
@@ -1108,15 +1154,8 @@ export async function main() {
           if (typeof args?.receives_all_direct === 'boolean') updates.receives_all_direct = args.receives_all_direct as boolean;
           if (typeof args?.default_model === 'string') updates.default_model = args.default_model as string;
           if (Object.keys(updates).length === 0) throw new Error('Pass at least one of: name, short_description, detailed_description, is_default, is_mandatory, is_human_seat, can_broadcast, receives_all_direct.');
-          const { role } = await updateRole(roleId, updates);
-          const tags = [
-            role.role_class === 'queen' ? 'Queen' : null,
-            role.is_human_seat ? 'human-seat' : null,
-            role.is_default ? 'default' : null,
-            role.is_mandatory ? 'mandatory' : null,
-          ].filter(Boolean).join(', ');
-          const tag = tags ? ` (${tags})` : '';
-          return { content: [{ type: 'text', text: `Updated role **${role.name}**${tag} (id: ${role.id}).` }] };
+          const { role, advisory } = await updateRole(roleId, updates);
+          return { content: [{ type: 'text', text: formatUpdatedRoleResult(role, advisory) }] };
         }
 
         case 'borg_patch-role-section': {
@@ -1129,8 +1168,9 @@ export async function main() {
           const heading = args?.heading as string;
           if (!heading) throw new Error('heading is required');
           let role: any;
+          let advisory: unknown;
           if (action === 'delete') {
-            ({ role } = await patchRoleSection(roleId, { action, heading }));
+            ({ role, advisory } = await patchRoleSection(roleId, { action, heading }));
           } else {
             const body = args?.body as string;
             if (typeof body !== 'string') {
@@ -1138,13 +1178,12 @@ export async function main() {
             }
             if (action === 'insert') {
               const after = (typeof args?.after === 'string' ? args.after : null) as string | null;
-              ({ role } = await patchRoleSection(roleId, { action, heading, body, after }));
+              ({ role, advisory } = await patchRoleSection(roleId, { action, heading, body, after }));
             } else {
-              ({ role } = await patchRoleSection(roleId, { action, heading, body }));
+              ({ role, advisory } = await patchRoleSection(roleId, { action, heading, body }));
             }
           }
-          const verb = action === 'replace' ? 'Replaced' : action === 'insert' ? 'Inserted' : 'Deleted';
-          return { content: [{ type: 'text', text: `${verb} section **${heading}** in role **${role.name}** (id: ${role.id}).` }] };
+          return { content: [{ type: 'text', text: formatPatchedRoleSectionResult(action, heading, role, advisory) }] };
         }
 
         case 'borg_delete-role': {

package/src/opencode-drone.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { createHash, randomUUID } from 'crypto';
+import { createServer } from 'node:net';
 import { join } from 'path';
 import { tmpdir } from 'os';
 
@@ -749,6 +750,62 @@ export function computeOpenCodePort(droneId: string, base: number = 14096): numb
   return base + (Math.abs(hash) % 1024);
 }
 
+/**
+ * Ask the OS for an available loopback port. The old deterministic hash is
+ * retained above only for compatibility fixtures; launch paths must not use a
+ * bounded shared port space where two drones can collide.
+ */
+async function canBindOpenCodePort(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, '127.0.0.1', () => {
+      probe.close(() => resolve(true));
+    });
+  });
+}
+
+export function configuredOpenCodePort(env: NodeJS.ProcessEnv = process.env): number | null {
+  const port = Number(env.BORG_OPENCODE_PORT);
+  return Number.isInteger(port) && port > 0 && port <= 65_535 ? port : null;
+}
+
+export const OPEN_CODE_PORT_MISSING_DIAGNOSTIC =
+  'OpenCode launch port is missing; skipping OpenCode entry injection. Relaunch through borg.';
+
+export function openCodeLaunchBinding(port: number): {
+  cliPort: string;
+  envPort: string;
+  serverUrl: string;
+} {
+  const value = String(port);
+  return { cliPort: value, envPort: value, serverUrl: `http://127.0.0.1:${value}` };
+}
+
+export async function allocateOpenCodePort(
+  isPortAvailable: (port: number) => Promise<boolean> = canBindOpenCodePort,
+): Promise<number> {
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const port = await new Promise<number>((resolve, reject) => {
+      const probe = createServer();
+      const fail = (error: Error) => {
+        probe.close(() => reject(error));
+      };
+      probe.once('error', fail);
+      probe.listen(0, '127.0.0.1', () => {
+        const address = probe.address();
+        if (address === null || typeof address === 'string') {
+          fail(new Error('OpenCode port allocation returned no TCP address'));
+          return;
+        }
+        probe.close((error) => error ? reject(error) : resolve(address.port));
+      });
+    });
+    if (await isPortAvailable(port)) return port;
+  }
+  throw new Error('OpenCode port allocation could not claim an available loopback port');
+}
+
 /** Test-only cleanup for module state and the local cross-process binding. */
 export function __resetOpenCodeDroneForTests(): void {
   abandonOpenCodeDeliveries(state);

package/src/remote-client.ts

@@ -85,10 +85,27 @@ export const LOCAL_SERVER_RESPONSE_LIMIT_BYTES = 32 * 1024 * 1024;
 // bounded read throws → the 401 fails closed to non-destructive CREDENTIAL_REJECTED.
 const AUTH_ERROR_ENVELOPE_LIMIT_BYTES = 64 * 1024;
 const ROLE_SECTION_CONFLICT_CODE = 'ROLE_SECTION_CONFLICT';
+const CAPACITY_EXCEEDED_CODE = 'CAPACITY_EXCEEDED';
 export const LOCAL_SERVER_REQUEST_TIMEOUT_MS = 5_000;
 const LOCAL_SERVER_RESPONSE_LIMIT_MESSAGE =
   'Local Borg server response exceeded the response limit';
 
+function sanitizeServerMessage(message: string): string {
+  return message
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, '')
+    .replace(/\\u(?:000[0-9a-f]|001[0-9a-f]|007f|008[0-9a-f]|009[0-9a-f])/gi, '');
+}
+
+export const SERVER_ADVISORY_MAX_CHARS = 512;
+
+export function sanitizeServerAdvisory(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const sanitized = sanitizeServerMessage(value).trim();
+  return sanitized.length > 0 ? sanitized.slice(0, SERVER_ADVISORY_MAX_CHARS) : undefined;
+}
+
 /**
  * Parse a `Retry-After` header (delta-seconds form, which the worker
  * emits — mcp-server.ts:382/583) into milliseconds. Returns null when
@@ -725,11 +742,11 @@ async function authedFetch(
   }
 
   if (!response.ok) {
-    // Do not copy a server response body into errors or debug output: a malicious or
-    // misconfigured server could reflect bearer/invitation material or inject
-    // terminal controls. Decode only the bounded protocol error code for typed
-    // branching; never surface the server-provided message or details.
+    // Decode only the bounded protocol error envelope. Its message is the
+    // server's operator-facing action guidance; details and unrecognized bodies
+    // remain excluded from the client error.
     let code: ErrorCode | undefined;
+    let serverMessage: string | undefined;
     let protocolMismatch = false;
     try {
       const body = await readBoundedResponseBody(
@@ -739,7 +756,11 @@ async function authedFetch(
       );
       const parsed = JSON.parse(body);
       try {
-        code = decodeProtocolErrorEnvelope(parsed).error.code;
+        const decoded = decodeProtocolErrorEnvelope(parsed);
+        code = decoded.error.code;
+        serverMessage = response.status === 404
+          ? undefined
+          : sanitizeServerMessage(decoded.error.message);
       } catch (error) {
         if (
           error instanceof ProtocolContractError &&
@@ -750,21 +771,25 @@ async function authedFetch(
         if (
           parsed !== null && typeof parsed === 'object' &&
           parsed.error !== null && typeof parsed.error === 'object' &&
-          parsed.error.code === ROLE_SECTION_CONFLICT_CODE
+          (parsed.error.code === ROLE_SECTION_CONFLICT_CODE
+            || parsed.error.code === CAPACITY_EXCEEDED_CODE)
         ) {
           // The shared protocol intentionally omits this server-local code. Re-validate the whole
           // envelope through the strict shared decoder with only the recognized
-          // code substituted; no server-provided diagnostic is ever surfaced.
-          decodeProtocolErrorEnvelope({
+          // code substituted. The original message remains in place so the
+          // shared decoder validates its length and diagnostic shape.
+          const decoded = decodeProtocolErrorEnvelope({
             ...parsed,
             error: {
               ...parsed.error,
               code: ErrorCode.INVALID_INPUT,
-              message: 'Role section conflict.',
               ...(Object.hasOwn(parsed.error, 'details') ? { details: 'Redacted.' } : {}),
             },
           });
-          code = ROLE_SECTION_CONFLICT_CODE as ErrorCode;
+          code = parsed.error.code as ErrorCode;
+          serverMessage = response.status === 404
+            ? undefined
+            : sanitizeServerMessage(decoded.error.message);
         }
       }
     } catch {
@@ -782,7 +807,9 @@ async function authedFetch(
     }
     throw new BorgServerHttpError(
       response.status,
-      `Borg server request failed (HTTP ${response.status})`,
+      serverMessage
+        ? `Borg server request failed (HTTP ${response.status}): ${serverMessage}`
+        : `Borg server request failed (HTTP ${response.status})`,
       code,
     );
   }
@@ -1302,7 +1329,7 @@ export async function updateCube(
   updates: { name?: string; cube_directive?: string; message_taxonomy?: MessageTaxonomy | null },
   activeOverride?: ActiveCube,
   connectionOverride?: RemoteConnection,
-): Promise<{ cube: any }> {
+): Promise<{ cube: any; advisory?: unknown }> {
   assertUuidShape(cubeId, 'cube_id');
   const active = activeOverride ?? await getActiveCube();
   if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');
@@ -1438,7 +1465,7 @@ export async function updateRole(
   targetCubeId?: string,
   activeOverride?: ActiveCube,
   connectionOverride?: RemoteConnection,
-): Promise<{ role: any }> {
+): Promise<{ role: any; advisory?: unknown }> {
   assertUuidShape(roleId, 'role_id');
   const active = activeOverride ?? await getActiveCube();
   if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');
@@ -1514,7 +1541,7 @@ export async function patchRoleSection(
   targetCubeId?: string,
   activeOverride?: ActiveCube,
   connectionOverride?: RemoteConnection,
-): Promise<{ role: any }> {
+): Promise<{ role: any; advisory?: unknown }> {
   assertUuidShape(roleId, 'role_id');
   const active = activeOverride ?? await getActiveCube();
   if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');