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(proxy): disclose what enabling cloud routing decides, and let users pin a tier (#2927)

Dragan Spiridonove1f7e4a23288
diff --git a/v3/@claude-flow/cli/__tests__/proxy-config-command.test.ts b/v3/@claude-flow/cli/__tests__/proxy-config-command.test.ts
index 55b65a0ee8..de54ed3026 100644
--- a/v3/@claude-flow/cli/__tests__/proxy-config-command.test.ts
+++ b/v3/@claude-flow/cli/__tests__/proxy-config-command.test.ts
@@ -6,7 +6,7 @@
* and by a live behavioral test against the real v0.1.0 binary.
*/
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
@@ -109,3 +109,154 @@ describe('proxy config', () => {
expect(raw).toContain('default_data_plane = "cloud"');
});
});
+
+/**
+ * `--routing-mode` (meta-proxy ADR-321 rev-2). Values match the Rust
+ * `RoutingMode` enum. The invariant worth pinning is ADR-321 Revision 3's:
+ * the plane choice and this Cloud-only tier setting are SEPARATE controls,
+ * so selecting a tier must never activate Cloud.
+ */
+describe('proxy config --routing-mode', () => {
+ const configPath = () => path.join(stateDir, 'proxy-config.toml');
+
+ it('writes routing_mode without touching the data plane or granting consent', async () => {
+ const configSub = await getConfigSub();
+
+ const result = await configSub.action!(ctxWithFlags({ routingMode: 'high' }));
+
+ expect(result?.success).toBe(true);
+ const raw = fs.readFileSync(configPath(), 'utf-8');
+ expect(raw).toContain('routing_mode = "high"');
+ expect(raw).not.toContain('default_data_plane');
+
+ const { hasConsent } = await import('../src/funnel/index.js');
+ expect(hasConsent('cloud-routing')).toBe(false);
+ });
+
+ it('accepts every mode meta-proxy defines', async () => {
+ const configSub = await getConfigSub();
+
+ for (const mode of ['auto', 'low', 'mid', 'high']) {
+ const result = await configSub.action!(ctxWithFlags({ routingMode: mode }));
+ expect(result?.success, mode).toBe(true);
+ expect(fs.readFileSync(configPath(), 'utf-8')).toContain(`routing_mode = "${mode}"`);
+ }
+ });
+
+ it('rejects a mode meta-proxy would not understand, and writes nothing', async () => {
+ const configSub = await getConfigSub();
+
+ const result = await configSub.action!(ctxWithFlags({ routingMode: 'ultra' }));
+
+ expect(result?.success).toBe(false);
+ expect(fs.existsSync(configPath())).toBe(false);
+ });
+
+ it('refuses to pin a tier while --local-only is turning the cloud plane off', async () => {
+ const configSub = await getConfigSub();
+
+ const result = await configSub.action!(ctxWithFlags({ localOnly: true, routingMode: 'high' }));
+
+ expect(result?.success).toBe(false);
+ expect(fs.existsSync(configPath())).toBe(false);
+ });
+
+ it('applies alongside --cloud --yes in one command', async () => {
+ const configSub = await getConfigSub();
+
+ const result = await configSub.action!(ctxWithFlags({ cloud: true, yes: true, routingMode: 'low' }));
+
+ expect(result?.success).toBe(true);
+ const raw = fs.readFileSync(configPath(), 'utf-8');
+ expect(raw).toContain('default_data_plane = "cloud"');
+ expect(raw).toContain('routing_mode = "low"');
+ });
+
+ /** The unconfirmed path's whole promise is that nothing was written. */
+ it('writes nothing when passed with an unconfirmed --cloud', async () => {
+ const configSub = await getConfigSub();
+
+ const result = await configSub.action!(ctxWithFlags({ cloud: true, routingMode: 'low' }));
+
+ expect((result?.data as { confirmed?: boolean })?.confirmed).toBe(false);
+ expect(fs.existsSync(configPath())).toBe(false);
+ });
+
+ it('reports the current mode with no flags, defaulting to auto when unset', async () => {
+ const configSub = await getConfigSub();
+
+ const unset = await configSub.action!(ctxWithFlags({}));
+ expect((unset?.data as { routingMode?: string })?.routingMode).toBe('auto');
+
+ await configSub.action!(ctxWithFlags({ routingMode: 'mid' }));
+ const set = await configSub.action!(ctxWithFlags({}));
+ expect((set?.data as { routingMode?: string })?.routingMode).toBe('mid');
+ });
+
+ it('treats an unrecognized routing_mode already in the file as auto', async () => {
+ fs.writeFileSync(configPath(), 'routing_mode = "ultra"\n');
+ const configSub = await getConfigSub();
+
+ const result = await configSub.action!(ctxWithFlags({}));
+
+ expect((result?.data as { routingMode?: string })?.routingMode).toBe('auto');
+ });
+
+ it('preserves unrelated lines when writing routing_mode', async () => {
+ fs.writeFileSync(configPath(), 'bind = "127.0.0.1:11435"\nsponsored_daily_cap_usd = 5.0\n');
+ const configSub = await getConfigSub();
+
+ await configSub.action!(ctxWithFlags({ routingMode: 'high' }));
+
+ const raw = fs.readFileSync(configPath(), 'utf-8');
+ expect(raw).toContain('bind = "127.0.0.1:11435"');
+ expect(raw).toContain('sponsored_daily_cap_usd = 5.0');
+ expect(raw).toContain('routing_mode = "high"');
+ });
+});
+
+/**
+ * meta-proxy#43 M5b β€” "add equivalent disclosure to any terminal flow that
+ * explicitly activates Cloud". The console got this in M5a (#60); this
+ * command is the terminal flow, and these are the three questions
+ * activating Cloud actually decides.
+ */
+describe('cloud routing disclosure', () => {
+ async function disclosureShownOnUnconfirmedCloud(): Promise<string> {
+ const lines: string[] = [];
+ const { output } = await import('../src/output.js');
+ const spy = vi.spyOn(output, 'writeln').mockImplementation((line?: string) => {
+ lines.push(String(line ?? ''));
+ });
+ try {
+ const configSub = await getConfigSub();
+ await configSub.action!(ctxWithFlags({ cloud: true }));
+ } finally {
+ spy.mockRestore();
+ }
+ return lines.join('\n');
+ }
+
+ it('says who processes the prompts', async () => {
+ expect(await disclosureShownOnUnconfirmedCloud()).toContain('api.cognitum.one');
+ });
+
+ it("says who pays, and that Passthrough uses the user's own subscription instead", async () => {
+ const text = await disclosureShownOnUnconfirmedCloud();
+
+ expect(text).toContain('metered against your Cognitum account');
+ expect(text).toContain('Passthrough');
+ });
+
+ /**
+ * The omission that mattered: on the Cloud plane the client's requested
+ * model is deliberately not used, and before this the disclosure never
+ * said so β€” a user could enable Cloud believing their model choice held.
+ */
+ it('says the plane picks the tier rather than using the requested model, and how to override', async () => {
+ const text = await disclosureShownOnUnconfirmedCloud();
+
+ expect(text).toContain('instead of using the model');
+ expect(text).toContain('ruflo proxy config --routing-mode');
+ });
+});
diff --git a/v3/@claude-flow/cli/src/commands/proxy.ts b/v3/@claude-flow/cli/src/commands/proxy.ts
index bdc99bd052..53a2b625de 100644
--- a/v3/@claude-flow/cli/src/commands/proxy.ts
+++ b/v3/@claude-flow/cli/src/commands/proxy.ts
@@ -97,12 +97,58 @@ function writeDataPlane(plane: 'local' | 'cloud'): void {
writeConfigLine('default_data_plane', `"${plane}"`);
}
+/**
+ * `routing_mode` β€” how the Cloud plane picks a tier (meta-proxy ADR-321
+ * rev-2). Values match the Rust `RoutingMode` enum (`src/config.rs`, also
+ * `#[serde(rename_all = "snake_case")]`); absent from the file means `auto`,
+ * so an existing config keeps working untouched.
+ */
+const ROUTING_MODES = ['auto', 'low', 'mid', 'high'] as const;
+type RoutingMode = (typeof ROUTING_MODES)[number];
+
+function readRoutingMode(): RoutingMode {
+ const match = readProxyConfigRaw().match(/^routing_mode\s*=\s*"([^"]*)"/m);
+ const value = match?.[1];
+ return (ROUTING_MODES as readonly string[]).includes(value ?? '') ? (value as RoutingMode) : 'auto';
+}
+
+function writeRoutingMode(mode: RoutingMode): void {
+ writeConfigLine('routing_mode', `"${mode}"`);
+}
+
+/**
+ * ADR-304/321. This is the terminal-side equivalent of the Developer
+ * Console's Cloud selector disclosure β€” meta-proxy#43 M5a covered the
+ * console, M5b covers "any terminal flow that explicitly activates Cloud",
+ * which is this command.
+ *
+ * It answers the three questions activating Cloud actually decides, because
+ * each has a different answer than the plane the user is leaving:
+ * who processes the prompt, who pays for it, and which model runs. The third
+ * is the one the previous text omitted entirely, and it is not a detail β€”
+ * on the Cloud plane the client's requested model is deliberately NOT used.
+ */
const CLOUD_ROUTING_DISCLOSURE = [
'Enabling cloud routing.',
'',
- 'With cloud routing ON, prompts for cloud-tier requests are sent to',
- 'api.cognitum.one and forwarded to the selected provider',
- '(Claude / GPT / Gemini / DeepSeek / OpenRouter).',
+ 'Who processes your prompts:',
+ ' Prompts for cloud-tier requests are sent to api.cognitum.one and',
+ ' forwarded to the selected provider (Claude / GPT / Gemini / DeepSeek /',
+ ' OpenRouter). Cognitum handles them server-side.',
+ '',
+ 'Who pays:',
+ ' Cloud-tier requests are metered against your Cognitum account, not',
+ ' against your own Claude subscription. Your subscription is used only',
+ ' by the Passthrough plane (the proxy\'s default), which is unaffected',
+ ' by everything below.',
+ '',
+ 'Which model runs:',
+ ' The cloud plane picks the tier per prompt instead of using the model',
+ ' your client asked for (ADR-321). That is the point of the plane: a',
+ ' trivial question is not served at frontier rates because the client',
+ ' happened to name a frontier model. The scorer reads prompt shape, not',
+ ' task difficulty, so pin a tier if you disagree with its judgement:',
+ ' ruflo proxy config --routing-mode high',
'',
'Requests routed to local backends never leave this machine.',
'',
@@ -111,22 +157,47 @@ const CLOUD_ROUTING_DISCLOSURE = [
const configSub: Command = {
name: 'config',
- description: 'Toggle cloud routing (ADR-304) β€” local backends only by default',
+ description: 'Toggle cloud routing and its tier selection (ADR-304/321) β€” local backends only by default',
options: [
{ name: 'cloud', description: 'Enable cloud routing (requires cloud-routing consent)', type: 'boolean', default: false },
{ name: 'local-only', description: 'Disable cloud routing, revert to local-only routing', type: 'boolean', default: false },
+ {
+ name: 'routing-mode',
+ description: `How the cloud plane picks a tier: ${ROUTING_MODES.join(' | ')} (default: auto)`,
+ type: 'string',
+ },
{ name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
],
action: async (ctx): Promise<CommandResult> => {
const wantCloud = Boolean(ctx.flags.cloud);
const wantLocalOnly = Boolean(ctx.flags.localOnly ?? ctx.flags['local-only']);
+ const rawRoutingMode = ctx.flags.routingMode ?? ctx.flags['routing-mode'];
+ const wantRoutingMode = typeof rawRoutingMode === 'string' ? rawRoutingMode : undefined;
if (wantCloud && wantLocalOnly) {
output.printError('Pass either --cloud or --local-only, not both.');
return { success: false, exitCode: 1 };
}
- if (!wantCloud && !wantLocalOnly) {
+ if (wantRoutingMode !== undefined && !(ROUTING_MODES as readonly string[]).includes(wantRoutingMode)) {
+ output.printError(
+ `Unknown routing mode "${wantRoutingMode}". Valid values: ${ROUTING_MODES.join(', ')}.`,
+ );
+ return { success: false, exitCode: 1 };
+ }
+ const routingMode = wantRoutingMode as RoutingMode | undefined;
+
+ // A tier only means anything on the Cloud plane, and --local-only leaves
+ // it. Writing both would record a preference the same command just made
+ // unreachable, so say so instead of silently picking one.
+ if (routingMode && wantLocalOnly) {
+ output.printError(
+ '--routing-mode only governs the cloud plane, which --local-only turns off. Pass one or the other.',
+ );
+ return { success: false, exitCode: 1 };
+ }
+
+ if (!wantCloud && !wantLocalOnly && !routingMode) {
const plane = readDataPlane();
output.writeln(`Current data plane: ${plane}`);
output.writeln(
@@ -134,7 +205,32 @@ const configSub: Command = {
? 'Cloud routing is ON β€” cloud-tier requests go to api.cognitum.one.'
: 'Cloud routing is OFF β€” requests never leave this machine (or use your own Claude subscription on Passthrough).',
);
- return { success: true, data: { plane } };
+ const mode = readRoutingMode();
+ output.writeln(
+ mode === 'auto'
+ ? ' Tier selection: auto β€” Cognitum scores each prompt and picks low/mid/high.'
+ : ` Tier selection: pinned to ${mode}.`,
+ );
+ if (plane !== 'cloud') output.writeln(' (Tier selection applies only while cloud routing is ON.)');
+ return { success: true, data: { plane, routingMode: mode } };
+ }
+
+ // Setting a tier must never activate Cloud β€” meta-proxy ADR-321
+ // Revision 3 keeps the plane choice and this Cloud-only secondary
+ // setting as separate controls, so `--routing-mode` alone writes only
+ // `routing_mode` and asks for no consent it does not need.
+ if (routingMode && !wantCloud) {
+ writeRoutingMode(routingMode);
+ output.printSuccess(
+ routingMode === 'auto'
+ ? 'Cloud tier selection set to auto β€” Cognitum scores each prompt.'
+ : `Cloud tier selection pinned to ${routingMode}.`,
+ );
+ if (readDataPlane() !== 'cloud') {
+ output.writeln(' Cloud routing is currently OFF, so this takes effect once you enable it:');
+ output.writeln(' ruflo proxy config --cloud --yes');
+ }
+ return { success: true, data: { routingMode } };
}
if (wantLocalOnly) {
@@ -150,15 +246,25 @@ const configSub: Command = {
output.writeln('');
if (!ctx.flags.yes) {
output.writeln('Re-run with --yes to confirm: ruflo proxy config --cloud --yes');
+ // Nothing is written on the unconfirmed path β€” including any
+ // --routing-mode passed alongside, which would otherwise leave a
+ // trace of an activation the user never confirmed.
return { success: true, data: { confirmed: false } };
}
recordConsent('cloud-routing', true, 'proxy-config-cloud');
}
writeDataPlane('cloud');
+ if (routingMode) writeRoutingMode(routingMode);
+ const effectiveMode = routingMode ?? readRoutingMode();
output.printSuccess('Cloud routing enabled.');
+ output.writeln(
+ effectiveMode === 'auto'
+ ? ' Tier selection: auto β€” Cognitum scores each prompt and picks low/mid/high.'
+ : ` Tier selection: pinned to ${effectiveMode}.`,
+ );
output.writeln(' Requests routed to local backends still never leave this machine.');
output.writeln(' Disable anytime: ruflo proxy config --local-only');
- return { success: true, data: { plane: 'cloud' } };
+ return { success: true, data: { plane: 'cloud', routingMode: effectiveMode } };
},
};
@@ -414,6 +520,7 @@ export const proxyCommand: Command = {
{ command: 'ruflo proxy start', description: 'Start meta-proxy in the foreground' },
{ command: 'ruflo proxy status', description: 'Show install + process status' },
{ command: 'ruflo proxy config --cloud --yes', description: 'Enable cloud routing (ADR-304)' },
+ { command: 'ruflo proxy config --routing-mode high', description: 'Pin the cloud tier instead of auto (ADR-321)' },
{ command: 'ruflo proxy config --local-only', description: 'Revert to local-only routing' },
{ command: 'ruflo proxy sponsor-status', description: 'Show current sponsored-mode state' },
{ command: 'ruflo proxy sponsor-enable --yes', description: 'Opt into sponsored downtime capacity' },
diff --git a/v3/docs/adr/ADR-304-local-meta-llm-proxy.md b/v3/docs/adr/ADR-304-local-meta-llm-proxy.md
index 978ac3b901..58df99c310 100644
--- a/v3/docs/adr/ADR-304-local-meta-llm-proxy.md
+++ b/v3/docs/adr/ADR-304-local-meta-llm-proxy.md
@@ -59,21 +59,9 @@ obtains credentials for proxy operation.
- **Default state after `ruflo proxy install` is local-only.** The proxy routes exclusively to local backends (Ollama, vLLM, SGLang). No prompt leaves the machine, and no request is made to api.cognitum.one for inference.
- **Cloud routing requires a separate explicit step** β€” `ruflo proxy config --cloud` β€” gated on the `cloud-routing` consent domain (ADR-302). Neither enrollment acceptance, `auth login`, nor proxy installation enables it.
-- **Pre-activation disclosure is mandatory.** Before cloud routing turns on, the UI states in plain terms what changes:
+- **Pre-activation disclosure is mandatory.** Before cloud routing turns on, the UI states in plain terms what changes. Activating Cloud decides three separate things, each with a different answer than the plane the user is leaving, so the disclosure answers all three: **who processes** the prompt (Cognitum, server-side, at api.cognitum.one), **who pays** (the user's Cognitum account β€” not their own Claude subscription, which is what the Passthrough plane uses), and **which model runs** (the plane selects a tier per prompt rather than honoring the client's requested model β€” see the routing-mode addendum below).
- ```
- Enabling cloud routing.
-
- With cloud routing ON, prompts for cloud-tier requests are sent to
- api.cognitum.one and forwarded to the selected provider
- (Claude / GPT / Gemini / DeepSeek / OpenRouter).
-
- Requests routed to local backends never leave this machine.
-
- Enable cloud routing? [y/N]
- ```
-
- The default answer is No.
+ The default answer is No. The exact wording lives in `CLOUD_ROUTING_DISCLOSURE` (`src/commands/proxy.ts`) and is asserted by `proxy-config-command.test.ts`; it is deliberately not transcribed here, because the previous copy in this ADR fell behind the shipped text and a reader could not tell which one was real.
- **Visible at runtime.** `ruflo proxy status` and every request receipt state the data plane used (`local` vs `cloud:<provider>`), so the user can verify where any given prompt went.
- Cloud routing can be disabled at any time (`ruflo proxy config --local-only`), reverting to a purely local multi-backend router and revoking the `cloud-routing` consent receipt.
@@ -129,3 +117,48 @@ is never written (the proxy's own untouched default).
`ruflo proxy config` (no flags) reports the current plane by reading the same file, defaulting to
`"passthrough"` (matching the Rust struct's own default) when no config file exists yet.
+
+## Addendum (2026-08-05) β€” Cloud tier selection is a user-visible setting, and the disclosure now says so
+
+Two gaps closed together, both traceable to meta-proxy#43.
+
+**1. The Cloud plane does not use the client's requested model, and we never said so.** meta-proxy
+ADR-321 rev-2 (shipped v0.6.0, work item M2 of cognitum-one/meta-proxy#43) applies tier selection to
+*all* Cloud traffic. Previously it applied only on the quota-failover reasons, so a deliberately
+configured Cloud plane forwarded the client's own model name β€” and since Claude Code names a
+frontier model by default, every request was served at the top tier with no ceiling and no proxy
+daily cap. That was the defect; difficulty-routing all Cloud traffic is the fix, not a regression.
+
+The boundary that matters for this ADR's local-first posture is unchanged and explicit in rev-2:
+**Passthrough and Local are untouched.** Those are the user's own subscription and their own
+backend; the proxy never rewrites a model there. A ruflo user reaches the Cloud plane only by
+running `proxy config --cloud`, and automatic movement off Passthrough still requires the ADR-313 /
+ADR-314 consent gates.
+
+Our disclosure never mentioned any of this β€” a user could enable Cloud believing their model choice
+still held. #43 M5a added processor/billing confirmation to the Developer Console selector; **M5b
+("equivalent disclosure to any terminal flow that explicitly activates Cloud") is this command**,
+and it is what the rewritten `CLOUD_ROUTING_DISCLOSURE` closes.
+
+**2. `ruflo proxy config --routing-mode <auto|low|mid|high>`.** rev-2's escape hatch is the
+`routing_mode` config field; the Developer Console gained a control for it (meta-proxy#52) and ruflo
+had none, so a ruflo user was stuck with `auto` with no way to disagree. The scorer reads prompt
+*shape* (length bands, code/reasoning markers, `max_tokens` bands), not task difficulty, so a
+short-but-hard prompt can under-escalate β€” pinning a tier is how a user overrides that judgement.
+
+Wire values were confirmed against meta-proxy's `RoutingMode` enum (`src/config.rs`, same
+`#[serde(rename_all = "snake_case")]` treatment as `DataPlane`): `routing_mode = "auto" | "low" |
+"mid" | "high"`, `#[serde(default)]` so an existing config file that omits it keeps working and
+means `auto`. An unrecognized value already in the file is reported as `auto` rather than echoed
+back, matching the proxy's own degrade-to-safe-default behavior.
+
+**Setting a tier must never activate Cloud.** meta-proxy ADR-321 Revision 3 keeps the plane choice
+and this Cloud-only secondary setting as separate controls, so `--routing-mode` alone writes only
+`routing_mode`, asks for no consent it does not need, and tells the user the setting is inert until
+Cloud is on. `--routing-mode` with `--local-only` is refused rather than silently resolved, and an
+unconfirmed `--cloud` still writes nothing at all.
+
+**Still open upstream, deliberately not implemented here:** #43 M3 β€” a Cloud tier ceiling and daily
+cap. Sponsored has `sponsored_daily_cap_usd`; Cloud has no proxy-side equivalent. #43 records the
+cap amount and reset semantics as a product decision that must not be guessed, so the disclosure
+makes no claim about caps in either direction.