Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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;