@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/core/brain_config.d.ts

@@ -0,0 +1,52 @@
+/** Provider id matches the slot prefix in the vault
+ *  (byok_<provider>_api_key). */
+export type BrainProvider = 'anthropic' | 'openai' | 'google_ai' | 'deepseek' | 'xai' | 'mistral' | 'cohere' | 'yujin_managed';
+export declare const ALL_BRAIN_PROVIDERS: readonly BrainProvider[];
+/** Vault slot name a given provider stores its key under. The
+ *  yujin_managed virtual provider has no client-side key (the
+ *  worker holds the real provider key); the secret needed for
+ *  auth is the yf_server_api_key in the regular vault, not a
+ *  byok_ slot. We return a stable placeholder so callers that
+ *  query slot existence get a meaningful answer. */
+export declare function vaultSlotForProvider(p: BrainProvider): string;
+export interface TierBinding {
+    provider: BrainProvider;
+    model: string;
+}
+export interface BrainConfig {
+    version: 1;
+    eco: TierBinding;
+    frontier: TierBinding;
+    /** Default tier when the cost router cannot infer from
+     *  workflow state / verb_id. */
+    chat_default_tier: 'eco' | 'frontier';
+    /** PND-069 -- modo eco habilitado. Cuando es false, el router
+     *  sirve TODOS los turnos con frontier (algunos usuarios
+     *  prefieren el mejor modelo siempre y pagan el costo). El
+     *  override explicito /eco por turno sigue ganando. */
+    eco_enabled: boolean;
+    /** PND-069 -- modalidad de billing para el brain Anthropic:
+     *  'plan' = suscripcion Claude (subproceso claude-code-cli);
+     *  'console' = API key (Console). Solo aplica a providers con
+     *  ambas modalidades (hoy: anthropic). Prioridad de resolucion
+     *  en yf chat: flag --provider > este campo > wizard_state.
+     *  Cambiarlo requiere reabrir el panel. */
+    anthropic_mode?: 'plan' | 'console';
+    /** Startup tabs (dogfood 2026-06-10) -- al abrir Forge se
+     *  instancian 4 pestanas del pizarron (grafo grafico, grafo
+     *  semantico, pendings, workflow). Default true; el usuario lo
+     *  apaga con este switch en Ajustes. */
+    startup_tabs_enabled: boolean;
+}
+export declare function defaultBrainConfig(): BrainConfig;
+/** Map a deprecated model id to its current replacement (or pass through). */
+export declare function migrateModelId(m: string): string;
+export declare function readBrainConfig(): Promise<BrainConfig>;
+export declare function writeBrainConfig(cfg: BrainConfig): Promise<void>;
+/** Mutate one tier without losing the other. */
+export declare function setTierBinding(tier: 'eco' | 'frontier', provider: BrainProvider, model: string): Promise<BrainConfig>;
+/** Set the default tier for chat turns the router cannot infer. */
+export declare function setChatDefaultTier(tier: 'eco' | 'frontier'): Promise<BrainConfig>;
+/** Reset to factory defaults. */
+export declare function resetBrainConfig(): Promise<BrainConfig>;
+//# sourceMappingURL=brain_config.d.ts.map

package/dist/core/brain_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain_config.d.ts","sourceRoot":"","sources":["../../src/core/brain_config.ts"],"names":[],"mappings":"AA+BA;iCACiC;AACjC,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,GACV,KAAK,GACL,SAAS,GACT,QAAQ,GAMR,eAAe,CAAC;AAEpB,eAAO,MAAM,mBAAmB,EAAE,SAAS,aAAa,EAGvD,CAAC;AAEF;;;;;oDAKoD;AACpD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAW7D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,GAAG,EAAE,WAAW,CAAC;IACjB,QAAQ,EAAE,WAAW,CAAC;IACtB;oCACgC;IAChC,iBAAiB,EAAE,KAAK,GAAG,UAAU,CAAC;IACtC;;;2DAGuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;+CAK2C;IAC3C,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;4CAGwC;IACxC,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,kBAAkB,IAAI,WAAW,CAShD;AA0BD,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAeD,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAyB5D;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtE;AAED,gDAAgD;AAChD,wBAAsB,cAAc,CAClC,IAAI,EAAE,KAAK,GAAG,UAAU,EACxB,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,WAAW,CAAC,CAKtB;AAED,mEAAmE;AACnE,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,KAAK,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAKvF;AAED,iCAAiC;AACjC,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,WAAW,CAAC,CAI7D"}

package/dist/core/brain_config.js

@@ -0,0 +1,157 @@
+/**
+ * Brain config -- which provider + model serves each tier
+ * (alpha.51).
+ *
+ * Storage:
+ *   $YF_CONFIG_DIR/brain_config.json (or ~/.yujin-forge/brain_config.json)
+ *
+ * Shape:
+ *   {
+ *     "version": 1,
+ *     "eco":      { "provider": "google_ai", "model": "gemini-2.5-flash-lite" },
+ *     "frontier": { "provider": "anthropic", "model": "claude-opus-4-7" },
+ *     "chat_default_tier": "frontier"
+ *   }
+ *
+ * The API keys themselves live in the encrypted vault (see
+ * src/core/provider_keys.ts). This file ONLY records the
+ * provider+model selection per tier; the runtime cost router
+ * looks up the matching API key when it needs to invoke.
+ *
+ * Defaults (no file present):
+ *   eco       -> google_ai / gemini-2.5-flash-lite
+ *   frontier  -> anthropic / claude-opus-4-7
+ *   chat_default_tier -> 'frontier'
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const ALL_BRAIN_PROVIDERS = [
+    'anthropic', 'openai', 'google_ai', 'deepseek', 'xai', 'mistral', 'cohere',
+    'yujin_managed',
+];
+/** Vault slot name a given provider stores its key under. The
+ *  yujin_managed virtual provider has no client-side key (the
+ *  worker holds the real provider key); the secret needed for
+ *  auth is the yf_server_api_key in the regular vault, not a
+ *  byok_ slot. We return a stable placeholder so callers that
+ *  query slot existence get a meaningful answer. */
+export function vaultSlotForProvider(p) {
+    switch (p) {
+        case 'anthropic': return 'anthropic_api_key';
+        case 'openai': return 'openai_api_key';
+        case 'google_ai': return 'google_ai_key';
+        case 'deepseek': return 'deepseek_api_key';
+        case 'xai': return 'xai_api_key';
+        case 'mistral': return 'mistral_api_key';
+        case 'cohere': return 'cohere_api_key';
+        case 'yujin_managed': return 'yujin_managed';
+    }
+}
+export function defaultBrainConfig() {
+    return {
+        version: 1,
+        eco: { provider: 'google_ai', model: 'gemini-2.5-flash-lite' },
+        frontier: { provider: 'anthropic', model: 'claude-opus-4-8' },
+        chat_default_tier: 'frontier',
+        eco_enabled: true,
+        startup_tabs_enabled: true,
+    };
+}
+function brainConfigPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'brain_config.json');
+}
+function normaliseProvider(v) {
+    if (typeof v !== 'string')
+        return null;
+    const lc = v.toLowerCase().trim();
+    return ALL_BRAIN_PROVIDERS.includes(lc) ? lc : null;
+}
+/* Anthropic rotates models (Opus 4.7 -> 4.8, etc.). A stale model id
+ * makes `claude -p` / the API return 404 "model not found". Remap known
+ * dead ids on read so existing configs self-heal -- no user action. */
+const DEPRECATED_MODELS = {
+    'claude-opus-4-7': 'claude-opus-4-8',
+    'claude-opus-4-6': 'claude-opus-4-8',
+    'claude-opus-4-5': 'claude-opus-4-8',
+    'claude-sonnet-4-5': 'claude-sonnet-4-6',
+    'claude-sonnet-4-4': 'claude-sonnet-4-6',
+    'claude-haiku-4-4': 'claude-haiku-4-5-20251001',
+};
+/** Map a deprecated model id to its current replacement (or pass through). */
+export function migrateModelId(m) {
+    return DEPRECATED_MODELS[m] ?? m;
+}
+function normaliseTierBinding(v, fallback) {
+    if (!v || typeof v !== 'object')
+        return fallback;
+    const obj = v;
+    const provider = normaliseProvider(obj.provider);
+    const rawModel = typeof obj.model === 'string' && obj.model.trim() !== ''
+        ? obj.model.trim()
+        : fallback.model;
+    return {
+        provider: provider ?? fallback.provider,
+        model: migrateModelId(rawModel),
+    };
+}
+export async function readBrainConfig() {
+    const def = defaultBrainConfig();
+    try {
+        const raw = await fs.readFile(brainConfigPath(), 'utf-8');
+        const j = JSON.parse(raw);
+        const cfg = {
+            version: 1,
+            eco: normaliseTierBinding(j.eco, def.eco),
+            frontier: normaliseTierBinding(j.frontier, def.frontier),
+            chat_default_tier: (j.chat_default_tier === 'eco' || j.chat_default_tier === 'frontier')
+                ? j.chat_default_tier
+                : def.chat_default_tier,
+            /* Archivos previos a PND-069 no tienen el campo: default
+             * true (comportamiento historico). */
+            eco_enabled: j.eco_enabled !== false,
+            startup_tabs_enabled: j.startup_tabs_enabled !== false,
+        };
+        if (j.anthropic_mode === 'plan' || j.anthropic_mode === 'console') {
+            cfg.anthropic_mode = j.anthropic_mode;
+        }
+        return cfg;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return def;
+        throw err;
+    }
+}
+export async function writeBrainConfig(cfg) {
+    const p = brainConfigPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(cfg, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+}
+/** Mutate one tier without losing the other. */
+export async function setTierBinding(tier, provider, model) {
+    const cfg = await readBrainConfig();
+    cfg[tier] = { provider, model };
+    await writeBrainConfig(cfg);
+    return cfg;
+}
+/** Set the default tier for chat turns the router cannot infer. */
+export async function setChatDefaultTier(tier) {
+    const cfg = await readBrainConfig();
+    cfg.chat_default_tier = tier;
+    await writeBrainConfig(cfg);
+    return cfg;
+}
+/** Reset to factory defaults. */
+export async function resetBrainConfig() {
+    const def = defaultBrainConfig();
+    await writeBrainConfig(def);
+    return def;
+}
+//# sourceMappingURL=brain_config.js.map

package/dist/core/brain_config.js.map

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

package/dist/core/budget.d.ts

@@ -0,0 +1,96 @@
+export type PlanSlug = 'free' | 'starter' | 'pro' | 'pro_plus' | 'byok_only';
+interface PlanLimits {
+    /** Tokens in+out together per month. 0 = blocked, Infinity = unlimited. */
+    eco_tokens: number;
+    frontier_tokens: number;
+    label: string;
+    /** Storefront link when the user wants to buy an extension. */
+    extension_url?: string;
+}
+export interface BudgetOverrides {
+    version: 1;
+    /** Bought eco tokens added to plan baseline. */
+    eco_extra_tokens: number;
+    /** Bought frontier tokens added to plan baseline. */
+    frontier_extra_tokens: number;
+}
+/** Persist overrides (called after a successful purchase). */
+export declare function setBudgetOverrides(next: Partial<BudgetOverrides>): Promise<BudgetOverrides>;
+export declare function isPlanSlug(s: string): s is PlanSlug;
+export declare function listPlanSlugs(): readonly PlanSlug[];
+/** Persist a local plan override -- used by `yf brain config
+ *  --plan <slug>` and by tests. The license_sync still wins when
+ *  a valid license.json exists, EXCEPT if this override is
+ *  newer (so tests + dev can pretend to be on any plan). */
+export declare function setLocalPlanOverride(plan: PlanSlug | null): Promise<void>;
+export interface BudgetStatus {
+    plan: PlanSlug;
+    plan_label: string;
+    month: string;
+    renewal_at: string;
+    extension_url?: string;
+    /** alpha.59m -- where the numbers came from. 'server' is
+     *  billing-grade (worker KV); 'local' is the on-disk cost_meter
+     *  cache (used when offline / byok_only / no license). The UI
+     *  shows a chip so the user knows which one is in play. */
+    source?: 'local' | 'server';
+    /** When source='server', the server-reported plan slug (worker
+     *  vocabulary -- paid / trial / free-public / etc) so the UI
+     *  can label the chip with the actual billing plan, not the
+     *  local override. */
+    server_plan?: string;
+    eco: {
+        cap: number;
+        used: number;
+        remaining: number;
+        /** Percentage 0..100 (capped). Infinity caps -> 0 (no progress bar). */
+        used_pct: number;
+    };
+    frontier: {
+        cap: number;
+        used: number;
+        remaining: number;
+        used_pct: number;
+    };
+}
+/** Headline call: returns everything the UI needs to render the
+ *  budget card.
+ *
+ *  alpha.59m -- the source preference is now:
+ *    1. Server-side cost_meter (KV in the HITO 4 worker) when
+ *       readCostMeter() succeeds. This is billing-grade.
+ *    2. Local cost_meter.json fallback. Used when there is no
+ *       license / vault secret / network. NOT a "legacy fallback"
+ *       (forbidden by feedback_no_fallback_to_legacy) -- it is
+ *       the legitimate source for BYOK users.
+ *
+ *  Opt-out: YF_USE_HITO4_FLOWS=0 forces local.
+ */
+export declare function readBudgetStatus(): Promise<BudgetStatus>;
+/** Helpers for tests / debug. */
+export declare function _planDefaults(): Record<PlanSlug, PlanLimits>;
+export interface CapCheck {
+    /** True when the tier still has budget for the turn. */
+    allowed: boolean;
+    /** Tier the check was made against. */
+    tier: 'eco' | 'frontier';
+    /** Plan in effect. */
+    plan: PlanSlug;
+    /** Cap for the tier (Infinity for unlimited). */
+    cap: number;
+    /** Tokens consumed this month. */
+    used: number;
+    /** Remaining tokens (Infinity for unlimited). */
+    remaining: number;
+    /** Suggested upgrade URL when blocked. */
+    extension_url?: string;
+    /** Reason string for logs. */
+    reason: string;
+}
+/** Pre-flight check: would a turn at `tier` exceed the cap?
+ *  Returns {allowed:false} when used >= cap. The chat handler
+ *  responds with 429 plan_limit_exceeded and the panel surfaces
+ *  the cap modal. */
+export declare function checkCap(tier: 'eco' | 'frontier'): Promise<CapCheck>;
+export {};
+//# sourceMappingURL=budget.d.ts.map

package/dist/core/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/core/budget.ts"],"names":[],"mappings":"AA2BA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,CAAC;AAE7E,UAAU,UAAU;IAClB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAeD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAuBD,8DAA8D;AAC9D,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAajG;AAUD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,QAAQ,CAEnD;AAED,wBAAgB,aAAa,IAAI,SAAS,QAAQ,EAAE,CAEnD;AAED;;;4DAG4D;AAC5D,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/E;AA0ED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;+DAG2D;IAC3D,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B;;;0BAGsB;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE;QACH,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,wEAAwE;QACxE,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACR,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AA0ED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,CAAC,CA0C9D;AAED,iCAAiC;AACjC,wBAAgB,aAAa,IAAI,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAE5D;AAED,MAAM,WAAW,QAAQ;IACvB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IACzB,sBAAsB;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;qBAGqB;AACrB,wBAAsB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgB1E"}

package/dist/core/budget.js

@@ -0,0 +1,328 @@
+/**
+ * Budget config + computed status (alpha.52).
+ *
+ * The cost meter records what was used. This module:
+ *   1. Defines per-plan budget caps per tier per month.
+ *   2. Reads the user's current plan (from license cache).
+ *   3. Combines plan defaults + user-configured overrides
+ *      (extensions purchased) into the active budget.
+ *   4. Computes the renewal date (first day of next month).
+ *   5. Returns a BudgetStatus the panel UI + CLI consume.
+ *
+ * Storage:
+ *   $YF_CONFIG_DIR/budget_overrides.json -- extra tokens the
+ *     user purchased on top of the plan default. Shape:
+ *       { version: 1, eco_extra_tokens: N, frontier_extra_tokens: M }
+ *
+ *   Plan defaults are hardcoded here (free / starter / pro /
+ *   pro+) so the CLI works offline. Server-side, the license
+ *   API can override these per-tenant.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readCurrentMonthTotals } from './cost_meter.js';
+/* Default per-plan budgets. Conservative numbers; can be tuned
+ * once we see real usage. */
+const PLAN_DEFAULTS = {
+    free: { label: 'Free', eco_tokens: 100_000, frontier_tokens: 0, },
+    starter: { label: 'Starter $10/mo', eco_tokens: 1_000_000, frontier_tokens: 0, extension_url: 'https://yujin.app/plan' },
+    pro: { label: 'Pro $20/mo', eco_tokens: 5_000_000, frontier_tokens: 0, extension_url: 'https://yujin.app/plan' },
+    pro_plus: { label: 'Pro+ $50/mo', eco_tokens: 25_000_000, frontier_tokens: 500_000, extension_url: 'https://yujin.app/plan' },
+    /* Bring-your-own-key only: the user pays the provider directly,
+     * Forge does not meter (caps are Infinity). Cost is reflected
+     * for visibility only. */
+    byok_only: { label: 'BYOK (unlimited)', eco_tokens: Infinity, frontier_tokens: Infinity },
+};
+function overridesPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'budget_overrides.json');
+}
+async function readOverrides() {
+    try {
+        const raw = await fs.readFile(overridesPath(), 'utf-8');
+        const j = JSON.parse(raw);
+        if (j && j.version === 1) {
+            return {
+                version: 1,
+                eco_extra_tokens: typeof j.eco_extra_tokens === 'number' && j.eco_extra_tokens >= 0 ? j.eco_extra_tokens : 0,
+                frontier_extra_tokens: typeof j.frontier_extra_tokens === 'number' && j.frontier_extra_tokens >= 0 ? j.frontier_extra_tokens : 0,
+            };
+        }
+    }
+    catch { /* missing -> defaults */ }
+    return { version: 1, eco_extra_tokens: 0, frontier_extra_tokens: 0 };
+}
+/** Persist overrides (called after a successful purchase). */
+export async function setBudgetOverrides(next) {
+    const cur = await readOverrides();
+    const merged = {
+        version: 1,
+        eco_extra_tokens: typeof next.eco_extra_tokens === 'number' && next.eco_extra_tokens >= 0 ? next.eco_extra_tokens : cur.eco_extra_tokens,
+        frontier_extra_tokens: typeof next.frontier_extra_tokens === 'number' && next.frontier_extra_tokens >= 0 ? next.frontier_extra_tokens : cur.frontier_extra_tokens,
+    };
+    const p = overridesPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(merged, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+    return merged;
+}
+function planOverridePath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'plan_override.json');
+}
+const ALL_PLAN_SLUGS = ['free', 'starter', 'pro', 'pro_plus', 'byok_only'];
+export function isPlanSlug(s) {
+    return ALL_PLAN_SLUGS.includes(s);
+}
+export function listPlanSlugs() {
+    return ALL_PLAN_SLUGS;
+}
+/** Persist a local plan override -- used by `yf brain config
+ *  --plan <slug>` and by tests. The license_sync still wins when
+ *  a valid license.json exists, EXCEPT if this override is
+ *  newer (so tests + dev can pretend to be on any plan). */
+export async function setLocalPlanOverride(plan) {
+    const p = planOverridePath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    if (plan === null) {
+        try {
+            await fs.unlink(p);
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify({ version: 1, plan, ts: new Date().toISOString() }, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+}
+async function readLocalPlanOverride() {
+    try {
+        const raw = await fs.readFile(planOverridePath(), 'utf-8');
+        const j = JSON.parse(raw);
+        const p = typeof j.plan === 'string' ? j.plan.toLowerCase() : '';
+        if (isPlanSlug(p))
+            return { plan: p, ts: typeof j.ts === 'string' ? j.ts : '' };
+    }
+    catch { /* missing -> null */ }
+    return null;
+}
+/** Read the user's plan slug.
+ *  Resolution order:
+ *    1. License cache (license.json) -- authoritative; set by the
+ *       license sync from the server.
+ *    2. Local override (plan_override.json) -- ONLY wins when it is
+ *       newer than the license cache (PND-055/CR-D11). The old code
+ *       returned the override unconditionally, so anyone could
+ *       write plan_override.json with byok_only (caps Infinity) or
+ *       pro_plus and bypass the client-side caps even after a fresh
+ *       license sync. The server remains the real authority for
+ *       managed billing; this only tightens the client gate.
+ *    3. Fallback to byok_only so the UI never blocks BYOK users.
+ */
+async function readLicensePlan() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    try {
+        const raw = await fs.readFile(path.join(base, 'license.json'), 'utf-8');
+        const j = JSON.parse(raw);
+        const p = typeof j.plan === 'string' ? j.plan.toLowerCase() : '';
+        let slug = null;
+        if (p === 'free')
+            slug = 'free';
+        else if (p === 'starter')
+            slug = 'starter';
+        else if (p === 'pro')
+            slug = 'pro';
+        else if (p === 'pro+' || p === 'pro_plus' || p === 'pro-plus')
+            slug = 'pro_plus';
+        else if (p === 'byok' || p === 'byok_only')
+            slug = 'byok_only';
+        if (slug === null)
+            return null;
+        const ts = typeof j.last_validated_at === 'string' ? j.last_validated_at
+            : (typeof j.ts === 'string' ? j.ts : '');
+        return { plan: slug, ts };
+    }
+    catch { /* no license file */ }
+    return null;
+}
+async function readPlanSlug() {
+    const override = await readLocalPlanOverride();
+    const license = await readLicensePlan();
+    if (override && license) {
+        /* Both present: the newer timestamp wins. Empty/unparseable
+         * timestamps are treated as oldest so a dated license beats a
+         * timeless override. */
+        const ot = Date.parse(override.ts);
+        const lt = Date.parse(license.ts);
+        const oNum = Number.isFinite(ot) ? ot : -Infinity;
+        const lNum = Number.isFinite(lt) ? lt : -Infinity;
+        return oNum > lNum ? override.plan : license.plan;
+    }
+    if (override)
+        return override.plan;
+    if (license)
+        return license.plan;
+    return 'byok_only';
+}
+/** Compute the first day of the next calendar month in ISO form. */
+function nextMonthFirstDay() {
+    const now = new Date();
+    const y = now.getUTCFullYear();
+    const m = now.getUTCMonth();
+    const next = new Date(Date.UTC(y, m + 1, 1, 0, 0, 0));
+    return next.toISOString();
+}
+function pct(used, cap) {
+    if (!Number.isFinite(cap) || cap <= 0)
+        return 0;
+    const v = Math.round((used / cap) * 100);
+    return v < 0 ? 0 : (v > 100 ? 100 : v);
+}
+/** alpha.59m -- try the authoritative server cost_meter first.
+ *  Returns null when unreachable / no license / no vault secret.
+ *  Times out at 1.2s so a slow worker never holds up the budget
+ *  card render. */
+async function tryReadServerStatus() {
+    /* Dynamic import to keep this module dep-free in tests that
+     *  don't exercise the worker path. */
+    const mod = await import('../license/hito4_client.js').catch(() => null);
+    if (!mod)
+        return null;
+    const { readCostMeter } = mod;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 1200);
+    try {
+        /* readCostMeter does its own fetch -- AbortController is
+         *  cosmetic here, the timeout is a hard ceiling via Promise.race. */
+        const r = await Promise.race([
+            readCostMeter({}),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 1200)),
+        ]);
+        clearTimeout(timer);
+        if (!r.ok || !r.body || r.body.ok !== true)
+            return null;
+        const body = r.body;
+        const ecoCap = body.caps.eco_total;
+        const frontierCap = body.caps.frontier_total;
+        const ecoUsed = body.row.eco.tokens_in + body.row.eco.tokens_out;
+        const frontierUsed = body.row.frontier.tokens_in + body.row.frontier.tokens_out;
+        /* Mirror the server plan vocabulary into a local label. */
+        const labelMap = {
+            paid: 'Paid', trial: 'Trial', institutional: 'Institutional',
+            gifted: 'Gifted', 'free-public': 'Free public',
+            cancelled: 'Cancelled', none: 'No plan',
+        };
+        return {
+            plan: 'pro_plus', /* placeholder for local enum; UI prefers server_plan */
+            plan_label: labelMap[body.plan] ?? body.plan,
+            month: body.month,
+            renewal_at: nextMonthFirstDay(),
+            source: 'server',
+            server_plan: body.plan,
+            eco: {
+                cap: ecoCap,
+                used: ecoUsed,
+                remaining: Math.max(0, ecoCap - ecoUsed),
+                used_pct: pct(ecoUsed, ecoCap),
+            },
+            frontier: {
+                cap: frontierCap,
+                used: frontierUsed,
+                remaining: Math.max(0, frontierCap - frontierUsed),
+                used_pct: pct(frontierUsed, frontierCap),
+            },
+        };
+    }
+    catch {
+        clearTimeout(timer);
+        return null;
+    }
+}
+/** Headline call: returns everything the UI needs to render the
+ *  budget card.
+ *
+ *  alpha.59m -- the source preference is now:
+ *    1. Server-side cost_meter (KV in the HITO 4 worker) when
+ *       readCostMeter() succeeds. This is billing-grade.
+ *    2. Local cost_meter.json fallback. Used when there is no
+ *       license / vault secret / network. NOT a "legacy fallback"
+ *       (forbidden by feedback_no_fallback_to_legacy) -- it is
+ *       the legitimate source for BYOK users.
+ *
+ *  Opt-out: YF_USE_HITO4_FLOWS=0 forces local.
+ */
+export async function readBudgetStatus() {
+    const useServer = process.env.YF_USE_HITO4_FLOWS !== '0'
+        && process.env.YF_USE_HITO4_FLOWS !== 'false'
+        && process.env.YF_USE_HITO4_FLOWS !== 'no';
+    if (useServer) {
+        const server = await tryReadServerStatus();
+        if (server)
+            return server;
+    }
+    const plan = await readPlanSlug();
+    const limits = PLAN_DEFAULTS[plan];
+    const overrides = await readOverrides();
+    const totals = await readCurrentMonthTotals();
+    const ecoCap = Number.isFinite(limits.eco_tokens)
+        ? limits.eco_tokens + overrides.eco_extra_tokens
+        : Infinity;
+    const frontierCap = Number.isFinite(limits.frontier_tokens)
+        ? limits.frontier_tokens + overrides.frontier_extra_tokens
+        : Infinity;
+    const ecoUsed = totals.eco.tokens_in + totals.eco.tokens_out;
+    const frontierUsed = totals.frontier.tokens_in + totals.frontier.tokens_out;
+    return {
+        plan,
+        plan_label: limits.label,
+        month: totals.month,
+        renewal_at: nextMonthFirstDay(),
+        extension_url: limits.extension_url,
+        source: 'local',
+        eco: {
+            cap: ecoCap,
+            used: ecoUsed,
+            remaining: Number.isFinite(ecoCap) ? Math.max(0, ecoCap - ecoUsed) : Infinity,
+            used_pct: pct(ecoUsed, ecoCap),
+        },
+        frontier: {
+            cap: frontierCap,
+            used: frontierUsed,
+            remaining: Number.isFinite(frontierCap) ? Math.max(0, frontierCap - frontierUsed) : Infinity,
+            used_pct: pct(frontierUsed, frontierCap),
+        },
+    };
+}
+/** Helpers for tests / debug. */
+export function _planDefaults() {
+    return PLAN_DEFAULTS;
+}
+/** Pre-flight check: would a turn at `tier` exceed the cap?
+ *  Returns {allowed:false} when used >= cap. The chat handler
+ *  responds with 429 plan_limit_exceeded and the panel surfaces
+ *  the cap modal. */
+export async function checkCap(tier) {
+    const status = await readBudgetStatus();
+    const slot = status[tier];
+    const allowed = !Number.isFinite(slot.cap) || slot.used < slot.cap;
+    return {
+        allowed,
+        tier,
+        plan: status.plan,
+        cap: slot.cap,
+        used: slot.used,
+        remaining: slot.remaining,
+        extension_url: status.extension_url,
+        reason: allowed
+            ? 'within cap'
+            : 'tier=' + tier + ' used=' + slot.used + ' >= cap=' + slot.cap + ' plan=' + status.plan,
+    };
+}
+//# sourceMappingURL=budget.js.map