@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.119

package/dist/core/cost_meter.js

@@ -0,0 +1,111 @@
+/**
+ * Cost meter -- per-tier per-month token + event tracking
+ * (alpha.52).
+ *
+ * Storage: $YF_CONFIG_DIR/cost_meter.json (or
+ * ~/.yujin-forge/cost_meter.json). Single file rotated by month
+ * key (YYYY-MM) so the budget UI can show "used this month vs
+ * cap" without parsing a JSONL log.
+ *
+ * Shape:
+ *   {
+ *     "version": 1,
+ *     "months": {
+ *       "2026-06": {
+ *         "eco":       { "tokens_in": N, "tokens_out": M, "calls": K },
+ *         "frontier":  { "tokens_in": N, "tokens_out": M, "calls": K }
+ *       },
+ *       "2026-07": { ... }
+ *     }
+ *   }
+ *
+ * Concurrency model:
+ *   - Local single-process. The chat server is the only writer.
+ *   - Writes use atomic tmp+rename. A torn write only loses one
+ *     event, not the file.
+ *
+ * Failure mode:
+ *   - recordCostEvent NEVER throws. If the FS is unavailable the
+ *     event is dropped silently. We do not want a vault permission
+ *     bug to break a chat turn.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+function meterPath() {
+    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, 'cost_meter.json');
+}
+function emptyMonth() {
+    return {
+        eco: { tokens_in: 0, tokens_out: 0, calls: 0 },
+        frontier: { tokens_in: 0, tokens_out: 0, calls: 0 },
+    };
+}
+function emptyMeter() {
+    return { version: 1, months: {} };
+}
+function monthKey(iso) {
+    /* YYYY-MM */
+    return iso.slice(0, 7);
+}
+async function readMeter() {
+    try {
+        const raw = await fs.readFile(meterPath(), 'utf-8');
+        const j = JSON.parse(raw);
+        if (j && j.version === 1 && j.months && typeof j.months === 'object')
+            return j;
+    }
+    catch { /* missing or malformed -> fresh */ }
+    return emptyMeter();
+}
+async function writeMeter(m) {
+    const p = meterPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(m, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+}
+/** Append one cost event. Never throws. */
+export async function recordCostEvent(ev) {
+    try {
+        const m = await readMeter();
+        const key = monthKey(ev.ts);
+        if (!m.months[key])
+            m.months[key] = emptyMonth();
+        const bucket = m.months[key][ev.tier];
+        bucket.tokens_in += Math.max(0, ev.tokensIn | 0);
+        bucket.tokens_out += Math.max(0, ev.tokensOut | 0);
+        bucket.calls += 1;
+        await writeMeter(m);
+    }
+    catch {
+        /* swallow */
+    }
+}
+/** Return totals for the current calendar month. */
+export async function readCurrentMonthTotals() {
+    const m = await readMeter();
+    const now = new Date().toISOString();
+    const key = monthKey(now);
+    const bucket = m.months[key] ?? emptyMonth();
+    return { month: key, eco: bucket.eco, frontier: bucket.frontier };
+}
+/** Return totals for ALL months tracked. Useful for /api debug. */
+export async function readAllMonths() {
+    return readMeter();
+}
+/** Drop the persisted meter -- tests + manual reset. */
+export async function resetCostMeter() {
+    try {
+        await fs.unlink(meterPath());
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+//# sourceMappingURL=cost_meter.js.map

package/dist/core/cost_meter.js.map

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

package/dist/core/cost_router.d.ts

@@ -0,0 +1,106 @@
+import { type BrainProvider, type BrainConfig } from './brain_config.js';
+/** Decision returned by the router. */
+export interface BrainSelection {
+    tier: 'eco' | 'frontier';
+    provider: BrainProvider;
+    model: string;
+    /** The decrypted API key. Caller MUST NOT log this. */
+    api_key: string | null;
+    /** Human reason -- for the cost log + debug. */
+    reason: string;
+    /** True when the chosen provider is wired at runtime. */
+    runtime_wired: boolean;
+}
+/** Inputs the router accepts. All optional. */
+export interface BrainSelectContext {
+    /** verb_id the LLM is about to invoke (when known). */
+    verb_id?: string;
+    /** Workflow phase id (phase_i ... phase_vi). */
+    workflow_phase?: string;
+    /** User override for this turn ('eco' | 'frontier' | undefined). */
+    user_override?: 'eco' | 'frontier';
+    /** Free text reason from the caller, e.g. "Phase III RFP writing". */
+    caller_hint?: string;
+    /** User message text for the smart-auto path (gate + classifier). */
+    user_text?: string;
+    /** Recent conversation turns for sticky-followup detection. */
+    history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /** Attachment count (files, images, voice notes). */
+    attachments?: number;
+    /** Previous tier in the conversation, used for sticky follow-ups. */
+    previous_tier?: 'eco' | 'frontier';
+    /** alpha.56 -- previous turn invoked a doc-loading verb. When
+     *  true, route to frontier regardless of gate/classifier
+     *  output, because the next message is almost certainly the
+     *  user asking the model to reason over that doc. */
+    previous_doc_loaded?: boolean;
+    /** alpha.59z.7 -- active SQ rules for the current workflow
+     *  step (mirror of workflow.active_sq_rules). When the user
+     *  request looks like a rule-violation, the router escalates
+     *  to frontier so the LLM can defend the rules properly. Eco
+     *  brains (Haiku) tend to capitulate on rule defense even
+     *  with strong instructions. */
+    active_sq_rules?: readonly string[];
+    /** alpha.59z.7 -- when true, the user request crosses a phase
+     *  boundary (asks for arch-level work mid-block-dev, asks for
+     *  RFP revision after approval gate, etc). Eco brains
+     *  (Gemini) tend to not acknowledge the active step before
+     *  proceeding. Forcing frontier ensures the SCAN-FIRST
+     *  imperative is honored. */
+    phase_crossover?: boolean;
+}
+/** alpha.59z.7 -- heuristic: does the user text look like a
+ *  request to violate one of the active SQ rules? Catches the
+ *  most common patterns where the user pushes Forge to skip
+ *  tests, ignore docs, etc. False positives are cheap (we just
+ *  escalate to frontier); false negatives let the eco brain
+ *  capitulate. */
+export declare function looksLikeRuleViolation(userText: string | undefined): {
+    hit: boolean;
+    pattern?: string;
+};
+/** alpha.59z.7 -- heuristic: does the user text suggest a phase
+ *  cross-over (e.g. asking to revisit a prior phase, jump
+ *  forward, change an approved doc)? */
+export declare function looksLikePhaseCrossover(userText: string | undefined, workflowPhase: string | undefined): {
+    hit: boolean;
+    pattern?: string;
+};
+/**
+ * Legacy synchronous decideTier (kept for callers that have no
+ * user_text). Equivalent to decideCheapTier with a fallback to
+ * the configured default. Used by tests.
+ */
+export declare function decideTier(ctx: BrainSelectContext, cfg: BrainConfig): {
+    tier: 'eco' | 'frontier';
+    reason: string;
+};
+export interface SmartAutoTelemetry {
+    gate_decision: 'eco' | 'frontier';
+    gate_confidence: number;
+    gate_signals: string[];
+    gate_ambiguous: boolean;
+    classifier_used: boolean;
+    classifier_verdict?: 'simple' | 'complex' | 'destructive' | null;
+    classifier_confidence?: number;
+    classifier_signals?: string[];
+    classifier_cached?: boolean;
+}
+/**
+ * Full routing decision. Reads brain_config + vault to resolve a
+ * concrete provider+model+key. Logs the decision.
+ *
+ * alpha.55: when no cheap signal applies, runs reasoning_gate +
+ * turn_classifier for a smart-auto decision instead of falling
+ * back to the configured default tier blindly.
+ */
+export declare function selectBrainForTurn(ctx?: BrainSelectContext): Promise<BrainSelection>;
+/**
+ * Convenience: resolve only the anthropic key when the caller
+ * doesn't need full routing.
+ */
+export declare function resolveAnthropicKey(): Promise<string | null>;
+//# sourceMappingURL=cost_router.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cost_router.d.ts","sourceRoot":"","sources":["../../src/core/cost_router.ts"],"names":[],"mappings":"AA+CA,OAAO,EAEL,KAAK,aAAa,EAAE,KAAK,WAAW,EACrC,MAAM,mBAAmB,CAAC;AAS3B,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,aAAa,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,aAAa,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IACnC;;;yDAGqD;IACrD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;oCAKgC;IAChC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;iCAK6B;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;kBAKkB;AAClB,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAmBvG;AAED;;wCAEwC;AACxC,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAe3I;AA2DD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,WAAW,GAAG;IACrE,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,CAOA;AAKD,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,KAAK,GAAG,UAAU,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,CAAC;IACjE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAqKD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,GAAE,kBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CA6E9F;AAgDD;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGlE"}