π 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): 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.tsindex 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.tsindex 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.mdindex 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.