claude-flow 3.14.4 → 3.16.0

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

@@ -0,0 +1,253 @@
+/**
+ * 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 { existsSync } from 'node:fs';
+import { getProjectCwd } from './types.js';
+import { resolve, isAbsolute } from 'node:path';
+const PACKAGE_NAME = 'agenticow';
+// Cache: module load is expensive enough to amortize across handler calls.
+// null = not yet attempted; false = attempted and unavailable; module = loaded.
+let _agenticowMod = null;
+let _loadAttempted = false;
+async function loadAgenticow() {
+    if (_loadAttempted)
+        return _agenticowMod;
+    _loadAttempted = true;
+    try {
+        _agenticowMod = await import(PACKAGE_NAME);
+        return _agenticowMod;
+    }
+    catch (err) {
+        if (err && (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND' ||
+            /Cannot find (module|package)/i.test(String(err.message)))) {
+            _agenticowMod = false;
+            return null;
+        }
+        throw err;
+    }
+}
+function degradedResult(reason) {
+    return { success: true, degraded: true, reason };
+}
+function resolveMemoryPath(path) {
+    if (!path || typeof path !== 'string')
+        throw new Error('memory path is required');
+    // D-2 style: reject path traversal in user-supplied paths
+    if (/\.\.[\\/]|\0/.test(path))
+        throw new Error('memory path contains disallowed characters');
+    return isAbsolute(path) ? path : resolve(getProjectCwd(), path);
+}
+/**
+ * Lineage manifest companion path. agenticow persists the COW chain
+ * (working → checkpoints → base) into `<file>.agenticow.json` next to the
+ * `.rvf` data file. Without this, checkpoints and forks are in-memory only
+ * and disappear when the AgenticMemory handle closes. Mirrors the bin
+ * CLI's `manifestFor(file)` helper.
+ */
+function manifestFor(file) {
+    return `${file}.agenticow.json`;
+}
+function validateLabel(label) {
+    if (!label || typeof label !== 'string')
+        throw new Error('label is required');
+    if (label.length > 256)
+        throw new Error('label exceeds 256 chars');
+    if (!/^[A-Za-z0-9_.\-:/@]+$/.test(label)) {
+        throw new Error('label may only contain [A-Za-z0-9_.\\-:/@]');
+    }
+    return label;
+}
+/**
+ * Open (or create) a base memory file. When a lineage manifest exists at
+ * `<file>.agenticow.json`, we load that to restore the COW chain (checkpoints,
+ * ancestors). When only the `.rvf` exists, fresh-open it. When neither exists,
+ * dimension is required to create. Mirrors the bin CLI's `loadMem()` helper.
+ */
+async function openWithLineage(api, file, dimension) {
+    const manifest = manifestFor(file);
+    if (existsSync(manifest)) {
+        // The class-level static method `load` reconstructs the full chain.
+        return api.AgenticMemory.load(manifest);
+    }
+    const opts = {};
+    if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {
+        opts.dimension = dimension;
+    }
+    else if (!existsSync(file)) {
+        throw new Error('dimension is required when creating a new memory file');
+    }
+    return api.open(file, opts);
+}
+export const agenticowTools = [
+    {
+        name: 'agenticow_branch',
+        description: 'agenticow@~0.2.3 — COW-fork a base .rvf memory file. Measured 162-byte branches regardless of base size (verified at N=1k/10k/50k). Use when you need per-Darwin-iteration / per-user / per-session memory personalization. Copying the parent .rvf file is wrong because full-copy snapshots grow linearly (the 3.3 GB Darwin-worktree bloat fixed in v3.14.4); agenticow gives read-through semantics (parent ∪ edits, child wins) at constant 162 B. Optional dep — degrades to {degraded:true} when missing.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'branch'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: { type: 'string', description: 'Path to base .rvf memory file (absolute or relative to cwd)' },
+                branchPath: { type: 'string', description: 'Path to write the branch file' },
+                label: { type: 'string', description: 'Human-readable label for the branch (alnum + _.-:/@ only)' },
+                dimension: { type: 'integer', description: 'Vector dimension (required only when basePath does not exist yet)' },
+            },
+            required: ['basePath', 'branchPath', 'label'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const label = validateLabel(String(input.label));
+            const basePath = resolveMemoryPath(String(input.basePath));
+            const branchPath = resolveMemoryPath(String(input.branchPath));
+            const dim = input.dimension;
+            const base = await openWithLineage(api, basePath, dim);
+            try {
+                const branch = await base.fork(label, branchPath);
+                // Persist lineage manifests so the branch (and base) reopen with
+                // their COW chain intact. Without this, fork is in-memory only.
+                await branch.save?.(manifestFor(branchPath));
+                await base.save?.(manifestFor(basePath));
+                await branch.close?.();
+                return {
+                    success: true,
+                    basePath,
+                    branchPath,
+                    label,
+                };
+            }
+            finally {
+                await base.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_checkpoint',
+        description: 'agenticow — freeze a labelled restore point on an .rvf memory file. Subsequent edits stay in a fresh COW child; rollback returns here. Use when you are about to run an experimental Darwin tick or speculative agent edit that may need to be discarded. Relying on the working node alone is wrong because there is no "undo last N writes" semantics — without a checkpoint, a bad ingest contaminates the base. Persists via .agenticow.json lineage manifest so it survives close+reopen.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'checkpoint'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+                label: { type: 'string', description: 'Checkpoint label (alnum + _.-:/@ only)' },
+            },
+            required: ['path', 'label'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const label = validateLabel(String(input.label));
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const cp = await mem.checkpoint(label);
+                await mem.save?.(manifestFor(path));
+                return { success: true, path, label, checkpoint: cp };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_rollback',
+        description: 'agenticow — discard all edits since the most recent checkpoint on an .rvf memory file. Reuses a fresh COW child derived from the checkpoint. Use when a Darwin tick or agent experiment regressed and you want to revert memory state without re-running. Deleting+rebuilding the .rvf is wrong because rebuild cost is O(N) and the data after the bad point is lost; rollback is O(edits-since-checkpoint) and the earlier history stays intact via the lineage manifest.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'rollback'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const r = await mem.rollback();
+                await mem.save?.(manifestFor(path));
+                return { success: true, path, rolledBack: true, result: r };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_promote',
+        description: 'agenticow — merge a branch\'s edits back into its base (or an explicit target) memory file. After promote, branch edits become part of base lineage. Use when a per-user / per-Darwin-iteration branch has been validated and should graduate to shared memory (federation merge, A/B winner). Manually re-ingesting edits into the base is wrong because the edit set is opaque to the caller and tombstones (deletions) are easily missed; promote applies the full edit + tombstone set atomically.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'promote', 'merge'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                branchPath: { type: 'string', description: 'Path to branch .rvf file' },
+                basePath: {
+                    type: 'string',
+                    description: 'Path to base .rvf file. When omitted, promote merges into the ' +
+                        'recorded fork parent (most common case).',
+                },
+            },
+            required: ['branchPath'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const branchPath = resolveMemoryPath(String(input.branchPath));
+            const basePath = input.basePath ? resolveMemoryPath(String(input.basePath)) : undefined;
+            const branch = await openWithLineage(api, branchPath);
+            const base = basePath ? await openWithLineage(api, basePath) : undefined;
+            try {
+                const result = base ? await branch.promote(base) : await branch.promote();
+                // Persist mutated lineage so promote survives close+reopen
+                await branch.save?.(manifestFor(branchPath));
+                if (base && basePath)
+                    await base.save?.(manifestFor(basePath));
+                return { success: true, branchPath, basePath: basePath ?? null, promoted: result ?? true };
+            }
+            finally {
+                await branch.close?.();
+                await base?.close?.();
+            }
+        },
+    },
+];
+//# sourceMappingURL=agenticow-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