🌊 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(proxy): show actionable lifecycle guidance (#2710)
rUv5c02b5cda843
diff --git a/ruflo/package.json b/ruflo/package.jsonindex 70489c9cbf..2ac09036d9 100644--- a/ruflo/package.json+++ b/ruflo/package.json@@ -1,6 +1,6 @@{"name": "ruflo",- "version": "3.32.4",+ "version": "3.32.5","description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration","main": "bin/ruflo.js","type": "module",@@ -40,7 +40,7 @@"package:rvf": "bash src/scripts/package-rvf.sh"},"dependencies": {- "@claude-flow/cli": "^3.32.4"+ "@claude-flow/cli": "^3.32.5"},"optionalDependencies": {},"overrides": {diff --git a/v3/@claude-flow/cli/__tests__/proxy-console-guidance.test.ts b/v3/@claude-flow/cli/__tests__/proxy-console-guidance.test.tsnew file mode 100644index 0000000000..1ab5f3c1d5--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/proxy-console-guidance.test.ts@@ -0,0 +1,68 @@+/** Bare `ruflo proxy` should be an actionable lifecycle dashboard, not the+ * unrelated sponsored-capacity status command. */++import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';++const writeln = vi.fn();++vi.mock('../src/output.js', () => ({+ output: {+ writeln,+ printJson: vi.fn(),+ printInfo: vi.fn(),+ printSuccess: vi.fn(),+ printError: vi.fn(),+ printWarning: vi.fn(),+ createSpinner: vi.fn(),+ },+}));++let stateDir: string;+let savedEnv: NodeJS.ProcessEnv;++beforeEach(() => {+ stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proxy-console-guidance-test-'));+ savedEnv = { ...process.env };+ process.env.RUFLO_STATE_DIR = stateDir;+ writeln.mockClear();+});++afterEach(() => {+ process.env = savedEnv;+ fs.rmSync(stateDir, { recursive: true, force: true });+});++function renderedLines(): string[] {+ return writeln.mock.calls.map(([line]) => String(line));+}++describe('bare proxy console guidance', () => {+ it('tells a user with an installed but stopped proxy exactly how to start it', async () => {+ const { proxyBinaryPath } = await import('../src/proxy/paths.js');+ fs.mkdirSync(path.dirname(proxyBinaryPath()), { recursive: true });+ fs.writeFileSync(proxyBinaryPath(), 'test binary marker');++ const { proxyCommand } = await import('../src/commands/proxy.js');+ const result = await proxyCommand.action!({ args: [], flags: { _: [] }, cwd: stateDir, interactive: false });+ const lines = renderedLines().join('\n');++ expect(result).toMatchObject({ success: true, data: { installed: true, running: false } });+ expect(lines).toContain('Meta Proxy');+ expect(lines).toContain('npx ruflo@latest proxy start --service');+ expect(lines).toContain('npx ruflo@latest auth login');+ expect(lines).not.toContain('Sponsored downtime consent');+ expect(lines).not.toContain('Rate-limit flag');+ });++ it('gives installation guidance before the proxy exists', async () => {+ const { proxyConsoleGuidance } = await import('../src/commands/proxy-lifecycle.js');+ const lines = proxyConsoleGuidance({ installed: false, running: false, pid: null, stalePidFile: false }).join('\n');++ expect(lines).toContain('npx ruflo@latest proxy install --yes');+ expect(lines).toContain('Meta-Proxy v0.4.0');+ expect(lines).not.toContain('auth login');+ });+});diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.jsonindex baf350e2eb..2d172b9865 100644--- a/v3/@claude-flow/cli/package.json+++ b/v3/@claude-flow/cli/package.json@@ -1,6 +1,6 @@{"name": "@claude-flow/cli",- "version": "3.32.4",+ "version": "3.32.5","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",diff --git a/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts b/v3/@claude-flow/cli/src/commands/proxy-lifecycle.tsindex 41050c5aaa..2b39ac224e 100644--- a/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts+++ b/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts@@ -15,6 +15,7 @@ import {startBackground,stopProxy,getProxyStatus,+ type ProxyStatus,readProxyLogTail,watchProxyLog,ProxyNotInstalledError,@@ -26,6 +27,57 @@ import { removeInjectedToken, startTokenRefreshPump } from '../proxy/token-bridg/** Pinned and reviewed; later upgrades remain explicit commands. */export const DEFAULT_PROXY_RELEASE = '0.4.0';+const PROXY_COMMAND = 'npx ruflo@latest proxy';+const AUTH_COMMAND = 'npx ruflo@latest auth';++/**+ * Human-oriented next steps for `ruflo proxy` and `ruflo proxy status`.+ * Keep this independent of the command framework so the state-specific+ * guidance has a small, direct regression-test surface.+ */+export function proxyConsoleGuidance(status: ProxyStatus): string[] {+ if (!status.installed) {+ return [+ '',+ 'Next step',+ ` ${PROXY_COMMAND} install --yes Install signed Meta-Proxy v${DEFAULT_PROXY_RELEASE}`,+ '',+ 'After installation, start it in the background:',+ ` ${PROXY_COMMAND} start --service`,+ ];+ }++ if (!status.running) {+ return [+ '',+ 'Next step',+ ` ${PROXY_COMMAND} start --service Start the proxy in the background`,+ '',+ 'Foreground mode (shows live logs; Ctrl+C stops it):',+ ` ${PROXY_COMMAND} start`,+ '',+ 'Optional: enable Cognitum cloud routing (local-only is the default):',+ ` ${AUTH_COMMAND} login`,+ ` ${PROXY_COMMAND} config --cloud --yes`,+ ];+ }++ return [+ '',+ 'Meta Proxy is ready.',+ ` Logs: ${PROXY_COMMAND} logs`,+ ` Stop: ${PROXY_COMMAND} stop`,+ '',+ 'Optional: enable Cognitum cloud routing (local-only is the default):',+ ` ${AUTH_COMMAND} login`,+ ` ${PROXY_COMMAND} config --cloud --yes`,+ ];+}++export function printProxyConsoleGuidance(status: ProxyStatus): void {+ for (const line of proxyConsoleGuidance(status)) output.writeln(line);+}+const INSTALL_DISCLOSURE = ['Installing the Meta LLM Proxy (ADR-304/307).','',@@ -183,11 +235,11 @@ const statusSub: Command = {output.printJson(status);return { success: true, data: status };}- output.writeln(`Installed: ${status.installed ? 'yes' : 'no'}`);- output.writeln(`Running: ${status.running ? `yes (pid ${status.pid})` : 'no'}`);+ output.writeln('Meta Proxy');+ output.writeln(` Installation: ${status.installed ? 'ready' : 'not installed'}`);+ output.writeln(` Process: ${status.running ? `running (pid ${status.pid})` : 'not running'}`);if (status.stalePidFile) output.writeln(' (a stale PID file was found and will be cleared on next start)');- if (!status.installed) output.writeln(`Run: ruflo proxy install --yes (installs ${DEFAULT_PROXY_RELEASE})`);- else if (!status.running) output.writeln('Run: ruflo proxy start');+ printProxyConsoleGuidance(status);return { success: true, data: status };},};diff --git a/v3/@claude-flow/cli/src/commands/proxy.ts b/v3/@claude-flow/cli/src/commands/proxy.tsindex 4ce39389e9..afe7d6956e 100644--- a/v3/@claude-flow/cli/src/commands/proxy.ts+++ b/v3/@claude-flow/cli/src/commands/proxy.ts@@ -25,7 +25,8 @@ import { clearRateLimitStatus, readRateLimitStatus } from '../funnel/rate-limit-import { clearQuotaLowStatus, readQuotaLowStatus } from '../funnel/power-saver-notifier.js';import { getInstalledCliVersion } from '../init/helper-refresh.js';import * as path from 'path';-import { proxyLifecycleSubcommands } from './proxy-lifecycle.js';+import { proxyLifecycleSubcommands, printProxyConsoleGuidance } from './proxy-lifecycle.js';+import { getProxyStatus } from '../proxy/lifecycle.js';const PROXY_CONFIG_FILE = 'proxy-config.toml';@@ -419,11 +420,14 @@ export const proxyCommand: Command = {{ command: 'ruflo proxy power-saver-enable --yes', description: 'Opt into power saver mode' },{ command: 'ruflo proxy training-share-enable --yes', description: 'Opt into training-data sharing (ADR-315)' },],- action: async (ctx) => {- const { getProxyStatus } = await import('../proxy/lifecycle.js');+ action: async () => {const status = getProxyStatus();- output.writeln(`Installed: ${status.installed ? 'yes' : 'no'}; Running: ${status.running ? `yes (pid ${status.pid})` : 'no'}`);- return sponsorStatusSub.action!(ctx);+ output.writeln('Meta Proxy');+ output.writeln(` Installation: ${status.installed ? 'ready' : 'not installed'}`);+ output.writeln(` Process: ${status.running ? `running (pid ${status.pid})` : 'not running'}`);+ if (status.stalePidFile) output.writeln(' (a stale PID file was found and will be cleared on next start)');+ printProxyConsoleGuidance(status);+ return { success: true, data: status };},};