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

feat(observability): turns per human message — the other half of the #70 ledger

wg2038dd0beeedeae9
diff --git a/server/src/__tests__/agents-observability-turns.test.ts b/server/src/__tests__/agents-observability-turns.test.ts
new file mode 100644
index 0000000..2f6ecbf
--- /dev/null
+++ b/server/src/__tests__/agents-observability-turns.test.ts
@@ -0,0 +1,132 @@
+/**
+ * The fan-out-width half of the wake-economics ledger: turns per human
+ * message. The SQL does the grouping; these tests pin the JS contract —
+ * bucket mapping, the numeric conversion of pg's decimal strings, the fixed
+ * histogram order — and that the metric rides along on the wake-economics
+ * response where the panel reads it.
+ *
+ * Run: node --import tsx --test server/src/__tests__/agents-observability-turns.test.ts
+ */
+import { afterEach, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+// Same pattern as computer-engine-redetect.test.ts: pin the HTTP runtime
+// client and mock the pool, so no Redis or Postgres is needed.
+process.env.CUMORA_RUNTIME_CLIENT = 'http'
+process.env.OPENAI_API_KEY ??= 'test-key'
+
+const { getWakeEconomics, getTurnsPerMessage } = await import('../agents/observability.js')
+const { pool } = await import('../db/pool.js')
+
+const realQuery = pool.query.bind(pool)
+
+afterEach(() => {
+ ;(pool as unknown as { query: typeof realQuery }).query = realQuery
+})
+
+type QueryHandler = (sql: string, params?: unknown[]) => { rows: unknown[] }
+
+function mockPool(handler: QueryHandler): void {
+ ;(pool as unknown as { query: QueryHandler }).query = (sql: string, params?: unknown[]) => handler(sql, params)
+}
+
+const WAKE_SQL_PREFIX = 'WITH run_convo AS'
+const TURNS_SQL_PREFIX = 'WITH scope AS'
+
+function mockWakeAndTurns(turnRows: unknown[]): void {
+ mockPool((sql) => {
+ if (sql.startsWith(WAKE_SQL_PREFIX)) {
+ return {
+ rows: [{
+ conversation_kind: 'group',
+ runs: 10,
+ silent_runs: 3,
+ model: 'gpt-test',
+ input_tokens: '1000',
+ cached_tokens: '0',
+ cache_creation_tokens: '0',
+ output_tokens: '200',
+ }],
+ }
+ }
+ if (sql.startsWith(TURNS_SQL_PREFIX)) return { rows: turnRows }
+ throw new Error('unexpected query: ' + sql.slice(0, 60))
+ })
+}
+
+test('turns-per-message buckets carry the histogram in fixed order', async () => {
+ mockPool((sql) => {
+ if (sql.startsWith(TURNS_SQL_PREFIX)) {
+ return {
+ rows: [{
+ conversation_kind: 'group',
+ messages: 100,
+ turns: 240,
+ avg_turns: '2.4000000000000000',
+ median_turns: '2',
+ w0: 15,
+ w1: 30,
+ w2: 25,
+ w3_5: 20,
+ w6: 10,
+ }],
+ }
+ }
+ throw new Error('unexpected query: ' + sql.slice(0, 60))
+ })
+ const [b] = await getTurnsPerMessage({ companyId: 'c1', sinceHours: 24 })
+ assert.equal(b.conversationKind, 'group')
+ assert.equal(b.messages, 100)
+ assert.equal(b.turns, 240)
+ assert.equal(b.avgTurns, 2.4)
+ assert.equal(b.medianTurns, 2)
+ assert.deepEqual(
+ b.hist.map((h) => h.turns),
+ ['0', '1', '2', '3–5', '6+'],
+ 'the bar renderer relies on this order: darkest segment is 6+',
+ )
+ assert.deepEqual(b.hist.map((h) => h.messages), [15, 30, 25, 20, 10])
+ assert.equal(b.hist.reduce((s, h) => s + h.messages, 0), b.messages, 'histogram sums to the denominator')
+})
+
+test('a window with no human messages yields no buckets, not zeroes', async () => {
+ mockPool((sql) => {
+ if (sql.startsWith(TURNS_SQL_PREFIX)) return { rows: [] }
+ throw new Error('unexpected query: ' + sql.slice(0, 60))
+ })
+ assert.deepEqual(await getTurnsPerMessage({ companyId: 'c1' }), [])
+})
+
+test('the metric rides along on the wake-economics response the panel reads', async () => {
+ mockWakeAndTurns([{
+ conversation_kind: 'group',
+ messages: 4,
+ turns: 12,
+ avg_turns: '3.0',
+ median_turns: '3',
+ w0: 0,
+ w1: 1,
+ w2: 1,
+ w3_5: 2,
+ w6: 0,
+ }])
+ const res = await getWakeEconomics({ companyId: 'c1', sinceHours: 24 })
+ assert.equal(res.costEstimated, true, 'no prices configured here — the dollars are modelled and must say so')
+ assert.equal(res.buckets[0].runs, 10)
+ assert.deepEqual(res.turnsPerMessage.map((b) => b.conversationKind), ['group'])
+ assert.equal(res.turnsPerMessage[0].avgTurns, 3)
+})
+
+test('sinceHours is clamped to the same window the rest of the panel uses', async () => {
+ let captured: unknown[] = []
+ mockPool((sql, params = []) => {
+ if (sql.startsWith(TURNS_SQL_PREFIX)) {
+ captured = params as unknown[]
+ return { rows: [] }
+ }
+ throw new Error('unexpected query: ' + sql.slice(0, 60))
+ })
+ await getTurnsPerMessage({ companyId: 'c1', sinceHours: 99999 })
+ // 720h ceiling, expressed as milliseconds — same clamp as getWakeEconomics.
+ assert.equal(captured[1], 720 * 3_600_000)
+})
diff --git a/server/src/agents/observability.ts b/server/src/agents/observability.ts
index 8e039e2..40b3894 100644
--- a/server/src/agents/observability.ts
+++ b/server/src/agents/observability.ts
@@ -564,6 +564,9 @@ export interface WakeEconomics {
/** 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.
@@ -687,5 +690,117 @@ export async function getWakeEconomics(args: {
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 jsonb_array_elements_text(c.members) AS j(mid)
+ JOIN participants ap ON ap.id = j.mid AND ap.company_id = c.company_id
+ WHERE 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(avg(t.turns), 0) AS avg_turns,
+ COALESCE(percentile_cont(0.5) WITHIN GROUP (ORDER BY t.turns), 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 },
+ ],
+ }))
+}
diff --git a/src/api/client.ts b/src/api/client.ts
index 193e220..b5c9fa2 100644
--- a/src/api/client.ts
+++ b/src/api/client.ts
@@ -467,11 +467,23 @@ export interface ApiSilentWakeBucket {
silentSpendUsd: number
}
+export interface ApiTurnsPerMessageBucket {
+ conversationKind: string
+ messages: number
+ turns: number
+ avgTurns: number
+ medianTurns: number
+ hist: { turns: string; messages: number }[]
+}
+
export interface ApiWakeEconomics {
sinceHours: number
buckets: ApiSilentWakeBucket[]
/** The RATIOS are measured either way; only the dollar column is modelled. */
costEstimated: boolean
+ /** Fan-out width per human message. Room-wide: not scoped by the agentId
+ * filter, because width is a property of the room, not of one agent. */
+ turnsPerMessage: ApiTurnsPerMessageBucket[]
}
export interface ApiTriageEconomics {
diff --git a/src/desktop/ObservabilityView.tsx b/src/desktop/ObservabilityView.tsx
index bd89fff..95bf254 100644
--- a/src/desktop/ObservabilityView.tsx
+++ b/src/desktop/ObservabilityView.tsx
@@ -873,6 +873,67 @@ function WakeEconomicsPanel(props: {
</table>
<div className="mt-2.5 text-[11px] leading-[1.6] text-ink-500">{t('obs.wakesFootnote')}</div>
</div>
+
+ {/* Fan-out width — the other half of the #70 ledger. Where the
+ silent rate says "of the turns that fired, how many said
+ nothing", this says how many turns fired per message in the
+ first place. Room-wide by construction, so when an agent
+ filter is active, say so instead of silently mixing scopes. */}
+ {(data.turnsPerMessage?.length ?? 0) > 0 && (
+ <div className="rounded-[10px] border border-ink-100 bg-paper px-3.5 py-3">
+ <div className="flex items-baseline justify-between gap-2">
+ <div className="text-[9.5px] font-bold uppercase tracking-[0.12em] text-ink-300">{t('obs.fanoutTitle')}</div>
+ {props.agentId !== 'all' && <div className="text-[9.5px] text-ink-400">{t('obs.fanoutRoomWide')}</div>}
+ </div>
+ <table className="mt-2 w-full text-[11.5px]">
+ <thead className="text-[9px] font-bold uppercase tracking-[0.1em] text-ink-400">
+ <tr>
+ <th className="py-1 text-left">{t('obs.colKind')}</th>
+ <th className="py-1 text-right">{t('obs.colMessages')}</th>
+ <th className="py-1 text-right">{t('obs.colTurns')}</th>
+ <th className="py-1 text-right">{t('obs.colAvg')}</th>
+ <th className="py-1 text-right">{t('obs.colMedian')}</th>
+ <th className="py-1 text-right">{t('obs.colDist')}</th>
+ </tr>
+ </thead>
+ <tbody className="divide-y divide-ink-100">
+ {data.turnsPerMessage.map((b) => (
+ <tr key={b.conversationKind}>
+ <td className="py-1">
+ <span className={cn(
+ 'rounded-full px-1.5 py-0.5 text-[9px] font-bold uppercase',
+ b.conversationKind === 'group' ? 'bg-sky2-50 text-skype-deep' : 'bg-ink-100 text-ink-600',
+ )}>
+ {b.conversationKind === 'group' ? t('obs.kindGroup') : t('obs.kindDirect')}
+ </span>
+ </td>
+ <td className="py-1 text-right tabular-nums text-ink-600">{b.messages}</td>
+ <td className="py-1 text-right tabular-nums text-ink-600">{b.turns}</td>
+ <td className="py-1 text-right tabular-nums text-ink-700">{b.avgTurns.toFixed(1)}</td>
+ <td className="py-1 text-right tabular-nums text-ink-700">{b.medianTurns.toFixed(1)}</td>
+ <td className="py-1">
+ <div className="flex h-2 w-40 overflow-hidden rounded-full bg-ink-100">
+ {b.hist.map((h, i) => (
+ <div
+ key={h.turns}
+ title={`${h.turns} turns: ${h.messages}`}
+ className="h-full"
+ style={{
+ width: `${(h.messages / Math.max(1, b.messages)) * 100}%`,
+ background: 'var(--skype)',
+ opacity: 0.18 + i * 0.2,
+ }}
+ />
+ ))}
+ </div>
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ <div className="mt-2.5 text-[11px] leading-[1.6] text-ink-500">{t('obs.fanoutFootnote')}</div>
+ </div>
+ )}
</div>
)}
</div>
diff --git a/src/locales/en.ts b/src/locales/en.ts
index e168883..3cd2aef 100644
--- a/src/locales/en.ts
+++ b/src/locales/en.ts
@@ -863,6 +863,14 @@ export const en = {
'obs.kindGroup': 'Group',
'obs.kindDirect': 'Direct',
'obs.wakesFootnote': 'A wake counts as silent when the agent posted no message into any conversation that woke it, within 10 minutes of the run starting. Group and direct are never averaged: a DM legitimately answers far more often, and blending the two hides the only rate worth acting on. This reports what happened, not what would have been saved.',
+ 'obs.fanoutTitle': 'Fan-out width — turns per human message',
+ 'obs.fanoutRoomWide': 'room-wide · not filtered by agent',
+ 'obs.colMessages': 'Messages',
+ 'obs.colTurns': 'Turns',
+ 'obs.colAvg': 'Avg',
+ 'obs.colMedian': 'Median',
+ 'obs.colDist': 'Distribution',
+ 'obs.fanoutFootnote': 'How many big-brain turns one human message causes: the runs whose drained inbox included it. The bar shows the share of messages at 0 / 1 / 2 / 3–5 / 6+ turns, darkest at 6+. A width near 1 means a message lands on one agent; the #70 routing work is about moving group rooms toward it.',
'obs.triageTitle': 'Triage Economics',
'obs.triageSubtitle': 'Does the small-brain gate save money? Each triage is a cold session (uncached input); the big-brain turns it shields are cache-warm.',
'obs.triageEstimateWarn':
diff --git a/src/locales/zh-CN.ts b/src/locales/zh-CN.ts
index c6a90db..093d282 100644
--- a/src/locales/zh-CN.ts
+++ b/src/locales/zh-CN.ts
@@ -864,6 +864,14 @@ export const zhCN: Partial<Record<keyof typeof en, string>> = {
'obs.kindGroup': '群聊',
'obs.kindDirect': '私聊',
'obs.wakesFootnote': '一次唤醒被计为「静默」,是指在运行开始后的 10 分钟内,该 agent 没有向任何唤醒它的会话发出消息。群聊与私聊从不合并平均:私聊本来就回复得多得多,混在一起会掩盖唯一值得据以行动的那个比率。这里报告的是实际发生了什么,而不是「本来能省多少」。',
+ 'obs.fanoutTitle': '扇出宽度 — 每条人类消息触发多少次对话',
+ 'obs.fanoutRoomWide': '按房间统计 · 不随上方 Agent 筛选',
+ 'obs.colMessages': '消息数',
+ 'obs.colTurns': 'Turn 数',
+ 'obs.colAvg': '平均',
+ 'obs.colMedian': '中位数',
+ 'obs.colDist': '分布',
+ 'obs.fanoutFootnote': '一条人类消息引发多少次大模型 turn:统计读了它的 run。色条按 0 / 1 / 2 / 3–5 / 6+ 个 turn 的消息占比展示,颜色越深 turn 越多。宽度接近 1 说明消息只落到一个 agent 手里;#70 的路由工作,做的就是让群聊的宽度往 1 靠。',
'obs.triageTitle': '分流经济学',
'obs.triageSubtitle': '小脑把关到底省不省钱?每次分流都是冷启动会话(未缓存的输入),而被它挡住的大脑对话是缓存命中的。',
'obs.triageEstimateWarn':