HealthLog/src/lib/insights/briefing-provider.ts

/**
 * Metered provider chokepoint for the comprehensive-briefing tier.
 *
 * The status/reference tier funnels every generation through
 * `runStatusCompletion`, which reserves against the day's token ledger before
 * egress and reconciles after. The comprehensive briefing did not: both the
 * shared generator (`comprehensive-generate.ts`) and the on-demand
 * `POST /api/insights/generate` route called `runRawCompletionWithFallback`
 * directly, so none of that spend reached `coach_usage` and no daily ceiling
 * applied to it. The briefing is the single most expensive generation in the
 * product — a full feature snapshot in, a multi-section JSON payload out — and
 * it retries up to twice per run (JSON-shape retry, grounding-correction
 * retry), so an unmetered run could cost three full generations.
 *
 * This is the same accounting the status tier uses, not a second mechanism:
 * `reserveBudget` (one atomic upsert-increment, no read-then-write window) +
 * `resolveDailyCap(chain)` for the cost owner + `reconcileSpend` against the
 * provider's reported count. Every provider call on the briefing path routes
 * through here, so a retry is reserved and charged like any other call — a
 * user at the ceiling does not get a free correction pass.
 *
 * The cap follows the COST OWNER, not the surface. `resolveDailyCap` charges
 * the operator ceiling only when the chain's primary is the operator's own
 * credential (`admin-openai` / `admin-codex`); a self-hoster on their own key,
 * their own ChatGPT plan, or a local model is measured against the generous
 * user-plan ceiling, so their hardware is never rationed by the operator's
 * bill.
 *
 * Callers own the consent gate and MUST apply it before calling in — a
 * consent-blocked user must never have budget reserved against them, because
 * nothing is ever sent upstream on their behalf.
 */
import {
  runRawCompletionWithFallback,
  type ProviderChainResolved,
  type RunRawWithFallbackResult,
} from "@/lib/ai/provider-runner";
import {
  buildDateKey,
  reconcileSpend,
  reserveBudget,
  resolveDailyCap,
} from "@/lib/ai/coach/budget";
import { singleUserTurn } from "@/lib/ai/types";
import { annotate } from "@/lib/logging/context";

/**
 * Which call on the briefing path this was. Threaded onto the refusal
 * annotation so an operator can tell a first-pass refusal (the whole briefing
 * is missing) apart from a retry refusal (the first pass landed, the
 * correction did not).
 */
export type BriefingCompletionStage =
  "generate" | "json-retry" | "grounding-retry" | "reroll";

/**
 * Thrown when the reservation would push the user past the day's ceiling.
 *
 * Deliberately a distinct type rather than a generic provider error: the
 * callers map it to their own honest outcome (a typed `skipped` for the
 * off-request generator, a 429 for the on-demand route) instead of reporting
 * an upstream failure that never happened. No provider was contacted.
 */
export class BriefingBudgetExceededError extends Error {
  constructor(
    readonly stage: BriefingCompletionStage,
    readonly totalAfter: number,
  ) {
    super("insights.briefing.budget_exceeded");
    this.name = "BriefingBudgetExceededError";
  }
}

export interface RunBriefingCompletionArgs {
  userId: string;
  /** The resolved provider chain. Its primary decides the daily cap. */
  chain: ProviderChainResolved[];
  systemPrompt: string;
  userPrompt: string;
  temperature: number;
  maxTokens: number;
  /** Upstream per-request timeout, already resolved from the user's setting. */
  timeoutMs: number;
  stage: BriefingCompletionStage;
  /**
   * Deterministic seed. Omitted by the daily-briefing re-roll on purpose —
   * a pinned seed would reproduce the phrasing the re-roll exists to vary.
   */
  seed?: number;
  /** UTC day-key override; defaults to today. Tests pin it. */
  dateKey?: string;
}

/**
 * Reserve, run the chain, reconcile. Returns the runner's result untouched so
 * every existing caller keeps its own parsing, grounding, and error mapping.
 *
 * Failure semantics:
 *   - over the ceiling  → `BriefingBudgetExceededError`, nothing reserved
 *     (the reservation is refunded inside `reserveBudget`), no egress.
 *   - provider threw    → the reservation is refunded IN FULL and the original
 *     error re-thrown, so `AllProvidersFailedError` still reaches the callers
 *     that map it to a user-facing status.
 *   - provider returned → charged the reported count, net of cached input
 *     tokens; falls back to the reservation when the provider reports no
 *     count, so an unreported generation is never billed as free.
 */
export async function runBriefingCompletion(
  args: RunBriefingCompletionArgs,
): Promise<RunRawWithFallbackResult> {
  const dateKey = args.dateKey ?? buildDateKey();

  // Reserve an ESTIMATE up front — the output ceiling plus a ~4-chars-per-token
  // approximation of the prompt about to be sent — and reconcile against the
  // provider's reported count afterwards. Same shape as the status tier.
  const estimatedTokens =
    args.maxTokens +
    Math.ceil((args.systemPrompt.length + args.userPrompt.length) / 4);

  const reservation = await reserveBudget(
    args.userId,
    estimatedTokens,
    dateKey,
    resolveDailyCap(args.chain),
  );
  if (!reservation.allowed) {
    annotate({
      action: { name: "insights.briefing.budget_exceeded" },
      meta: { stage: args.stage, totalAfter: reservation.totalAfter },
    });
    throw new BriefingBudgetExceededError(args.stage, reservation.totalAfter);
  }

  let outcome: RunRawWithFallbackResult;
  try {
    outcome = await runRawCompletionWithFallback({
      userId: args.userId,
      providers: args.chain,
      params: singleUserTurn({
        system: args.systemPrompt,
        user: args.userPrompt,
        temperature: args.temperature,
        maxTokens: args.maxTokens,
        seed: args.seed,
        timeoutMs: args.timeoutMs,
        // Every briefing call parses its reply with `JSON.parse`, so opt the
        // chains with a native JSON mode into it.
        responseFormat: "json",
      }),
    });
  } catch (err) {
    // No usable reply: refund the whole reservation rather than bill an
    // invented figure. A partially-burned upstream call is possible here, but
    // we have no reported count to charge, and over-charging a failed
    // generation would ration the retry the user is entitled to.
    await reconcileSpend(args.userId, reservation.reserved, 0, dateKey).catch(
      () => {
        // Best-effort: a failed refund leaves the conservative reservation in
        // place (never an undercount) and must not mask the provider error.
      },
    );
    throw err;
  }

  const actualTokens = outcome.result.tokensUsed ?? reservation.reserved;
  await reconcileSpend(
    args.userId,
    reservation.reserved,
    actualTokens,
    dateKey,
    outcome.result.cachedInputTokens ?? 0,
  ).catch(() => {
    // Ledger reconcile is best-effort; a failure leaves the reservation in
    // place and never breaks a generation that already succeeded.
  });

  return outcome;
}