claude-flow 3.42.4 → 3.43.0

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

@@ -0,0 +1,245 @@
+/**
+ * typesafe-router.ts — opt-in `@ruvector/typesafe` augmentation for `hooks_route`.
+ *
+ * Mirrors ADR-150's MetaHarness rules for optional integrations:
+ *   1. Removable — the package is loaded with a dynamic import only; any load,
+ *      construction or decide error falls back to the existing router.
+ *   2. Opt-in    — does nothing unless `CLAUDE_FLOW_ROUTER_TYPESAFE=1`. With the
+ *      flag unset the package is never imported and the legacy result is
+ *      returned unchanged (same object, no added fields).
+ *   3. Optional  — declared as an optional peer of `@claude-flow/cli`.
+ *   4. Honest    — the result carries `routedBy`, typesafe's confidence, abstain
+ *      mass and `calibrated` flag verbatim. The default `hash` embedder is
+ *      uncalibrated, so its confidence is reported as `confidenceCalibrated:
+ *      false` and is never copied into `estimatedMetrics.successProbability`.
+ *
+ * Gate: typesafe's answer is used only when all hold —
+ *   - `abstain <= maxAbstain` (default 0.30)
+ *   - lift = top-1 probability × option count >= `minLift` (default 1.2, i.e.
+ *     20% above chance). Lift, not raw confidence, because confidence scales
+ *     with the option count (~0.1 for ten agents) and differs per embedder.
+ *   - top-1 beats the runner-up by >= `minMargin` (default 0.005); a uniform
+ *     distribution — text that matches nothing — has margin 0.
+ * Otherwise the legacy route is kept and `typesafe.reason` says which gate failed.
+ *
+ * @module typesafe-router
+ */
+const MODULE_ID = '@ruvector/typesafe';
+/**
+ * Default loader. The variable specifier keeps tsc/bundlers off the optional peer;
+ * `require` (the package is CJS) covers hosts that rewrite dynamic import (vite-node).
+ * An absent package still surfaces as MODULE_NOT_FOUND → "not installed".
+ */
+async function loadTypesafeModule() {
+    try {
+        return await import(/* @vite-ignore */ MODULE_ID);
+    }
+    catch (importErr) {
+        try {
+            const { createRequire } = await import('node:module');
+            return createRequire(import.meta.url)(MODULE_ID);
+        }
+        catch (requireErr) {
+            throw requireErr?.code === 'MODULE_NOT_FOUND' ? requireErr : importErr;
+        }
+    }
+}
+/** Agent descriptions + `not_for` hints that separate neighbouring roles. */
+const AGENT_PROFILES = {
+    tester: { what: 'write and run unit tests, integration tests, e2e tests, test coverage and specs', not_for: 'reviewing code, researching issues or reading the latest news' },
+    reviewer: { what: 'review code quality, pull requests, diffs and best practices', not_for: 'writing tests, implementing features or researching background information' },
+    researcher: { what: 'research, investigate, explore, read and summarize issues, docs, discussions and prior art', not_for: 'writing code, writing tests or reviewing a diff' },
+    coder: { what: 'implement features, write code, fix bugs and build functionality', not_for: 'research, review or test-only work' },
+    architect: { what: 'design system architecture, module boundaries, APIs, schemas and refactoring plans', not_for: 'running tests or small bug fixes' },
+    'security-architect': { what: 'security, authentication, authorization, encryption, vulnerabilities, CVEs and audits', not_for: 'general feature work or performance tuning' },
+    'performance-engineer': { what: 'performance optimization, profiling, benchmarks, latency and bottlenecks', not_for: 'security review or writing documentation' },
+    devops: { what: 'deployment, CI/CD pipelines, docker, kubernetes and infrastructure', not_for: 'application feature code or unit tests' },
+    'memory-specialist': { what: 'memory systems, caches, vector stores, embeddings and persistence', not_for: 'UI work or deployment pipelines' },
+    'swarm-specialist': { what: 'multi-agent swarms, coordinators, hive-mind, mesh topology and agent orchestration', not_for: 'single-file code edits' },
+};
+/**
+ * Build choice options from the router's pattern table: every primary agent of
+ * a pattern, plus the profiled roles (researcher/reviewer) the table only lists
+ * as alternates. Each pattern's keywords are appended to its primary agent's
+ * `what`, so the options track TASK_PATTERNS rather than a parallel list.
+ */
+export function buildAgentCriteria(patterns) {
+    const keywordsByAgent = new Map();
+    for (const { agents, keywords } of Object.values(patterns)) {
+        const primary = agents[0];
+        if (!primary)
+            continue;
+        const set = keywordsByAgent.get(primary) ?? new Set();
+        keywords.forEach(k => set.add(k));
+        keywordsByAgent.set(primary, set);
+    }
+    for (const agent of ['researcher', 'reviewer', 'tester', 'coder']) {
+        if (!keywordsByAgent.has(agent))
+            keywordsByAgent.set(agent, new Set());
+    }
+    const criteria = {};
+    for (const [agent, kws] of keywordsByAgent) {
+        const profile = AGENT_PROFILES[agent] ?? { what: `${agent.replace(/-/g, ' ')} tasks` };
+        const kw = [...kws].join(', ');
+        criteria[agent] = {
+            what: kw ? `${profile.what}; keywords: ${kw}` : profile.what,
+            ...(profile.not_for ? { not_for: profile.not_for } : {}),
+        };
+    }
+    return criteria;
+}
+function num(raw, dflt, max = 1) {
+    const n = raw === undefined || raw === '' ? NaN : Number(raw);
+    return Number.isFinite(n) && n >= 0 && n <= max ? n : dflt;
+}
+/** Read config from env. Invalid numeric values fall back to the defaults. */
+export function readTypesafeConfig(env = process.env) {
+    const modelDir = env.CLAUDE_FLOW_ROUTER_TYPESAFE_MODEL_DIR;
+    const manifest = env.CLAUDE_FLOW_ROUTER_TYPESAFE_MANIFEST;
+    return {
+        enabled: env.CLAUDE_FLOW_ROUTER_TYPESAFE === '1',
+        minLift: num(env.CLAUDE_FLOW_ROUTER_TYPESAFE_MIN_LIFT, 1.2, 255),
+        maxAbstain: num(env.CLAUDE_FLOW_ROUTER_TYPESAFE_MAX_ABSTAIN, 0.3),
+        minMargin: num(env.CLAUDE_FLOW_ROUTER_TYPESAFE_MIN_MARGIN, 0.005),
+        embedder: modelDir && manifest ? { kind: 'onnx', modelDir, manifest } : 'hash',
+    };
+}
+/**
+ * Stateful router: loads the module and builds one engine on first use, caches
+ * a load failure so a missing package costs one import attempt per process.
+ */
+export class TypesafeRouter {
+    engine = null;
+    mod = null;
+    loadError = null;
+    env;
+    loadModule;
+    debug;
+    constructor(deps = {}) {
+        this.env = deps.env ?? process.env;
+        this.loadModule = deps.loadModule ?? loadTypesafeModule;
+        this.debug = deps.debug ?? ((m) => { if (this.env.CLAUDE_FLOW_LOG_LEVEL === 'debug')
+            console.error(`[typesafe-router] ${m}`); });
+    }
+    isEnabled() { return readTypesafeConfig(this.env).enabled; }
+    async ensureEngine(cfg) {
+        if (this.engine || this.loadError)
+            return this.engine;
+        try {
+            const raw = (await this.loadModule());
+            const mod = (typeof raw.createTypesafe === 'function' ? raw : raw.default);
+            if (!mod || typeof mod.createTypesafe !== 'function')
+                throw new Error('module has no createTypesafe export');
+            this.mod = mod;
+            this.engine = mod.createTypesafe({ embedder: cfg.embedder });
+        }
+        catch (err) {
+            const e = err;
+            this.loadError = e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND'
+                ? `${MODULE_ID} not installed`
+                : `${MODULE_ID} failed to load: ${e?.message ?? String(err)}`;
+            this.debug(this.loadError);
+        }
+        return this.engine;
+    }
+    /** Ask typesafe for an agent. Never throws; `used: false` means keep the legacy route. */
+    async route(task, patterns) {
+        const cfg = readTypesafeConfig(this.env);
+        const thresholds = { minLift: cfg.minLift, maxAbstain: cfg.maxAbstain, minMargin: cfg.minMargin };
+        const embedder = cfg.embedder === 'hash' ? 'hash' : 'onnx';
+        if (!cfg.enabled)
+            return { used: false, reason: 'CLAUDE_FLOW_ROUTER_TYPESAFE is not 1', thresholds };
+        const engine = await this.ensureEngine(cfg);
+        if (!engine)
+            return { used: false, reason: this.loadError ?? 'typesafe unavailable', thresholds, embedder };
+        let answer;
+        try {
+            const criteria = buildAgentCriteria(patterns);
+            const question = this.mod?.choice ? this.mod.choice(criteria) : { type: 'choice', criteria };
+            const res = await engine.decide(task, { agent: question });
+            answer = res.agent;
+            if (!answer || typeof answer.choice !== 'string')
+                throw new Error('no choice in answer');
+        }
+        catch (err) {
+            const reason = `typesafe decide failed: ${err?.message ?? String(err)}`;
+            this.debug(reason);
+            return { used: false, reason, thresholds, embedder, backend: engine.backend };
+        }
+        const probs = Object.values(answer.probabilities ?? {}).sort((a, b) => b - a);
+        const margin = (probs[0] ?? 0) - (probs[1] ?? 0);
+        const lift = (probs[0] ?? 0) * probs.length;
+        const base = { answer, lift, thresholds, embedder, backend: engine.backend };
+        const f = (n) => n.toFixed(2);
+        if (answer.abstain > cfg.maxAbstain) {
+            return { ...base, used: false, reason: `typesafe abstain ${f(answer.abstain)} > max ${f(cfg.maxAbstain)}; kept existing router` };
+        }
+        if (lift < cfg.minLift) {
+            return { ...base, used: false, reason: `typesafe lift ${f(lift)} (top-1 × ${probs.length} options) < min ${f(cfg.minLift)}; kept existing router` };
+        }
+        if (margin < cfg.minMargin) {
+            return { ...base, used: false, reason: `typesafe top-1 margin ${margin.toFixed(3)} < min ${cfg.minMargin.toFixed(3)} (no clear winner); kept existing router` };
+        }
+        return { ...base, used: true, reason: `typesafe choice "${answer.choice}" (confidence ${f(answer.confidence)}, lift ${f(lift)}, abstain ${f(answer.abstain)}, ${answer.calibrated ? 'calibrated' : 'UNCALIBRATED'} ${embedder} embedder)` };
+    }
+}
+const round2 = (n) => Math.round(n * 100) / 100;
+/**
+ * Merge a typesafe outcome into a legacy `hooks_route` result. Disabled or
+ * error results (`success: false`) pass through untouched.
+ */
+export async function applyTypesafeRouting(params, legacy, patterns, router) {
+    if (!router.isEnabled() || !legacy || legacy.success === false || typeof params.task !== 'string')
+        return legacy;
+    const text = typeof params.context === 'string' && params.context ? `${params.task} ${params.context}` : params.task;
+    const outcome = await router.route(text, patterns);
+    const legacyRouting = (legacy.routing ?? {});
+    const legacyPrimary = (legacy.primaryAgent ?? {});
+    const a = outcome.answer;
+    const typesafe = {
+        used: outcome.used,
+        reason: outcome.reason,
+        ...(a ? {
+            choice: a.choice,
+            confidence: round2(a.confidence),
+            abstain: round2(a.abstain),
+            lift: outcome.lift === undefined ? undefined : round2(outcome.lift),
+            calibrated: a.calibrated,
+            head: a.head,
+            model: a.model,
+            probabilities: Object.fromEntries(Object.entries(a.probabilities).map(([k, v]) => [k, round2(v)])),
+        } : {}),
+        backend: outcome.backend,
+        embedder: outcome.embedder,
+        thresholds: outcome.thresholds,
+    };
+    if (!outcome.used || !a) {
+        return { ...legacy, routedBy: String(legacyRouting.method ?? 'legacy'), typesafe };
+    }
+    const alternatives = Object.entries(a.probabilities)
+        .filter(([k]) => k !== a.choice)
+        .sort((x, y) => y[1] - x[1])
+        .slice(0, 2)
+        .map(([type, p]) => ({ type, confidence: round2(p), reason: 'typesafe runner-up (probability share)' }));
+    return {
+        ...legacy,
+        routing: { ...legacyRouting, method: 'typesafe', backend: `@ruvector/typesafe (${outcome.backend ?? 'unknown'}, ${outcome.embedder} embedder)` },
+        routedBy: 'typesafe',
+        matchedPattern: `typesafe:${a.choice}`,
+        primaryAgent: {
+            type: a.choice,
+            confidence: round2(a.confidence),
+            confidenceCalibrated: a.calibrated,
+            reason: outcome.reason,
+        },
+        alternativeAgents: alternatives,
+        fallbackRoute: { agent: legacyPrimary.type, confidence: legacyPrimary.confidence, method: legacyRouting.method },
+        typesafe,
+    };
+}
+let sharedRouter = null;
+/** Process-wide router used by hooks_route. */
+export function getTypesafeRouter() {
+    return (sharedRouter ??= new TypesafeRouter());
+}
+//# sourceMappingURL=typesafe-router.js.map

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js

@@ -42,11 +42,40 @@ async function acquireLock(lockPath) {
     }
     throw new Error('policy-state-lock-timeout');
 }
-function writeJsonAtomic(file, value) {
+// #3398: Windows rename over a file another process holds open fails with
+// EPERM/EBUSY/EACCES. Retry (~1.3s total, inside LOCK_WAIT_MS), never leave the
+// temp file; a final failure still throws — the state holds the receipt ledger
+// and consumed approval uses, so dropping it would let an approval be reused.
+const RENAME_RETRY_DELAYS_MS = [25, 50, 100, 150, 250, 300, 400];
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+async function writeJsonAtomic(file, value) {
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    renameSync(temporary, file);
+    let renamed = false;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+        for (let attempt = 0;; attempt++) {
+            try {
+                renameSync(temporary, file);
+                renamed = true;
+                return;
+            }
+            catch (error) {
+                const code = error?.code ?? '';
+                if (!TRANSIENT_RENAME_CODES.has(code) || attempt >= RENAME_RETRY_DELAYS_MS.length)
+                    throw error;
+                await sleep(RENAME_RETRY_DELAYS_MS[attempt]);
+            }
+        }
+    }
+    finally {
+        if (!renamed) {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* never created or already gone */ }
+        }
+    }
 }
 function trustPaths(projectRoot) {
     const trustRoot = join(userInfo().homedir, '.config', 'ruflo', 'policy-trust');
@@ -87,7 +116,7 @@ function verifyStateAnchor(projectRoot, state) {
         throw new Error('policy-state-authentication-failed');
     }
 }
-function writePolicyState(projectRoot, statePath, state) {
+async function writePolicyState(projectRoot, statePath, state) {
     const anchorPath = trustPaths(projectRoot).anchor;
     if (state.mode === 'enforce' || existsSync(anchorPath)) {
         const key = trustKey(projectRoot, true);
@@ -102,15 +131,15 @@ function writePolicyState(projectRoot, statePath, state) {
         // crash then leaves either a valid pair or an anchored mismatch that
         // fails closed; it can never leave enforce state silently unanchored.
         if (!existsSync(anchorPath)) {
-            writeJsonAtomic(anchorPath, anchor);
-            writeJsonAtomic(statePath, state);
+            await writeJsonAtomic(anchorPath, anchor);
+            await writeJsonAtomic(statePath, state);
             return;
         }
-        writeJsonAtomic(statePath, state);
-        writeJsonAtomic(anchorPath, anchor);
+        await writeJsonAtomic(statePath, state);
+        await writeJsonAtomic(anchorPath, anchor);
         return;
     }
-    writeJsonAtomic(statePath, state);
+    await writeJsonAtomic(statePath, state);
 }
 function detectLegacyCapabilities(projectRoot) {
     const candidates = [
@@ -179,7 +208,7 @@ export async function autoMigratePolicyStateIfNeeded(projectRoot = process.cwd()
                 state.mode = configured;
                 state.configuredMode = configured;
             }
-            writePolicyState(projectRoot, target.state, state);
+            await writePolicyState(projectRoot, target.state, state);
         }
     }
     finally {
@@ -202,7 +231,7 @@ export async function withPolicyTransaction(projectRoot, operation, options = {}
         const nextState = engine.exportState();
         if (!engine.verifyLedger().valid)
             throw new Error('policy-ledger-verification-failed');
-        writePolicyState(projectRoot, target.state, nextState);
+        await writePolicyState(projectRoot, target.state, nextState);
         return result;
     }
     finally {

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.42.4",
+  "version": "3.43.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -143,12 +143,16 @@
   },
   "peerDependencies": {
     "@metaharness/router": "^0.4.0",
+    "@ruvector/typesafe": "^0.1.0",
     "metaharness": "^0.4.1"
   },
   "peerDependenciesMeta": {
     "@metaharness/router": {
       "optional": true
     },
+    "@ruvector/typesafe": {
+      "optional": true
+    },
     "metaharness": {
       "optional": true
     }