borgmcp 3.15.1 → 3.16.0

package/src/index.ts

@@ -52,8 +52,17 @@ import {
   applyTemplate,
   whoami,
   roleRationale,
+  putDocument,
+  getDocument,
+  listDocuments,
+  removeDocument,
   type LocalManageAuthority,
 } from './remote-client.js';
+import {
+  formatDocument,
+  formatDocumentCitations,
+  formatDocumentMetadata,
+} from './document-render.js';
 import {
   getTemplate,
   listTemplateNames,
@@ -840,6 +849,33 @@ export async function main() {
           return { content: [{ type: 'text', text: lines.join('\n') }] };
         }
 
+        case 'borg_put-document': {
+          const active = await requireActiveCube();
+          const result = await putDocument(active.sessionToken, active.apiUrl, args ?? {}, active.serverTrustIdentity);
+          return { content: [{ type: 'text', text: `Created cube document.\n\n${formatDocument(result.document)}` }] };
+        }
+
+        case 'borg_get-document': {
+          const active = await requireActiveCube();
+          const result = await getDocument(active.sessionToken, active.apiUrl, args ?? {}, active.serverTrustIdentity);
+          return { content: [{ type: 'text', text: formatDocument(result.document) }] };
+        }
+
+        case 'borg_list-documents': {
+          const active = await requireActiveCube();
+          const result = await listDocuments(active.sessionToken, active.apiUrl, args ?? {}, active.serverTrustIdentity);
+          const text = result.documents.length === 0
+            ? `No active or superseded documents in cube "${active.name}".`
+            : result.documents.map(formatDocumentMetadata).join('\n\n');
+          return { content: [{ type: 'text', text }] };
+        }
+
+        case 'borg_remove-document': {
+          const active = await requireActiveCube();
+          const result = await removeDocument(active.sessionToken, active.apiUrl, args ?? {}, active.serverTrustIdentity);
+          return { content: [{ type: 'text', text: `Removed cube document.\n\n${formatDocumentMetadata(result.document)}` }] };
+        }
+
         case 'borg_log': {
           const message = args?.message as string;
           if (!message || typeof message !== 'string') throw new Error('message is required');
@@ -870,6 +906,7 @@ export async function main() {
             args?.visibility === 'broadcast' || args?.visibility === 'direct'
               ? args.visibility
               : undefined;
+          const documents = args?.documents as string[] | undefined;
           if (!active.serverTrustIdentity) {
             throw new Error('Selected Borg server authority state is missing or unreadable');
           }
@@ -877,6 +914,7 @@ export async function main() {
             ...(explicitClass ? { class: explicitClass } : {}),
             ...(hasTo ? { to: recipients ?? [] } : {}),
             ...(visibility ? { visibility } : {}),
+            ...(documents ? { documents } : {}),
             serverTrustIdentity: active.serverTrustIdentity,
           };
           const result = await appendLog(active.sessionToken, active.apiUrl, message, appendOpts);
@@ -891,7 +929,12 @@ export async function main() {
                 .map((r) => r.label)
                 .join(', ')}. Message delivered — they'll read it when they return.`
             : '';
-          const text = `Logged to cube "${displayIdentity.cubeName}" as ${displayIdentity.droneLabel}. (entry id: ${result.entry.id})${echo}${unreachable}`;
+          const cited = formatDocumentCitations(result.entry.documents);
+          const citations = cited.length > 0 ? `\nDocuments: ${cited.join('; ')}` : '';
+          const advisory = result.advisory?.code === 'STORE_AS_DOCUMENT'
+            ? `\nAdvisory: this message exceeded ${result.advisory.threshold_bytes} UTF-8 bytes. Store durable detail with borg_put-document and cite its full id in borg_log.documents.`
+            : '';
+          const text = `Logged to cube "${displayIdentity.cubeName}" as ${displayIdentity.droneLabel}. (entry id: ${result.entry.id})${echo}${unreachable}${citations}${advisory}`;
           return { content: [{ type: 'text', text }] };
         }
 

package/src/launch-all-cmd.ts

@@ -320,6 +320,20 @@ export async function runLaunchAll(
     return 0;
   }
 
+  // Confirm the one configured authority is accepting pinned protocol requests
+  // before any agent process starts. Per-seat checks below remain authoritative
+  // for each saved session only after this fleet-wide readiness boundary passes.
+  try {
+    await deps.probeAuthority(lockLaunchable[0].seat);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    deps.stderr(
+      `borg launch-all: configured Borg authority is unavailable (${reason}); ` +
+        'nothing was launched. Ask the server operator to restore it, then retry.\n',
+    );
+    return 1;
+  }
+
   // 4b. server-liveness skip — drop seats the server reports EVICTED (gone).
   //     Reuses the gh#882 per-seat probe (each seat's OWN token → 410
   //     DRONE_EVICTED). Relaunching an evicted seat silently re-mints a fresh

package/src/launch-all-deps.ts

@@ -26,6 +26,9 @@ import {
 import { getRoster, getCube } from './remote-client.js';
 import { defaultProbeSeat, type SeatStatus } from './seat-probe.js';
 import { borgHomeRoot } from './private-root.js';
+import { preflightBorgServerTag } from './server-handshake.js';
+import { loadBorgServerTrust } from './server-trust.js';
+import { BorgServerTrustError } from './server-errors.js';
 
 /** Subprocess runner — sync, returns stdout, THROWS on non-zero exit or ENOENT. */
 export type RunSyncFn = (cmd: string, args: string[]) => string;
@@ -71,6 +74,8 @@ export interface LaunchAllDeps {
     token: string,
     cubeId: string
   ) => Promise<{ id: string; name: string; roles: Array<{ id: string; name: string }> }>;
+  /** Verify the configured pinned authority is accepting protocol requests. */
+  probeAuthority: (seat: ActiveCube) => Promise<void>;
   /**
    * Probe ONE saved seat's server-side liveness using ITS OWN token (gh#877
    * reuse via seat-probe.ts). Lets launch-all skip evicted seats instead
@@ -156,6 +161,16 @@ export function buildDefaultLaunchAllDeps(): LaunchAllDeps {
     getRoster: (seat, since) => getRoster(seat, since),
     // getCube uses the drone session token via authedFetch (cubeId-only); apiUrl/token unused.
     getCube: (_apiUrl, _token, cubeId) => getCube(cubeId),
+    probeAuthority: async (seat) => {
+      if (!seat.serverTrustIdentity) {
+        throw new BorgServerTrustError('Saved Borg server trust identity is missing');
+      }
+      const trust = await loadBorgServerTrust(seat.apiUrl);
+      if (trust.identity !== seat.serverTrustIdentity) {
+        throw new BorgServerTrustError('Saved Borg server trust identity changed');
+      }
+      await preflightBorgServerTag(seat.apiUrl, trust.fetchImpl);
+    },
     probeSeat: (seat) => defaultProbeSeat(seat),
     getCliPreferenceForPath: (projectPath) => getProjectCliPreferenceForPath(projectPath),
     readAllProjectIdentities: () => cubesReadAllProjectIdentities(),

package/src/log-stream.ts

@@ -28,7 +28,12 @@ import { Buffer } from 'node:buffer';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { compareBroadcastHwm, type BroadcastHwm } from 'borgmcp-shared/log-stream-hwm';
-import { decodeProtocolErrorEnvelope, ErrorCode } from 'borgmcp-shared/protocol';
+import {
+  decodeDocumentCitations,
+  decodeProtocolErrorEnvelope,
+  ErrorCode,
+  type DocumentCitation,
+} from 'borgmcp-shared/protocol';
 import { getActiveCube, inboxPathForDrone } from './cubes.js';
 import { assertUuidShape } from './evict-drone.js';
 import { loadBorgServerTrust } from './server-trust.js';
@@ -59,6 +64,7 @@ import { formatCubeActivityWakeMessage } from './cube-activity-wake-copy.js';
 import { readBoundedResponseBody } from './server-response.js';
 import { BorgServerError } from './server-errors.js';
 import { markSeatRejected } from './seats.js';
+import { formatDocumentCitations } from './document-render.js';
 import { hasPendingWakeEntry as hasPendingDurableWakeEntry } from './remote-client.js';
 import {
   acquireStreamLease,
@@ -1426,7 +1432,14 @@ function parseEventBlock(block: string): ParsedEvent | null {
     const validCursor = cursor &&
       typeof cursor.id === 'string' &&
       typeof cursor.created_at === 'string';
-    const entry = parsed?.entry ?? parsed;
+    let entry = parsed?.entry ?? parsed;
+    if (entry?.documents !== undefined) {
+      try {
+        entry = { ...entry, documents: decodeDocumentCitations(entry.documents) };
+      } catch {
+        return { type: 'unknown', raw: block };
+      }
+    }
     return {
       type: 'log',
       id,
@@ -1493,6 +1506,7 @@ export interface EnrichedEntry {
   drone_label?: string | null;
   role_name?: string | null;
   message?: string;
+  documents?: DocumentCitation[];
 }
 
 function parseHeartbeatHwm(value: unknown): BroadcastHwm | null {
@@ -1566,7 +1580,11 @@ export function formatInboxLine(entry: EnrichedEntry): string {
   const idPrefix = entryId ? `[entry_id: ${entryId}] ` : '';
   // Normalize \r\n, \r, and \n all to ` ⏎ ` so the entry fits on one
   // physical line regardless of line-ending convention in the source.
-  const message = rawMessage.replace(/\r\n|\r|\n/g, ' ⏎ ');
+  const citations = formatDocumentCitations(entry.documents);
+  const withDocuments = citations.length > 0
+    ? `${rawMessage}\nDocuments: ${citations.join('; ')}`
+    : rawMessage;
+  const message = withDocuments.replace(/\r\n|\r|\n/g, ' ⏎ ');
   return `${ts} ${label} (${role}): ${idPrefix}${message}`;
 }
 

package/src/regen-format.ts

@@ -17,6 +17,7 @@ import {
   RUNTIME_METADATA_ADVISORY,
   renderRuntimeMetadataLines,
 } from './roster-render.js';
+import { formatDocumentCitations } from './document-render.js';
 import { shellEscape } from './shell-escape.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 import { isBorgSession } from './launch-gate.js';
@@ -697,5 +698,9 @@ export function formatLogEntryMarkdown(
     typeof entry.drone_id === 'string' && entry.drone_id.length > 0
       ? ` ${formatDroneAddressToken(entry.drone_id)}`
       : '';
-  return `**[${ts}]**${entryId}${addr} ${d?.label ?? '?'} (${r?.name ?? '?'}): ${entry.message}`;
+  const citations = formatDocumentCitations(entry.documents);
+  const documents = citations.length > 0
+    ? `\n  Documents:\n${citations.map((citation) => `  - ${citation}`).join('\n')}`
+    : '';
+  return `**[${ts}]**${entryId}${addr} ${d?.label ?? '?'} (${r?.name ?? '?'}): ${entry.message}${documents}`;
 }

package/src/remote-client.ts

@@ -16,6 +16,7 @@ import {
 import { randomUUID } from 'node:crypto';
 import {
   createProtocolEnvelope,
+  decodeAppendLogRequest,
   decodeAppendLogResult,
   decodeDeleteCubeResponse,
   decodeDeleteRoleRequest,
@@ -25,6 +26,15 @@ import {
   decodeProtocolEnvelope,
   decodeProtocolErrorEnvelope,
   decodeReassignDroneResult,
+  decodeReadLogResult,
+  decodePutDocumentRequest,
+  decodePutDocumentResult,
+  decodeGetDocumentRequest,
+  decodeGetDocumentResult,
+  decodeListDocumentsRequest,
+  decodeListDocumentsResult,
+  decodeRemoveDocumentRequest,
+  decodeRemoveDocumentResult,
   decodeRoleRationaleRequest,
   decodeRoleRationaleResult,
   decodeUpdateDroneRuntimeMetadataResponse,
@@ -35,6 +45,10 @@ import {
   type EvictDroneResult,
   type ReassignDroneResult,
   type RoleRationaleResult,
+  type PutDocumentResult,
+  type GetDocumentResult,
+  type ListDocumentsResult,
+  type RemoveDocumentResult,
 } from 'borgmcp-shared/protocol';
 import { consolePrefix } from './console-prefix.js';
 import { debugLog } from './debug.js';
@@ -315,7 +329,7 @@ async function decodeLocalProtocolResponse<T>(
 async function localServerRequest<T>(
   active: ActiveCube,
   path: string,
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH',
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
   payload?: Record<string, unknown>,
   options: {
     retryMode?: AuthedFetchRetryMode;
@@ -549,7 +563,7 @@ async function localReadLogPage(
     retryMode?: AuthedFetchRetryMode;
   } = {},
 ): Promise<any> {
-  const payload = await localServerRequest<any>(
+  const payload = await localServerRequest(
     active,
     `/api/cubes/${active.cubeId}/logs`,
     'PUT',
@@ -557,7 +571,7 @@ async function localReadLogPage(
       cursor: opts.cursor ?? null,
       ...(opts.limit === undefined ? {} : { limit: opts.limit }),
     },
-    { retryMode: opts.retryMode },
+    { retryMode: opts.retryMode, decodePayload: decodeReadLogResult },
   );
   if (!payload) throw new Error('Local Borg server returned an empty log response');
   return payload;
@@ -1321,6 +1335,82 @@ export async function roleRationale(
   };
 }
 
+export async function putDocument(
+  sessionToken: string,
+  apiUrl: string,
+  input: unknown,
+  serverTrustIdentity?: string,
+): Promise<PutDocumentResult> {
+  const request = decodePutDocumentRequest(input);
+  const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
+  const result = await localServerRequest<PutDocumentResult>(
+    local,
+    `/api/cubes/${local.cubeId}/documents`,
+    'PUT',
+    { ...request },
+    { decodePayload: decodePutDocumentResult },
+  );
+  if (!result) throw new Error('Local Borg server returned an empty document response');
+  return result;
+}
+
+export async function getDocument(
+  sessionToken: string,
+  apiUrl: string,
+  input: unknown,
+  serverTrustIdentity?: string,
+): Promise<GetDocumentResult> {
+  const request = decodeGetDocumentRequest(input);
+  const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
+  const result = await localServerRequest<GetDocumentResult>(
+    local,
+    `/api/cubes/${local.cubeId}/documents/${encodeURIComponent(request.id)}`,
+    'GET',
+    { ...request },
+    { decodePayload: decodeGetDocumentResult },
+  );
+  if (!result) throw new Error('Local Borg server returned an empty document response');
+  return result;
+}
+
+export async function listDocuments(
+  sessionToken: string,
+  apiUrl: string,
+  input: unknown,
+  serverTrustIdentity?: string,
+): Promise<ListDocumentsResult> {
+  decodeListDocumentsRequest(input);
+  const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
+  const result = await localServerRequest<ListDocumentsResult>(
+    local,
+    `/api/cubes/${local.cubeId}/documents`,
+    'GET',
+    {},
+    { decodePayload: decodeListDocumentsResult },
+  );
+  if (!result) throw new Error('Local Borg server returned an empty document-list response');
+  return result;
+}
+
+export async function removeDocument(
+  sessionToken: string,
+  apiUrl: string,
+  input: unknown,
+  serverTrustIdentity?: string,
+): Promise<RemoveDocumentResult> {
+  const request = decodeRemoveDocumentRequest(input);
+  const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
+  const result = await localServerRequest<RemoveDocumentResult>(
+    local,
+    `/api/cubes/${local.cubeId}/documents/${encodeURIComponent(request.id)}`,
+    'DELETE',
+    { ...request },
+    { decodePayload: decodeRemoveDocumentResult },
+  );
+  if (!result) throw new Error('Local Borg server returned an empty document response');
+  return result;
+}
+
 /**
  * Append a message to the cube's shared activity log.
  */
@@ -1333,6 +1423,7 @@ export async function appendLog(
     recipientDroneIds?: string[];
     class?: string;
     to?: string[];
+    documents?: string[];
     serverTrustIdentity?: string;
   } = {}
 ): Promise<ReturnType<typeof decodeAppendLogResult>> {
@@ -1342,6 +1433,9 @@ export async function appendLog(
       'Remove visibility to direct to recipients, or remove to: to broadcast.',
     );
   }
+  if (opts.to?.length === 0) {
+    throw new Error('Direct log recipient list must contain at least one recipient');
+  }
   const postId = randomUUID();
   const local = await localAuthorityContext(
     sessionToken,
@@ -1370,22 +1464,21 @@ export async function appendLog(
     } else if (visibility === undefined && recipientDroneIds !== undefined) {
       visibility = 'direct';
     }
+    const request = decodeAppendLogRequest({
+      post_id: postId,
+      message,
+      ...(visibility ? { visibility } : {}),
+      ...(visibility === 'direct' && recipientDroneIds
+        ? { recipientDroneIds }
+        : {}),
+      ...(opts.class ? { class: opts.class } : {}),
+      ...(opts.documents ? { documents: opts.documents } : {}),
+    });
     const payload = await localServerRequest<ReturnType<typeof decodeAppendLogResult>>(
       local,
       `/api/cubes/${local.cubeId}/logs`,
       'POST',
-      {
-        post_id: postId,
-        message,
-        ...(visibility ? { visibility } : {}),
-        ...(visibility === 'direct' && recipientDroneIds
-          ? { recipientDroneIds }
-          : {}),
-        // server#48 append-time taxonomy routing: forward the requested class
-        // so the server can classify/route. It is honored only when no explicit
-        // visibility/recipients override it (server resolveMessageRouting).
-        ...(opts.class ? { class: opts.class } : {}),
-      },
+      { ...request },
       { retryMode: 'append-log', decodePayload: decodeAppendLogResult },
     );
     if (!payload) throw new Error('Local Borg server returned an empty log response');

package/src/server-handshake.ts

@@ -215,10 +215,11 @@ export interface ServerAttachResult {
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v9.
+ * Attach an enrolled client principal to one granted cube/role over protocol v10.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
- * OS keychain (keyed by the stable per-seat identity) BEFORE this request, so an
- * interrupted/lost response is recovered by re-sending the exact same bearer —
+ * local 0600 credential store (keyed by the stable per-seat identity) BEFORE
+ * this request, so an interrupted/lost response is recovered by re-sending the
+ * exact same bearer —
  * the server binds only its digest. A verified `created`/`reused` response
  * activates that pending record in place; the server never returns a bearer.
  */

package/src/tool-manifest.ts

@@ -7,7 +7,7 @@
  * CONTRACT-BACKED DATA — imports only published scalar contract constants, with
  * no client runtime side effects.
  */
-import { DECISION_TEXT_MAX_BYTES } from 'borgmcp-shared/protocol';
+import { DECISION_TEXT_MAX_BYTES, DOCUMENT_CONTENT_TYPES } from 'borgmcp-shared/protocol';
 
 export interface ToolManifestEntry {
   name: string;
@@ -307,10 +307,69 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
             },
           },
         },
+        {
+          name: 'borg_put-document',
+          description:
+            'Create an immutable cube document containing Markdown or plain text. Use this for durable material that is too large or detailed for an activity-log message. Pass `supersedes` with the full prior document id to create its next linear revision; content is never edited in place. Requires the selected local client to have a live cube-write or cube-manage grant.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              title: {
+                type: 'string',
+                maxLength: 120,
+                description: 'Document title, trimmed and control-free; max 120 Unicode characters and 480 UTF-8 bytes.',
+              },
+              content_type: {
+                type: 'string',
+                enum: [...DOCUMENT_CONTENT_TYPES],
+                description: 'Exact document content type: text/markdown or text/plain.',
+              },
+              content: {
+                type: 'string',
+                description: 'Immutable document content. The server enforces its configured UTF-8 byte limit.',
+              },
+              supersedes: {
+                type: 'string',
+                description: 'Optional full opaque id of the active document this new revision supersedes.',
+              },
+            },
+            required: ['title', 'content_type', 'content'],
+          },
+        },
+        {
+          name: 'borg_get-document',
+          description:
+            'Fetch one cube document by its full opaque id, including immutable content, revision links, state, author, and removal audit metadata. Exact-id reads retain removed content for audit. Requires a live cube-read, cube-write, or cube-manage grant.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Full opaque document id. Do not abbreviate it.' },
+            },
+            required: ['id'],
+          },
+        },
+        {
+          name: 'borg_list-documents',
+          description:
+            'List active and superseded document metadata in the current cube. Removed documents are omitted; use borg_get-document with an exact known id for retained audit content. Document bodies are not included.',
+          inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+        {
+          name: 'borg_remove-document',
+          description:
+            'Mark one cube document removed while retaining its immutable content and audit metadata. The server permits the document author or a client with a live cube-manage grant; workflow role labels grant no permission. Idempotent for an already removed document.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Full opaque document id to remove. Do not abbreviate it.' },
+            },
+            required: ['id'],
+          },
+        },
         {
           name: 'borg_log',
           description:
-            'Append a message to the cube\'s activity log. By default entries broadcast to all drones. When a cube declares a message taxonomy, borg_log applies class-based smart defaults: prefix-matched directed classes route to their default recipients unless you pass `to:`, `class:`, or explicit visibility. Pass `to: [...]` to direct by exact drone label, drone id, the 8-hex short-uuid (the `id:` token shown in roster/read-log — a drone_id prefix that is STABLE across label renumber), role name, or role slug.',
+            'Append a message to the cube\'s activity log. By default entries broadcast to all drones. Cite durable cube documents by passing their full ids in `documents`; citations carry current metadata but do not inline document content. When a cube declares a message taxonomy, borg_log applies class-based smart defaults: prefix-matched directed classes route to their default recipients unless you pass `to:`, `class`, or explicit visibility. Pass `to: [...]` to direct by exact drone label, drone id, the 8-hex short-uuid (the `id:` token shown in roster/read-log — a drone_id prefix that is STABLE across label renumber), role name, or role slug.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -331,6 +390,14 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
                 enum: ['broadcast', 'direct'],
                 description: 'Optional explicit visibility. Overrides class-based routing defaults.',
               },
+              documents: {
+                type: 'array',
+                items: { type: 'string' },
+                minItems: 1,
+                maxItems: 100,
+                uniqueItems: true,
+                description: 'Optional full opaque ids of 1-100 same-cube documents to cite atomically. Unknown, duplicate, or foreign ids are refused.',
+              },
             },
             required: ['message'],
           },