claude-flow 3.15.0 → 3.16.1

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/business-pod-tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Business-pod MCP tools — ADR-164 Phase 2 + Phase 3.
+ *
+ * Phase 2 surfaces pod-template validation (`business_pod_validate`).
+ * Phase 3 adds the domain-affinity routing decision (`business_pod_route_backend`)
+ * so any caller (agent, /loop driver, CI workflow) can ask "which backend
+ * should @metaharness/router prefer for this pod?" without re-implementing
+ * the §3.4 rules. The decision is structural and deterministic — no learned
+ * weights, no schedule, just (preferLocalExecution, budgetUsdMonthly).
+ *
+ * Both tools accept either a pod template *object* or a string *path* to a
+ * JSON file. The path form is provided so /loop drivers can avoid loading
+ * the template themselves; the object form is for callers that already have
+ * the validated template in hand.
+ *
+ * @module @claude-flow/cli/mcp-tools/business-pod
+ */
+import type { MCPTool } from './types.js';
+export declare const businessPodTools: MCPTool[];
+//# sourceMappingURL=business-pod-tools.d.ts.map

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

@@ -0,0 +1,169 @@
+/**
+ * Business-pod MCP tools — ADR-164 Phase 2 + Phase 3.
+ *
+ * Phase 2 surfaces pod-template validation (`business_pod_validate`).
+ * Phase 3 adds the domain-affinity routing decision (`business_pod_route_backend`)
+ * so any caller (agent, /loop driver, CI workflow) can ask "which backend
+ * should @metaharness/router prefer for this pod?" without re-implementing
+ * the §3.4 rules. The decision is structural and deterministic — no learned
+ * weights, no schedule, just (preferLocalExecution, budgetUsdMonthly).
+ *
+ * Both tools accept either a pod template *object* or a string *path* to a
+ * JSON file. The path form is provided so /loop drivers can avoid loading
+ * the template themselves; the object form is for callers that already have
+ * the validated template in hand.
+ *
+ * @module @claude-flow/cli/mcp-tools/business-pod
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { validatePodTemplate, PodTemplateValidationError, KNOWN_AGENT_TYPES, } from '../business-pods/pod-schema.js';
+import { selectAgentBackend, } from '../business-pods/domain-affinity-policy.js';
+/**
+ * Load a pod template from either an in-memory object or a JSON-file path.
+ * Returns either the parsed (unvalidated) JSON or an `error` shape suitable
+ * for direct return from an MCP handler.
+ */
+function loadTemplate(input) {
+    if (input.podTemplate !== undefined && input.podTemplate !== null) {
+        if (typeof input.podTemplate !== 'object' || Array.isArray(input.podTemplate)) {
+            return { ok: false, error: 'podTemplate must be a JSON object', path: '/podTemplate' };
+        }
+        return { ok: true, raw: input.podTemplate };
+    }
+    if (typeof input.podTemplatePath === 'string' && input.podTemplatePath.length > 0) {
+        const abs = isAbsolute(input.podTemplatePath)
+            ? input.podTemplatePath
+            : resolve(process.cwd(), input.podTemplatePath);
+        if (!existsSync(abs)) {
+            return { ok: false, error: `pod template file not found: ${abs}`, path: '/podTemplatePath' };
+        }
+        try {
+            const raw = JSON.parse(readFileSync(abs, 'utf-8'));
+            return { ok: true, raw };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { ok: false, error: `failed to parse pod template JSON: ${msg}`, path: '/podTemplatePath' };
+        }
+    }
+    return {
+        ok: false,
+        error: 'either podTemplate (object) or podTemplatePath (string) must be provided',
+        path: '/',
+    };
+}
+export const businessPodTools = [
+    {
+        name: 'business_pod_validate',
+        description: 'ADR-164 Phase 2 — Validate a business-pod template JSON against the schema in ADR-164 §3.3 (name, agents[], allowedMcpTools, bench, piiPolicy, budgets, cronSchedule, auditReadView, reservationExpiryMs bounded by ADR-164.1 §3.2). Use when a /loop driver or CI workflow needs to pre-flight a pod template before pod-tick.mjs reaches it — surfacing validation as JSON keeps the optional-dep degraded path clean. Hand-parsing the JSON in the caller is wrong because it skips the JSON-pointer error path and the reservationExpiryMs [5000, 300000] ms bound check that ADR-164.1 mandates. Pair with business_pod_validate -> pod-tick.mjs in the sales-pod smoke contract.',
+        category: 'business-pods',
+        tags: ['business-pods', 'pod-template', 'validation', 'adr-164', 'adr-164.1'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                podTemplate: {
+                    type: 'object',
+                    description: 'The pod template object to validate. Must conform to the PodTemplate interface from ADR-164 §3.3.',
+                },
+            },
+            required: ['podTemplate'],
+        },
+        handler: async (input) => {
+            if (typeof input.podTemplate !== 'object' || input.podTemplate === null) {
+                return {
+                    success: false,
+                    valid: false,
+                    error: 'podTemplate must be a JSON object',
+                    path: '/',
+                };
+            }
+            try {
+                const template = validatePodTemplate(input.podTemplate);
+                // Lightweight agent-type sanity check — surface unknown types as a
+                // warning rather than a hard failure so operators can prototype with
+                // not-yet-registered roles. pod-tick.mjs enforces the hard check.
+                const unknownAgents = template.agents
+                    .map((a) => a.agentType)
+                    .filter((t) => !KNOWN_AGENT_TYPES.includes(t));
+                return {
+                    success: true,
+                    valid: true,
+                    template,
+                    warnings: unknownAgents.length > 0
+                        ? [`unknown agent types (pod-tick.mjs will reject): ${unknownAgents.join(', ')}`]
+                        : [],
+                };
+            }
+            catch (err) {
+                if (err instanceof PodTemplateValidationError) {
+                    return {
+                        success: false,
+                        valid: false,
+                        error: err.message,
+                        path: err.path,
+                    };
+                }
+                throw err;
+            }
+        },
+    },
+    {
+        name: 'business_pod_route_backend',
+        description: 'ADR-164 Phase 3 — Compute the domain-affinity routing decision for a business pod per ADR-164 §3.4 and return {backend, reason}. The three backends are local-stdio (preferLocalExecution=true), cloud-managed (preferLocalExecution=false AND budgetUsdMonthly >= 50), and remote-peer (everything else — small-budget non-local pods route through a federation peer node). Use when a /loop driver, @metaharness/router policy hook, or operator CLI needs the structural routing pick BEFORE the cost-optimal KRR step — surfacing this as an MCP tool keeps the rule auditable from the pod template alone and lets non-TS callers reach it. Re-implementing the rule in the caller is wrong because it forks the §3.4 source-of-truth and skips the {success,valid,error,path} envelope shape callers already rely on from business_pod_validate. Pair with business_pod_validate when pre-flighting a template, since this tool also runs full schema validation and degrades to the same error shape on malformed input. Threshold lives in CLOUD_BUDGET_THRESHOLD_USD in domain-affinity-policy.ts — keep that constant and this description aligned.',
+        category: 'business-pods',
+        tags: ['business-pods', 'pod-template', 'routing', 'domain-affinity', 'adr-164'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                podTemplate: {
+                    type: 'object',
+                    description: 'In-memory pod template object. One of podTemplate or podTemplatePath is required.',
+                },
+                podTemplatePath: {
+                    type: 'string',
+                    description: 'Absolute or cwd-relative path to a pod template JSON file. One of podTemplate or podTemplatePath is required.',
+                },
+            },
+        },
+        handler: async (input) => {
+            const loaded = loadTemplate(input);
+            if (!loaded.ok) {
+                return {
+                    success: false,
+                    valid: false,
+                    error: loaded.error,
+                    path: loaded.path,
+                };
+            }
+            let template;
+            try {
+                template = validatePodTemplate(loaded.raw);
+            }
+            catch (err) {
+                if (err instanceof PodTemplateValidationError) {
+                    return {
+                        success: false,
+                        valid: false,
+                        error: err.message,
+                        path: err.path,
+                    };
+                }
+                throw err;
+            }
+            const decision = selectAgentBackend(template);
+            return {
+                success: true,
+                valid: true,
+                backend: decision.backend,
+                reason: decision.reason,
+                pod: {
+                    name: template.name,
+                    preferLocalExecution: template.preferLocalExecution,
+                    budgetUsdMonthly: template.budgetUsdMonthly,
+                },
+            };
+        },
+    },
+];
+//# sourceMappingURL=business-pod-tools.js.map

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

@@ -0,0 +1,55 @@
+/**
+ * http_fetch MCP tool — ADR-164 §5.1.8.
+ *
+ * The Operations business pod (templates/ops.json) references `http_fetch` as
+ * an allowed MCP tool for the synthetic-endpoint availability bench (probe
+ * 200/500 from a configured URL, escalate to #ops on 500-rate spikes).
+ * Phase 3 left this as a TODO; Phase 4 ships the tool with secure-by-default
+ * gating per the §5.1.8 contract: URL allowlist (no file://, ftp://, no
+ * RFC-1918 / loopback unless explicitly enabled), header sanitization (no
+ * auth pass-through unless explicitly enabled), hard timeout via
+ * AbortController, response truncation, default User-Agent.
+ *
+ * Architectural constraints (load-bearing):
+ *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in)
+ *   - DEFAULT-REFUSES Authorization / Cookie / X-Auth-* (CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH=1 opt-in)
+ *   - hard timeout 30s default, 60s ceiling
+ *   - response truncated to 256KB default, 1MB ceiling
+ *   - no redirects auto-followed beyond fetch's default; status reported as-is
+ *
+ * @module @claude-flow/cli/mcp-tools/http-fetch
+ */
+import type { MCPTool } from './types.js';
+export declare class HttpFetchValidationError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Decide whether the URL is permitted under the default secure-by-default
+ * allowlist. Block file://, ftp://, RFC-1918 private addresses, loopback,
+ * link-local — unless CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 is set.
+ */
+export declare function validateUrl(rawUrl: string): URL;
+export declare function validateHeaders(headers: Record<string, string>): Record<string, string>;
+export interface HttpFetchResult {
+    success: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    bodyTruncated: boolean;
+    bytesRead: number;
+    durationMs: number;
+    url: string;
+    method: string;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Pure execution path so tests can call it without going through the MCP
+ * dispatcher. Returns a result object (does not throw on validation failure
+ * — it returns success: false with an errorCode).
+ */
+export declare function httpFetchExecute(input: Record<string, unknown>): Promise<HttpFetchResult>;
+export declare const httpFetchTools: MCPTool[];
+//# sourceMappingURL=http-fetch-tools.d.ts.map