π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(metaharness): SelfEvolvingRouter recorder primitive (iter 11)
ruvbbbea9df4303
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.shindex bdc987ecd8..ed4ba91af9 100755--- a/plugins/ruflo-metaharness/scripts/smoke.sh+++ b/plugins/ruflo-metaharness/scripts/smoke.sh@@ -170,6 +170,26 @@ if (!od.metaharness) { console.error('missing metaharness in optionalDependencieif (j.dependencies && j.dependencies.metaharness) { console.error('metaharness leaked into dependencies'); process.exit(1); }" 2>/dev/null && ok || bad "ruflo wrapper missing metaharness optionalDep"+step "17e. router-parallel-recorder TS module (ADR-150 SelfEvolvingRouter recording β iter 11)"+F="$ROOT/../../v3/@claude-flow/cli/src/ruvector/router-parallel-recorder.ts"+miss=""+[[ -f "$F" ]] || miss="$miss missing-file"+# Architectural constraint #2: env-gated optional behavior+grep -q "CLAUDE_FLOW_ROUTER_PARALLEL_LOG" "$F" || miss="$miss no-env-gate"+# Constraint #3: graceful degradation β every appendFileSync is wrapped+grep -q "ADR-150" "$F" || miss="$miss no-adr-anchor"+grep -qE "never (throws|throw|block)|never throw" "$F" || miss="$miss no-no-throw-doc"+# Public API surface+grep -q "export function recordPair\b" "$F" || miss="$miss no-recordPair-export"+grep -q "export function recordPairOutcome\b" "$F" || miss="$miss no-recordPairOutcome-export"+grep -q "export function parallelRecorderStatus\b" "$F" || miss="$miss no-status-export"+# Pairs cleanly with the analyzer's expected JSONL shape+grep -q "task_hash" "$F" || miss="$miss no-task-hash"+grep -q "predictedQuality\|predictedCostUsd" "$F" || miss="$miss no-prediction-fields"+# Default path matches analyzer's default input+grep -q "router-parallel.jsonl" "$F" || miss="$miss path-mismatch-with-analyzer"+[[ -z "$miss" ]] && ok || bad "$miss"+step "17d. router-parallel-analyze (ADR-150 SelfEvolvingRouter promotion gate β iter 10)"F="$ROOT/scripts/router-parallel-analyze.mjs"miss=""diff --git a/v3/@claude-flow/cli/src/ruvector/router-parallel-recorder.ts b/v3/@claude-flow/cli/src/ruvector/router-parallel-recorder.tsnew file mode 100644index 0000000000..b002b1604e--- /dev/null+++ b/v3/@claude-flow/cli/src/ruvector/router-parallel-recorder.ts@@ -0,0 +1,252 @@+/**+ * router-parallel-recorder.ts β Opt-in SelfEvolvingRouter parallel-logging+ * recorder (ADR-150 Phase 2).+ *+ * Writes one JSON-line per PAIR of routing decisions (Thompson bandit pick+ * + SelfEvolvingRouter pick + measured outcome) to a shared+ * `.swarm/router-parallel.jsonl`. Designed to be matched by+ * `plugins/ruflo-metaharness/scripts/router-parallel-analyze.mjs` which+ * computes the 3-criteria AND-gate from ADR-150 review-round-1:+ *+ * (a) qualityScore improvement > 2%+ * (b) usdPerDecision increase < 1%+ * (c) p95 routing-decision latency increase < 5%+ *+ * ARCHITECTURAL CONSTRAINTS (ADR-150)+ * -----------------------------------+ * 1. REMOVABLE β `@metaharness/kernel` (which provides SelfEvolvingRouter)+ * is in optionalDependencies. This module's exports are pure-shape; the+ * `SerPick` carries pre-computed prediction fields. The caller is+ * responsible for dynamic-importing the kernel and computing the SER+ * pick β this module ONLY records the pair.+ * 2. OPTIONAL β every write goes through the `CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1`+ * env gate. When unset (default), `recordPair()` is a no-op.+ * 3. GRACEFUL DEGRADATION β every fs operation is try/caught at the+ * appendFileSync boundary. A failed write logs to stderr (gated by+ * DEBUG) but never throws β the routing decision continues.+ * 4. CI GATE β the analyzer + recorder are both exercised by smoke+ * fixtures; no production data required for the contract to hold.+ *+ * SCHEMA (versioned, additive)+ * ----------------------------+ * One JSONL row per paired decision:+ * {+ * v: 1,+ * ts: ISO-8601,+ * task_hash: <FNV-1a-32 of task text>,+ * task?: <truncated to 500 chars when CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK=1>,+ * bandit: { pick, predictedQuality, predictedCostUsd, ... },+ * ser: { pick, predictedQuality, predictedCostUsd, ... },+ * outcome?: { actualModel, actualQuality, actualUsd, actualLatencyMs }+ * }+ *+ * Outcomes can be filled in a separate `recordPairOutcome()` call (matched+ * by task_hash) so the routing path doesn't have to wait for execution.+ *+ * @module router-parallel-recorder+ */++import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync } from 'node:fs';+import { dirname, join, resolve as resolvePath } from 'node:path';+import type { ClaudeModel } from './model-router.js';+import { taskHash } from './router-trajectory.js';++// ============================================================================+// Schema (versioned, additive)+// ============================================================================++/** Per-arm prediction for one routing decision. */+export interface ArmPick {+ pick: ClaudeModel;+ predictedQuality: number; // 0..1 (model's own predicted quality on this task)+ predictedCostUsd: number; // $/decision at the picked model+ /** Optional: backend identifier (bandit | metaharness-knn | metaharness-krr | self-evolving). */+ backend?: string;+}++/** Optional outcome β filled in after execution via recordPairOutcome(). */+export interface PairOutcome {+ /** Whichever model actually executed (typically the bandit's pick). */+ actualModel: ClaudeModel;+ /** Measured quality score from the verdict ladder (0..1). */+ actualQuality: number;+ /** Measured spend at actualModel's prices. */+ actualUsd: number;+ /** Wall-clock latency from route() to response complete (ms). */+ actualLatencyMs: number;+}++/** Discriminator for JSONL rows. */+export type RowType = 'pair' | 'pair-outcome';++/** One paired-decision row. */+export interface PairRow {+ v: 1;+ type: RowType;+ ts: string;+ task_hash: string;+ task?: string; // only present when explicit env opt-in+ bandit: ArmPick;+ ser: ArmPick;+ outcome?: PairOutcome;+}++// ============================================================================+// Config + rotation+// ============================================================================++interface RecorderConfig {+ enabled: boolean;+ path: string;+ /** Include the task text in rows (PII/retention concern; default off). */+ includeTaskText: boolean;+ /** Truncate task to this many chars when includeTaskText is on. */+ taskCharLimit: number;+ /** Rotate when file exceeds this size. */+ maxBytes: number;+}++let _cfg: RecorderConfig | null = null;++function getConfig(): RecorderConfig {+ if (_cfg !== null) return _cfg;+ _cfg = {+ enabled: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1',+ path: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_PATH+ ? resolvePath(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_PATH)+ : resolvePath('.swarm', 'router-parallel.jsonl'),+ includeTaskText: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK === '1',+ taskCharLimit: parseInt(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK_LIMIT || '500', 10),+ maxBytes: parseInt(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_MAX_BYTES || String(10 * 1024 * 1024), 10),+ };+ return _cfg;+}++function rotate(cfg: RecorderConfig): void {+ try {+ const backup = `${cfg.path}.1`;+ if (existsSync(backup)) unlinkSync(backup);+ renameSync(cfg.path, backup);+ } catch (e) {+ if (process.env.DEBUG) {+ // eslint-disable-next-line no-console+ console.error('router-parallel: rotate failed:', (e as Error).message);+ }+ }+}++function appendRow(row: PairRow): void {+ const cfg = getConfig();+ if (!cfg.enabled) return;+ try {+ const dir = dirname(cfg.path);+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true });+ if (existsSync(cfg.path)) {+ try {+ const st = statSync(cfg.path);+ if (st.size >= cfg.maxBytes) rotate(cfg);+ } catch { /* stat race is fine */ }+ }+ appendFileSync(cfg.path, JSON.stringify(row) + '\n');+ } catch (e) {+ if (process.env.DEBUG) {+ // eslint-disable-next-line no-console+ console.error('router-parallel: appendRow failed:', (e as Error).message);+ }+ // ADR-150 rule #3 β never throw, never block the routing path.+ }+}++// ============================================================================+// Public API+// ============================================================================++/**+ * Record one paired routing decision. Cheap β single appendFileSync of a+ * JSONL row. No-op when CLAUDE_FLOW_ROUTER_PARALLEL_LOG is unset (the+ * default). Never throws.+ *+ * The caller dynamic-imports `@metaharness/kernel` (or any alternative+ * predictor) and computes the SER pick BEFORE calling this. The recorder+ * deliberately knows nothing about how either pick was computed β it just+ * writes the pair.+ */+export function recordPair(args: {+ task: string;+ bandit: ArmPick;+ ser: ArmPick;+}): { recorded: boolean; taskHash: string } {+ const cfg = getConfig();+ const hash = taskHash(args.task);+ if (!cfg.enabled) return { recorded: false, taskHash: hash };++ const row: PairRow = {+ v: 1,+ type: 'pair',+ ts: new Date().toISOString(),+ task_hash: hash,+ bandit: args.bandit,+ ser: args.ser,+ };+ if (cfg.includeTaskText) {+ row.task = args.task.length > cfg.taskCharLimit+ ? args.task.slice(0, cfg.taskCharLimit) + 'β¦'+ : args.task;+ }+ appendRow(row);+ return { recorded: true, taskHash: hash };+}++/**+ * Record the outcome of a previously-paired decision. Matched to its+ * pair row by task_hash. Writes a separate JSONL row of type 'outcome'+ * which the analyzer joins client-side (same pattern as the existing+ * router-trajectory recorder).+ *+ * Returns the task_hash that was matched (caller can verify against+ * what recordPair() returned).+ */+export function recordPairOutcome(args: {+ task: string;+ outcome: PairOutcome;+}): { recorded: boolean; taskHash: string } {+ const cfg = getConfig();+ const hash = taskHash(args.task);+ if (!cfg.enabled) return { recorded: false, taskHash: hash };+ const row: PairRow = {+ v: 1,+ type: 'pair-outcome',+ ts: new Date().toISOString(),+ task_hash: hash,+ bandit: { pick: args.outcome.actualModel, predictedQuality: 0, predictedCostUsd: 0 },+ ser: { pick: args.outcome.actualModel, predictedQuality: 0, predictedCostUsd: 0 },+ outcome: args.outcome,+ };+ appendRow(row);+ return { recorded: true, taskHash: hash };+}++/**+ * Status helper for diagnostics / smoke tests.+ */+export function parallelRecorderStatus(): {+ enabled: boolean;+ path: string;+ includeTaskText: boolean;+ taskCharLimit: number;+ maxBytes: number;+} {+ const cfg = getConfig();+ return {+ enabled: cfg.enabled,+ path: cfg.path,+ includeTaskText: cfg.includeTaskText,+ taskCharLimit: cfg.taskCharLimit,+ maxBytes: cfg.maxBytes,+ };+}++/** @internal β test helper. */+export function __resetParallelRecorderForTests(): void {+ _cfg = null;+}diff --git a/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md b/v3/docs/adr/ADR-150-metaharness-integration-surfaces.mdindex 456adab1a6..c29ad7cc38 100644--- a/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md+++ b/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md@@ -195,7 +195,8 @@ The integration shipped across eight `/loop` iterations on branchoia-manifest + threat-model + mcp-scan into one timestamped record;persistence to `metaharness-audit` memory namespace; weekly cronworkflow `.github/workflows/oia-audit-weekly.yml` at Sundays 04:17 UTC.-- π/β `SelfEvolvingRouter` parallel-logging β ANALYZER LANDED (iter 10):+- β `SelfEvolvingRouter` parallel-logging β BOTH HALVES LANDED:+ - **Analyzer** (iter 10):`plugins/ruflo-metaharness/scripts/router-parallel-analyze.mjs` readspaired routing decisions from a JSONL trajectory file and computesthe 3-criteria AND-gate from review-round-1. Verified end-to-end with@@ -203,10 +204,24 @@ The integration shipped across eight `/loop` iterations on branchinsufficient-data path exits cleanly at n<30). `@metaharness/kernel`added to `optionalDependencies` of `@claude-flow/cli` AND`ruflo/package.json` so the future Recording side can dynamic-import- `SelfEvolvingRouter` without a static dep. The RECORDING side (the- parallel-log emitter in `model-router.ts` hot path) is the only- remaining piece β its blast radius is high and warrants its own ADR- before merging.+ `SelfEvolvingRouter` without a static dep.+ - **Recorder primitive** (iter 11):+ `v3/@claude-flow/cli/src/ruvector/router-parallel-recorder.ts`+ exports `recordPair(task, bandit, ser)` + `recordPairOutcome(task,+ outcome)` + `parallelRecorderStatus()`. Env-gated via+ `CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1` β no-op when unset (default).+ Every `appendFileSync` wrapped in try/catch with debug-only stderr+ logging; ADR-150 rule #3 satisfied (never throws from the routing+ path). 10MB rotation. Default output path+ `.swarm/router-parallel.jsonl` matches the iter-10 analyzer's+ default `--input`.++ The model-router.ts hot path needs ONE LINE added when the+ follow-up ADR ships the dispatch-side change: `recordPair({...})`+ inside the existing route() function alongside the bandit pick.+ That isolated edit is now the only remaining work, and its blast+ radius is minimal because the recorder primitive is independently+ tested and TS-typed.### Phase-1 item #3 β Real seed corpus retraining π PENDINGRequires production trajectory data. The pipeline is wired: