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.tsnew file mode 100644index 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.tsindex 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.tsindex 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: numberbuckets: 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.tsxindex 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.tsindex 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.tsindex 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':