Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
8.3 KB
Raw Blame
import { PROVIDER_AUTH_MODE, isLlmProviderId } from '@clerum/llm-providers'
import type { DbClient } from '../db.js'
import {
  linkedCodexExactUsage,
  loadLlmProviderAttemptBySdkAttemptId,
} from './llmProviderAttemptStore.js'

// ─── Plugin Workload SDK — immutable spend floor ─────────────────────────
// `plugin_workload_sdk_spend_outcomes` rows are an append-only FLOOR: the
// least spend provable at write time. They are never updated (the runtime role
// holds SELECT/INSERT only). The effective truth of an oauth-broker attempt is
// derived at read time from the linked `llm_provider_attempts` usage — see
// `deriveEffectiveSpend` in pluginWorkloadSdkFinalization.ts.
//
// This module owns the ONLY INSERT statement against the table so that both
// writers (finalize and the stale-lease sweeper) share one shape and
// `token_pair_check` is guaranteed by the `PersistableSpend` type rather than
// by tests.

export type SpendOutcomeRow = {
  provider_attempt_id: string
  invocation_id: string
  recipe_namespace: string
  recipe_name: string
  attempt_generation: number | string
  attempt_index: number | string
  target_ref: string
  host_ref: string | null
  provider: string
  model: string
  credential_slot: string
  outcome: 'exact' | 'unknown' | 'not_executed'
  input_tokens: number | string | null
  output_tokens: number | string | null
}

/**
 * A spend value that can be persisted. The union makes the database's
 * `token_pair_check` unrepresentable to violate: `exact` always carries both
 * token counts, `unknown`/`not_executed` never carry either.
 */
export type PersistableSpend =
  | { outcome: 'exact'; inputTokens: number; outputTokens: number }
  | { outcome: 'unknown' | 'not_executed'; inputTokens: null; outputTokens: null }

export function spendFloor(outcome: 'unknown' | 'not_executed'): PersistableSpend {
  return { outcome, inputTokens: null, outputTokens: null }
}

export function isOauthBrokerProvider(provider: string): boolean {
  return isLlmProviderId(provider) && PROVIDER_AUTH_MODE[provider] === 'oauth-broker'
}

export const SPEND_OUTCOME_COLUMNS = `provider_attempt_id, invocation_id, recipe_namespace, recipe_name,
       attempt_generation, attempt_index, target_ref, host_ref, provider,
       model, credential_slot, outcome, input_tokens, output_tokens`

const SPEND_OUTCOME_SELECT = `SELECT ${SPEND_OUTCOME_COLUMNS}
  FROM plugin_workload_sdk_spend_outcomes
 WHERE provider_attempt_id = $1`

export async function loadSpendOutcomeRow(
  db: DbClient,
  providerAttemptId: string
): Promise<SpendOutcomeRow | null> {
  const result = await db.query(SPEND_OUTCOME_SELECT, [providerAttemptId])
  return (result.rows[0] as SpendOutcomeRow | undefined) ?? null
}

export type SpendOutcomeFloorInput = {
  providerAttemptId: string
  invocationId: string
  recipeNamespace: string
  recipeName: string
  attemptGeneration: number
  attemptIndex: number
  targetRef: string
  /** NULL when no runtime JWT proves the host (stale-lease recovery). */
  hostRef: string | null
  provider: string
  model: string
  credentialSlot: string
  reason: string
  /** Set only when this finalization actually ingested a `usage_events` row. */
  usageRequestId: string | null
}

/**
 * The single INSERT into the spend ledger. `ON CONFLICT DO NOTHING` on the
 * physical-attempt primary key makes every writer idempotent against the
 * others; a null return means another writer already froze this attempt's
 * floor and the caller must re-read it.
 */
export async function insertSpendOutcomeFloor(
  db: DbClient,
  row: SpendOutcomeFloorInput,
  spend: PersistableSpend
): Promise<SpendOutcomeRow | null> {
  const inserted = await db.query(
    `INSERT INTO plugin_workload_sdk_spend_outcomes
       (provider_attempt_id, invocation_id, recipe_namespace, recipe_name,
        attempt_generation, attempt_index, target_ref, host_ref, provider, model,
        credential_slot, outcome, reason, input_tokens, output_tokens, usage_request_id)
     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
     ON CONFLICT (provider_attempt_id) DO NOTHING
     RETURNING ${SPEND_OUTCOME_COLUMNS}`,
    [
      row.providerAttemptId,
      row.invocationId,
      row.recipeNamespace,
      row.recipeName,
      row.attemptGeneration,
      row.attemptIndex,
      row.targetRef,
      row.hostRef,
      row.provider,
      row.model,
      row.credentialSlot,
      spend.outcome,
      row.reason,
      spend.inputTokens,
      spend.outputTokens,
      row.usageRequestId,
    ]
  )
  if ((inserted.rowCount ?? inserted.rows.length) === 0) return null
  return inserted.rows[0] as SpendOutcomeRow
}

const TERMINAL_PRIOR_ATTEMPT_STATUSES = new Set(['skipped', 'failed', 'provider_unavailable'])

/**
 * Best floor provable for a physical attempt that was already closed before
 * the one being finalized. A ready Codex row wins regardless of the physical
 * status (the subscription was billed), otherwise the status decides.
 */
async function resolvePriorAttemptSpend(
  db: DbClient,
  attemptId: string,
  provider: string,
  status: string
): Promise<PersistableSpend> {
  if (!TERMINAL_PRIOR_ATTEMPT_STATUSES.has(status)) {
    // reservePluginWorkloadSdkProviderAttempt refuses to hand out index k+1
    // unless attempt k is already terminal, and no writer moves a terminal
    // attempt back. Reaching this means that fence broke: fail loudly rather
    // than freeze a floor over a still-running provider call.
    throw new Error(
      `prior provider attempt ${attemptId} is not terminal (status=${status}); the reservation fence is broken`
    )
  }
  if (isOauthBrokerProvider(provider)) {
    const linked = await loadLlmProviderAttemptBySdkAttemptId(db, attemptId)
    const exact = linkedCodexExactUsage(linked)
    if (exact) return { outcome: 'exact', ...exact }
    // A linked row exists only if authorize-link ran, which means the
    // host already asked the broker for a ticket — that call may still bill.
    // `not_executed` is terminal (deriveEffectiveSpend only lifts unknown to
    // exact), so freezing it here would lose that spend permanently. Same rule
    // the winner already applies in resolvePersistableSpend.
    if (linked) return spendFloor('unknown')
  }
  return spendFloor(status === 'provider_unavailable' ? 'unknown' : 'not_executed')
}

/**
 * On a successful failover only the winning attempt reaches
 * `finalize`, so every attempt it displaced would stay terminal without a
 * spend row — the legacy status endpoint does not touch the ledger and the
 * sweeper only visits `in_progress` invocations. Discover those attempts from
 * the database instead of trusting the host to declare them, and freeze one
 * floor each. Invocation and receipt rows are deliberately untouched: the
 * winning attempt already owns their transition.
 */
export async function settlePriorProviderAttemptFloors(
  db: DbClient,
  scope: {
    invocationId: string
    attemptGeneration: number
    attemptIndex: number
    hostRef: string
  }
): Promise<void> {
  const priors = await db.query(
    `SELECT id, recipe_namespace, recipe_name, attempt_index, target_ref,
            provider, model, credential_slot, status
       FROM plugin_workload_sdk_provider_attempts
      WHERE invocation_id = $1
        AND attempt_generation = $2
        AND attempt_index < $3
      ORDER BY attempt_index
      FOR UPDATE`,
    [scope.invocationId, scope.attemptGeneration, scope.attemptIndex]
  )
  for (const prior of priors.rows as Array<Record<string, unknown>>) {
    const attemptId = String(prior.id)
    const provider = String(prior.provider)
    const spend = await resolvePriorAttemptSpend(db, attemptId, provider, String(prior.status))
    await insertSpendOutcomeFloor(
      db,
      {
        providerAttemptId: attemptId,
        invocationId: scope.invocationId,
        recipeNamespace: String(prior.recipe_namespace),
        recipeName: String(prior.recipe_name),
        attemptGeneration: scope.attemptGeneration,
        attemptIndex: Number(prior.attempt_index),
        targetRef: String(prior.target_ref),
        hostRef: scope.hostRef,
        provider,
        model: String(prior.model),
        credentialSlot: String(prior.credential_slot),
        reason: `prior_attempt_${String(prior.status)}`,
        usageRequestId: null,
      },
      spend
    )
  }
}