borgmcp-shared 0.2.2

package/src/protocol/types.ts

@@ -0,0 +1,201 @@
+import type { MessageTaxonomy } from '../templates.js';
+
+export type AgentKind = 'claude' | 'codex' | 'opencode';
+export type RoleClass = 'queen' | 'worker';
+export type LogVisibility = 'broadcast' | 'direct';
+export type AckKind = 'ack' | 'claim';
+export type WakePath = 'live' | 'degraded' | 'deaf';
+export type WakePathAlertClass =
+  | 'dead'
+  | 'post-blocked'
+  | 'presumed-dead'
+  | 'systemic-post-block'
+  | 'wake-path-deaf'
+  | 'systemic-wake-path-deaf'
+  | 'independent';
+
+export interface Cube {
+  id: string;
+  owner_id: string;
+  name: string;
+  cube_directive: string;
+  created_at: string;
+  updated_at: string;
+  message_taxonomy?: MessageTaxonomy | null;
+  /** Added to orientation responses; optional when reading older servers. */
+  directive_hash?: string;
+}
+
+export interface Role {
+  id: string;
+  cube_id: string;
+  name: string;
+  short_description: string;
+  detailed_description: string;
+  is_default: boolean;
+  /** Additive fields are optional for compatibility with older servers. */
+  is_mandatory?: boolean;
+  is_human_seat: boolean;
+  can_broadcast?: boolean;
+  receives_all_direct?: boolean;
+  role_class?: RoleClass;
+  created_at: string;
+  detailed_description_hash?: string;
+}
+
+export type PublicRole = Omit<Role, 'detailed_description' | 'detailed_description_hash'>;
+
+export interface Drone {
+  id: string;
+  cube_id: string;
+  role_id: string;
+  label: string;
+  is_queen_class?: boolean;
+  last_seen: string;
+  last_log_post?: string | null;
+  hostname: string | null;
+  last_regen_at?: string | null;
+  regen_count?: number | string;
+  last_read_log_at?: string | null;
+  last_event_received_at?: string | null;
+  wake_path_client_sse_connected?: boolean | null;
+  wake_path_client_monitor_armed?: boolean | null;
+  wake_path_alert_class?: WakePathAlertClass | null;
+  agent_kind?: AgentKind | null;
+  reported_model?: string | null;
+  working_repo_name?: string | null;
+  working_repo_origin?: string | null;
+  evicted_at?: null;
+  created_at: string;
+  seen_since?: boolean;
+}
+
+export interface RosterDrone extends Drone {
+  behind_by: number;
+  wake_path: WakePath;
+  wake_path_deaf_streak?: number;
+  wake_path_last_challenge_at?: string | null;
+  wake_path_last_alert_at?: string | null;
+}
+
+export interface RegenIdentityDrone extends Drone {
+  frozen_at?: null;
+}
+
+export interface ActivityLogEntry {
+  id: string;
+  cube_id: string;
+  drone_id: string | null;
+  message: string;
+  visibility: LogVisibility;
+  created_at: string;
+}
+
+export interface EnrichedStreamEntry extends ActivityLogEntry {
+  drone_label: string | null;
+  role_name: string | null;
+  recipient_drone_ids: string[];
+}
+
+export interface AssimilateRequest {
+  cube_id?: string;
+  cube_name?: string;
+  role_id?: string;
+  role_name?: string;
+  prior_drone_id?: string;
+  hostname?: string | null;
+  agent_kind?: AgentKind | null;
+}
+
+export interface AssimilateResponse {
+  cube: Cube;
+  role: Role;
+  drone: Drone;
+  sessionToken: string;
+  reattached?: boolean;
+}
+
+export interface WhoAmIResponse {
+  cube_id: string;
+  cube_name: string;
+  drone_id: string;
+  drone_label: string;
+  role_id: string;
+  role_name: string;
+}
+
+export interface RosterResponse {
+  drones: RosterDrone[];
+  roles: PublicRole[];
+  message_taxonomy?: MessageTaxonomy | null;
+  since?: string | null;
+}
+
+export interface ReadLogClaim {
+  log_entry_id: string;
+  claimant_drone_id: string;
+  claimant_label: string | null;
+  claimant_role: string | null;
+  claimed_at: string;
+  stale: boolean;
+}
+
+export interface ReadLogResponse {
+  entries: ActivityLogEntry[];
+  drones: Drone[];
+  roles: PublicRole[];
+  behind_by?: number;
+  has_more?: boolean;
+  /** Added with advisory claims; optional when reading older servers. */
+  claims?: ReadLogClaim[];
+}
+
+export interface RoutingEcho {
+  class: string | null;
+  recipients: string[];
+  fellOpen: boolean;
+  message: string | null;
+}
+
+export interface AppendLogRequest {
+  message: string;
+  visibility?: LogVisibility;
+  recipientDroneIds?: string[];
+  class?: string;
+  to?: string[];
+}
+
+export interface AppendLogResponse {
+  entry: ActivityLogEntry;
+  routing?: RoutingEcho | null;
+  unreachableRecipients?: Array<{ id: string; label: string }>;
+}
+
+export interface Decision {
+  id: string;
+  cube_id: string;
+  topic: string;
+  decision: string;
+  rationale: string | null;
+  ratified_by?: string | null;
+  status?: 'active' | 'superseded' | 'removed';
+  supersedes?: string | null;
+  created_at: string;
+}
+
+export interface RecordDecisionRequest {
+  topic: string;
+  decision: string;
+  rationale?: string;
+}
+
+export interface RegenResponse {
+  cube: Cube;
+  role: Role;
+  drone: RegenIdentityDrone;
+  roles: PublicRole[];
+  drones: Drone[];
+  decisions?: Decision[];
+  recentLog?: ActivityLogEntry[];
+  behind_by?: number;
+}

package/src/protocol/version.ts

@@ -0,0 +1,31 @@
+/** Current Borg coordination protocol generation. */
+export const PROTOCOL_VERSION = '1' as const;
+
+/** Protocol generations accepted by this package release. */
+export const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION] as const;
+
+export type ProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
+
+export interface CompatibilityEntry {
+  packageRange: string;
+  protocolVersions: readonly ProtocolVersion[];
+  notes: string;
+}
+
+/**
+ * Compatibility table for published package releases. Pre-1.0 package
+ * releases may add contracts, but do not change an existing wire shape without
+ * a documented migration path.
+ */
+export const COMPATIBILITY_MATRIX: readonly CompatibilityEntry[] = [
+  {
+    packageRange: '>=0.2.0 <0.3.0',
+    protocolVersions: SUPPORTED_PROTOCOL_VERSIONS,
+    notes: 'Versioned envelope, codecs, and adapter conformance for Borg MCP servers.',
+  },
+];
+
+export function isProtocolVersionSupported(value: unknown): value is ProtocolVersion {
+  return typeof value === 'string' &&
+    (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(value);
+}

package/src/role-section.ts

@@ -0,0 +1,270 @@
+/**
+ * Role-text section parsing and granular section patching.
+ *
+ * This module remains platform-dependency-free so clients, servers, and tests
+ * all use one canonical parser without importing runtime or storage adapters.
+ *
+ * ## Why not markdown `##` headings
+ *
+ * Real role `detailed_description` text (see `client/src/templates.ts`)
+ * does NOT use `##` headings. It is structured as:
+ *
+ *   - a PREAMBLE — free prose before the first label line
+ *     (e.g. "You implement changes to the codebase…");
+ *   - one or more SECTIONS, each headed by a PLAIN-LABEL LINE — a line
+ *     that is a short label terminated by a single trailing colon and
+ *     nothing else (e.g. `Workflow:`, `Project conventions:`,
+ *     `Your job:`, `Log conventions you use:`);
+ *   - TRAILING inlined `${ESCALATION_DISCIPLINE}` / `${...}` constant
+ *     text woven onto the end of the field. That text uses `**bold:**`
+ *     markdown emphasis, NOT bare label lines, so it is NOT a section
+ *     boundary — it falls into the last label section as literal text.
+ *
+ * A parser that splits on `##` finds ZERO sections in real role text.
+ * The label-line delimiter below matches the ACTUAL structure.
+ *
+ * ## Byte-identical round-trip invariant
+ *
+ * `serializeSections(parseRoleSections(text)) === text` for ANY input.
+ * The parser does not trim, normalize newlines, or otherwise rewrite
+ * bytes — each section's `body` retains the exact slice (including its
+ * heading line and the newline that terminates it) so concatenation
+ * reproduces the original field verbatim. The single named-fragment
+ * mutation is therefore the ONLY byte-level change a patch makes.
+ */
+
+/** What kind of label heads a section. */
+export type RoleSectionKind = 'preamble' | 'label';
+
+export interface RoleSection {
+  /**
+   * The section's label WITHOUT the trailing colon, trimmed
+   * (e.g. "Workflow", "Project conventions"). `null` for the preamble
+   * (the pre-first-label span). Used as the addressing key for patches.
+   */
+  heading: string | null;
+  kind: RoleSectionKind;
+  /**
+   * The EXACT source slice for this section, including its heading line
+   * (for label sections) and every byte through to (but not including)
+   * the next section's heading line. Concatenating every section's
+   * `body` in order reproduces the original text byte-for-byte.
+   */
+  body: string;
+}
+
+export type RoleSectionPatchOp =
+  | { action: 'replace'; heading: string; body: string }
+  | { action: 'insert'; heading: string; body: string; after?: string | null }
+  | { action: 'delete'; heading: string };
+
+/**
+ * Test whether a single line is a plain-label section heading.
+ *
+ * Rules (deliberately narrow to avoid false positives against prose
+ * that merely contains a colon):
+ *   - no leading whitespace (label lines start at column 0);
+ *   - the line ends with exactly one `:`;
+ *   - the text before the colon is non-empty, contains no other `:`,
+ *     and is "short" (≤ 60 chars) — long colon-terminated prose lines
+ *     are not labels;
+ *   - the label is not a markdown emphasis run (does not start with
+ *     `*`, `-`, `#`, `>` or backtick) — those are list/markdown lines,
+ *     not plain labels (the woven `**Dense communication discipline:**`
+ *     constant headings must NOT be treated as section boundaries).
+ */
+export function isLabelLine(line: string): boolean {
+  // Leading whitespace disqualifies (label lines are flush-left).
+  if (/^\s/.test(line)) return false;
+  if (!line.endsWith(':')) return false;
+  const label = line.slice(0, -1);
+  if (label.length === 0) return false;
+  if (label.length > 60) return false;
+  // Exactly one colon total (the trailing one).
+  if (label.includes(':')) return false;
+  // Markdown/list/quote/code lead-ins are not plain labels.
+  if (/^[*\-#>`]/.test(label)) return false;
+  return true;
+}
+
+/**
+ * Parse role `detailed_description` text into ordered sections.
+ *
+ * The result always round-trips byte-identical through
+ * `serializeSections`. An empty string yields a single empty preamble
+ * section so callers always have a stable shape to address.
+ */
+export function parseRoleSections(text: string): RoleSection[] {
+  const sections: RoleSection[] = [];
+  const lines = text.split('\n');
+
+  // Reconstruct each line WITH its terminating newline so that the
+  // concatenation is lossless. `split('\n')` drops the separators; we
+  // re-append '\n' to every line except the last (which had no trailing
+  // newline in the source unless the source ended with one — in which
+  // case the final split element is '' and contributes nothing).
+  const lineWithSep = (idx: number): string =>
+    idx < lines.length - 1 ? lines[idx] + '\n' : lines[idx];
+
+  let currentHeading: string | null = null;
+  let currentKind: RoleSectionKind = 'preamble';
+  let currentBody = '';
+  let started = false;
+
+  const flush = () => {
+    sections.push({ heading: currentHeading, kind: currentKind, body: currentBody });
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (isLabelLine(raw)) {
+      // Close the in-progress section (preamble or previous label) and
+      // open a new label section headed by this line.
+      flush();
+      currentHeading = raw.slice(0, -1).trim();
+      currentKind = 'label';
+      currentBody = lineWithSep(i);
+      started = true;
+    } else {
+      currentBody += lineWithSep(i);
+      started = true;
+    }
+  }
+
+  // Always emit the final in-progress section. For empty input this is a
+  // single empty preamble (started === false, currentBody === '').
+  if (started || sections.length === 0) {
+    flush();
+  }
+
+  return sections;
+}
+
+/** Concatenate sections back into the original field text. */
+export function serializeSections(sections: RoleSection[]): string {
+  return sections.map((s) => s.body).join('');
+}
+
+function normalizeHeading(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+/**
+ * Build the body for a freshly inserted/replaced label section from a
+ * heading + caller-supplied body text.
+ *
+ * The heading line is rendered as `<heading>:` on its own line. The
+ * caller's `body` is the text BELOW the heading. We guarantee the
+ * section body ends with a single trailing newline so adjacent sections
+ * stay separated when re-serialized (matching how real role text
+ * separates label sections with blank lines is the caller's choice via
+ * their body text; we only ensure the structural newline).
+ */
+function renderLabelSection(heading: string, body: string): string {
+  const headingLine = `${heading.trim()}:\n`;
+  if (body === '') return headingLine;
+  // Ensure the body ends with a newline so the next section's heading
+  // starts on its own line.
+  const normalizedBody = body.endsWith('\n') ? body : body + '\n';
+  return headingLine + normalizedBody;
+}
+
+/**
+ * Guarantee the section at `idx` ends in a newline before a new section
+ * heading is glued on after it.
+ *
+ * Real role `detailed_description` text (every template role) ends WITHOUT
+ * a trailing newline — it closes on the woven `${...DISCIPLINE}` constant.
+ * Appending a `<heading>:` line directly onto such text would fuse the
+ * heading onto the prior section's last line, so the heading is no longer
+ * a flush-left label and the inserted section is LOST on re-parse. Adding
+ * the structural newline here keeps the inserted heading on its own line.
+ *
+ * No-ops when the preceding body is empty (an empty preamble needs no
+ * separator) or already ends in '\n' (preserves the already-correct case
+ * byte-for-byte).
+ */
+function ensureTrailingNewline(sections: RoleSection[], idx: number): void {
+  if (idx < 0 || idx >= sections.length) return;
+  const prev = sections[idx];
+  if (prev.body !== '' && !prev.body.endsWith('\n')) {
+    sections[idx] = { ...prev, body: prev.body + '\n' };
+  }
+}
+
+/**
+ * Apply a single section-level patch to role text, returning the new
+ * full field text. Every other byte is preserved.
+ *
+ *   - replace: overwrite the matched section's body with a re-rendered
+ *     `<heading>:\n<body>` block. The heading match is case-insensitive
+ *     on the label; the re-rendered heading uses the supplied casing.
+ *   - insert: add a new label section. Placed after the section named by
+ *     `after` (case-insensitive), or appended at the end when `after` is
+ *     omitted/null. Rejects if a section with the same heading already
+ *     exists (use replace instead).
+ *   - delete: drop the matched section entirely.
+ *
+ * Throws when the target section is missing (replace/delete) or already
+ * present (insert), or when `after` does not resolve.
+ */
+export function patchRoleSectionText(text: string, op: RoleSectionPatchOp): string {
+  const sections = parseRoleSections(text);
+  const targetKey = normalizeHeading(op.heading);
+
+  if (op.action === 'replace') {
+    const idx = sections.findIndex(
+      (s) => s.kind === 'label' && s.heading != null && normalizeHeading(s.heading) === targetKey
+    );
+    if (idx === -1) {
+      throw new Error(`Role section "${op.heading}" not found. Use action="insert" to add it.`);
+    }
+    sections[idx] = {
+      heading: op.heading.trim(),
+      kind: 'label',
+      body: renderLabelSection(op.heading, op.body),
+    };
+    return serializeSections(sections);
+  }
+
+  if (op.action === 'delete') {
+    const idx = sections.findIndex(
+      (s) => s.kind === 'label' && s.heading != null && normalizeHeading(s.heading) === targetKey
+    );
+    if (idx === -1) {
+      throw new Error(`Role section "${op.heading}" not found.`);
+    }
+    sections.splice(idx, 1);
+    return serializeSections(sections);
+  }
+
+  // insert
+  const exists = sections.some(
+    (s) => s.kind === 'label' && s.heading != null && normalizeHeading(s.heading) === targetKey
+  );
+  if (exists) {
+    throw new Error(`Role section "${op.heading}" already exists. Use action="replace" to overwrite it.`);
+  }
+  const newSection: RoleSection = {
+    heading: op.heading.trim(),
+    kind: 'label',
+    body: renderLabelSection(op.heading, op.body),
+  };
+
+  if (op.after == null) {
+    ensureTrailingNewline(sections, sections.length - 1);
+    sections.push(newSection);
+    return serializeSections(sections);
+  }
+
+  const afterKey = normalizeHeading(op.after);
+  const afterIdx = sections.findIndex(
+    (s) => s.kind === 'label' && s.heading != null && normalizeHeading(s.heading) === afterKey
+  );
+  if (afterIdx === -1) {
+    throw new Error(`Cannot insert after section "${op.after}" — it does not exist.`);
+  }
+  ensureTrailingNewline(sections, afterIdx);
+  sections.splice(afterIdx + 1, 0, newSection);
+  return serializeSections(sections);
+}