claude-flow 3.20.0 → 3.21.0

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

@@ -0,0 +1,24 @@
+/**
+ * agenticow speculate — MCP surface for speculative branch-and-promote
+ * (agenticow step 4).
+ *
+ * Exposes the `SpeculativeExploration` module as a single MCP tool
+ * `agenticow_speculate` so agents can drive parallel A/B memory exploration:
+ * fan out N candidate ingest-sets, each on its own 162-byte COW branch of a
+ * shared base `.rvf`, score them by a probe query, PROMOTE the winner into
+ * base, and DISCARD the losers (delete their branch files).
+ *
+ * Because MCP inputs are JSON (not JS functions), candidates are DECLARATIVE:
+ * each candidate is a label + a set of vectors to ingest, and scoring is a
+ * probe query (`nearest`) or an ingest count (`count`). The generic
+ * `explore(base, {label, fn}[], score)` core does the real work.
+ *
+ * Optional-dep contract (mirrors agenticow-tools.ts): when `agenticow` is not
+ * installed the tool returns `{success:true, degraded:true,
+ * reason:'agenticow-not-found'}` and never throws for that reason.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-speculate
+ */
+import type { MCPTool } from './types.js';
+export declare const agenticowSpeculateTools: MCPTool[];
+//# sourceMappingURL=agenticow-speculate-tools.d.ts.map

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

@@ -0,0 +1,202 @@
+/**
+ * agenticow speculate — MCP surface for speculative branch-and-promote
+ * (agenticow step 4).
+ *
+ * Exposes the `SpeculativeExploration` module as a single MCP tool
+ * `agenticow_speculate` so agents can drive parallel A/B memory exploration:
+ * fan out N candidate ingest-sets, each on its own 162-byte COW branch of a
+ * shared base `.rvf`, score them by a probe query, PROMOTE the winner into
+ * base, and DISCARD the losers (delete their branch files).
+ *
+ * Because MCP inputs are JSON (not JS functions), candidates are DECLARATIVE:
+ * each candidate is a label + a set of vectors to ingest, and scoring is a
+ * probe query (`nearest`) or an ingest count (`count`). The generic
+ * `explore(base, {label, fn}[], score)` core does the real work.
+ *
+ * Optional-dep contract (mirrors agenticow-tools.ts): when `agenticow` is not
+ * installed the tool returns `{success:true, degraded:true,
+ * reason:'agenticow-not-found'}` and never throws for that reason.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-speculate
+ */
+import { loadAgenticow, degradedResult, resolveMemoryPath, openWithLineage, manifestFor, validateLabel, } from './agenticow-loader.js';
+import { explore, } from '../agenticow/speculative-exploration.js';
+/** Turn a validated label into a filesystem-safe branch filename segment. */
+function safeSegment(label) {
+    return label.replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 64) || 'branch';
+}
+export const agenticowSpeculateTools = [
+    {
+        name: 'agenticow_speculate',
+        description: "agenticow — speculative branch-and-promote for parallel A/B memory exploration. " +
+            "Forks a 162-byte COW branch per candidate off a shared base .rvf, ingests each candidate's " +
+            "vectors into its OWN isolated branch, scores every branch (probe-query 'nearest' distance or " +
+            "ingest 'count'), PROMOTES the winning branch's edits into base, and DISCARDS the losers by " +
+            "deleting their branch files. Use when you want to try N competing memory-write strategies and " +
+            "keep only the best — the memory-state analogue of worktree-per-agent code exploration. " +
+            "Copying the base per candidate is wrong (full-copy snapshots grow linearly, the 3.3 GB Darwin " +
+            "bloat); COW forks are constant-size and losers cost ~162 B to throw away. Optional dep — " +
+            "degrades to {degraded:true} when agenticow is missing.",
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'speculative', 'branch', 'promote', 'ab'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: {
+                    type: 'string',
+                    description: 'Path to base .rvf memory file (absolute or relative to cwd)',
+                },
+                dimension: {
+                    type: 'integer',
+                    description: 'Vector dimension (required only when basePath does not exist yet)',
+                },
+                candidates: {
+                    type: 'array',
+                    description: 'The A/B candidates. Each explores its own COW branch.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string', description: 'Branch label (alnum + _.-:/@ only)' },
+                            ingest: {
+                                type: 'array',
+                                description: 'Vectors to ingest into this candidate branch',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        id: { type: 'integer', description: 'Explicit vector id (auto when omitted)' },
+                                        vector: { type: 'array', items: { type: 'number' }, description: 'Dense vector' },
+                                        text: { type: 'string', description: 'Optional payload text' },
+                                    },
+                                    required: ['vector'],
+                                },
+                            },
+                            branchPath: {
+                                type: 'string',
+                                description: 'Optional explicit path for this branch file (default: alongside base)',
+                            },
+                        },
+                        required: ['label', 'ingest'],
+                    },
+                },
+                probe: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: "Probe vector for scoreBy='nearest' (scores each branch by best-hit similarity)",
+                },
+                k: { type: 'integer', description: 'Nearest-neighbours to fetch per probe (default 1)' },
+                scoreBy: {
+                    type: 'string',
+                    enum: ['nearest', 'count'],
+                    description: "'nearest' = closest probe distance wins; 'count' = most accepted ingests wins. Default 'nearest'.",
+                },
+                requireClearance: {
+                    type: 'boolean',
+                    description: 'ADR-171 fail-closed gate. When true, the top-scored winner is NOT promoted (base stays unchanged) and a provenance-tagged receipt is emitted — score alone cannot graduate work. Use when speculating over TASK outcomes rather than pure memory A/B. Default false (score-only promotion, tagged `unverified`).',
+                    default: false,
+                },
+            },
+            required: ['basePath', 'candidates'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const basePath = resolveMemoryPath(String(input.basePath));
+            const dimension = input.dimension;
+            const scoreBy = input.scoreBy === 'count' ? 'count' : 'nearest';
+            const k = Number.isInteger(input.k) && input.k > 0 ? input.k : 1;
+            const probe = Array.isArray(input.probe) ? input.probe : null;
+            const rawCandidates = input.candidates;
+            if (!Array.isArray(rawCandidates) || rawCandidates.length === 0) {
+                throw new Error('at least one candidate is required');
+            }
+            if (scoreBy === 'nearest' && !probe) {
+                throw new Error("scoreBy='nearest' requires a probe vector");
+            }
+            // Build the generic {label, fn} candidates. Each fn ingests into its own
+            // branch handle, then (for 'nearest') probes it so we can score.
+            const candidates = rawCandidates.map((c) => {
+                const label = validateLabel(String(c.label));
+                if (!Array.isArray(c.ingest) || c.ingest.length === 0) {
+                    throw new Error(`candidate ${label} must ingest at least one vector`);
+                }
+                const records = c.ingest.map((r) => ({
+                    ...(Number.isInteger(r.id) ? { id: r.id } : {}),
+                    vector: r.vector,
+                    ...(typeof r.text === 'string' ? { text: r.text } : {}),
+                }));
+                return {
+                    label,
+                    fn: (branch) => {
+                        const res = branch.ingest(records);
+                        const accepted = Number(res?.accepted ?? records.length);
+                        let hits = [];
+                        if (probe) {
+                            hits = (branch.query(probe, k) || []).map((h) => ({
+                                id: h.id,
+                                distance: h.distance,
+                            }));
+                        }
+                        const bestDistance = hits.length ? hits[0].distance : null;
+                        return { accepted, bestDistance, hits };
+                    },
+                };
+            });
+            const score = (r) => {
+                if (scoreBy === 'count')
+                    return r.accepted;
+                // nearest: smaller distance = better. Map to a higher-is-better score.
+                if (r.bestDistance === null)
+                    return -Infinity;
+                return 1 / (1 + Math.max(0, r.bestDistance));
+            };
+            const branchPath = (label) => {
+                const explicit = rawCandidates.find((c) => validateLabel(String(c.label)) === label)?.branchPath;
+                if (explicit)
+                    return resolveMemoryPath(String(explicit));
+                return `${basePath}.spec-${safeSegment(label)}.rvf`;
+            };
+            // ADR-171 promotion gate. For pure memory A/B the `score` IS the chosen
+            // metric (not a proxy for task correctness), so score-only promotion is
+            // legitimate and stays the default (tagged `unverified`, never
+            // masquerading as ground truth). Callers grafting this onto TASK work
+            // pass requireClearance:true to fail-closed — the winner is then
+            // ineligible unless a real clearance mechanism graduates it.
+            const requireClearance = input.requireClearance === true;
+            const exploreOpts = { branchPath, persist: true };
+            if (requireClearance)
+                exploreOpts.requireClearance = true;
+            // Open base, run the speculative exploration, persist base with the winner promoted.
+            const base = await openWithLineage(api, basePath, dimension);
+            try {
+                const result = await explore(base, candidates, score, exploreOpts);
+                base.save?.(manifestFor(basePath));
+                return {
+                    success: true,
+                    basePath,
+                    scoreBy,
+                    winner: result.winner,
+                    scores: result.scores,
+                    promoted: result.promoted,
+                    promotedBy: result.promotedBy,
+                    promotionDecision: result.promotionDecision,
+                    promoteStats: result.promoteStats,
+                    discarded: result.discarded,
+                    receipts: result.receipts,
+                    branches: result.branches.map((b) => ({
+                        label: b.label,
+                        path: b.path,
+                        score: b.score,
+                        kept: b.kept,
+                        accepted: b.result.accepted,
+                        bestDistance: b.result.bestDistance,
+                    })),
+                };
+            }
+            finally {
+                await base.close?.();
+            }
+        },
+    },
+];
+//# sourceMappingURL=agenticow-speculate-tools.js.map

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

@@ -31,83 +31,10 @@
  *
  * @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);
-}
+// Loader + path/lineage helpers are shared with the SwarmMemoryBranches
+// service (src/services/swarm-memory-branches.ts) via one module so the
+// optional-dep dance and the COW open/fork semantics live in exactly one place.
+import { loadAgenticow, degradedResult, resolveMemoryPath, manifestFor, validateLabel, openWithLineage, } from './agenticow-loader.js';
 export const agenticowTools = [
     {
         name: 'agenticow_branch',
@@ -157,7 +84,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_ingest',
-        description: 'agenticow — write vectors (with optional text payloads) into an .rvf memory branch or base. Records: [{id?, vector, text?}] — id auto-assigns when omitted. This is the write half that makes a branch usable: agenticow_branch creates an empty COW child, but without ingest it has nothing to read back. Use after branching to populate an agent/session-local memory. Editing the base directly is wrong when the writes are speculative — ingest into a branch, then promote only if validated. Persists via .agenticow.json lineage manifest.',
+        description: 'agenticow — write vectors (with optional text payloads) into an .rvf memory branch or base. Records: [{id?, vector, text?}] — id auto-assigns when omitted. This is the write half that makes a branch usable: agenticow_branch creates an empty COW child, but without ingest it has nothing to read back. Use when you have branched and must populate the branch (agenticow_branch alone leaves it empty). Editing the base directly is wrong when the writes are speculative — ingest into a branch, then promote only if validated. Persists via .agenticow.json lineage manifest.',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'ingest', 'write'],
         inputSchema: {
@@ -213,7 +140,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_query',
-        description: 'agenticow — k-NN read across an .rvf memory branch\'s full COW lineage (parent ∪ edits, child wins), returning {id, distance, branch, text}. Read-only (no manifest write). The `branch` field on each hit tells you which lineage node the result came from — the read-through semantics that make branching useful. Use to retrieve from an agent/session branch without materializing a full copy. Re-opening the base and manually merging edits is wrong: query already spans the chain (and uses the single-call Rust path when the branch was forked with nativeAnn).',
+        description: 'agenticow — k-NN read across an .rvf memory branch\'s full COW lineage (parent ∪ edits, child wins), returning {id, distance, branch, text}. Read-only (no manifest write). The `branch` field on each hit tells you which lineage node the result came from — the read-through semantics that make branching useful. Use when you need to read from an agent/session branch without materializing a full copy. Re-opening the base and manually merging edits is wrong: query already spans the chain (and uses the single-call Rust path when the branch was forked with nativeAnn).',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'query', 'read', 'search'],
         inputSchema: {
@@ -251,7 +178,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_diff',
-        description: 'agenticow — show what a branch changed relative to its lineage: {added, overridden, deleted} vector-id lists. Use before promote to preview the exact merge, or to audit what an agent/session branch actually wrote. Diffing by re-querying is wrong because deletions (tombstones) are invisible to a read — diff() surfaces them explicitly. Requires the branch was opened with edit tracking (default on).',
+        description: 'agenticow — show what a branch changed relative to its lineage: {added, overridden, deleted} vector-id lists. Use when you are about to promote and want to preview the exact merge, or when auditing what a branch actually wrote. Diffing by re-querying is wrong because deletions (tombstones) are invisible to a read — diff() surfaces them explicitly. Requires the branch was opened with edit tracking (default on).',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'diff'],
         inputSchema: {
@@ -278,7 +205,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_lineage',
-        description: 'agenticow — walk the COW chain of an .rvf memory file: an ordered list of nodes (role working|checkpoint|base, id, label, parent, createdAt, mutations, tombstones). Use to understand branch history, find checkpoint ids for a targeted rollback, or debug a promote. Guessing the chain from filenames is wrong — lineage is the authoritative structure the store maintains.',
+        description: 'agenticow — walk the COW chain of an .rvf memory file: an ordered list of nodes (role working|checkpoint|base, id, label, parent, createdAt, mutations, tombstones). Use when you need branch history — to find checkpoint ids for a targeted rollback, or to debug a promote. Guessing the chain from filenames is wrong — lineage is the authoritative structure the store maintains.',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'lineage', 'history'],
         inputSchema: {
@@ -305,7 +232,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_status',
-        description: 'agenticow — health/geometry of an .rvf memory file: {totalVectors, totalSegments, fileSize, currentEpoch, deadSpaceRatio, readOnly, chainDepth, dimension, metric}. Use to check vector count before/after ingest, spot compaction pressure (deadSpaceRatio), or confirm the dimension before ingesting into a shared base. Pure read.',
+        description: 'agenticow — health/geometry of an .rvf memory file: {totalVectors, totalSegments, fileSize, currentEpoch, deadSpaceRatio, readOnly, chainDepth, dimension, metric}. Use when you need to check vector count before/after ingest, spot compaction pressure (deadSpaceRatio), or confirm the dimension before ingesting into a shared base. Pure read.',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'status'],
         inputSchema: {

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

@@ -27,6 +27,7 @@ export { autopilotTools } from './autopilot-tools.js';
 export { metaharnessTools } from './metaharness-tools.js';
 export { testgenTools } from './testgen-tools.js';
 export { agenticowTools } from './agenticow-tools.js';
+export { agenticowSpeculateTools } from './agenticow-speculate-tools.js';
 export { agentbbsTools } from './agentbbs-tools.js';
 export { businessPodTools } from './business-pod-tools.js';
 export { httpFetchTools } from './http-fetch-tools.js';

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

@@ -29,6 +29,8 @@ export { metaharnessTools } from './metaharness-tools.js';
 export { testgenTools } from './testgen-tools.js';
 // agenticow@~0.2.3 — Copy-On-Write memory branching (162-byte branches)
 export { agenticowTools } from './agenticow-tools.js';
+// agenticow step 4 — speculative branch-and-promote (A/B memory exploration)
+export { agenticowSpeculateTools } from './agenticow-speculate-tools.js';
 // ADR-164 — AgentBBS federated business-domain BBS rooms (Phase 1)
 export { agentbbsTools } from './agentbbs-tools.js';
 // ADR-164 Phase 2 — Business-pod template validation

package/v3/@claude-flow/cli/dist/src/ruvector/router-trajectory.d.ts

@@ -13,6 +13,19 @@
  * Schema is versioned (`"v": 1`). New required fields bump the version;
  * additive optional fields do not.
  *
+ * COMPANION: run-transcript-recorder.ts (weight-eft capture path)
+ * --------------------------------------------------------------
+ * This recorder captures the routing DECISION only (task, embedding, scalar
+ * quality, tokens, cost) — enough to retrain the router. It deliberately does
+ * NOT carry the full message transcript, the produced patch, or a resolved
+ * boolean. `@metaharness/weight-eft` needs those to build SFT/DPO training
+ * rows, so a SEPARATE opt-in recorder — `run-transcript-recorder.ts` — captures
+ * the full run transcript to `.swarm/run-transcripts.jsonl`. Both share the
+ * `taskHash()` below as their join key, and both are off-by-default for the
+ * same PII/retention reason. Use `unifiedRecorderStatus()` (bottom of this
+ * file) to inspect both at once. Keeping them as two files keeps the routing
+ * hot path free of the heavier transcript payload.
+ *
  * @module router-trajectory
  */
 import type { ClaudeModel } from './model-router.js';
@@ -158,4 +171,24 @@ export declare function pairTrajectoryRows(rows: TrajectoryRow[]): {
 };
 /** Test seam — reset cached config so unit tests can change env vars between cases. */
 export declare function __resetTrajectoryRecorderForTests(): void;
+/**
+ * Unified status for BOTH the routing-decision recorder (this module) and the
+ * companion run-transcript recorder (the weight-eft capture path). The
+ * run-transcript recorder is loaded dynamically so this module has no static
+ * dependency on it (the reverse edge — run-transcript-recorder → taskHash —
+ * is the only static link, keeping the import acyclic).
+ */
+export declare function unifiedRecorderStatus(): Promise<{
+    routerTrajectory: {
+        enabled: boolean;
+        path: string;
+        taskCharLimit: number;
+    };
+    runTranscripts: {
+        enabled: boolean;
+        path: string;
+    } | {
+        unavailable: true;
+    };
+}>;
 //# sourceMappingURL=router-trajectory.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/router-trajectory.js

@@ -13,6 +13,19 @@
  * Schema is versioned (`"v": 1`). New required fields bump the version;
  * additive optional fields do not.
  *
+ * COMPANION: run-transcript-recorder.ts (weight-eft capture path)
+ * --------------------------------------------------------------
+ * This recorder captures the routing DECISION only (task, embedding, scalar
+ * quality, tokens, cost) — enough to retrain the router. It deliberately does
+ * NOT carry the full message transcript, the produced patch, or a resolved
+ * boolean. `@metaharness/weight-eft` needs those to build SFT/DPO training
+ * rows, so a SEPARATE opt-in recorder — `run-transcript-recorder.ts` — captures
+ * the full run transcript to `.swarm/run-transcripts.jsonl`. Both share the
+ * `taskHash()` below as their join key, and both are off-by-default for the
+ * same PII/retention reason. Use `unifiedRecorderStatus()` (bottom of this
+ * file) to inspect both at once. Keeping them as two files keeps the routing
+ * hot path free of the heavier transcript payload.
+ *
  * @module router-trajectory
  */
 import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync } from 'node:fs';
@@ -247,4 +260,22 @@ export function __resetTrajectoryRecorderForTests() {
     _cfg = null;
     _cachedSize = -1;
 }
+/**
+ * Unified status for BOTH the routing-decision recorder (this module) and the
+ * companion run-transcript recorder (the weight-eft capture path). The
+ * run-transcript recorder is loaded dynamically so this module has no static
+ * dependency on it (the reverse edge — run-transcript-recorder → taskHash —
+ * is the only static link, keeping the import acyclic).
+ */
+export async function unifiedRecorderStatus() {
+    const routerTrajectory = trajectoryRecorderStatus();
+    try {
+        const mod = await import('./run-transcript-recorder.js');
+        const s = mod.runTranscriptRecorderStatus();
+        return { routerTrajectory, runTranscripts: { enabled: s.enabled, path: s.path } };
+    }
+    catch {
+        return { routerTrajectory, runTranscripts: { unavailable: true } };
+    }
+}
 //# sourceMappingURL=router-trajectory.js.map

package/v3/@claude-flow/cli/dist/src/ruvector/run-transcript-recorder.d.ts

@@ -0,0 +1,154 @@
+/**
+ * run-transcript-recorder.ts — Opt-in FULL run-transcript recorder for the
+ * weight-eft training-data export path (agenticow / ADR-150 weight-eft slice).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The existing `router-trajectory.ts` recorder captures only the ROUTING
+ * DECISION for a task: task text, embedding, scalar quality, tokens, cost.
+ * `@metaharness/weight-eft` needs something the routing recorder never had —
+ * the full ReAct message TRANSCRIPT, the produced patch, and a resolved
+ * boolean — to build SFT/DPO training rows. This module is that missing
+ * capture surface. It writes one JSON-line per completed run to
+ * `.swarm/run-transcripts.jsonl`, in a shape the archive-builder in
+ * `services/weight-eft.ts` maps directly to `DarwinTrajectory[]`.
+ *
+ * OFF BY DEFAULT (PII / RETENTION SURFACE)
+ * ----------------------------------------
+ * Rows carry the FULL prompt + assistant transcript + patch — a much larger
+ * PII/retention surface than the routing recorder. Mirroring why
+ * router-trajectory.ts is off-by-default, every write goes through the
+ * `CLAUDE_FLOW_RUN_TRANSCRIPTS=1` env gate. When unset (the default),
+ * `recordRunTranscript()` is a no-op. There is no way to enable it implicitly.
+ *
+ * HONESTY: `resolved` IS A PROXY
+ * ------------------------------
+ * `DarwinTrajectory.resolved` is meant to be GOLD-resolved status from the
+ * official SWE-bench harness. Ruflo has NO SWE-bench oracle. Every record
+ * therefore stamps `resolved_source` describing where the boolean actually
+ * came from, so no downstream consumer can mistake a proxy for gold:
+ *   - 'gold-oracle'      — a real conformant gold eval supplied it (never
+ *                          ruflo today; reserved for an external caller)
+ *   - 'output-verifier'  — ruflo's structural output-verifier confidence,
+ *                          thresholded — an EXPLICIT proxy
+ *   - 'api-success'      — the model returned without an API error — the
+ *                          weakest proxy (says nothing about correctness)
+ *   - 'external'         — supplied verbatim by the caller, provenance unknown
+ *
+ * ARCHITECTURAL CONSTRAINTS (mirror router-trajectory.ts / ADR-150)
+ * -----------------------------------------------------------------
+ * 1. OPT-IN — gated behind CLAUDE_FLOW_RUN_TRANSCRIPTS=1; default off.
+ * 2. NEVER THROWS — every fs op is try/caught at the append boundary; a
+ *    failed write is silent (DEBUG-logged) and never breaks the run.
+ * 3. NO metaharness COUPLING — this module imports nothing from
+ *    `@metaharness/*`; it only defines a portable record shape. The
+ *    services/weight-eft.ts archive-builder does the (optional) mapping.
+ *
+ * SCHEMA (versioned, additive) — one JSONL row per completed run:
+ *   { v, ts, instance_id, task_hash, model, tier, resolved, resolved_source,
+ *     messages[], model_patch, sample?, source?, tokens?, cost_usd? }
+ *
+ * @module run-transcript-recorder
+ */
+/** An OpenAI-style tool call (the ReAct action). Mirrors weight-eft's ToolCall. */
+export interface ToolCallLite {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** A chat message in an OpenAI-compatible transcript. Mirrors weight-eft's ChatMessage. */
+export interface ChatMessageLite {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: ToolCallLite[];
+    tool_call_id?: string;
+    name?: string;
+}
+/** Where a `resolved` boolean actually came from (never silently "gold"). */
+export type ResolvedSource = 'gold-oracle' | 'output-verifier' | 'api-success' | 'external';
+/** Ruflo's cascade tier. haiku → 'cheap' (first tier), sonnet/opus → 'frontier'. */
+export type RunTier = 'cheap' | 'frontier';
+/** One persisted run transcript. Maps 1:1 to a DarwinTrajectory (+ provenance). */
+export interface RunTranscriptRecord {
+    v: 1;
+    ts: string;
+    instance_id: string;
+    task_hash: string;
+    model: string;
+    tier: RunTier;
+    resolved: boolean;
+    resolved_source: ResolvedSource;
+    messages: ChatMessageLite[];
+    model_patch: string;
+    sample?: number;
+    source?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    cost_usd?: number;
+}
+/**
+ * Record one completed run transcript. Cheap — a single appendFileSync of a
+ * JSONL row. No-op when CLAUDE_FLOW_RUN_TRANSCRIPTS is unset (the default).
+ * Never throws.
+ *
+ * `resolvedSource` is REQUIRED so a proxy can never masquerade as gold. If you
+ * only have "the API returned", pass 'api-success' — the honest weakest label.
+ */
+export declare function recordRunTranscript(args: {
+    /** Task/issue text — used for the FNV hash + default instance id. */
+    task: string;
+    /** Concrete model id that produced the run (e.g. "claude-haiku-4"). */
+    model: string;
+    /** Ruflo cascade tier of `model`. */
+    tier: RunTier;
+    /** The resolved boolean (see resolvedSource for what it actually means). */
+    resolved: boolean;
+    /** Provenance of `resolved`. Never omit — honesty is the point. */
+    resolvedSource: ResolvedSource;
+    /** OpenAI-shaped message transcript (system/user/assistant/tool). */
+    messages: ChatMessageLite[];
+    /** Unified diff the run produced. '' when the path produces no patch. */
+    modelPatch?: string;
+    /** Override the default "run-<hash>" instance id (contamination key). */
+    instanceId?: string;
+    /** Best-of-N sample index on the same instance (default 0). */
+    sample?: number;
+    /** Provenance tag, e.g. "agent-execute", "autopilot". */
+    source?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    costUsd?: number;
+}): {
+    recorded: boolean;
+    instanceId: string;
+    taskHash: string;
+};
+/**
+ * Read + parse the run-transcript JSONL back into records. Used by the
+ * archive-builder (`services/weight-eft.ts`). Malformed lines are skipped and
+ * counted, never thrown. Returns `[]` if the file is absent.
+ */
+export declare function readRunTranscripts(path?: string): {
+    records: RunTranscriptRecord[];
+    malformed: number;
+    path: string;
+};
+/** Map a ruflo model tier label to the weight-eft policy tier. */
+export declare function tierForModel(model: string | undefined): RunTier;
+/** Diagnostic for status/CLI. */
+export declare function runTranscriptRecorderStatus(): {
+    enabled: boolean;
+    path: string;
+    maxSizeBytes: number;
+    maxRotations: number;
+};
+/** @internal — test seam: reset cached config so tests can flip env vars. */
+export declare function __resetRunTranscriptRecorderForTests(): void;
+//# sourceMappingURL=run-transcript-recorder.d.ts.map