borgmcp 5.4.0 → 5.5.0

package/dist/representative-cmd.js

@@ -0,0 +1,286 @@
+/**
+ * `borg representative <prepare|status|mcp>` — operator entry for the human
+ * representative ("Hermes") connection.
+ *
+ * prepare  binds ONE dedicated non-human-seat drone in this repository's cube
+ *          to ONE explicitly named Coordinator drone. It creates/resumes the
+ *          seat through the launch-free assimilate seam: no agent CLI starts
+ *          and no existing drone's identity is touched.
+ * status   shows the saved binding and re-checks it against the live cube.
+ * mcp      serves the restricted stdio MCP facade for a generic MCP host.
+ *
+ * No command accepts a credential: the seat bearer stays in the private seat
+ * store and is hydrated in-process only.
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { normalizeServerEndpoint } from './server-endpoint.js';
+import { validateName } from './name-validator.js';
+import { RepresentativeError, assertRepresentativeRole, representativeStatus, resolveCoordinator, } from './representative-core.js';
+import { RepresentativeStoreError, representativeRecoveryCommand, } from './representative-store.js';
+import { shellEscape } from './shell-escape.js';
+export const DEFAULT_REPRESENTATIVE_ROLE = 'hermes-representative';
+export function parseRepresentativeArgs(args) {
+    const [action, ...rest] = args;
+    if (action !== 'prepare' && action !== 'status' && action !== 'mcp') {
+        return { ok: false, error: 'expected one of: prepare, status, mcp' };
+    }
+    const values = {};
+    let rebind = false;
+    const valueFlags = action === 'prepare' ? ['--coordinator', '--role', '--worktree', '--host'] : ['--worktree'];
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (action === 'prepare' && arg === '--rebind') {
+            rebind = true;
+        }
+        else if (valueFlags.includes(arg)) {
+            const next = rest[i + 1];
+            if (typeof next !== 'string' || next.length === 0 || next.startsWith('-')) {
+                return { ok: false, error: `${arg} requires a value` };
+            }
+            values[arg] = next;
+            i += 1;
+        }
+        else {
+            return {
+                ok: false,
+                error: `unknown argument: ${arg}. Supported: ${[...valueFlags, ...(action === 'prepare' ? ['--rebind'] : [])].join(', ')}`,
+            };
+        }
+    }
+    if (action !== 'prepare') {
+        const worktree = values['--worktree'];
+        if (worktree !== undefined && !isAbsolute(worktree)) {
+            return { ok: false, error: '--worktree must be an absolute path to the representative worktree' };
+        }
+        return { ok: true, command: { action, ...(worktree ? { worktree } : {}) } };
+    }
+    const coordinator = values['--coordinator'];
+    if (!coordinator) {
+        return {
+            ok: false,
+            error: '--coordinator <drone-label> is required: name the exact Coordinator drone (see `borg drones`). It is never chosen for you.',
+        };
+    }
+    const role = values['--role'] ?? DEFAULT_REPRESENTATIVE_ROLE;
+    if (!validateName(role).ok)
+        return { ok: false, error: '--role must be a valid role name' };
+    if (values['--worktree'] !== undefined && !validateName(values['--worktree']).ok) {
+        return { ok: false, error: '--worktree for prepare is a new worktree NAME (as in `borg assimilate --worktree`), not a path' };
+    }
+    return {
+        ok: true,
+        command: {
+            action,
+            coordinator,
+            role,
+            rebind,
+            ...(values['--worktree'] ? { worktreeName: values['--worktree'] } : {}),
+            ...(values['--host'] ? { host: values['--host'] } : {}),
+        },
+    };
+}
+function canonicalWorktree(path, deps) {
+    let real = resolve(path);
+    try {
+        real = realpathSync(real);
+    }
+    catch {
+        /* a missing path simply finds no binding below */
+    }
+    return deps.findProjectRoot(real);
+}
+function describeError(error) {
+    if (error instanceof RepresentativeError || error instanceof RepresentativeStoreError) {
+        return `${error.code}: ${error.message}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function sameSeat(binding, active) {
+    return active.cubeId === binding.cubeId &&
+        active.droneId === binding.representativeDroneId &&
+        active.apiUrl === binding.origin &&
+        active.serverTrustIdentity === binding.trustIdentity;
+}
+/** Load the saved binding and prove the worktree's hydrated seat is still that exact seat. Fails closed. */
+export async function resolveRepresentativeContext(worktree, deps) {
+    const binding = await deps.store.getBinding(worktree);
+    if (!binding) {
+        throw new RepresentativeError('NOT_PREPARED', `No representative connection is prepared for ${worktree}. Run \`borg representative prepare --coordinator <drone-label>\` there first.`);
+    }
+    const active = await deps.hydrateSeat(worktree);
+    if (!active) {
+        throw new RepresentativeError('SEAT_UNAVAILABLE', `The saved representative connection is missing, reset or rejected. Run \`${representativeRecoveryCommand(binding)}\`.`);
+    }
+    if (!sameSeat(binding, active)) {
+        throw new RepresentativeError('BINDING_MISMATCH', `This worktree's saved connection is not the bound server/cube/drone. Run \`${representativeRecoveryCommand(binding)}\` to confirm a rebind; nothing is sent until then.`);
+    }
+    return { binding, backend: await deps.backendFor(active), store: deps.store };
+}
+export function hermesConfigSnippet(worktree) {
+    return (`mcp_servers:\n` +
+        `  borg-representative:\n` +
+        `    command: borg\n` +
+        `    args: ["representative", "mcp", "--worktree", ${JSON.stringify(worktree)}]\n`);
+}
+export async function runRepresentativePrepare(command, deps) {
+    try {
+        // Same canonical key as status/mcp, so a symlinked cwd cannot bind under a path they never look up.
+        let worktree = canonicalWorktree(deps.cwd(), deps);
+        const existing = command.worktreeName === undefined ? await deps.hydrateSeat(worktree) : null;
+        if (existing && command.host && normalizeServerEndpoint(command.host) !== normalizeServerEndpoint(existing.apiUrl)) {
+            throw new RepresentativeError('BINDING_MISMATCH', 'The explicit --host does not match this worktree\'s saved connection. Use a worktree connected to the requested server; nothing was rebound.');
+        }
+        const prepared = await deps.prepareSeat({
+            role: command.role,
+            coordinator: command.coordinator,
+            ...(existing ? { resume: true } : {}),
+            ...(command.worktreeName ? { worktreeName: command.worktreeName } : {}),
+            ...(command.host ? { host: command.host } : {}),
+        });
+        if (prepared.code !== 0) {
+            deps.stderr('borg representative: the representative connection could not be prepared; nothing was bound.\n');
+            return prepared.code || 1;
+        }
+        if (prepared.worktree)
+            worktree = canonicalWorktree(prepared.worktree, deps);
+        const active = await deps.hydrateSeat(worktree);
+        if (!active || !active.serverTrustIdentity) {
+            throw new RepresentativeError('SEAT_UNAVAILABLE', `No usable saved connection was found for ${worktree}.`);
+        }
+        const backend = await deps.backendFor(active);
+        const me = await backend.whoami();
+        if (me.cube_id !== active.cubeId || me.drone_id !== active.droneId) {
+            throw new RepresentativeError('BINDING_MISMATCH', 'The server does not recognise this worktree\'s saved connection.');
+        }
+        const roster = await backend.roster();
+        const self = roster.drones.find((drone) => drone.id === me.drone_id);
+        const selfRole = roster.roles.find((role) => role.id === self?.role_id);
+        if (!self || !selfRole)
+            throw new RepresentativeError('SEAT_UNAVAILABLE', 'The representative drone is not active in the cube.');
+        assertRepresentativeRole(selfRole, self);
+        if (selfRole.name.toLowerCase() !== command.role.toLowerCase()) {
+            throw new RepresentativeError('REPRESENTATIVE_ROLE_MISMATCH', `This worktree's drone ${self.label} holds role ${JSON.stringify(selfRole.name)}, not ${JSON.stringify(command.role)}. ` +
+                'The representative needs its own dedicated drone. Use the preparation syntax in `borg representative --help` with an explicit Coordinator and the intended role or new worktree name.');
+        }
+        const coordinator = resolveCoordinator(roster, { label: command.coordinator, selfDroneId: me.drone_id });
+        const binding = {
+            worktree,
+            origin: active.apiUrl,
+            trustIdentity: active.serverTrustIdentity,
+            cubeId: me.cube_id,
+            cubeName: me.cube_name,
+            representativeDroneId: me.drone_id,
+            representativeLabel: me.drone_label,
+            representativeRoleName: selfRole.name,
+            coordinatorDroneId: coordinator.drone.id,
+            coordinatorLabel: coordinator.drone.label,
+            coordinatorRoleName: coordinator.role.name,
+            ...(active.repositoryOrigin ? { repositoryOrigin: active.repositoryOrigin } : {}),
+            boundAt: new Date().toISOString(),
+        };
+        const outcome = await deps.store.saveBinding(binding, { rebind: command.rebind });
+        deps.stdout(`◼ Human representative connection ${outcome === 'unchanged' ? 'resumed' : outcome}.\n` +
+            `  cube:            ${binding.cubeName} (${binding.cubeId})\n` +
+            `  representative:  ${binding.representativeLabel} — role ${binding.representativeRoleName} (not a human seat)\n` +
+            `  coordinator:     ${binding.coordinatorLabel} — role ${binding.coordinatorRoleName} (human seat)\n` +
+            `  worktree:        ${worktree}\n\n` +
+            `No agent CLI was launched. Serve it to a generic MCP host with:\n` +
+            `  borg representative mcp --worktree ${worktree}\n\n` +
+            `Example host configuration (no secrets belong here):\n${hermesConfigSnippet(worktree)}`);
+        return 0;
+    }
+    catch (error) {
+        deps.stderr(`◼ borg representative prepare: ${describeError(error)}\n`);
+        return 1;
+    }
+}
+export async function runRepresentativeStatus(command, deps) {
+    try {
+        const worktree = canonicalWorktree(command.worktree ?? deps.cwd(), deps);
+        const ctx = await resolveRepresentativeContext(worktree, deps);
+        const status = await representativeStatus(ctx);
+        const { representativeOwnership } = await import('./representative-owner.js');
+        const ownership = await representativeOwnership(ctx.binding);
+        deps.stdout(`${JSON.stringify({ ...status, ownership }, null, 2)}\n`);
+        return status.connected ? 0 : 1;
+    }
+    catch (error) {
+        deps.stderr(`◼ borg representative status: ${describeError(error)}\n`);
+        return 1;
+    }
+}
+/**
+ * Serve the stdio facade. The binding selection is captured at startup; a later
+ * operator rebind is NOT picked up by a running process — calls fail closed
+ * until the host restarts it.
+ */
+export async function runRepresentativeMcp(command, deps, io) {
+    let worktree;
+    let pinned;
+    try {
+        worktree = canonicalWorktree(command.worktree ?? deps.cwd(), deps);
+        pinned = (await resolveRepresentativeContext(worktree, deps)).binding;
+        const active = await deps.hydrateSeat(worktree);
+        if (active)
+            io.pinSeat?.(active);
+    }
+    catch (error) {
+        // stdout is reserved for JSON-RPC frames; refuse to start on stderr only.
+        deps.stderr(`◼ borg representative mcp: ${describeError(error)}\n`);
+        return 1;
+    }
+    const { serveRepresentativeMcp } = await import('./representative-mcp.js');
+    const served = await serveRepresentativeMcp({
+        version: io.version,
+        heartbeatIntervalMs: io.heartbeatIntervalMs,
+        ...(io.stdin ? { stdin: io.stdin } : {}),
+        ...(io.stdout ? { stdout: io.stdout } : {}),
+        context: async () => {
+            const ctx = await resolveRepresentativeContext(worktree, deps);
+            if (ctx.binding.cubeId !== pinned.cubeId ||
+                ctx.binding.coordinatorDroneId !== pinned.coordinatorDroneId ||
+                ctx.binding.representativeDroneId !== pinned.representativeDroneId) {
+                throw new RepresentativeError('BINDING_MISMATCH', 'The operator changed this connection\'s cube or Coordinator while it was running. Restart the MCP server to use the new binding.');
+            }
+            return ctx;
+        },
+    });
+    const stdin = io.stdin ?? process.stdin;
+    stdin.once('end', () => { void served.close(); });
+    await served.closed;
+    return 0;
+}
+export async function buildDefaultRepresentativeDeps() {
+    const [{ findProjectRoot, getActiveCubeForWorktree }, { createSeatBackend }, { createRepresentativeStore }] = await Promise.all([
+        import('./cubes.js'),
+        import('./representative-core.js'),
+        import('./representative-store.js'),
+    ]);
+    return {
+        cwd: () => process.cwd(),
+        findProjectRoot,
+        hydrateSeat: (worktree) => getActiveCubeForWorktree(worktree),
+        prepareSeat: async ({ role, coordinator, worktreeName, host, resume }) => {
+            const [{ prepareConnection }, { buildDefaultAssimilateDeps }] = await Promise.all([
+                import('./assimilate-cmd.js'),
+                import('./assimilate-deps.js'),
+            ]);
+            let worktree;
+            const code = await prepareConnection({ role, flags: { ...(resume ? { here: true } : {}), ...(worktreeName ? { worktree: worktreeName } : {}), ...(host ? { server: host } : {}) } }, buildDefaultAssimilateDeps(), {
+                validateRole: assertRepresentativeRole,
+                onPrepared: (prepared) => { worktree = prepared.worktree; },
+                authoritySelectionCommand: 'borg representative prepare --host <host>' +
+                    (coordinator ? ` --coordinator ${shellEscape(coordinator)}` : '') +
+                    ` --role ${shellEscape(role)}` +
+                    (worktreeName ? ` --worktree ${shellEscape(worktreeName)}` : ''),
+            });
+            return { code, ...(worktree ? { worktree } : {}) };
+        },
+        backendFor: createSeatBackend,
+        store: createRepresentativeStore(),
+        stdout: (text) => { process.stdout.write(text); },
+        stderr: (text) => { process.stderr.write(text); },
+    };
+}
+//# sourceMappingURL=representative-cmd.js.map

package/dist/representative-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"representative-cmd.js","sourceRoot":"","sources":["../src/representative-cmd.ts"],"names":[],"mappings":"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"}

package/dist/representative-core.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Human representative core ("Hermes"): a SEPARATE, non-human-seat drone that
+ * relays the human's requests, questions and decisions to ONE explicitly bound
+ * Coordinator drone and reads that Coordinator's replies.
+ *
+ * It is not the Coordinator and carries none of its playbook: it cannot address
+ * workers, broadcast, or manage the cube. Every message is attributed as an
+ * automated relay and states whether the content is user-authorized or the
+ * model's own advice. Borg does not verify that claim — it is delegate
+ * messaging, not server-enforced per-message human authority.
+ *
+ * The backend is injected so the same logic runs against the real seat-scoped
+ * client (`createSeatBackend`) or a controlled test double.
+ */
+import { ErrorCode, type Role, type RosterDrone as ProtocolDrone, type EnrichedStreamEntry, type DocumentCitation } from 'borgmcp-shared/protocol';
+import type { ActiveCube } from './cubes.js';
+import { type RepresentativeBinding, type RepresentativeStore } from './representative-store.js';
+export declare const REPRESENTATIVE_MESSAGE_LIMIT_BYTES = 3000;
+export declare const REPRESENTATIVE_DELIVERY_NOTE: string;
+export type RepresentativeErrorCode = typeof ErrorCode.INVALID_INPUT | 'DECISION_REQUIRES_USER_AUTHORIZATION' | 'REQUEST_ID_CONFLICT' | 'AMBIGUOUS_SEND_UNRESOLVED' | 'SEND_REJECTED' | 'REPRESENTATIVE_OWNERSHIP_REQUIRED' | 'NOT_PREPARED' | 'SEAT_UNAVAILABLE' | 'BINDING_MISMATCH' | 'BINDING_CONFLICT' | 'COORDINATOR_NOT_FOUND' | 'COORDINATOR_AMBIGUOUS' | 'COORDINATOR_NOT_HUMAN_SEAT' | 'COORDINATOR_IS_SELF' | 'COORDINATOR_UNAVAILABLE' | 'REPRESENTATIVE_ROLE_NOT_PERMITTED' | 'REPRESENTATIVE_ROLE_MISMATCH' | 'NOT_A_COORDINATOR_REPLY';
+export interface RepresentativeErrorDetails {
+    owner?: import('./stream-owner.js').StreamOwnershipSnapshot;
+    request_id?: string;
+    cause_code?: string;
+    cause_message?: string;
+    recovery?: string;
+}
+export declare class RepresentativeError extends Error {
+    readonly code: RepresentativeErrorCode;
+    readonly details?: RepresentativeErrorDetails | undefined;
+    constructor(code: RepresentativeErrorCode, message: string, details?: RepresentativeErrorDetails | undefined);
+}
+type RosterRole = Pick<Role, 'id' | 'name' | 'is_human_seat' | 'role_class'>;
+type RosterDrone = Pick<ProtocolDrone, 'id' | 'label' | 'role_id' | 'is_queen_class'>;
+type LogEntry = Pick<EnrichedStreamEntry, 'id' | 'drone_id' | 'message' | 'visibility' | 'created_at' | 'recipient_drone_ids' | 'documents'>;
+/** The only Borg operations the representative may perform, all seat-scoped. */
+export interface RepresentativeBackend {
+    whoami(): Promise<{
+        cube_id: string;
+        cube_name: string;
+        drone_id: string;
+        drone_label: string;
+        role_id: string;
+        role_name: string;
+    }>;
+    roster(): Promise<{
+        drones: RosterDrone[];
+        roles: RosterRole[];
+    }>;
+    /**
+     * MUST make a single transport attempt and surface the client's typed errors
+     * unchanged: a typed 4xx/401/410 refusal is reported as "not stored" only
+     * because no hidden retry can sit between a committed write and that answer.
+     */
+    append(input: {
+        postId: string;
+        message: string;
+        to: string[];
+    }): Promise<{
+        entry: LogEntry;
+        deduplicated: boolean;
+        unreachableRecipients?: Array<{
+            id: string;
+            label: string;
+        }>;
+    }>;
+    /**
+     * Drains THIS seat's own unread cursor only (no other drone's cursor exists
+     * here) — the WHOLE returned page, including entries the caller then filters
+     * out. `limit` is a page-size hint: the client's digest mode may return more.
+     */
+    readUnread(limit?: number, continuationGuard?: () => Promise<void>): Promise<{
+        entries: LogEntry[];
+        has_more?: boolean;
+    }>;
+    readEntry(entryId: string): Promise<{
+        entry: LogEntry;
+    }>;
+    ack(entryId: string): Promise<void>;
+}
+export interface RepresentativeContext {
+    binding: RepresentativeBinding;
+    backend: RepresentativeBackend;
+    store: RepresentativeStore;
+    now?: () => Date;
+}
+/** Real backend: the existing seat-scoped client calls for one hydrated seat. */
+export declare function createSeatBackend(active: ActiveCube): Promise<RepresentativeBackend>;
+export declare function assertRepresentativeRole(role: {
+    name: string;
+    is_human_seat?: boolean;
+    role_class?: string;
+}, drone?: {
+    is_queen_class?: boolean;
+}): void;
+/**
+ * Resolve the ONE Coordinator drone the operator named. Exact label match only;
+ * a missing, duplicated, non-human-seat or self target fails — no fallback.
+ */
+export declare function resolveCoordinator(roster: {
+    drones: RosterDrone[];
+    roles: RosterRole[];
+}, selector: {
+    label: string;
+    selfDroneId: string;
+}): {
+    drone: RosterDrone;
+    role: RosterRole;
+};
+export type RepresentativeKind = 'request' | 'question' | 'decision';
+export type RepresentativeAuthorization = 'user_authorized' | 'model_advice';
+export interface RepresentativeSendInput {
+    request_id?: string;
+    kind: RepresentativeKind;
+    authorization: RepresentativeAuthorization;
+    message: string;
+}
+export interface RepresentativeSendResult {
+    outcome: 'sent' | 'ambiguous';
+    request_id: string;
+    entry_id?: string;
+    /** True when the server recognised the post id and stored nothing new. */
+    deduplicated?: boolean;
+    /** True when the local ledger already held this exact sent request; no network call was made. */
+    duplicate?: boolean;
+    coordinator: {
+        drone_id: string;
+        label: string;
+    };
+    warning?: string;
+    /** Ambiguous only: the sanitized underlying failure. */
+    cause?: SendFailureCause;
+    guidance?: string;
+}
+export declare function formatRepresentativeMessage(binding: RepresentativeBinding, requestId: string, input: RepresentativeSendInput): string;
+export interface SendFailureCause {
+    /** Stable, bounded cause code — a typed server/protocol code where one exists. */
+    code: string;
+    /** Sanitized, bounded underlying message. Never a credential: client errors carry none. */
+    message: string;
+}
+export declare function sendRepresentativeMessage(ctx: RepresentativeContext, raw: unknown): Promise<RepresentativeSendResult>;
+export interface RepresentativeReply {
+    documents?: DocumentCitation[];
+    document_delivery?: string;
+    entry_id: string;
+    created_at: string;
+    from_drone_id: string;
+    from_label: string;
+    addressed: 'direct' | 'broadcast';
+    /** A ledger request id quoted in the reply text. Textual correlation only. */
+    in_reply_to: string | null;
+    message: string;
+}
+export declare function readRepresentativeReplies(ctx: RepresentativeContext, raw: unknown): Promise<{
+    replies: RepresentativeReply[];
+    ignored_entries: number;
+    has_more: boolean;
+    delivery: string;
+}>;
+export declare function ackRepresentativeReply(ctx: RepresentativeContext, raw: unknown): Promise<{
+    acknowledged: string;
+}>;
+export declare function representativeStatus(ctx: RepresentativeContext): Promise<{
+    role: string;
+    connected: boolean;
+    problem?: {
+        code: string;
+        message: string;
+    };
+    cube: {
+        id: string;
+        name: string;
+    };
+    repository_origin: string | null;
+    worktree: string;
+    representative: {
+        drone_id: string;
+        label: string;
+        role: string;
+    };
+    coordinator: {
+        drone_id: string;
+        label: string;
+        role: string;
+    };
+    unresolved_requests: Array<{
+        request_id: string;
+        state: string;
+        kind: string;
+        updated_at: string;
+    }>;
+    delivery: string;
+    authority: string;
+}>;
+export {};
+//# sourceMappingURL=representative-core.d.ts.map

package/dist/representative-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"representative-core.d.ts","sourceRoot":"","sources":["../src/representative-core.ts"],"names":[],"mappings":"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"}