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
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 },
],
}))
}