π 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
fix(embeddings): report a skipped model download as failure, not success (#3376)
Mr. Mak3fc37ef4c1e9
diff --git a/v3/@claude-flow/cli/__tests__/embeddings-init-skipped-download-3376.test.ts b/v3/@claude-flow/cli/__tests__/embeddings-init-skipped-download-3376.test.tsnew file mode 100644index 0000000000..1aee475392--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/embeddings-init-skipped-download-3376.test.ts@@ -0,0 +1,203 @@+/**+ * #3376: `embeddings init` reported success after skipping the model download.+ *+ * `getEmbeddings()` (commands/embeddings.ts) dynamic-imports the optional+ * `@claude-flow/embeddings` package and returns null when it is absent β which+ * is every plain `npm i -g ruflo`, because that package is not declared in the+ * CLI's package.json at all. The `else` branch of `if (embeddings)` slept 500ms+ * faking download progress, printed a dimmed "(Skipped β β¦)" note onto the+ * spinner's tail, and then fell through to the success path: a settings table+ * asserting the model and 384 dimensions, `.claude-flow/embeddings.json`+ * recording a `modelPath` that contains no model, and exit 0.+ *+ * That matters because `embeddings init --download` is the command+ * `memory/embedding-policy.ts` names in its `[no-stub]` error β the documented+ * repair for broken embeddings reported success and changed nothing.+ *+ * These tests drive the command actions in-process (same shape as+ * proxy-config-command.test.ts) because the observable contract is the+ * CommandResult the dispatcher turns into an exit code: index.ts does+ * `if (result && !result.success) process.exit(result.exitCode || 1)`.+ */+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';+import { createRequire } from 'module';+import * as fs from 'fs';+import * as os from 'os';+import * as path from 'path';+import type { Command, CommandContext } from '../src/types.js';++// These tests describe what happens when the optional embeddings package is+// NOT resolvable. That is the state of this workspace (it is not a dependency+// of @claude-flow/cli), but assert it rather than assume it: if someone ever+// adds the package, these tests must skip rather than pass for a wrong reason.+function embeddingsPackagePresent(): boolean {+ try {+ createRequire(import.meta.url).resolve('@claude-flow/embeddings');+ return true;+ } catch {+ return false;+ }+}++const SKIP = embeddingsPackagePresent();++let initCmd: Command;+let modelsCmd: Command;+let warnings: string[];+let lines: string[];+let tableRows: Array<Record<string, string>>;+let savedCwd: string;+let workdir: string;++beforeAll(async () => {+ const { embeddingsCommand } = await import('../src/commands/embeddings.js');+ const init = embeddingsCommand.subcommands?.find((c) => c.name === 'init');+ const models = embeddingsCommand.subcommands?.find((c) => c.name === 'models');+ if (!init || !models) throw new Error('embeddings init/models subcommand not found');+ initCmd = init;+ modelsCmd = models;+});++beforeEach(async () => {+ savedCwd = process.cwd();+ // realpath: on macOS os.tmpdir() is /var/... but process.cwd() reports the+ // resolved /private/var/..., and the command records process.cwd().+ workdir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ruflo-3376-')));+ // `embeddings init` resolves .claude-flow against process.cwd(), not ctx.cwd.+ process.chdir(workdir);++ warnings = [];+ lines = [];+ tableRows = [];+ const { output } = await import('../src/output.js');+ vi.spyOn(output, 'printWarning').mockImplementation((m: string) => { warnings.push(m); });+ // Spinner.stop()/succeed()/fail() render through the formatter's writeln,+ // so this captures the headline the user sees where the spinner was.+ vi.spyOn(output, 'writeln').mockImplementation((t = '') => { lines.push(t); });+ vi.spyOn(output, 'printTable').mockImplementation((o: { data: Array<Record<string, string>> }) => {+ tableRows.push(...o.data);+ });+ // Keep the suite's own output readable; these carry no assertions.+ vi.spyOn(output, 'printInfo').mockImplementation(() => {});+ vi.spyOn(output, 'printBox').mockImplementation(() => {});+ vi.spyOn(output, 'printList').mockImplementation(() => {});+});++afterEach(() => {+ vi.restoreAllMocks();+ process.chdir(savedCwd);+ fs.rmSync(workdir, { recursive: true, force: true });+});++function ctx(flags: Record<string, unknown> = {}): CommandContext {+ return { args: [], flags: { _: [], ...flags }, cwd: process.cwd(), interactive: false };+}++function readConfig(): Record<string, unknown> {+ return JSON.parse(fs.readFileSync(path.join(workdir, '.claude-flow', 'embeddings.json'), 'utf-8'));+}++describe.skipIf(SKIP)('#3376 embeddings init does not report success for a skipped download', () => {+ it('fails with exit code 1 when the download was requested and did not happen', async () => {+ const result = await initCmd.action!(ctx());++ // Pre-fix: success: true, no exitCode β the dispatcher exited 0.+ expect(result.success).toBe(false);+ expect(result.exitCode).toBe(1);+ });++ it('warns prominently instead of dimming the skip onto the spinner line', async () => {+ await initCmd.action!(ctx());++ // Pre-fix the only disclosure was output.writeln(output.dim(...)), so+ // printWarning was never called at all.+ expect(warnings.length).toBeGreaterThan(0);+ expect(warnings.join('\n')).toContain('@claude-flow/embeddings is not installed');+ });++ it('does not claim the subsystem was initialized', async () => {+ await initCmd.action!(ctx());++ // Pre-fix the spinner succeeded with exactly this, contradicting the+ // dimmed skip note printed one line above it.+ expect(lines.join('\n')).not.toContain('Embedding subsystem initialized');+ expect(lines.join('\n')).toContain('NOT downloaded');+ });++ it('marks the model as not downloaded in the settings table', async () => {+ await initCmd.action!(ctx());++ // Pre-fix the table listed Model / Dimension / Model Path with no+ // indication that the path was empty.+ const status = tableRows.find((r) => r.setting === 'Model Status');+ expect(status?.value).toEqual(expect.stringContaining('NOT downloaded'));+ });++ it('records modelDownloaded: false rather than asserting a model is present', async () => {+ await initCmd.action!(ctx());++ const config = readConfig();+ // Pre-fix: the key did not exist and the config asserted the model path+ // unconditionally.+ expect(config.modelDownloaded).toBe(false);+ expect(config.modelSkipReason).toContain('@claude-flow/embeddings');++ // Nothing was actually downloaded β the directory the config points at is+ // empty. This is the fact the old config contradicted.+ expect(fs.readdirSync(path.join(workdir, '.claude-flow', 'models'))).toHaveLength(0);+ });++ it('keeps the existing config shape so older readers still work', async () => {+ await initCmd.action!(ctx());++ const config = readConfig();+ // Every key mcp-tools/embeddings-tools.ts's EmbeddingsConfig reads is+ // still present and unchanged in meaning; the new keys are additive.+ expect(config.model).toBe('all-MiniLM-L6-v2');+ expect(config.modelPath).toBe(path.join(workdir, '.claude-flow', 'models'));+ expect(config.dimension).toBe(384);+ expect(config.cacheSize).toBe(256);+ expect(config.hyperbolic).toMatchObject({ enabled: true, curvature: -1 });+ expect(config.neural).toMatchObject({ enabled: true });+ expect(typeof config.initialized).toBe('string');+ });++ it('still succeeds with --no-download, because no download was asked for', async () => {+ const result = await initCmd.action!(ctx({ download: false }));++ // Configuring hyperbolic settings without a model is a legitimate use;+ // only a download that was requested and skipped is a failure.+ expect(result.success).toBe(true);+ const config = readConfig();+ expect(config.modelDownloaded).toBe(false);+ expect(config.modelSkipReason).toContain('--no-download');+ });++ it('does not sleep 500ms faking download progress', async () => {+ const started = Date.now();+ await initCmd.action!(ctx());+ const elapsed = Date.now() - started;++ // Pre-fix this path always cost at least the hardcoded+ // `await new Promise(r => setTimeout(r, 500))`. The real work here is a+ // mkdir and a small JSON write (single-digit ms), so 300ms is ~15x+ // headroom over the actual cost while staying well under the 500ms floor+ // the removed sleep imposed. This is the one timing-based assertion here.+ expect(elapsed).toBeLessThan(300);+ });+});++describe.skipIf(SKIP)('#3376 embeddings models --download reports the same skip honestly', () => {+ it('fails with exit code 1 and does not sleep 500ms', async () => {+ const started = Date.now();+ const result = await modelsCmd.action!(ctx({ download: 'all-MiniLM-L6-v2' }));+ const elapsed = Date.now() - started;++ // Pre-fix: spinner.succeed('Download skipped β β¦') after a 500ms sleep,+ // then `return { success: true }`.+ expect(result.success).toBe(false);+ expect(result.exitCode).toBe(1);+ expect(warnings.join('\n')).toContain('was not downloaded');+ expect(elapsed).toBeLessThan(300);+ });+});diff --git a/v3/@claude-flow/cli/src/commands/embeddings.ts b/v3/@claude-flow/cli/src/commands/embeddings.tsindex 6536423c95..ac23b5e744 100644--- a/v3/@claude-flow/cli/src/commands/embeddings.ts+++ b/v3/@claude-flow/cli/src/commands/embeddings.ts@@ -776,7 +776,13 @@ const initCommand: Command = {fs.mkdirSync(modelDir, { recursive: true });}- // Download model if requested+ // Download model if requested. #3376: record what actually happened+ // instead of assuming the download ran β `getEmbeddings()` returns null+ // whenever the optional @claude-flow/embeddings package is absent, which+ // is every plain `npm i -g ruflo` install.+ let modelDownloaded = false;+ let modelSkipReason: string | null = null;+if (download) {spinner.setText(`Downloading ONNX model: ${model}...`);const embeddings = await getEmbeddings();@@ -785,11 +791,16 @@ const initCommand: Command = {await embeddings.downloadEmbeddingModel(model, modelDir, (p) => {spinner.setText(`Downloading ${model}... ${p.percent.toFixed(0)}%`);});+ modelDownloaded = true;} else {- // Embeddings package not available β skip download- await new Promise(r => setTimeout(r, 500));- output.writeln(output.dim(' (Skipped β @claude-flow/embeddings not installed)'));+ // No download happened. That is the outcome of this command, not an+ // aside β reported below via spinner.fail + a warning, never as a+ // dimmed note on a success path. No fake progress delay: there is+ // nothing in progress.+ modelSkipReason = '@claude-flow/embeddings is not installed';}+ } else {+ modelSkipReason = 'download disabled by --no-download';}// Write embeddings config@@ -800,6 +811,12 @@ const initCommand: Command = {modelPath: modelDir,dimension,cacheSize,+ // #3376: additive, optional fields. `modelPath` keeps its old meaning+ // (the directory the model belongs in), but it no longer implies a+ // model is in it β `modelDownloaded` says whether one is. Readers that+ // predate these keys are unaffected; they ignore unknown properties.+ modelDownloaded,+ ...(modelSkipReason ? { modelSkipReason } : {}),hyperbolic: {enabled: hyperbolic,curvature,@@ -816,7 +833,15 @@ const initCommand: Command = {fs.writeFileSync(configPath, JSON.stringify(config, null, 2));- spinner.succeed('Embedding subsystem initialized');+ // A download that was asked for and did not happen is a failed init:+ // the only substantive step of `embeddings init` did not run. #3376.+ const downloadSkipped = download && !modelDownloaded;++ if (downloadSkipped) {+ spinner.fail('Embedding model NOT downloaded β embedding subsystem is not ready');+ } else {+ spinner.succeed('Embedding subsystem initialized');+ }output.writeln();output.printTable({@@ -826,6 +851,7 @@ const initCommand: Command = {],data: [{ setting: 'Model', value: model },+ { setting: 'Model Status', value: modelDownloaded ? output.success('Downloaded') : output.error('NOT downloaded') },{ setting: 'Dimension', value: String(dimension) },{ setting: 'Cache Size', value: String(cacheSize) + ' entries' },{ setting: 'Hyperbolic', value: hyperbolic ? `${output.success('Enabled')} (c=${curvature})` : output.dim('Disabled') },@@ -835,6 +861,21 @@ const initCommand: Command = {],});+ if (downloadSkipped) {+ output.writeln();+ output.printWarning(`No embedding model was installed: ${modelSkipReason}.`);+ output.printWarning('Until a real embedder is present, embeddings fall back to hash vectors, which carry no semantic meaning.');+ output.printInfo(`Configuration was still written to ${configPath}, recording "modelDownloaded": false.`);+ output.writeln();+ output.writeln(output.dim('To finish initializing:'));+ output.printList([+ 'npm install @claude-flow/embeddings - the package this command downloads with; then: embeddings init --force',+ 'npm install ruvector - the other real embedder ruflo accepts; needs no download step',+ 'embeddings init --no-download --force - keep this configuration without a model (exits 0)',+ ]);+ return { success: false, exitCode: 1, data: config };+ }+output.writeln();if (hyperbolic) {output.printBox([@@ -1322,8 +1363,11 @@ const modelsCommand: Command = {return { success: false, exitCode: 1 };}} else {- await new Promise(r => setTimeout(r, 500));- spinner.succeed(`Download skipped β @claude-flow/embeddings not installed`);+ // #3376, same class as `init`: nothing was downloaded, so this is a+ // failure, not a success with a caveat. No fake progress delay either.+ spinner.fail(`Download skipped β @claude-flow/embeddings is not installed`);+ output.printWarning(`"${download}" was not downloaded. Install @claude-flow/embeddings to enable model downloads.`);+ return { success: false, exitCode: 1 };}return { success: true };}diff --git a/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.tsindex 28b9d88f55..993eb5cc52 100644--- a/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts@@ -20,6 +20,14 @@ interface EmbeddingsConfig {modelPath: string;dimension: number;cacheSize: number;+ /**+ * #3376 β whether a model was actually downloaded into `modelPath`.+ * Optional: configs written before this field existed omit it, and+ * `undefined` means "unknown", not "false". `embeddings init` (CLI) sets it.+ */+ modelDownloaded?: boolean;+ /** #3376 β why no model was downloaded, when `modelDownloaded` is false. */+ modelSkipReason?: string;hyperbolic: {enabled: boolean;curvature: number;