@kaitranntt/ccs 8.2.0 → 8.3.0

package/dist/cliproxy/routing/pool-onboarding-hint.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Pool onboarding hint
+ *
+ * Fires once (per install, TTY only) when a user has >= 2 native Claude account
+ * profiles and has not yet enabled pool routing.  Covers the #1464 use case:
+ * existing users with multiple native profiles who have never touched CLIProxy
+ * and would miss the 1->2 account-add opt-in prompt.
+ *
+ * Three hint sites call this module:
+ *   1. ccs doctor  (post-checks summary, fires for ALL install types)
+ *   2. account-flow launch (print-only, pre-spawn) - unified config only
+ *   3. ccs auth create (before spawning Claude for a 2nd+ profile) - unified config only
+ *
+ * Sites 2 and 3 are gated on hasUnifiedConfig() so that legacy profiles.json-only
+ * installs receive the hint exclusively from ccs doctor (site 1).  This ensures
+ * once-per-install dismissal semantics for every install type: unified installs
+ * dismiss via config.yaml on first show; legacy installs see the hint from
+ * doctor only (which is the natural discovery surface for that population).
+ *
+ * Dismissal: stored in pool_routing.onboarding_hint_dismissed in config.yaml.
+ * Reuses the Phase 3 pool_routing schema family - one schema home, no duplicate
+ * plumbing.  Legacy installs cannot persist a dismissal without config.yaml;
+ * this is intentional - dismissal for legacy users happens via ccs migrate or
+ * pool enable (both create config.yaml).
+ *
+ * TTY contract: non-TTY sessions never print the hint (single line only).
+ * The hint is informational only - it never blocks the calling flow.
+ *
+ * History note: pooled sessions live in the CLIProxy lane, not the native
+ * profile's CLAUDE_CONFIG_DIR lane.  Transcripts and --continue inventory do
+ * NOT follow.  This is stated on the docs page linked in the hint copy.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeShowPoolOnboardingHint = exports.countNativeClaudeProfiles = exports.dismissOnboardingHint = exports.isOnboardingHintDismissed = exports.POOL_DOCS_LINK = void 0;
+const ui_1 = require("../../utils/ui");
+const config_loader_facade_1 = require("../../config/config-loader-facade");
+const profile_registry_1 = require("../../auth/profile-registry");
+// Docs anchor - Phase 7 acceptance item: verify curl returns HTTP 200 before release.
+// Pattern matches canonical docs domain used in error-codes.ts and version-command.ts.
+exports.POOL_DOCS_LINK = 'https://docs.ccs.kaitran.ca/features/pool';
+/**
+ * Whether the one-time pool onboarding hint has already been dismissed.
+ *
+ * @param config - Optional pre-loaded config to avoid a redundant disk read +
+ *   YAML parse.  When omitted the config is loaded here.
+ */
+function isOnboardingHintDismissed(config) {
+    const cfg = config ?? (0, config_loader_facade_1.loadOrCreateUnifiedConfig)();
+    return cfg.cliproxy?.pool_routing?.onboarding_hint_dismissed === true;
+}
+exports.isOnboardingHintDismissed = isOnboardingHintDismissed;
+/**
+ * Mark the pool onboarding hint as permanently dismissed.
+ * Written after first display so subsequent invocations are silent.
+ *
+ * Guard: skipped when config.yaml does not yet exist (legacy profiles.json-only
+ * installs). Writing here would create config.yaml, flipping isUnifiedMode()
+ * and silently mode-migrating the install outside the deliberate ccs migrate
+ * flow. For those users the hint may re-appear across process restarts; that
+ * is acceptable -- the hint is informational and non-blocking, and the user
+ * can silence it permanently via ccs migrate.
+ */
+function dismissOnboardingHint() {
+    if (!(0, config_loader_facade_1.hasUnifiedConfig)()) {
+        // Legacy-only install: skip persist to avoid implicit config.yaml creation.
+        return;
+    }
+    (0, config_loader_facade_1.mutateConfig)((cfg) => {
+        if (!cfg.cliproxy)
+            return;
+        cfg.cliproxy.pool_routing = {
+            ...cfg.cliproxy.pool_routing,
+            onboarding_hint_dismissed: true,
+        };
+    });
+}
+exports.dismissOnboardingHint = dismissOnboardingHint;
+/**
+ * Whether pool routing is currently enabled.
+ *
+ * @param config - Optional pre-loaded config to avoid a redundant disk read +
+ *   YAML parse.  When omitted the config is loaded here.
+ */
+function isPoolEnabled(config) {
+    const cfg = config ?? (0, config_loader_facade_1.loadOrCreateUnifiedConfig)();
+    return cfg.cliproxy?.pool_routing?.enabled === true;
+}
+/**
+ * Count native Claude account profiles (type === 'account').
+ *
+ * Uses ProfileRegistry so the count respects both legacy profiles.json and
+ * unified config accounts - same source of truth as the rest of the codebase.
+ *
+ * type === 'account' implies Claude: per the profile-registry schema, every
+ * account profile is an isolated Claude instance (CLAUDE_CONFIG_DIR lane) with
+ * no CLI discriminator. Gemini/Codex multi-account lives in CLIProxy auth
+ * files, never in profiles.json, so this filter cannot over-count.
+ */
+function countNativeClaudeProfiles() {
+    try {
+        const registry = new profile_registry_1.ProfileRegistry();
+        const profiles = registry.getAllProfilesMerged();
+        return Object.values(profiles).filter((p) => p.type === 'account').length;
+    }
+    catch {
+        return 0;
+    }
+}
+exports.countNativeClaudeProfiles = countNativeClaudeProfiles;
+/**
+ * Maybe print the one-time pool onboarding hint.
+ *
+ * Skips silently when any of the following are true:
+ *   - Not a TTY (piped / CI / non-interactive)
+ *   - Fewer than 2 native Claude account profiles exist
+ *   - Pool routing is already enabled
+ *   - The hint was already dismissed
+ *   - Any error occurs while deciding (e.g. malformed config.yaml)
+ *
+ * Checks run cheapest-first: TTY and profile count are evaluated before any
+ * config read, and the config is loaded exactly once for the two
+ * config-derived checks.  The entire decision is wrapped in try/catch so a
+ * hint failure can never break an account launch.
+ *
+ * When the hint is printed for the first time it is also dismissed so it
+ * never appears again (it is informational, not an interactive prompt).
+ *
+ * @param profileCount - Pre-computed profile count (pass undefined to compute
+ *   it here).  The caller may pass a count it already has to avoid a second
+ *   registry read.
+ */
+function maybeShowPoolOnboardingHint(profileCount) {
+    // A hint must never break a launch.  Any error in the decision path
+    // (malformed config.yaml, registry read failure, etc.) silently skips the
+    // hint rather than rethrowing into the caller's account-launch flow.
+    try {
+        // Cheapest checks first, no disk read required.
+        // Non-TTY: stay silent (piped / CI / non-interactive).
+        if (!process.stdout.isTTY) {
+            return { printed: false, skipReason: 'non-tty' };
+        }
+        const count = profileCount ?? countNativeClaudeProfiles();
+        if (count < 2) {
+            return { printed: false, skipReason: 'fewer-than-2-profiles' };
+        }
+        // Load config once and reuse it for both config-derived checks below,
+        // avoiding two disk reads + YAML parses per call.
+        const config = (0, config_loader_facade_1.loadOrCreateUnifiedConfig)();
+        if (isPoolEnabled(config)) {
+            return { printed: false, skipReason: 'pool-already-enabled' };
+        }
+        if (isOnboardingHintDismissed(config)) {
+            return { printed: false, skipReason: 'dismissed' };
+        }
+        console.log((0, ui_1.info)(`You have ${count} Claude profiles. Pool routing can auto-continue 'ccs claude' when one account hits its limit. Enable: ccs cliproxy pool --enable  Docs: ${exports.POOL_DOCS_LINK}`));
+        // Dismiss so subsequent invocations (other sites or next run) are silent.
+        try {
+            dismissOnboardingHint();
+        }
+        catch {
+            // Best-effort: a config write failure must not surface to the user here.
+        }
+        return { printed: true };
+    }
+    catch {
+        // Decision failed (e.g. malformed config) - skip the hint, never throw.
+        return { printed: false, skipReason: 'error' };
+    }
+}
+exports.maybeShowPoolOnboardingHint = maybeShowPoolOnboardingHint;
+//# sourceMappingURL=pool-onboarding-hint.js.map

package/dist/cliproxy/routing/pool-onboarding-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-onboarding-hint.js","sourceRoot":"","sources":["../../../src/cliproxy/routing/pool-onboarding-hint.ts"],"names":[],"mappings":"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"}

package/dist/cliproxy/routing/pool-opt-in-prompt.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pool routing opt-in prompt
+ *
+ * Fires at the 1->2 account-add transition for verified providers (claude, agy).
+ * Informed-consent copy: discloses instance-global effect and lists ALL providers
+ * with >=2 accounts that will be affected.
+ *
+ * Codex/gemini get no prompt until failover behavior is verified for pool routing
+ * (spike Test D pending).  They continue with implicit round-robin.
+ *
+ * Remote/Docker targets: prompt replaced by manual-config hint because session
+ * affinity is not remotely toggleable from CCS (PR #1117 precedent).
+ */
+import type { CLIProxyProvider } from '../types';
+/**
+ * Whether the pool routing opt-in prompt has been permanently dismissed.
+ * Dismissal is recorded per-provider in pool_routing.prompt_dismissed.
+ */
+export declare function isPoolPromptDismissed(): boolean;
+/**
+ * Mark the pool routing prompt as permanently dismissed (user said no explicitly).
+ */
+export declare function dismissPoolPrompt(): void;
+export interface PoolOptInResult {
+    /** Whether the prompt was shown */
+    prompted: boolean;
+    /** Whether pool routing was enabled */
+    enabled: boolean;
+    /** Whether the prompt was skipped (remote, dismissed, not verified, already enabled) */
+    skipped: boolean;
+    skipReason?: string;
+}
+/**
+ * Offer pool routing opt-in when the account count crosses 1->2 for a verified provider.
+ *
+ * Call this immediately after a successful account registration when the provider
+ * transitions from 1 to 2 accounts.  The function is a no-op when:
+ *   - Pool routing is already enabled
+ *   - Provider is not in the verified pool list (codex, gemini, etc.)
+ *   - The prompt was previously dismissed
+ *   - Target is non-TTY (piped input / CI)
+ *
+ * Remote/Docker targets get a manual-config hint instead of an interactive prompt.
+ *
+ * @param provider - The provider that just reached 2 accounts
+ * @param accountCountBefore - Number of accounts before this add (should be 1 for transition)
+ * @param port - CLIProxy port (default: 8317)
+ */
+export declare function maybeOfferPoolRouting(provider: CLIProxyProvider, accountCountBefore: number, port?: number): Promise<PoolOptInResult>;
+//# sourceMappingURL=pool-opt-in-prompt.d.ts.map

package/dist/cliproxy/routing/pool-opt-in-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-opt-in-prompt.d.ts","sourceRoot":"","sources":["../../../src/cliproxy/routing/pool-opt-in-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA2BjD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC;AAyBD,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,IAAI,GAAE,MAA8B,GACnC,OAAO,CAAC,eAAe,CAAC,CAgJ1B"}

package/dist/cliproxy/routing/pool-opt-in-prompt.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Pool routing opt-in prompt
+ *
+ * Fires at the 1->2 account-add transition for verified providers (claude, agy).
+ * Informed-consent copy: discloses instance-global effect and lists ALL providers
+ * with >=2 accounts that will be affected.
+ *
+ * Codex/gemini get no prompt until failover behavior is verified for pool routing
+ * (spike Test D pending).  They continue with implicit round-robin.
+ *
+ * Remote/Docker targets: prompt replaced by manual-config hint because session
+ * affinity is not remotely toggleable from CCS (PR #1117 precedent).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeOfferPoolRouting = exports.dismissPoolPrompt = exports.isPoolPromptDismissed = void 0;
+const ui_1 = require("../../utils/ui");
+const prompt_1 = require("../../utils/prompt");
+const proxy_target_resolver_1 = require("../proxy/proxy-target-resolver");
+const routing_strategy_1 = require("./routing-strategy");
+const config_loader_facade_1 = require("../../config/config-loader-facade");
+const port_manager_1 = require("../config/port-manager");
+const path_resolver_1 = require("../config/path-resolver");
+const path_resolver_2 = require("../config/path-resolver");
+const account_manager_1 = require("../accounts/account-manager");
+const registry_1 = require("../accounts/registry");
+/**
+ * Collect names of all providers that currently have >= 2 accounts registered.
+ * Derived from the registry's actual provider keys so this list can never drift
+ * from the CLIProxyProvider type union (spec requirement: disclose ALL affected
+ * providers, not just a hardcoded subset).
+ */
+function getMultiAccountProviders() {
+    const result = [];
+    try {
+        const registry = (0, registry_1.loadAccountsRegistry)();
+        for (const p of Object.keys(registry.providers)) {
+            try {
+                if ((0, account_manager_1.getProviderAccounts)(p).length >= 2)
+                    result.push(p);
+            }
+            catch {
+                // Provider registry entry present but accounts unreadable — skip
+            }
+        }
+    }
+    catch {
+        // Registry unreadable (first-run, corrupt) — return empty; caller falls back to provider param
+    }
+    return result;
+}
+/**
+ * Whether the pool routing opt-in prompt has been permanently dismissed.
+ * Dismissal is recorded per-provider in pool_routing.prompt_dismissed.
+ */
+function isPoolPromptDismissed() {
+    return (0, config_loader_facade_1.loadOrCreateUnifiedConfig)().cliproxy?.pool_routing?.prompt_dismissed === true;
+}
+exports.isPoolPromptDismissed = isPoolPromptDismissed;
+/**
+ * Mark the pool routing prompt as permanently dismissed (user said no explicitly).
+ */
+function dismissPoolPrompt() {
+    // Defense in depth: never write the unified config on a legacy install — that
+    // would create config.yaml and silently flip isUnifiedMode().  maybeOfferPoolRouting
+    // already gates the only caller, but this keeps the exported helper safe too.
+    if (!(0, config_loader_facade_1.hasUnifiedConfig)())
+        return;
+    (0, config_loader_facade_1.mutateConfig)((cfg) => {
+        if (!cfg.cliproxy)
+            return;
+        cfg.cliproxy.pool_routing = {
+            ...cfg.cliproxy.pool_routing,
+            prompt_dismissed: true,
+        };
+    });
+}
+exports.dismissPoolPrompt = dismissPoolPrompt;
+/**
+ * Show the remote/Docker hint instead of an interactive prompt.
+ * Session affinity is not remotely toggleable from CCS (fail-closed
+ * per PR #1117 precedent) so we emit guidance only.
+ */
+function printRemoteHint(provider) {
+    console.log('');
+    console.log((0, ui_1.info)(`[i] Pool routing hint: you now have 2+ ${provider} accounts on a remote/Docker CLIProxy.`));
+    console.log('    CCS cannot toggle session affinity on remote targets yet (management API limitation).');
+    console.log('    To enable pool routing manually, add to your CLIProxy config.yaml:');
+    console.log('      disable-cooling: false');
+    console.log(`      max-retry-credentials: ${routing_strategy_1.POOL_MAX_RETRY_CREDENTIALS}`);
+    console.log('      routing:');
+    console.log('        strategy: fill-first');
+    console.log('        session-affinity: true');
+    console.log('        session-affinity-ttl: "1h"');
+    console.log('');
+}
+/**
+ * Offer pool routing opt-in when the account count crosses 1->2 for a verified provider.
+ *
+ * Call this immediately after a successful account registration when the provider
+ * transitions from 1 to 2 accounts.  The function is a no-op when:
+ *   - Pool routing is already enabled
+ *   - Provider is not in the verified pool list (codex, gemini, etc.)
+ *   - The prompt was previously dismissed
+ *   - Target is non-TTY (piped input / CI)
+ *
+ * Remote/Docker targets get a manual-config hint instead of an interactive prompt.
+ *
+ * @param provider - The provider that just reached 2 accounts
+ * @param accountCountBefore - Number of accounts before this add (should be 1 for transition)
+ * @param port - CLIProxy port (default: 8317)
+ */
+async function maybeOfferPoolRouting(provider, accountCountBefore, port = port_manager_1.CLIPROXY_DEFAULT_PORT) {
+    // Fast path: only fire at the 1->2 transition (accountCountBefore check only).
+    // The actual post-add count is verified below, after cheap early-exit guards pass,
+    // so that provider/dismissed/remote guards still return their expected skipReason
+    // regardless of whether the registry has been populated in the test environment.
+    if (accountCountBefore !== 1) {
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'not-at-transition' };
+    }
+    // Legacy install guard: on a profiles.json/config.json-only install there is no
+    // unified config.yaml.  Both accept (enablePoolRouting) and decline
+    // (dismissPoolPrompt) write the unified config, which would create config.yaml
+    // and silently flip isUnifiedMode() outside the deliberate `ccs migrate` flow,
+    // orphaning the user's config.json profiles.  Skip entirely before any prompt
+    // or dismissal persistence.  Mirrors the guards in create-command.ts and
+    // account-flow.ts and the hazard documented in pool-onboarding-hint.ts.
+    // Silent by design: legacy installs receive pool guidance exclusively from
+    // ccs doctor (pool-onboarding-hint site 1); printing here would nag on every
+    // account add with no dismissal available.
+    if (!(0, config_loader_facade_1.hasUnifiedConfig)()) {
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'legacy-config' };
+    }
+    // Only for providers where pool routing is verified
+    if (!routing_strategy_1.POOL_ROUTING_VERIFIED_PROVIDERS.has(provider)) {
+        return {
+            prompted: false,
+            enabled: false,
+            skipped: true,
+            skipReason: `provider-${provider}-unverified`,
+        };
+    }
+    // No-op if already enabled
+    const config = (0, config_loader_facade_1.loadOrCreateUnifiedConfig)();
+    if (config.cliproxy?.pool_routing?.enabled === true) {
+        return { prompted: false, enabled: true, skipped: true, skipReason: 'already-enabled' };
+    }
+    // No-op if user already dismissed
+    if (isPoolPromptDismissed()) {
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'dismissed' };
+    }
+    // Remote / Docker target: print hint, do not prompt.
+    // Check before account count so remote targets with locally-unknown registries
+    // still get the hint (the remote CLIProxy holds the authoritative account list).
+    const target = (0, proxy_target_resolver_1.getProxyTarget)();
+    if (target.isRemote) {
+        printRemoteHint(provider);
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'remote-target' };
+    }
+    // Verify the actual post-add count is >= 2.  registerAccount deduplicates by
+    // email/token-file so re-authenticating the single existing account keeps the
+    // count at 1 — not a real 1->2 transition.  Checking here (before TTY) ensures
+    // re-auth dedup always returns not-at-transition even in non-TTY/CI sessions.
+    const accountCountAfter = (0, account_manager_1.getProviderAccounts)(provider).length;
+    if (accountCountAfter < 2) {
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'not-at-transition' };
+    }
+    // Non-TTY (piped input / CI): skip silently
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'non-tty' };
+    }
+    // Automation bypass: InteractivePrompt.confirm auto-returns true when --yes/-y
+    // is in argv or CCS_YES=1 is set, regardless of the default:false.  This is an
+    // INSTANCE-GLOBAL routing/cooling consent decision; a generic automation flag
+    // must never grant it.  Skip WITHOUT printing the prompt and WITHOUT persisting
+    // dismissal, so a future interactive run still offers the opt-in.
+    if (process.env.CCS_YES === '1' ||
+        process.argv.includes('--yes') ||
+        process.argv.includes('-y')) {
+        return { prompted: false, enabled: false, skipped: true, skipReason: 'automation-bypass' };
+    }
+    // Gather all providers with 2+ accounts for disclosure
+    const multiAccountProviders = getMultiAccountProviders();
+    const providerList = multiAccountProviders.length > 0 ? multiAccountProviders.join(', ') : provider;
+    console.log('');
+    console.log((0, ui_1.warn)('Pool routing: you now have 2+ accounts for ' + provider));
+    console.log('');
+    console.log('    CCS can enable pool routing (fill-first + session affinity + 429 cooldown).');
+    console.log('    This is an INSTANCE-GLOBAL change: it affects account selection for ALL');
+    console.log(`    CLIProxy providers on this machine: ${providerList}`);
+    console.log('');
+    console.log('    What changes:');
+    console.log('      - disable-cooling: false  (cooldown is required for retry-cap to work)');
+    console.log('        A 429 suspends a credential briefly (1s -> 30m exp backoff).');
+    console.log('        A 401/403 suspends it for 30 minutes (correct: broken auth = no traffic).');
+    console.log('      - routing: fill-first      (drain one account before switching)');
+    console.log('      - session-affinity: true   (TTL 1h, pinned per conversation)');
+    console.log(`      - max-retry-credentials: ${routing_strategy_1.POOL_MAX_RETRY_CREDENTIALS}  (stop after ${routing_strategy_1.POOL_MAX_RETRY_CREDENTIALS} attempts per request)`);
+    console.log('');
+    console.log('    You can roll back at any time: ccs cliproxy pool --disable');
+    console.log('    (Or re-enable later: ccs cliproxy pool --enable)');
+    console.log('');
+    const yes = await prompt_1.InteractivePrompt.confirm('    Enable pool routing for all CLIProxy providers?', { default: false });
+    if (!yes) {
+        // Persist decline so we don't re-ask on every subsequent add
+        dismissPoolPrompt();
+        console.log((0, ui_1.info)("    Declined. Pool routing stays off. Run 'ccs cliproxy pool --enable' to opt in later."));
+        console.log('');
+        return { prompted: true, enabled: false, skipped: false };
+    }
+    const configPath = (0, path_resolver_1.getConfigPathForPort)(port);
+    const authDir = (0, path_resolver_2.getAuthDir)();
+    const result = (0, routing_strategy_1.enablePoolRouting)(port, { configPath, authDir });
+    console.log('');
+    if (result.failed) {
+        // Config regeneration failed and the flag was rolled back: pool routing is
+        // NOT active.  Surface the recovery copy and report enabled:false so callers
+        // (and quota/dashboard) do not claim pool ON.
+        console.log((0, ui_1.warn)(result.message));
+        console.log('');
+        return { prompted: true, enabled: false, skipped: false };
+    }
+    if (result.changed) {
+        console.log((0, ui_1.info)(result.message));
+    }
+    console.log('');
+    // User accepted and enablePoolRouting completed: pool routing is enabled
+    // even when this call was an idempotent no-op (changed=false).
+    return { prompted: true, enabled: true, skipped: false };
+}
+exports.maybeOfferPoolRouting = maybeOfferPoolRouting;
+//# sourceMappingURL=pool-opt-in-prompt.js.map

package/dist/cliproxy/routing/pool-opt-in-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-opt-in-prompt.js","sourceRoot":"","sources":["../../../src/cliproxy/routing/pool-opt-in-prompt.ts"],"names":[],"mappings":"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"}

package/dist/cliproxy/routing/routing-strategy.d.ts

@@ -2,12 +2,138 @@ import type { CliproxyRoutingStrategy } from '../types';
 export declare const DEFAULT_CLIPROXY_ROUTING_STRATEGY: CliproxyRoutingStrategy;
 export declare const DEFAULT_CLIPROXY_SESSION_AFFINITY_ENABLED = false;
 export declare const DEFAULT_CLIPROXY_SESSION_AFFINITY_TTL = "1h";
+/**
+ * Pool routing defaults written to config when pool routing is enabled.
+ * fill-first + session affinity drains one account before using another,
+ * maximising per-account context depth while honouring cooldown windows.
+ */
+export declare const POOL_ROUTING_STRATEGY: CliproxyRoutingStrategy;
+export declare const POOL_SESSION_AFFINITY_ENABLED = true;
+export declare const POOL_SESSION_AFFINITY_TTL = "1h";
+export declare const POOL_MAX_RETRY_CREDENTIALS = 3;
+/**
+ * Providers for which pool routing is available and the opt-in prompt
+ * shows the full cooling/routing disclosure.  Others (codex, gemini)
+ * have failover behaviour that is unverified for pool routing; they get
+ * a softened prompt variant or no prompt until spike Test D confirms.
+ */
+export declare const POOL_ROUTING_VERIFIED_PROVIDERS: Set<string>;
+/**
+ * Minimum CLIProxy version that supports pool routing keys:
+ * max-retry-credentials and the cooling flip.
+ * Older binaries silently ignore unknown keys — pool rails would appear active
+ * but have no effect.  Warn the user at enable time if below this version.
+ *
+ * NOTE: Update this constant when upstream first ships these keys.
+ * Current best estimate based on spec; adjust after spike Test D confirms.
+ */
+export declare const POOL_ROUTING_MIN_VERSION = "6.9.45";
+export interface EnablePoolRoutingResult {
+    /** Whether the pool routing state actually changed */
+    changed: boolean;
+    /** Whether an existing explicit user routing setting was preserved */
+    preservedExplicitSetting: boolean;
+    /**
+     * True when the config could not be regenerated and the pool flag was rolled
+     * back.  Pool routing is NOT active; the message carries recovery guidance.
+     */
+    failed?: boolean;
+    message: string;
+}
+export interface DisablePoolRoutingResult {
+    changed: boolean;
+    /** True when the config could not be regenerated and the flag was rolled back. */
+    failed?: boolean;
+    message: string;
+}
+/**
+ * Detect whether the user has set a routing strategy that differs from the
+ * injected default (round-robin).
+ *
+ * Background: loadOrCreateUnifiedConfig persists injected defaults to disk on
+ * first load, so `strategy: round-robin` may appear in the raw YAML even on a
+ * pristine config — it was injected by CCS, not written by the user.  A stored
+ * value EQUAL to the default is therefore treated as NOT explicit so that
+ * enablePoolRouting does not falsely claim to be "preserving a custom strategy".
+ *
+ * A value that DIFFERS from the default (e.g. fill-first) is treated as
+ * user-managed: preserve it and warn.
+ */
+export declare function hasExplicitRoutingStrategy(): boolean;
+/**
+ * Detect whether the user has set session-affinity to a value that differs
+ * from the injected default (false).
+ *
+ * Same rationale as hasExplicitRoutingStrategy: loadOrCreateUnifiedConfig may
+ * persist `session_affinity: false` as a default, so presence alone is not
+ * sufficient — only a value that differs from the default counts as explicit.
+ */
+export declare function hasExplicitSessionAffinity(): boolean;
+/**
+ * Enable pool routing: write pool_routing.enabled = true and the canonical
+ * pool defaults (fill-first, session affinity 1h, max-retry-credentials: 3)
+ * to the CCS unified config.  Regenerates the CLIProxy config.yaml so the
+ * cooling flip and routing block take effect immediately (CLIProxy hot-reloads).
+ *
+ * Explicit user routing settings are preserved and a warning is emitted.
+ * The pool flag is written regardless — the generator uses fill-first/affinity
+ * from the pool defaults when pool is enabled, bypassing any stored routing.
+ *
+ * Idempotent: calling when already enabled is a no-op.
+ */
+export declare function enablePoolRouting(port: number, options?: {
+    configPath?: string;
+    authDir?: string;
+}): EnablePoolRoutingResult;
+/**
+ * Disable pool routing: clear pool_routing.enabled and restore the non-pool
+ * config defaults (disable-cooling: true, round-robin, no affinity).
+ * Regenerates the CLIProxy config.yaml.
+ *
+ * IMPORTANT: disablePoolRouting MUST explicitly restore routing to round-robin
+ * and session_affinity to false.  Simply clearing pool_routing.enabled is not
+ * sufficient because the upstream CLIProxy default for disable-cooling is false
+ * (cooling ON) when the key is absent.  Leaving cooling ON for a user who has
+ * disabled pool routing would reintroduce the single-account blackout that v5
+ * (commit fb77d72a) fixed.
+ *
+ * Idempotent: calling when already disabled is a no-op.
+ */
+export declare function disablePoolRouting(port: number, options?: {
+    configPath?: string;
+    authDir?: string;
+}): DisablePoolRoutingResult;
+/**
+ * Pool routing mode summary surfaced alongside routing state for the dashboard.
+ * When pool routing is enabled the generator forces fill-first + session affinity
+ * + cooling, regardless of stored routing values.
+ */
+export interface CliproxyPoolRoutingState {
+    enabled: boolean;
+    maxRetryCredentials?: number;
+    /**
+     * Whether CCS can manage pool routing for this target.  enablePoolRouting only
+     * writes LOCAL config files, so a remote proxy is never affected by the local
+     * pool flag.  For remote targets this is false and `enabled` reflects the local
+     * config only (not the remote proxy's behaviour).  Omitted (treated as true)
+     * for local targets.  Mirrors CliproxySessionAffinityState.manageable.
+     */
+    manageable?: boolean;
+    /** Explanation surfaced when manageable is false (remote target). */
+    message?: string;
+}
 export interface CliproxyRoutingState {
     strategy: CliproxyRoutingStrategy;
     source: 'live' | 'config';
     target: 'local' | 'remote';
     reachable: boolean;
     message?: string;
+    /**
+     * Pool routing mode. For local targets `enabled` reflects the active proxy
+     * config. For remote targets `manageable` is false and `enabled` reflects only
+     * the local config (the remote proxy is not affected by it).
+     */
+    poolRouting?: CliproxyPoolRoutingState;
 }
 export interface CliproxyRoutingApplyResult extends CliproxyRoutingState {
     applied: 'live' | 'live-and-config' | 'config-only';
@@ -34,6 +160,12 @@ export declare function normalizeCliproxySessionAffinityTtl(value: unknown): str
 export declare function getConfiguredCliproxyRoutingStrategy(): CliproxyRoutingStrategy;
 export declare function getConfiguredCliproxySessionAffinitySettings(): Required<CliproxySessionAffinitySettings>;
 export declare function fetchLiveCliproxyRoutingStrategy(): Promise<CliproxyRoutingStrategy>;
+/**
+ * Read the pool routing mode from the unified config.
+ * Pool routing is proxy-wide opt-in; this reflects the persisted flag, not a
+ * live selector probe.
+ */
+export declare function getCliproxyPoolRoutingState(): CliproxyPoolRoutingState;
 export declare function readCliproxyRoutingState(): Promise<CliproxyRoutingState>;
 export declare function readCliproxySessionAffinityState(): Promise<CliproxySessionAffinityState>;
 export declare function applyCliproxyRoutingStrategy(strategy: CliproxyRoutingStrategy): Promise<CliproxyRoutingApplyResult>;

package/dist/cliproxy/routing/routing-strategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing-strategy.d.ts","sourceRoot":"","sources":["../../../src/cliproxy/routing/routing-strategy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAGxD,eAAO,MAAM,iCAAiC,EAAE,uBAAuC,CAAC;AACxF,eAAO,MAAM,yCAAyC,QAAQ,CAAC;AAC/D,eAAO,MAAM,qCAAqC,OAAO,CAAC;AAK1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACtE,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,aAAa,CAAC;CACrD;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,aAAa,CAAC;IACjC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kCAAmC,SAAQ,4BAA4B;IACtF,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC;CACxC;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAiB/F;AAED,wBAAgB,uCAAuC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CA0BtF;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAWjF;AAED,wBAAgB,oCAAoC,IAAI,uBAAuB,CAK9E;AAED,wBAAgB,4CAA4C,IAAI,QAAQ,CAAC,+BAA+B,CAAC,CAUxG;AAED,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAezF;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CA4B9E;AAED,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,4BAA4B,CAAC,CA8B9F;AAED,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAAC,0BAA0B,CAAC,CA4CrC;AAED,wBAAsB,oCAAoC,CACxD,QAAQ,EAAE,+BAA+B,GACxC,OAAO,CAAC,kCAAkC,CAAC,CAgD7C"}
+{"version":3,"file":"routing-strategy.d.ts","sourceRoot":"","sources":["../../../src/cliproxy/routing/routing-strategy.ts"],"names":[],"mappings":"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"}