claude-flow 3.14.4 → 3.16.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-tools.js

@@ -0,0 +1,394 @@
+/**
+ * AgentBBS MCP Tools — Federated business-domain BBS room surface (ADR-164 Phase 1).
+ *
+ * Exposes the `agentbbs@~0.1.0` (a sibling BBS-style federation peer by the same
+ * author as ruflo) as MCP tools so ruflo agents can register business rooms
+ * (#sales, #finance, #marketing, ...), publish/watch typed envelopes, and
+ * mint single-use human-join tokens for SSH/web cockpit access.
+ *
+ * Motivation:
+ *   ADR-164 wires the "business autopilot" cockpit on top of the existing
+ *   ruflo federation primitives (FederationEnvelope, PII pipeline, budget
+ *   circuit breaker). The 4 tools here are the ruflo-side handles into the
+ *   agentbbs Rust workspace (`crates/agentbbs-federation/` and
+ *   `crates/agentbbs-mcp/`) that already implement Ed25519-signed envelopes
+ *   and an MCP transport. Phase 1 ships the surface; Phases 2-5 wire deeper.
+ *
+ * Architectural constraint (mirrors metaharness-tools.ts / agenticow-tools.ts):
+ *   - `agentbbs` lives in `optionalDependencies` — must NOT be a hard runtime dep
+ *   - When the package is missing, every tool returns
+ *     `{success: true, degraded: true, reason: 'agentbbs-not-found'}`
+ *     so callers see one contract regardless of install state
+ *   - Phase 1: polling-based watch (streaming subscriptions are Phase 4)
+ *
+ * @module @claude-flow/cli/mcp-tools/agentbbs
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { resolve, isAbsolute, join } from 'node:path';
+import { randomBytes, createHash } from 'node:crypto';
+import { getProjectCwd } from './types.js';
+const PACKAGE_NAME = 'agentbbs';
+// Cache: amortize dynamic-import cost across handler calls.
+// null = not yet attempted; false = unavailable; module = loaded.
+let _agentbbsMod = null;
+let _loadAttempted = false;
+async function loadAgentbbs() {
+    if (_loadAttempted)
+        return _agentbbsMod || null;
+    _loadAttempted = true;
+    try {
+        _agentbbsMod = await import(PACKAGE_NAME);
+        return _agentbbsMod;
+    }
+    catch (err) {
+        if (err && (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND' ||
+            /Cannot find (module|package)/i.test(String(err?.message)))) {
+            _agentbbsMod = false;
+            return null;
+        }
+        throw err;
+    }
+}
+function degradedResult(reason) {
+    return { success: true, degraded: true, reason };
+}
+function resolveBasePath(input) {
+    const p = input && typeof input === 'string' && input.length > 0
+        ? input
+        : '.agentbbs';
+    if (/\.\.[\\/]|\0/.test(p))
+        throw new Error('basePath contains disallowed characters');
+    const abs = isAbsolute(p) ? p : resolve(getProjectCwd(), p);
+    return abs;
+}
+function validateRoomLabel(label) {
+    if (!label || typeof label !== 'string')
+        throw new Error('roomLabel is required');
+    if (label.length > 128)
+        throw new Error('roomLabel exceeds 128 chars');
+    // Rooms are conventionally `#sales`, `#finance`, etc. — keep `#` in the allow-list.
+    if (!/^[A-Za-z0-9_.\-:/@#]+$/.test(label)) {
+        throw new Error('roomLabel may only contain [A-Za-z0-9_.\\-:/@#]');
+    }
+    return label;
+}
+function validateRoomId(roomId) {
+    if (!roomId || typeof roomId !== 'string')
+        throw new Error('roomId is required');
+    if (roomId.length > 128)
+        throw new Error('roomId exceeds 128 chars');
+    if (!/^[A-Za-z0-9_.\-:/@#]+$/.test(roomId)) {
+        throw new Error('roomId may only contain [A-Za-z0-9_.\\-:/@#]');
+    }
+    return roomId;
+}
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function roomIdFromLabel(label) {
+    // Stable, deterministic roomId — strip leading `#`, lowercase, and append a
+    // short hash so we don't collide across two rooms with the same canonical
+    // label but different policies. Phase 1: deterministic over (label).
+    const norm = label.replace(/^#/, '').toLowerCase();
+    const h = createHash('sha256').update(`agentbbs:room:${norm}`).digest('hex').slice(0, 8);
+    return `${norm}-${h}`;
+}
+function roomLogPath(basePath, roomId) {
+    return join(basePath, `room-${roomId}.jsonl`);
+}
+function roomsRegistryPath(basePath) {
+    return join(basePath, 'rooms.json');
+}
+function readEnvelopes(path) {
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf-8');
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip malformed line */ }
+    }
+    return out;
+}
+function nextSeq(path) {
+    const env = readEnvelopes(path);
+    if (env.length === 0)
+        return 1;
+    return (env[env.length - 1].seq ?? env.length) + 1;
+}
+/**
+ * Ephemeral per-process Ed25519 keypair for human-join token signing.
+ * Phase 1 contract: keys are NOT persisted across process restart — every
+ * invocation can mint tokens but cross-process replay protection is the
+ * agentbbs server's responsibility (nonce JTI tracking, per ADR-164 §3.2.4).
+ * Phase 2+ will wire this to the existing federation Ed25519 keypair.
+ */
+let _signingKey = null;
+async function getSigningKey() {
+    if (_signingKey)
+        return _signingKey;
+    // Use @noble/ed25519 (already a hard dep of @claude-flow/cli for IPFS signing).
+    const ed = await import('@noble/ed25519');
+    const priv = ed.utils.randomPrivateKey
+        ? ed.utils.randomPrivateKey()
+        : randomBytes(32);
+    const pub = await (ed.getPublicKeyAsync ?? ed.getPublicKey)(priv);
+    _signingKey = { priv, pub };
+    return _signingKey;
+}
+function base64url(buf) {
+    return Buffer.from(buf).toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+export const agentbbsTools = [
+    {
+        name: 'federation_bbs_register',
+        description: 'agentbbs@~0.1.0 — Register a BBS room as a named federation peer (ADR-164 Phase 1). Maps a business-domain label like "#sales" or "#finance" to a stable roomId and emits an attested PeerHello envelope. Use when you are scaffolding the business-autopilot cockpit and need a room handle that subsequent publish/watch calls can target. Calling FederationCoordinator.joinPeer() directly is wrong because it bypasses the room policy bag (PII mode, budget cap, preferLocal routing) that the BBS plugin layers on top. Optional dep — degrades to {degraded:true} when missing.',
+        category: 'federation',
+        tags: ['agentbbs', 'federation', 'bbs', 'register', 'adr-164'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: {
+                    type: 'string',
+                    description: 'Directory where BBS room state is persisted (defaults to <cwd>/.agentbbs).',
+                },
+                roomLabel: {
+                    type: 'string',
+                    description: 'Human-readable room label, e.g. "#sales" or "finance". May include alnum + _.-:/@# .',
+                },
+                agentbbsBin: {
+                    type: 'string',
+                    description: 'Optional explicit path to the agentbbs binary. Reserved for Phase 2 wire-up; ignored in Phase 1.',
+                },
+            },
+            required: ['roomLabel'],
+        },
+        handler: async (input) => {
+            // Validate inputs FIRST so callers see deterministic errors regardless of
+            // optional-dep state. Degradation is a runtime-state branch, not a way
+            // to mask malformed requests.
+            const roomLabel = validateRoomLabel(String(input.roomLabel));
+            const basePath = resolveBasePath(input.basePath);
+            const api = await loadAgentbbs();
+            if (!api)
+                return degradedResult('agentbbs-not-found');
+            ensureDir(basePath);
+            const roomId = roomIdFromLabel(roomLabel);
+            const registryPath = roomsRegistryPath(basePath);
+            const registry = existsSync(registryPath) ? JSON.parse(readFileSync(registryPath, 'utf-8')) : {};
+            // Idempotent — re-registering the same label updates timestamp but keeps id stable.
+            const entry = {
+                roomId,
+                roomLabel,
+                registeredAt: new Date().toISOString(),
+                trustLevel: 'attested',
+            };
+            registry[roomId] = entry;
+            writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+            // Emit a synthetic PeerHello envelope into the room log so watchers see the join.
+            const logPath = roomLogPath(basePath, roomId);
+            const env = {
+                envelopeId: base64url(randomBytes(12)),
+                roomId,
+                seq: nextSeq(logPath),
+                msgType: 'PeerHello',
+                payload: { roomLabel, trustLevel: 'attested' },
+                timestamp: entry.registeredAt,
+            };
+            appendFileSync(logPath, JSON.stringify(env) + '\n');
+            // nodeId: deterministic per (cwd, roomId) so re-registers reuse identity.
+            const nodeId = createHash('sha256')
+                .update(`agentbbs:node:${basePath}:${roomId}`)
+                .digest('hex')
+                .slice(0, 16);
+            return {
+                success: true,
+                roomId,
+                nodeId,
+                trustLevel: 'attested',
+            };
+        },
+    },
+    {
+        name: 'federation_bbs_publish',
+        description: 'agentbbs — Publish a domain event from a pod agent to a BBS room (ADR-164 Phase 1). Wraps the payload in a ReplicateMessage envelope (envelopeId, seq, ts, msgType, payload) and appends it to the room log. Use when an agent has produced a typed event (pod-status, task-result, alert, human-override-ack, bench-result) that the human cockpit or other pods need to see. Storing into raw memory_store is wrong because it skips the room-scoped budget cap, PII pipeline gating, and monotonic seq numbering that ADR-164 §3.2.2 requires. Optional dep — degrades to {degraded:true} when missing.',
+        category: 'federation',
+        tags: ['agentbbs', 'federation', 'bbs', 'publish', 'adr-164'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: {
+                    type: 'string',
+                    description: 'Directory where BBS room state is persisted (defaults to <cwd>/.agentbbs).',
+                },
+                roomId: {
+                    type: 'string',
+                    description: 'Target room identifier as returned by federation_bbs_register.',
+                },
+                msgType: {
+                    type: 'string',
+                    description: 'Typed event kind (pod-status / task-result / alert / human-override-ack / bench-result).',
+                },
+                payload: {
+                    type: 'object',
+                    description: 'Event-specific JSON-serializable payload.',
+                },
+                signature: {
+                    type: 'string',
+                    description: 'Optional Ed25519 signature over the canonical envelope bytes. Phase 1: pass-through.',
+                },
+            },
+            required: ['roomId', 'msgType', 'payload'],
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            const roomId = validateRoomId(String(input.roomId));
+            const msgType = String(input.msgType ?? '');
+            if (!msgType)
+                throw new Error('msgType is required');
+            if (msgType.length > 64 || !/^[A-Za-z0-9_-]+$/.test(msgType)) {
+                throw new Error('msgType must be alnum + _ - and ≤64 chars');
+            }
+            if (typeof input.payload !== 'object' || input.payload === null) {
+                throw new Error('payload must be a JSON object');
+            }
+            const api = await loadAgentbbs();
+            if (!api)
+                return degradedResult('agentbbs-not-found');
+            ensureDir(basePath);
+            const logPath = roomLogPath(basePath, roomId);
+            const env = {
+                envelopeId: base64url(randomBytes(12)),
+                roomId,
+                seq: nextSeq(logPath),
+                msgType,
+                payload: input.payload,
+                timestamp: new Date().toISOString(),
+                signature: input.signature ? String(input.signature) : undefined,
+            };
+            appendFileSync(logPath, JSON.stringify(env) + '\n');
+            // Phase 1: recipientHopCount is always 0 (single-node). Phase 4+ will
+            // surface real hop counts from the WG mesh transport.
+            return {
+                success: true,
+                envelopeId: env.envelopeId,
+                recipientHopCount: 0,
+            };
+        },
+    },
+    {
+        name: 'federation_bbs_watch',
+        description: 'agentbbs — Poll recent envelopes from a BBS room (ADR-164 Phase 1). Returns envelopes newer than the optional sinceEnvelopeId, up to limit. Use when a pod agent needs to see incoming human overrides, new tasks, or peer events posted to its room. Polling memory_search for the room namespace is wrong because it loses the monotonic seq ordering and re-runs PII gating per query; this tool reads the canonical envelope log directly. Phase 1 is polling — Phase 4 layers streaming on the same surface. Optional dep — degrades to {degraded:true} when missing.',
+        category: 'federation',
+        tags: ['agentbbs', 'federation', 'bbs', 'watch', 'adr-164'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: {
+                    type: 'string',
+                    description: 'Directory where BBS room state is persisted (defaults to <cwd>/.agentbbs).',
+                },
+                roomId: {
+                    type: 'string',
+                    description: 'Room identifier to watch.',
+                },
+                sinceEnvelopeId: {
+                    type: 'string',
+                    description: 'Only return envelopes strictly after this id. Omit to return the most recent window.',
+                },
+                limit: {
+                    type: 'integer',
+                    description: 'Maximum envelopes to return (default 50, max 500).',
+                },
+            },
+            required: ['roomId'],
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            const roomId = validateRoomId(String(input.roomId));
+            const api = await loadAgentbbs();
+            if (!api)
+                return degradedResult('agentbbs-not-found');
+            const limitRaw = typeof input.limit === 'number' ? input.limit : 50;
+            const limit = Math.max(1, Math.min(500, Math.trunc(limitRaw)));
+            const sinceEnvelopeId = input.sinceEnvelopeId ? String(input.sinceEnvelopeId) : undefined;
+            const logPath = roomLogPath(basePath, roomId);
+            const all = readEnvelopes(logPath);
+            let slice = all;
+            if (sinceEnvelopeId) {
+                const idx = all.findIndex(e => e.envelopeId === sinceEnvelopeId);
+                slice = idx >= 0 ? all.slice(idx + 1) : all;
+            }
+            const envelopes = slice.slice(-limit);
+            return {
+                success: true,
+                roomId,
+                envelopes,
+                count: envelopes.length,
+                hasMore: slice.length > envelopes.length,
+            };
+        },
+    },
+    {
+        name: 'federation_bbs_human_join',
+        description: 'agentbbs — Mint a single-use Ed25519-signed token a human business owner presents to the agentbbs SSH/web front door to join a room (ADR-164 §3.2.4). Returns webUrl + sshCommand + handshakeToken + expiresAt. Use when the cockpit operator needs scoped, time-limited access to a room without sharing the federation root keypair. Issuing a permanent bearer token is wrong because the agentbbs server enforces single-use JTI replay protection and the 15-min default TTL — a long-lived token defeats both. Optional dep — degrades to {degraded:true} when missing.',
+        category: 'federation',
+        tags: ['agentbbs', 'federation', 'bbs', 'human-join', 'token', 'adr-164'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                roomId: {
+                    type: 'string',
+                    description: 'Room the token authorizes.',
+                },
+                ttlSeconds: {
+                    type: 'integer',
+                    description: 'Token lifetime in seconds. Max 900 (15 min). Default 300.',
+                },
+            },
+            required: ['roomId'],
+        },
+        handler: async (input) => {
+            const roomId = validateRoomId(String(input.roomId));
+            const api = await loadAgentbbs();
+            if (!api)
+                return degradedResult('agentbbs-not-found');
+            const ttlRaw = typeof input.ttlSeconds === 'number' ? input.ttlSeconds : 300;
+            const ttlSeconds = Math.max(30, Math.min(900, Math.trunc(ttlRaw)));
+            const now = Date.now();
+            const expiresAt = new Date(now + ttlSeconds * 1000).toISOString();
+            const nonce = base64url(randomBytes(16));
+            const payload = { roomId, nonce, expiresAt };
+            const canonical = JSON.stringify(payload);
+            const ed = await import('@noble/ed25519');
+            const { priv, pub } = await getSigningKey();
+            const sigBytes = await (ed.signAsync ?? ed.sign)(new TextEncoder().encode(canonical), priv);
+            // Token format: base64url(JSON{payload, sig, pub}). Single string, easy
+            // to paste into an SSH command line. The verifier reconstructs canonical
+            // bytes from payload and checks sig against pub.
+            const token = base64url(Buffer.from(JSON.stringify({
+                payload,
+                sig: base64url(sigBytes),
+                pub: base64url(pub),
+            })));
+            const webUrl = `https://agentbbs.local/rooms/${encodeURIComponent(roomId)}?token=${token}`;
+            const sshCommand = `ssh -p 2222 agentbbs.local -- join ${roomId} ${token}`;
+            return {
+                success: true,
+                webUrl,
+                sshCommand,
+                handshakeToken: token,
+                expiresAt,
+            };
+        },
+    },
+];
+//# sourceMappingURL=agentbbs-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/agenticow-tools.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agenticow MCP Tools — Copy-On-Write memory branching surface.
+ *
+ * Exposes `agenticow@~0.2.3` (a sibling RVF-based COW vector store by the same
+ * author as ruflo) as MCP tools so agents can branch, checkpoint, rollback,
+ * and promote memory state without copying GB-scale `.rvf` files.
+ *
+ * Motivation:
+ *   The v3.14.4 release uncovered a tarball-bloat regression where Darwin
+ *   loops' git-worktree-per-agent pattern accumulated 3.3 GB of disk. The
+ *   structural cause was full-copy snapshot semantics. Measured agenticow
+ *   branches are exactly 162 bytes regardless of base size (see
+ *   `docs/agenticow/findings.md` for the bench data).
+ *
+ * Architectural constraint (mirrors metaharness-tools.ts / testgen-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — must NOT be a hard runtime dep
+ *   - When the package is missing, every tool returns
+ *     `{success: true, degraded: true, reason: 'agenticow-not-found'}`
+ *     so callers see one contract regardless of install state
+ *
+ * Measured performance vs published claims (agenticow@0.2.3):
+ *   ✅ 162-byte branches — confirmed exact
+ *   ✅ 3,000×–180,000× smaller than full-copy at N=1k–50k
+ *   ❌ 0.5 ms branch — measured ~10ms (fixed cost, not size-proportional)
+ *   ❌ 83× faster — only beats full-copy past N ≈ 30k crossover
+ *
+ * Use cases (per ADR / findings doc):
+ *   - Per-Darwin-iteration memory branching (eliminates worktree bloat)
+ *   - Per-user / per-session personalization (cheap fork, no full copy)
+ *   - Federation: branch → promote back as merge semantics
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow
+ */
+import type { MCPTool } from './types.js';
+export declare const agenticowTools: MCPTool[];
+//# sourceMappingURL=agenticow-tools.d.ts.map