Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
37.6 KB
Raw Blame
import { randomUUID } from 'node:crypto'
import type { PoolClient } from 'pg'
import { pool } from '../db/pool.js'
import { EMPTY_USAGE, effectiveCostUsd, modelPriceTable, priceFor, type TokenUsage } from './cost.js'

export type AgentRunStatus = 'running' | 'completed' | 'failed' | 'skipped'
export type TriageSource = 'cloud' | 'byoa-claude' | 'byoa-codex' | 'byoa-grok' | 'byoa-cursor' | 'byoa-opencode' | 'byoa-pi' | 'byoa-gemini' | 'byoa-qwen' | 'byoa-antigravity' | 'byoa-zcode' | 'byoa-maka' | 'byoa-omp'
export type AgentEventLevel = 'debug' | 'info' | 'warn' | 'error'

type Queryable = Pick<PoolClient, 'query'>

const MAX_STRING_CHARS = 24_000
const MAX_JSON_CHARS = 160_000

function clip(value: unknown, depth = 0): unknown {
  if (typeof value === 'string') {
    return value.length > MAX_STRING_CHARS ? `${value.slice(0, MAX_STRING_CHARS)}…` : value
  }
  if (value === null || typeof value !== 'object') return value
  if (depth >= 8) return '[truncated]'
  if (Array.isArray(value)) return value.slice(0, 50).map((item) => clip(item, depth + 1))

  const out: Record<string, unknown> = {}
  for (const [key, item] of Object.entries(value as Record<string, unknown>).slice(0, 80)) {
    out[key] = clip(item, depth + 1)
  }
  return out
}

function jsonForDb(value: unknown): string {
  try {
    const text = JSON.stringify(clip(value))
    if (text.length <= MAX_JSON_CHARS) return text
    return JSON.stringify({ truncated: true, preview: text.slice(0, MAX_JSON_CHARS) })
  } catch {
    return JSON.stringify({ value: String(value) })
  }
}

export function errorText(err: unknown): string {
  if (err instanceof Error) return err.stack || err.message
  return String(err)
}

export async function createAgentRun(args: {
  agentId: string
  companyId?: string | null
  trigger?: Record<string, unknown>
  inputMessageIds?: string[]
  inboxCount?: number
  fingerprint?: string
}, db: Queryable = pool): Promise<string> {
  const id = `run-${randomUUID()}`
  await db.query(
    `INSERT INTO agent_runs (
       id, agent_id, company_id, trigger, status, stage,
       input_message_ids, inbox_count, fingerprint
     )
     VALUES ($1,$2,$3,$4::jsonb,'running','created',$5::jsonb,$6,$7)`,
    [
      id,
      args.agentId,
      args.companyId ?? null,
      jsonForDb(args.trigger ?? {}),
      jsonForDb(args.inputMessageIds ?? []),
      args.inboxCount ?? 0,
      args.fingerprint ?? null,
    ],
  )
  return id
}

export async function recordAgentEvent(args: {
  runId: string
  agentId: string
  companyId?: string | null
  kind: string
  level?: AgentEventLevel
  title: string
  data?: Record<string, unknown>
  stage?: string
}): Promise<void> {
  await pool.query(
    `INSERT INTO agent_events (id, run_id, agent_id, company_id, kind, level, title, data)
     VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb)`,
    [
      `evt-${randomUUID()}`,
      args.runId,
      args.agentId,
      args.companyId ?? null,
      args.kind,
      args.level ?? 'info',
      args.title,
      jsonForDb(args.data ?? {}),
    ],
  )
  await pool.query(
    `UPDATE agent_runs
        SET updated_at = NOW(),
            stage = COALESCE($2, stage)
      WHERE id = $1`,
    [args.runId, args.stage ?? null],
  )
}

/** Record a daemon-supplied event only when the JWT-pinned agent still owns
 *  the target run. The authorization predicate lives in the same statement as
 *  the INSERT so a guessed run id can never create an event or bump another
 *  agent's stage between a route-level check and the write itself. */
export async function recordAgentEventForOwner(args: {
  runId: string
  agentId: string
  companyId: string
  kind: string
  level?: AgentEventLevel
  title: string
  data?: Record<string, unknown>
  stage?: string
}, db: Queryable = pool): Promise<boolean> {
  const result = await db.query(
    `WITH owned_run AS MATERIALIZED (
       SELECT ar.id
         FROM agent_runs ar
        WHERE ar.id = $2
          AND ar.agent_id = $3
          AND ar.company_id = $4
          AND EXISTS (
            SELECT 1 FROM participants p
             WHERE p.id = $3 AND p.company_id = $4
               AND p.kind = 'agent' AND p.departed_at IS NULL
          )
     ), inserted AS (
       INSERT INTO agent_events (id, run_id, agent_id, company_id, kind, level, title, data)
       SELECT $1, owned_run.id, $3, $4, $5, $6, $7, $8::jsonb
         FROM owned_run
       RETURNING run_id
     )
     UPDATE agent_runs ar
        SET updated_at = NOW(),
            stage = COALESCE($9, ar.stage)
       FROM inserted
      WHERE ar.id = inserted.run_id
      RETURNING ar.id`,
    [
      `evt-${randomUUID()}`,
      args.runId,
      args.agentId,
      args.companyId,
      args.kind,
      args.level ?? 'info',
      args.title,
      jsonForDb(args.data ?? {}),
      args.stage ?? null,
    ],
  )
  return result.rowCount === 1
}

interface FinishAgentRunArgs {
  runId: string
  status: AgentRunStatus
  summary?: string
  error?: string | null
  toolCallCount?: number
  tokenCount?: number
  model?: string | null
  usage?: TokenUsage | null
}

async function finishAgentRunRow(
  args: FinishAgentRunArgs,
  owner?: { agentId: string; companyId: string },
  db: Queryable = pool,
): Promise<boolean> {
  const usage = args.usage ?? null
  const cost = usage ? effectiveCostUsd(args.model, usage) : null
  // Legacy token_count = input+output sum; keep it populated for back-compat.
  const tokenCount = args.tokenCount ?? (usage
    ? usage.inputTokens + usage.cachedInputTokens + usage.cacheCreationTokens + usage.outputTokens
    : 0)
  const ownerPredicate = owner
    ? `AND agent_id = $14
       AND company_id = $15
       AND EXISTS (
         SELECT 1 FROM participants p
          WHERE p.id = $14 AND p.company_id = $15
            AND p.kind = 'agent' AND p.departed_at IS NULL
       )`
    : ''
  const result = await db.query(
    `UPDATE agent_runs
        SET status = $2,
            stage = $2,
            summary = $3,
            error = $4,
            tool_call_count = $5,
            token_count = $6,
            input_tokens          = COALESCE($7, input_tokens),
            cached_input_tokens   = COALESCE($8, cached_input_tokens),
            cache_creation_tokens = COALESCE($9, cache_creation_tokens),
            output_tokens         = COALESCE($10, output_tokens),
            cost_usd              = COALESCE($11, cost_usd),
            cost_estimated        = COALESCE($12, cost_estimated),
            model                 = COALESCE($13, model),
            updated_at = NOW(),
            finished_at = NOW()
      WHERE id = $1
        ${ownerPredicate}
      RETURNING id`,
    [
      args.runId,
      args.status,
      args.summary ?? null,
      args.error ?? null,
      args.toolCallCount ?? 0,
      tokenCount,
      usage?.inputTokens ?? null,
      usage?.cachedInputTokens ?? null,
      usage?.cacheCreationTokens ?? null,
      usage?.outputTokens ?? null,
      cost?.usd ?? null,
      cost ? cost.estimated : null,
      args.model ?? null,
      ...(owner ? [owner.agentId, owner.companyId] : []),
    ],
  )
  return result.rowCount === 1
}

export async function finishAgentRun(args: FinishAgentRunArgs): Promise<void> {
  await finishAgentRunRow(args)
}

/** Finish a daemon run only when its persisted owner matches the current JWT. */
export async function finishAgentRunForOwner(
  args: FinishAgentRunArgs & { agentId: string; companyId: string },
  db: Queryable = pool,
): Promise<boolean> {
  const { agentId, companyId, ...run } = args
  return finishAgentRunRow(run, { agentId, companyId }, db)
}

/** Record one inbox-triage call (the small-brain gate) with its cache-aware cost.
 *  Best-effort: a DB hiccup must never break a turn. `usage` null/undefined means
 *  the engine gave us no token counts (e.g. codex) → stored as unmeasured. */
export async function recordTriage(args: {
  agentId: string
  companyId?: string | null
  source: TriageSource
  model?: string | null
  actionable: boolean
  reason?: string | null
  usage?: TokenUsage | null
  /** The big-brain run this triage WOKE (actionable=true), if known. */
  runId?: string | null
}): Promise<void> {
  const measured = !!args.usage
  const usage = args.usage ?? EMPTY_USAGE
  const cost = effectiveCostUsd(args.model, usage)
  try {
    await pool.query(
      `INSERT INTO agent_triages (
         id, agent_id, company_id, source, model, actionable, reason,
         input_tokens, cached_input_tokens, cache_creation_tokens, output_tokens,
         cost_usd, cost_estimated, measured, run_id
       ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)`,
      [
        `tri-${randomUUID()}`, args.agentId, args.companyId ?? null, args.source,
        args.model ?? null, args.actionable, (args.reason ?? '').slice(0, 500),
        usage.inputTokens, usage.cachedInputTokens, usage.cacheCreationTokens, usage.outputTokens,
        measured ? cost.usd : 0, cost.estimated, measured, args.runId ?? null,
      ],
    )
  } catch (err) {
    console.warn('[observability] recordTriage failed — dropping', err instanceof Error ? err.message : err)
  }
}

/** Heartbeat a still-running run: bump updated_at so the stale-run sweeper does
 *  NOT reap a legitimately long turn. Cloud turns stay alive implicitly (every
 *  recordAgentEvent bumps updated_at); BYOA turns emit no mid-run events, so the
 *  daemon must call this periodically while its engine turn is in flight, or any
 *  turn >maxAgeMs gets falsely closed as "orphaned". Only touches a 'running' row
 *  so it can never resurrect a finished/failed one. */
export async function touchAgentRun(runId: string): Promise<void> {
  await pool.query(
    `UPDATE agent_runs SET updated_at = NOW() WHERE id = $1 AND status = 'running'`,
    [runId],
  )
}

/** Ownership-aware daemon heartbeat. `owned` distinguishes an already-finished
 *  caller-owned run (valid no-op) from a missing or foreign run without leaking
 *  which of those two cases occurred. */
export async function touchAgentRunForOwner(args: {
  runId: string
  agentId: string
  companyId: string
}, db: Queryable = pool): Promise<{ owned: boolean; touched: boolean }> {
  const { rows } = await db.query<{ owned: boolean; touched: boolean }>(
    `WITH owned_run AS MATERIALIZED (
       SELECT ar.id, ar.status
         FROM agent_runs ar
        WHERE ar.id = $1
          AND ar.agent_id = $2
          AND ar.company_id = $3
          AND EXISTS (
            SELECT 1 FROM participants p
             WHERE p.id = $2 AND p.company_id = $3
               AND p.kind = 'agent' AND p.departed_at IS NULL
          )
     ), touched_run AS (
       UPDATE agent_runs ar
          SET updated_at = NOW()
         FROM owned_run
        WHERE ar.id = owned_run.id AND owned_run.status = 'running'
       RETURNING ar.id
     )
     SELECT EXISTS (SELECT 1 FROM owned_run) AS owned,
            EXISTS (SELECT 1 FROM touched_run) AS touched`,
    [args.runId, args.agentId, args.companyId],
  )
  return rows[0] ?? { owned: false, touched: false }
}

export async function markStaleAgentRuns(maxAgeMs: number = 10 * 60_000): Promise<Array<{ id: string; agent_id: string }>> {
  const { rows } = await pool.query<{ id: string; agent_id: string }>(
    `UPDATE agent_runs
        SET status = 'failed',
            stage = 'orphaned',
            summary = COALESCE(NULLIF(summary, ''), 'Agent run orphaned after runtime finalization was lost'),
            error = COALESCE(error, 'Agent run was left running without heartbeat and was closed by the stale-run sweeper'),
            updated_at = NOW(),
            finished_at = NOW()
      WHERE status = 'running'
        AND updated_at < NOW() - ($1::double precision * INTERVAL '1 millisecond')
      RETURNING id, agent_id`,
    [maxAgeMs],
  )
  return rows
}

export function startStaleAgentRunSweeper(
  intervalMs: number = 60_000,
  maxAgeMs: number = 10 * 60_000,
): NodeJS.Timeout {
  const tick = (): void => {
    void markStaleAgentRuns(maxAgeMs).then((rows) => {
      if (rows.length > 0) {
        console.warn(`[observability] closed ${rows.length} stale running agent run(s): ${rows.map((r) => r.id).join(', ')}`)
      }
    }).catch((err) => {
      console.warn('[observability] stale agent run sweeper failed:', err instanceof Error ? err.message : err)
    })
  }
  setImmediate(tick)
  const t = setInterval(tick, intervalMs)
  t.unref?.()
  return t
}

// ─── triage economics ─────────────────────────────────────────────────────

export interface TriageAgentRow {
  agentId: string
  agentName: string
  triageCount: number
  skipCount: number
  wakeCount: number
  triageCostUsd: number
  triageOverheadUsd: number   // triage cost spent on actionable=true (paid the gate AND ran the turn)
  turnCount: number
  avgTurnCostUsd: number
  turnCacheHitRate: number
  estimatedNetSavingsUsd: number  // skipCount*avgTurnCost − triageCost (this agent's own avg)
}

export interface TriageLedgerRow {
  id: string
  agentId: string
  agentName: string
  source: TriageSource
  model: string | null
  actionable: boolean
  reason: string | null
  inputTokens: number
  cachedInputTokens: number
  outputTokens: number
  costUsd: number
  costEstimated: boolean
  measured: boolean
  estSavingUsd: number | null  // for skips: this agent's avgTurnCost − this triage cost; null for wakes
  createdAt: string
}

/** The per-1M-token unit price actually used to cost a model in this window. */
export interface TriageUnitPrice {
  role: 'triage' | 'turn'   // triage = small brain (cerebellum), turn = big brain
  model: string
  inPer1M: number
  cachedInPer1M: number
  outPer1M: number
  estimated: boolean        // true = seeded/fallback (NOT an operator-supplied real rate)
}

/** A row in the full price-menu reference table. */
export interface TriagePriceRow {
  model: string
  inPer1M: number
  cachedInPer1M: number
  cacheWritePer1M: number
  outPer1M: number
  estimated: boolean
}

export interface TriageEconomics {
  sinceHours: number
  triageCount: number
  triageSkipCount: number
  triageWakeCount: number
  triageMeasuredCount: number
  triageCostUsd: number
  triageOverheadUsd: number
  triageInputTokens: number        // uncached input tokens across triages (real, plan-independent)
  triageCachedInputTokens: number
  triageOutputTokens: number
  turnCount: number
  turnCostUsd: number
  avgTurnCostUsd: number
  turnCacheHitRate: number
  estimatedAvoidedUsd: number      // Σ per-agent skipCount*avgTurnCost — the avoided BIG-BRAIN spend
  estimatedNetSavingsUsd: number   // estimatedAvoided − triageCost (LABELED estimate in the UI)
  costEstimated: boolean           // any price was a seeded/fallback estimate, not an operator rate
  byoaShare: number                // fraction of triages on BYOA (flat-rate $ → meter-equivalent, not a bill)
  unitPrices: TriageUnitPrice[]    // the actual per-token rates used (small brain vs big brain)
  priceTable: TriagePriceRow[]     // the full price menu (reference), always populated
  perAgent: TriageAgentRow[]
  recent: TriageLedgerRow[]
}

/** The honest triage ledger. Compares actual triage spend against the big-brain
 *  turns it shields, all cache-aware. The ONE counterfactual — "estimated net
 *  savings" — uses each agent's OWN recent mean turn cost as the value of an
 *  avoided turn, and is labeled as an estimate in the UI. Everything else is
 *  measured. */
export async function getTriageEconomics(args: {
  companyId: string
  agentId?: string | null
  sinceHours?: number
}): Promise<TriageEconomics> {
  const sinceHours = Math.min(720, Math.max(1, args.sinceHours ?? 24))
  const ms = sinceHours * 3_600_000
  const agentFilter = args.agentId ? 'AND t.agent_id = $3' : ''
  const runAgentFilter = args.agentId ? 'AND r.agent_id = $3' : ''
  const params: unknown[] = [args.companyId, ms]
  if (args.agentId) params.push(args.agentId)

  // IMPORTANT: cost is computed HERE, at query time, from the stored TOKEN COUNTS
  // × the CURRENT prices — NOT from the stored cost_usd (which froze whatever price
  // was in effect at record time). This way a price change (code OR
  // CUMORA_MODEL_PRICES_JSON) instantly re-prices ALL history, matching the
  // "token counts are real, prices are live" promise. We aggregate tokens grouped
  // by (agent, model) because the per-token rate is model-specific.
  const toUsage = (r: { input_tokens: string; cached_tokens: string; cache_creation_tokens: string; output_tokens: string }): TokenUsage => ({
    inputTokens: Number(r.input_tokens),
    cachedInputTokens: Number(r.cached_tokens),
    cacheCreationTokens: Number(r.cache_creation_tokens),
    outputTokens: Number(r.output_tokens),
  })

  const triAgg = await pool.query<{
    agent_id: string; agent_name: string; model: string | null; actionable: boolean;
    n: number; measured_n: number; byoa_n: number;
    input_tokens: string; cached_tokens: string; cache_creation_tokens: string; output_tokens: string;
  }>(
    `SELECT t.agent_id, COALESCE(p.name, t.agent_id) AS agent_name, t.model, t.actionable,
            count(*)::int AS n,
            count(*) FILTER (WHERE t.measured)::int AS measured_n,
            count(*) FILTER (WHERE t.source LIKE 'byoa%')::int AS byoa_n,
            COALESCE(sum(t.input_tokens), 0)::bigint AS input_tokens,
            COALESCE(sum(t.cached_input_tokens), 0)::bigint AS cached_tokens,
            COALESCE(sum(t.cache_creation_tokens), 0)::bigint AS cache_creation_tokens,
            COALESCE(sum(t.output_tokens), 0)::bigint AS output_tokens
       FROM agent_triages t
       LEFT JOIN participants p ON p.id = t.agent_id AND p.company_id = t.company_id
      WHERE t.company_id = $1 AND t.created_at > NOW() - ($2::double precision * INTERVAL '1 millisecond') ${agentFilter}
      GROUP BY t.agent_id, agent_name, t.model, t.actionable`,
    params,
  )

  // Only measured (non-zero-token) runs feed turn cost / the avg counterfactual —
  // orphaned/0-token runs would falsely depress it.
  const runAgg = await pool.query<{
    agent_id: string; model: string | null; turn_n: number;
    input_tokens: string; cached_tokens: string; cache_creation_tokens: string; output_tokens: string;
  }>(
    `SELECT r.agent_id, r.model,
            count(*)::int AS turn_n,
            COALESCE(sum(r.input_tokens), 0)::bigint AS input_tokens,
            COALESCE(sum(r.cached_input_tokens), 0)::bigint AS cached_tokens,
            COALESCE(sum(r.cache_creation_tokens), 0)::bigint AS cache_creation_tokens,
            COALESCE(sum(r.output_tokens), 0)::bigint AS output_tokens
       FROM agent_runs r
      WHERE r.company_id = $1 AND r.started_at > NOW() - ($2::double precision * INTERVAL '1 millisecond') ${runAgentFilter}
        AND (r.input_tokens + r.cached_input_tokens + r.output_tokens) > 0
      GROUP BY r.agent_id, r.model`,
    params,
  )

  interface Acc {
    agentName: string
    triageCount: number; skipCount: number; wakeCount: number; measuredCount: number; byoaCount: number
    triageCostUsd: number; triageOverheadUsd: number
    turnCount: number; turnCostUsd: number; cacheRead: number; totalInput: number
  }
  const acc = new Map<string, Acc>()
  const accOf = (id: string, name: string): Acc => {
    let a = acc.get(id)
    if (!a) {
      a = { agentName: name, triageCount: 0, skipCount: 0, wakeCount: 0, measuredCount: 0, byoaCount: 0, triageCostUsd: 0, triageOverheadUsd: 0, turnCount: 0, turnCostUsd: 0, cacheRead: 0, totalInput: 0 }
      acc.set(id, a)
    } else if (name !== id && a.agentName === id) {
      a.agentName = name
    }
    return a
  }
  const modelsSeen = new Set<string>()

  for (const t of triAgg.rows) {
    const a = accOf(t.agent_id, t.agent_name)
    if (t.model) modelsSeen.add(t.model)
    const cost = effectiveCostUsd(t.model, toUsage(t)).usd
    a.triageCount += t.n
    a.measuredCount += t.measured_n
    a.byoaCount += t.byoa_n
    a.triageCostUsd += cost
    if (t.actionable) { a.wakeCount += t.n; a.triageOverheadUsd += cost } else { a.skipCount += t.n }
  }
  for (const r of runAgg.rows) {
    const a = accOf(r.agent_id, r.agent_id)
    if (r.model) modelsSeen.add(r.model)
    const u = toUsage(r)
    a.turnCostUsd += effectiveCostUsd(r.model, u).usd
    a.turnCount += r.turn_n
    a.cacheRead += u.cachedInputTokens
    a.totalInput += u.inputTokens + u.cachedInputTokens
  }

  // perAgent = agents that actually triaged (a run-only agent has nothing to report
  // in a TRIAGE ledger). Their turn data is still accumulated above for avg cost.
  const perAgent: TriageAgentRow[] = [...acc.entries()]
    .filter(([, a]) => a.triageCount > 0)
    .map(([agentId, a]) => {
      const avgTurnCostUsd = a.turnCount > 0 ? a.turnCostUsd / a.turnCount : 0
      return {
        agentId, agentName: a.agentName,
        triageCount: a.triageCount, skipCount: a.skipCount, wakeCount: a.wakeCount,
        triageCostUsd: a.triageCostUsd, triageOverheadUsd: a.triageOverheadUsd,
        turnCount: a.turnCount, avgTurnCostUsd,
        turnCacheHitRate: a.totalInput > 0 ? a.cacheRead / a.totalInput : 0,
        estimatedNetSavingsUsd: a.skipCount * avgTurnCostUsd - a.triageCostUsd,
      }
    })
  const avgCostByAgent = new Map(perAgent.map((a) => [a.agentId, a.avgTurnCostUsd]))

  // Recent triage ledger — each row's cost computed LIVE from its tokens.
  const recentRows = await pool.query<{
    id: string; agent_id: string; agent_name: string; source: string; model: string | null;
    actionable: boolean; reason: string | null; input_tokens: number; cached_input_tokens: number;
    cache_creation_tokens: number; output_tokens: number; measured: boolean; created_at: Date
  }>(
    `SELECT t.id, t.agent_id, COALESCE(p.name, t.agent_id) AS agent_name, t.source, t.model,
            t.actionable, t.reason, t.input_tokens, t.cached_input_tokens, t.cache_creation_tokens,
            t.output_tokens, t.measured, t.created_at
       FROM agent_triages t
       LEFT JOIN participants p ON p.id = t.agent_id AND p.company_id = t.company_id
      WHERE t.company_id = $1 AND t.created_at > NOW() - ($2::double precision * INTERVAL '1 millisecond') ${agentFilter}
      ORDER BY t.created_at DESC
      LIMIT 200`,
    params,
  )
  const recent: TriageLedgerRow[] = recentRows.rows.map((r) => {
    const usage: TokenUsage = {
      inputTokens: r.input_tokens, cachedInputTokens: r.cached_input_tokens,
      cacheCreationTokens: r.cache_creation_tokens, outputTokens: r.output_tokens,
    }
    const priced = effectiveCostUsd(r.model, usage)
    const costUsd = r.measured ? priced.usd : 0
    const avg = avgCostByAgent.get(r.agent_id) ?? 0
    return {
      id: r.id, agentId: r.agent_id, agentName: r.agent_name,
      source: r.source as TriageSource, model: r.model,
      actionable: r.actionable, reason: r.reason,
      inputTokens: r.input_tokens, cachedInputTokens: r.cached_input_tokens, outputTokens: r.output_tokens,
      costUsd, costEstimated: priced.estimated, measured: r.measured,
      estSavingUsd: r.actionable ? null : avg - costUsd,
      createdAt: r.created_at.toISOString(),
    }
  })

  // Unit prices used, by role — live via priceFor (the rates the costs above used).
  const unitPrices: TriageUnitPrice[] = []
  const seenUnit = new Set<string>()
  const pushUnit = (role: 'triage' | 'turn', model: string | null): void => {
    if (!model) return
    const key = `${role}:${model}`
    if (seenUnit.has(key)) return
    seenUnit.add(key)
    const pr = priceFor(model)
    unitPrices.push({ role, model, inPer1M: pr.inPer1M, cachedInPer1M: pr.cachedInPer1M, outPer1M: pr.outPer1M, estimated: pr.verified !== true })
  }
  for (const t of triAgg.rows) pushUnit('triage', t.model)
  for (const r of runAgg.rows) pushUnit('turn', r.model)

  // Global rollups (turn metrics over ALL agents with runs; triage metrics + the
  // net over the agents that triaged, using each agent's OWN avg turn cost).
  let triageCostUsd = 0, estimatedAvoidedUsd = 0, triageCount = 0, triageSkip = 0, triageWake = 0
  let triageMeasured = 0, triageOverhead = 0, byoaTri = 0
  let turnCostUsd = 0, turnCount = 0, cacheRead = 0, totalInput = 0
  for (const a of acc.values()) {
    turnCostUsd += a.turnCostUsd; turnCount += a.turnCount; cacheRead += a.cacheRead; totalInput += a.totalInput
    if (a.triageCount > 0) {
      triageCostUsd += a.triageCostUsd; triageCount += a.triageCount; triageSkip += a.skipCount
      triageWake += a.wakeCount; triageMeasured += a.measuredCount; triageOverhead += a.triageOverheadUsd; byoaTri += a.byoaCount
      estimatedAvoidedUsd += a.skipCount * (a.turnCount > 0 ? a.turnCostUsd / a.turnCount : 0)
    }
  }
  // triage token totals (real, plan-independent) from the by-model groups.
  const triageInputTokens = triAgg.rows.reduce((s, t) => s + Number(t.input_tokens), 0)
  const triageCachedInputTokens = triAgg.rows.reduce((s, t) => s + Number(t.cached_tokens), 0)
  const triageOutputTokens = triAgg.rows.reduce((s, t) => s + Number(t.output_tokens), 0)
  const costEstimated = [...modelsSeen].some((m) => priceFor(m).verified !== true)

  return {
    sinceHours,
    triageCount,
    triageSkipCount: triageSkip,
    triageWakeCount: triageWake,
    triageMeasuredCount: triageMeasured,
    triageCostUsd,
    triageOverheadUsd: triageOverhead,
    triageInputTokens,
    triageCachedInputTokens,
    triageOutputTokens,
    turnCount,
    turnCostUsd,
    avgTurnCostUsd: turnCount > 0 ? turnCostUsd / turnCount : 0,
    turnCacheHitRate: totalInput > 0 ? cacheRead / totalInput : 0,
    estimatedAvoidedUsd,
    estimatedNetSavingsUsd: estimatedAvoidedUsd - triageCostUsd,
    costEstimated,
    byoaShare: triageCount > 0 ? byoaTri / triageCount : 0,
    unitPrices,
    priceTable: modelPriceTable(),
    perAgent: perAgent.sort((a, b) => b.triageCount - a.triageCount),
    recent,
  }
}

/** How long after a wake we still count a post as "this run answered".
 *  Ten minutes is the window @yetone used to publish the 26.3% figure in #70;
 *  keeping it identical is what makes this surface comparable to that number
 *  rather than a second, differently-shaped statistic. */
const SILENT_WINDOW_MS = 10 * 60_000

export interface SilentWakeBucket {
  /** 'group' | 'direct' — a DM legitimately answers far more often, so the two
   *  must never be averaged into one rate. */
  conversationKind: string
  runs: number
  silentRuns: number
  silentRate: number
  /** Big-brain spend on the silent runs, priced at query time from the stored
   *  token counts (same rule as the triage ledger: tokens are real, prices are
   *  live). */
  silentSpendUsd: number
}

export interface WakeEconomics {
  sinceHours: number
  buckets: SilentWakeBucket[]
  /** Any price used was a seed/fallback rather than an operator-supplied rate.
   *  The RATIOS are measured either way; only the dollars are modelled. */
  costEstimated: boolean
  /** Fan-out width: how many big-brain turns a human message causes. Room-wide
   *  — the agentId filter above does not apply to it. See getTurnsPerMessage. */
  turnsPerMessage: TurnsPerMessageBucket[]
}

/** How often a wake produced nothing.
 *
 *  A run counts as SILENT when the agent posted no message into any of the
 *  conversations that woke it, within SILENT_WINDOW_MS of the run starting.
 *  That is the whole point of #70: a group message wakes every member, each
 *  reasons over the same room, and most of them conclude it was not theirs —
 *  after the big brain has already been paid.
 *
 *  This exists so that decision stops needing a hand-written query. The routing
 *  change in #92 is meant to move this number; without a surface, "did it work"
 *  is an argument rather than a measurement.
 *
 *  Deliberately NOT a counterfactual: it reports what happened, not what would
 *  have been saved. The one modelled quantity is the dollar column, and
 *  `costEstimated` says so. */
export async function getWakeEconomics(args: {
  companyId: string
  agentId?: string | null
  sinceHours?: number
}): Promise<WakeEconomics> {
  const sinceHours = Math.min(720, Math.max(1, args.sinceHours ?? 24))
  const ms = sinceHours * 3_600_000
  const agentFilter = args.agentId ? 'AND r.agent_id = $4' : ''
  const params: unknown[] = [args.companyId, ms, SILENT_WINDOW_MS]
  if (args.agentId) params.push(args.agentId)

  // One aggregate, grouped in SQL — never a row per run in JS. Runs are reached
  // through idx_agent_runs_company_started; the silence probe is an anti-join
  // per (conversation, agent, window), which idx_messages_convo_created serves.
  // Only runs that actually spent tokens are counted: an orphaned 0-token row
  // never reached the model, so calling it a "silent wake" would inflate the
  // very number this exists to track.
  const { rows } = await pool.query<{
    conversation_kind: string
    runs: number
    silent_runs: number
    model: string | null
    input_tokens: string
    cached_tokens: string
    cache_creation_tokens: string
    output_tokens: string
  }>(
    `WITH run_convo AS (
       SELECT r.id, r.agent_id, r.started_at, r.model,
              r.input_tokens, r.cached_input_tokens, r.cache_creation_tokens, r.output_tokens,
              (SELECT cid FROM jsonb_array_elements_text(r.trigger->'conversationIds') AS cid LIMIT 1) AS conversation_id
         FROM agent_runs r
        WHERE r.company_id = $1
          AND r.started_at > NOW() - ($2::double precision * INTERVAL '1 millisecond')
          AND (r.input_tokens + r.cached_input_tokens + r.output_tokens) > 0
          ${agentFilter}
     )
     SELECT COALESCE(c.kind, 'group') AS conversation_kind,
            rc.model,
            count(*)::int AS runs,
            count(*) FILTER (
              WHERE NOT EXISTS (
                SELECT 1 FROM messages m
                 WHERE m.conversation_id = rc.conversation_id
                   AND m.author_id = rc.agent_id
                   AND m.created_at >= rc.started_at
                   AND m.created_at < rc.started_at + ($3::double precision * INTERVAL '1 millisecond')
              )
            )::int AS silent_runs,
            COALESCE(sum(rc.input_tokens) FILTER (WHERE NOT EXISTS (
                SELECT 1 FROM messages m
                 WHERE m.conversation_id = rc.conversation_id AND m.author_id = rc.agent_id
                   AND m.created_at >= rc.started_at
                   AND m.created_at < rc.started_at + ($3::double precision * INTERVAL '1 millisecond')
            )), 0)::bigint AS input_tokens,
            COALESCE(sum(rc.cached_input_tokens) FILTER (WHERE NOT EXISTS (
                SELECT 1 FROM messages m
                 WHERE m.conversation_id = rc.conversation_id AND m.author_id = rc.agent_id
                   AND m.created_at >= rc.started_at
                   AND m.created_at < rc.started_at + ($3::double precision * INTERVAL '1 millisecond')
            )), 0)::bigint AS cached_tokens,
            COALESCE(sum(rc.cache_creation_tokens) FILTER (WHERE NOT EXISTS (
                SELECT 1 FROM messages m
                 WHERE m.conversation_id = rc.conversation_id AND m.author_id = rc.agent_id
                   AND m.created_at >= rc.started_at
                   AND m.created_at < rc.started_at + ($3::double precision * INTERVAL '1 millisecond')
            )), 0)::bigint AS cache_creation_tokens,
            COALESCE(sum(rc.output_tokens) FILTER (WHERE NOT EXISTS (
                SELECT 1 FROM messages m
                 WHERE m.conversation_id = rc.conversation_id AND m.author_id = rc.agent_id
                   AND m.created_at >= rc.started_at
                   AND m.created_at < rc.started_at + ($3::double precision * INTERVAL '1 millisecond')
            )), 0)::bigint AS output_tokens
       FROM run_convo rc
       LEFT JOIN conversations c ON c.id = rc.conversation_id
      GROUP BY conversation_kind, rc.model`,
    params,
  )

  const byKind = new Map<string, { runs: number; silent: number; usd: number }>()
  let anyEstimated = false
  for (const r of rows) {
    const { usd, estimated } = effectiveCostUsd(r.model, {
      inputTokens: Number(r.input_tokens),
      cachedInputTokens: Number(r.cached_tokens),
      cacheCreationTokens: Number(r.cache_creation_tokens),
      outputTokens: Number(r.output_tokens),
    })
    if (estimated) anyEstimated = true
    const cur = byKind.get(r.conversation_kind) ?? { runs: 0, silent: 0, usd: 0 }
    cur.runs += r.runs
    cur.silent += r.silent_runs
    cur.usd += usd
    byKind.set(r.conversation_kind, cur)
  }

  return {
    sinceHours,
    costEstimated: anyEstimated,
    buckets: [...byKind].map(([conversationKind, v]) => ({
      conversationKind,
      runs: v.runs,
      silentRuns: v.silent,
      silentRate: v.runs > 0 ? v.silent / v.runs : 0,
      silentSpendUsd: v.usd,
    })).sort((a, b) => b.runs - a.runs),
    turnsPerMessage: await getTurnsPerMessage({ companyId: args.companyId, sinceHours }),
  }
}

/** One row of the fan-out-width distribution. */
export interface TurnsPerMessageBucket {
  conversationKind: string
  /** Denominator: human-authored messages in rooms with at least one agent. */
  messages: number
  /** Numerator: (message, run) pairs — runs whose drained inbox included the
   *  message. A run draining a burst counts toward each message it read. */
  turns: number
  avgTurns: number
  medianTurns: number
  hist: { turns: string; messages: number }[]
}

/** How many big-brain turns does one human message cause?
 *
 *  The silent-rate panel above answers "of the turns that fired, how many said
 *  nothing". This is the other half of #70's ledger: how MANY turns a message
 *  fires in the first place. The scheduler picks recipients purely by
 *  membership, so the width of that fan-out is the number any routing change
 *  (#92's `me`, a future `one-of-us`) claims to shrink — measured here instead
 *  of argued, per the ordering agreed in the #70 review.
 *
 *  Attribution: `agent_runs.input_message_ids` is the inbox a run actually
 *  drained, so a message's turn count is the number of token-bearing runs that
 *  read it. A run draining a burst of k messages counts toward each of them —
 *  that is deliberate (the message genuinely participated in that turn) and it
 *  is why this panel reports counts, not dollars: dollars per message would
 *      need fractional run attribution, which is a different, denser metric.
 *
 *  Denominator: human-authored, non-system messages in group/direct rooms with
 *  at least one agent member — so a message nobody's inbox ever reached shows
 *  up as 0 turns rather than vanishing. Room-wide by design: the agent filter
 *  above does not apply, because fan-out width is a property of the room. */
export async function getTurnsPerMessage(args: {
  companyId: string
  sinceHours?: number
}): Promise<TurnsPerMessageBucket[]> {
  const sinceHours = Math.min(720, Math.max(1, args.sinceHours ?? 24))
  const ms = sinceHours * 3_600_000

  const { rows } = await pool.query<{
    conversation_kind: string
    messages: number
    turns: number
    avg_turns: string
    median_turns: string
    w0: number
    w1: number
    w2: number
    w3_5: number
    w6: number
  }>(
    `WITH scope AS (
       SELECT m.id AS mid, c.kind AS conversation_kind
         FROM messages m
         JOIN conversations c ON c.id = m.conversation_id
         JOIN participants a ON a.id = m.author_id AND a.company_id = c.company_id
        WHERE c.company_id = $1
          AND c.kind IN ('group', 'direct')
          AND m.kind <> 'system'
          AND m.created_at > NOW() - ($2::double precision * INTERVAL '1 millisecond')
          AND a.kind = 'human'
          AND a.departed_at IS NULL
          AND EXISTS (
            SELECT 1
              FROM conversation_members cm
              JOIN participants ap
                ON ap.id = cm.participant_id
               AND ap.company_id = cm.company_id
             WHERE cm.conversation_id = c.id
               AND cm.company_id = c.company_id
               AND ap.kind = 'agent' AND ap.departed_at IS NULL
          )
     ),
     turns AS (
       SELECT j.mid, count(DISTINCT r.id)::int AS turns
         FROM agent_runs r
         CROSS JOIN LATERAL jsonb_array_elements_text(r.input_message_ids) AS j(mid)
        WHERE r.company_id = $1
          AND r.started_at > NOW() - ($2::double precision * INTERVAL '1 millisecond')
          AND (r.input_tokens + r.cached_input_tokens + r.output_tokens) > 0
        GROUP BY j.mid
     )
     SELECT s.conversation_kind,
            count(*)::int AS messages,
            COALESCE(sum(t.turns), 0)::int AS turns,
            -- COALESCE INSIDE the aggregate, not around it. A message no
            -- inbox reached has t.turns = NULL after the LEFT JOIN, and SQL
            -- aggregates skip NULLs — so avg and median silently dropped the
            -- zero-turn messages while the histogram (which already coalesces)
            -- counted them. On 4 messages, 2 of them unwoken, that reported a
            -- fan-out of 3.0 where the real width was 1.5, next to a rendered
            -- turns/messages pair that divides to 1.5. The whole point of
            -- this panel is that number.
            COALESCE(avg(COALESCE(t.turns, 0)), 0) AS avg_turns,
            COALESCE(percentile_cont(0.5) WITHIN GROUP (ORDER BY COALESCE(t.turns, 0)), 0) AS median_turns,
            count(*) FILTER (WHERE COALESCE(t.turns, 0) = 0)::int AS w0,
            count(*) FILTER (WHERE COALESCE(t.turns, 0) = 1)::int AS w1,
            count(*) FILTER (WHERE COALESCE(t.turns, 0) = 2)::int AS w2,
            count(*) FILTER (WHERE COALESCE(t.turns, 0) BETWEEN 3 AND 5)::int AS w3_5,
            count(*) FILTER (WHERE COALESCE(t.turns, 0) >= 6)::int AS w6
       FROM scope s
       LEFT JOIN turns t ON t.mid = s.mid
      GROUP BY s.conversation_kind`,
    [args.companyId, ms],
  )

  return rows.map((r) => ({
    conversationKind: r.conversation_kind,
    messages: r.messages,
    turns: r.turns,
    avgTurns: Number(r.avg_turns),
    medianTurns: Number(r.median_turns),
    hist: [
      { turns: '0', messages: r.w0 },
      { turns: '1', messages: r.w1 },
      { turns: '2', messages: r.w2 },
      { turns: '3–5', messages: r.w3_5 },
      { turns: '6+', messages: r.w6 },
    ],
  }))
}