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
30.3 KB
Raw Blame
/**
 * Heartbeat agenda pre-check — runs on the idle scheduler before we
 * wake an agent's brain.
 *
 * Why this exists:
 *   The plain idle wake hands a generic "is there anything worth
 *   doing?" prompt to the agent's main (brain) model. That call is
 *   expensive AND the agent has no agenda context — it has to query
 *   inbox / groups / contacts itself before it can even decide
 *   whether to act, burning a full reasoning turn on what often is
 *   "no, nothing to do."
 *
 *   This module front-runs that decision with a cheap (cerebellum)
 *   classifier. We collect the agent's actionable surface — Kanban
 *   cards assigned to or @-mentioning them in non-done columns, plus
 *   Calendar events due in the current/imminent slot — and feed it
 *   to a small JSON classifier that decides:
 *       (a) is anything genuinely worth waking the brain for? and
 *       (b) if so, what should it focus on first?
 *
 *   When the answer is yes, we wake with a focused
 *   `backgroundBrief` so the brain spends its turn EXECUTING, not
 *   deciding-whether-to-execute. When the answer is no, we skip the
 *   wake entirely — the brain never runs, no tokens spent.
 *
 *   Net effect: heartbeats become high-signal AND cheaper. The
 *   classifier is the cerebellum doing exactly what cerebellum is
 *   for: a fast yes/no on data, no real reasoning.
 */
import { pool } from '../db/pool.js'
import { env } from '../env.js'
import { getTrackedLlmClient } from './llm-ledger.js'
import { redis } from '../redis.js'

/** A Kanban card that the agent should plausibly act on. */
export interface AgendaCard {
  id: string
  board_id: string
  board_title: string
  column_id: string
  column_title: string
  title: string
  description: string | null
  assignee_id: string | null
  mentions: string[]
  updated_at: string
}

/** A calendar event in the current / imminent slot for this agent. */
export interface AgendaEvent {
  id: string
  title: string
  description: string | null
  start_at: string
  agent_prompt: string | null
  target_conversation_id: string | null
}

/** A conversation the agent is in that has gone quiet mid-flow — surfaced so the
 *  agent can proactively follow up (answer if it owes a reply, nudge if it's
 *  waiting, or prod a stalled human-started activity) instead of only ever
 *  reacting to new messages. `lastAuthorIsSelf` tells the brain which: false =
 *  someone else spoke last (you may owe a reply / be a bystander); true = you
 *  spoke last (you're awaiting them → consider a nudge). The brain reads the room
 *  and decides who/whether/how; the cerebellum only gates whether it's worth a wake. */
export interface StalledConvo {
  conversationId: string
  kind: string
  title: string | null
  lastMessageId: string
  lastAuthorId: string
  lastAuthorName: string
  lastAuthorIsSelf: boolean
  lastBody: string
  minutesSilent: number
  /** The last few messages (oldest→newest, "author: body"), so the cerebellum can
   *  tell a genuinely-waiting stall from a thread that has CONCLUDED / socially
   *  closed (a wrap-up flurry with no open ask). Without this it sees only the
   *  single last line and mistakes a finished activity for one still in motion. */
  recentTail: string
}

export interface AgentAgenda {
  cards: AgendaCard[]
  events: AgendaEvent[]
  stalls: StalledConvo[]
}

/** Patterns we treat as "the card is already finished, don't bug the
 *  agent." Matched case-insensitively against the column title — the
 *  Kanban schema doesn't carry an "is_done" flag, so column-title
 *  heuristics are the cheapest signal we have. */
const DONE_COLUMN_PATTERNS = /\b(done|complete|completed|shipped|archive|archived|closed|cancel|canceled|cancelled)\b/i

/** How far ahead a calendar event can be and still count as "current
 *  slot" for the heartbeat. 30 min gives the agent enough time to
 *  load context without surfacing things they should think about
 *  hours from now. */
const CALENDAR_LOOKAHEAD_MS = 30 * 60_000
/** How far in the past a still-active calendar event can be and still
 *  count. Covers the gap between the calendar dispatcher's last fire
 *  and this heartbeat. */
const CALENDAR_LOOKBEHIND_MS = 15 * 60_000

/** Stall window: a conversation counts as "stalled" only if its last message is
 *  at least STALL_MIN_MS old (give people time to reply naturally — don't nag)
 *  and at most STALL_MAX_MS old (don't resurrect ancient threads). Env-overridable. */
const STALL_MIN_MS = Number(process.env.CUMORA_STALL_MIN_MS) || 5 * 60_000
const STALL_MAX_MS = Number(process.env.CUMORA_STALL_MAX_MS) || 6 * 60 * 60_000
/** Cooldown between nudges to the SAME conversation, across ALL agents. Keyed on
 *  conversation only (NOT last-message-id) — a nudge changes the last message, so
 *  a per-message key would re-arm 5min later and nag. This guarantees a stalled
 *  conversation is nudged at most ONCE per cooldown by exactly ONE agent. Env-
 *  overridable; set very large for "one nudge per stall episode, basically once". */
const NUDGE_COOLDOWN_MS = Number(process.env.CUMORA_NUDGE_COOLDOWN_MS) || 45 * 60_000
/** SHORTER cooldown for nudges driven by the DETERMINISTIC fallback
 *  (cerebellum unavailable). Rationale: the deterministic rule is conservative
 *  on input but doesn't know whether the WOKEN agent's big brain will actually
 *  decide to post — if it declines, the 45min cerebellum-grade cooldown locks
 *  out everyone else and a single "no" decides the stall's fate. A short TTL
 *  lets other members get a turn at the same stall with a different big-brain
 *  judgment. The 45min lock is right when the cerebellum SAID "yes nudge";
 *  it's wrong as the only knob for an outage-time fallback. */
const NUDGE_COOLDOWN_FALLBACK_MS = Number(process.env.CUMORA_NUDGE_COOLDOWN_FALLBACK_MS) || 5 * 60_000

/** Claim the right to nudge a stalled conversation. Returns true for the FIRST
 *  caller (across all member agents); everyone else — and the same agent on a
 *  later heartbeat — gets false until the cooldown lapses. ONE key per
 *  CONVERSATION (NX + cooldown TTL).
 *
 *  Pass `source: 'fallback'` when the wake is from the deterministic agenda
 *  fallback (classifier 503), to use the shorter cooldown — a "no" from the
 *  chosen agent shouldn't permanently silence a stall the cerebellum can't
 *  even weigh in on. Default 'classified' preserves the 45min cooldown for
 *  the normal LLM-gated path. */
export async function claimStallNudge(
  conversationId: string,
  opts?: { source?: 'classified' | 'fallback' },
): Promise<boolean> {
  // Fallback path: after N successive nudges land without the stall
  // ACTUALLY advancing (new message in the convo), stop. The LLM judgment
  // has converged — every woken big brain is declining for the same
  // reason. Re-wakes every 5min after that point burn tokens for no
  // changed decision. The counter is the per-conversation declines
  // counter; the cap is small (3) so a stall the team has truly given
  // up on stops auto-firing — without permanently silencing it, because
  // the counter expires on the next NEW message in the convo (someone
  // posting resets the conversation state). Classified-path nudges
  // already use the 45min cooldown so they don't need a separate cap.
  if (opts?.source === 'fallback') {
    const declineKey = `cumora:nudge-declines:${conversationId}`
    const declines = await redis.get(declineKey).then((v) => Number(v) || 0).catch(() => 0)
    if (declines >= 3) return false
  }
  const key = `cumora:nudge:${conversationId}`
  const cooldownMs = opts?.source === 'fallback' ? NUDGE_COOLDOWN_FALLBACK_MS : NUDGE_COOLDOWN_MS
  const ttlSec = Math.ceil(cooldownMs / 1000)
  const res = await redis.set(key, '1', 'EX', ttlSec, 'NX').catch(() => null)
  if (res === 'OK' && opts?.source === 'fallback') {
    // Record the decline-attempt counter (TTL matches the stall window so
    // it auto-expires; resets on any actual conversation message via the
    // counter-reset path below). The naming is "declines" but it really
    // tracks "fallback claims granted without a follow-on post" — we can't
    // know whether the agent posted until later; the cleaner-on-post path
    // (resetStallNudgeDeclines) handles the truthing.
    const declineKey = `cumora:nudge-declines:${conversationId}`
    await redis.multi()
      .incr(declineKey)
      .expire(declineKey, Math.ceil(NUDGE_COOLDOWN_MS / 1000))
      .exec()
      .catch(() => null)
  }
  return res === 'OK'
}

/** Called when a NEW message lands in a conversation — clears the
 *  decline counter so future fallback nudges (if the convo stalls again
 *  LATER) get a fresh budget. The counter only existed to stop a single
 *  stalled state from being re-poked indefinitely; new activity = new
 *  state = new budget. Fire-and-forget. */
export async function resetStallNudgeDeclines(conversationId: string): Promise<void> {
  if (!conversationId) return
  await redis.del(`cumora:nudge-declines:${conversationId}`).catch(() => null)
}

/** Pull cards assigned to (or @-mentioning) the agent in non-done
 *  columns. Capped tightly so we never feed the classifier a wall of
 *  context. Stale cards (untouched for 30 days) are ignored — they're
 *  almost always abandoned work. */
async function loadAssignedCards(agentId: string, companyId: string): Promise<AgendaCard[]> {
  const { rows } = await pool.query<AgendaCard>(
    `SELECT c.id, c.board_id, b.title AS board_title,
            c.column_id, col.title AS column_title,
            c.title, c.description, c.assignee_id,
            COALESCE(c.mentions, '[]'::jsonb) AS mentions,
            c.updated_at::text AS updated_at
       FROM board_cards c
       JOIN boards b ON b.id = c.board_id
       JOIN board_columns col ON col.id = c.column_id
      WHERE b.company_id = $1
        AND (c.assignee_id = $2 OR c.mentions @> to_jsonb($2::text))
        AND c.updated_at > NOW() - INTERVAL '30 days'
      ORDER BY c.updated_at DESC
      LIMIT 20`,
    [companyId, agentId],
  )
  return rows.filter((r) => !DONE_COLUMN_PATTERNS.test(r.column_title ?? ''))
}

/** Pull calendar events for this agent that fall inside the current
 *  slot window. We deliberately keep `recurrence` off the result —
 *  the classifier doesn't need rule semantics, just the next concrete
 *  occurrence time, and the calendar dispatcher already handles the
 *  recurrence math for actual dispatches. */
async function loadDueEvents(agentId: string, companyId: string, now: Date): Promise<AgendaEvent[]> {
  const lookbehindFloor = new Date(now.getTime() - CALENDAR_LOOKBEHIND_MS)
  const lookaheadCeiling = new Date(now.getTime() + CALENDAR_LOOKAHEAD_MS)
  const { rows } = await pool.query<AgendaEvent>(
    `SELECT id, title, description, start_at::text AS start_at,
            agent_prompt, target_conversation_id
       FROM calendar_events
      WHERE company_id = $1
        AND assignee_id = $2
        AND status = 'active'
        AND start_at BETWEEN $3 AND $4
      ORDER BY start_at ASC
      LIMIT 10`,
    [companyId, agentId, lookbehindFloor, lookaheadCeiling],
  )
  return rows
}

/** Conversations the agent is a member of whose LATEST text message sits in the
 *  stall window [STALL_MIN_MS, STALL_MAX_MS] of silence. The participant-led
 *  normalized membership index narrows the conversations first, then
 *  idx_messages_convo_created serves the LATERAL latest-message lookup. */
async function loadStalledConversations(agentId: string, companyId: string): Promise<StalledConvo[]> {
  const { rows } = await pool.query<{
    conversation_id: string; kind: string; title: string | null
    last_message_id: string; last_author_id: string; last_author_name: string
    last_author_is_self: boolean; last_body: string; minutes_silent: string; recent_tail: string | null
  }>(
    `WITH convos AS (
         SELECT c.id, c.kind, c.title
           FROM conversations c
          WHERE c.company_id = $2
            AND EXISTS (
              SELECT 1 FROM conversation_members cm
               WHERE cm.conversation_id = c.id
                 AND cm.company_id = c.company_id
                 AND cm.participant_id = $1
            )
       )
       SELECT co.id AS conversation_id, co.kind, co.title,
              m.id AS last_message_id, m.author_id AS last_author_id,
              COALESCE(p.name, m.author_id) AS last_author_name,
              (m.author_id = $1) AS last_author_is_self,
              LEFT(m.body, 160) AS last_body,
              (EXTRACT(EPOCH FROM (NOW() - m.created_at)) / 60)::int::text AS minutes_silent,
              (
                SELECT string_agg(t.line, E'\n' ORDER BY t.created_at ASC)
                  FROM (
                    SELECT COALESCE(tp.name, tm.author_id) || ': ' || LEFT(tm.body, 100) AS line, tm.created_at
                      FROM messages tm
                      LEFT JOIN participants tp ON tp.id = tm.author_id AND tp.company_id = $2
                     WHERE tm.conversation_id = co.id AND tm.kind = 'text'
                     ORDER BY tm.created_at DESC
                     LIMIT 6
                  ) t
              ) AS recent_tail
         FROM convos co
         JOIN LATERAL (
           SELECT * FROM messages mm
            WHERE mm.conversation_id = co.id AND mm.kind = 'text'
            ORDER BY mm.created_at DESC
            LIMIT 1
         ) m ON true
         LEFT JOIN participants p ON p.id = m.author_id AND p.company_id = $2
        WHERE m.created_at <= NOW() - ($3::double precision * INTERVAL '1 millisecond')
          AND m.created_at >= NOW() - ($4::double precision * INTERVAL '1 millisecond')
        ORDER BY m.created_at DESC
        LIMIT 10`,
    [agentId, companyId, STALL_MIN_MS, STALL_MAX_MS],
  )
  return rows.map((r) => ({
    conversationId: r.conversation_id,
    kind: r.kind,
    title: r.title,
    lastMessageId: r.last_message_id,
    lastAuthorId: r.last_author_id,
    lastAuthorName: r.last_author_name,
    lastAuthorIsSelf: r.last_author_is_self,
    lastBody: r.last_body,
    minutesSilent: Number(r.minutes_silent),
    recentTail: r.recent_tail ?? '',
  }))
}

/** Public entry point. Empty result = "nothing on this agent's
 *  plate"; callers fall back to the generic idle behavior. */
export async function gatherAgentAgenda(
  agentId: string,
  companyId: string,
  now: Date = new Date(),
): Promise<AgentAgenda> {
  const [cards, events, stalls] = await Promise.all([
    loadAssignedCards(agentId, companyId),
    loadDueEvents(agentId, companyId, now),
    loadStalledConversations(agentId, companyId).catch((e) => {
      console.warn('[agenda] loadStalledConversations failed', e instanceof Error ? e.message : e)
      return [] as StalledConvo[]
    }),
  ])
  return { cards, events, stalls }
}

/** Render the agenda as a compact text block for the classifier. We
 *  intentionally do not include the full description body — the
 *  classifier only needs to decide go/no-go, and the brain will see
 *  the full card via the `kanban` CLI on actual wake.
 *
 *  Prefix-cache order (providers cache the longest unchanged prefix):
 *    1. cards (change only when a card row changes)
 *    2. stall identity + recent messages (change only on new chat)
 *    3. calendar slot (slides as wall-clock crosses 30m/15m windows)
 *  Wall-clock "Nm silent" is kept in a final timing section. That preserves
 *  the original recency signal while preventing a ticking value from
 *  invalidating the stable agenda prefix on every heartbeat. */
function byId<T extends { id: string }>(a: T, b: T): number {
  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0
}

function renderAgendaForClassifier(agenda: AgentAgenda): string {
  const lines: string[] = []
  // Sort by id so inserting/updating one row does not reshuffle the rest and
  // bust the prefix cache of every later line. Selection (most-recent LIMIT)
  // still happens in SQL; this is display order only.
  const cards = [...agenda.cards].sort(byId)
  const stalls = [...agenda.stalls].sort((a, b) => (
    a.conversationId < b.conversationId ? -1 : a.conversationId > b.conversationId ? 1 : 0
  ))
  if (cards.length > 0) {
    lines.push(`Kanban cards (${cards.length}):`)
    for (const c of cards) {
      const tag = c.assignee_id ? 'assigned' : 'mentioned'
      lines.push(`- [${tag}] "${c.title}" in ${c.board_title} / ${c.column_title} (id=${c.id}, updated ${c.updated_at})`)
    }
  }
  if (stalls.length > 0) {
    if (lines.length > 0) lines.push('')
    lines.push(`Conversations you're in that have gone quiet (${stalls.length}) — judge each: genuinely WAITING on someone, or already CONCLUDED/wound down?`)
    for (const s of stalls) {
      const who = s.lastAuthorIsSelf ? 'YOU spoke last, no reply since' : `${s.lastAuthorName} spoke last, you haven't responded`
      lines.push(`- [${s.kind}] ${s.title ?? s.conversationId} (${s.conversationId}) — ${who}. Last few messages:`)
      for (const ln of (s.recentTail || s.lastBody).split('\n')) lines.push(`    ${ln}`)
    }
  }
  if (agenda.events.length > 0) {
    if (lines.length > 0) lines.push('')
    lines.push(`Calendar events in current slot (${agenda.events.length}):`)
    for (const e of agenda.events) {
      const prompt = e.agent_prompt ? ` — prompt: ${e.agent_prompt.slice(0, 140)}` : ''
      lines.push(`- "${e.title}" at ${e.start_at}${prompt}`)
    }
  }
  if (stalls.length > 0) {
    if (lines.length > 0) lines.push('')
    lines.push('Current stall timing:')
    for (const s of stalls) lines.push(`- ${s.conversationId}: ${s.minutesSilent}m silent`)
  }
  if (lines.length === 0) return '(empty)'
  return lines.join('\n')
}

export interface AgendaVerdict {
  /** Whether the agent should wake right now to act on this agenda. */
  actionable: boolean
  /** One-line focus the brain should drive toward, if actionable. */
  focus: string
  /** Telemetry-only reason string; never shown to the agent. The literal
   *  string `'classifier error'` is a sentinel — callers should treat it
   *  as "triage failed, fall back to the safe path" rather than "no work
   *  to do," so a transient LLM outage doesn't silence every agent with
   *  agenda items. */
  reason: string
}

/** Sentinel value for {@link AgendaVerdict.reason} when the underlying
 *  classifier call threw. Exported so callers can detect it without
 *  string-matching. */
export const AGENDA_CLASSIFIER_ERROR = 'classifier error'

/** Parse the support model's verdict conservatively. JSON mode is not enough
 * for every OpenAI-compatible provider: DeepSeek sometimes wraps JSON, omits
 * key quotes, or truncates after all required fields. Recover only an explicit
 * actionable value. A malformed positive also needs a non-empty focus, so
 * salvage can never turn ambiguous output into a wake. */
export function parseAgendaVerdict(raw: string): {
  actionable?: unknown
  focus?: unknown
  reason?: unknown
} | null {
  const unfenced = raw.trim()
    .replace(/^```(?:json)?\s*/i, '')
    .replace(/\s*```$/i, '')
  const firstBrace = unfenced.indexOf('{')
  if (firstBrace < 0) return null
  const lastBrace = unfenced.lastIndexOf('}')
  const candidate = unfenced.slice(firstBrace, lastBrace > firstBrace ? lastBrace + 1 : undefined)
  try {
    return JSON.parse(candidate) as { actionable?: unknown; focus?: unknown; reason?: unknown }
  } catch { /* conservative field salvage below */ }

  const actionMatch = candidate.match(
    /(?:["']?actionable["']?)\s*:\s*(true|false|1|0|["']true["']|["']false["'])/i,
  )
  if (!actionMatch) return null
  const actionToken = actionMatch[1].replace(/["']/g, '').toLowerCase()
  const actionable = actionToken === 'true' || actionToken === '1'
  const stringField = (name: string): string => {
    const match = candidate.match(new RegExp(`(?:["']?${name}["']?)\\s*:\\s*(["'])([\\s\\S]*?)\\1(?:\\s*[,}]|$)`, 'i'))
    return match?.[2] ?? ''
  }
  const focus = stringField('focus')
  const reason = stringField('reason')
  if (actionable && !focus.trim()) {
    return { actionable: false, focus: '', reason: 'malformed positive verdict without focus' }
  }
  return { actionable, focus, reason }
}

/** Cerebellum classifier: given the agenda + persona, decide if a
 *  wake is justified. Strict JSON. Falls back to "actionable=false"
 *  on any error so a classifier outage doesn't burn brain calls on
 *  every heartbeat. */
export async function classifyAgendaActionable(args: {
  persona: { name: string; role: string; style: string; model: string | null }
  companyId: string
  agenda: AgentAgenda
  /** Optional agent id — when provided, the ledger row is scoped to this
   *  agent so the per-agent spend rollup ("whose heartbeats burn the most")
   *  is queryable. Cloud callers (idle.ts) pass `personaId`; the BYOA
   *  endpoint passes `c.sub`. Older callers can omit it. */
  agentId?: string
}): Promise<AgendaVerdict> {
  const { persona, companyId, agenda } = args
  if (agenda.cards.length === 0 && agenda.events.length === 0 && agenda.stalls.length === 0) {
    return { actionable: false, focus: '', reason: 'empty agenda' }
  }
  const rendered = renderAgendaForClassifier(agenda)
  const styleHint = (persona.style ?? '').slice(0, 400)
  const instructions = `You are Cumora's heartbeat agenda triage. Given an agent's currently-assigned Kanban cards and their currently-due calendar events, decide whether the agent should wake up RIGHT NOW to act on something, or stay quiet.

Decide "actionable: true" only when at least one item is concrete, fresh, AND clearly belongs to this agent's role. Reject:
- vague brainstorming cards with no owner action
- cards already in a done/archive-style column
- events that are personal markers (no agent_prompt)
- duplicates of work the agent has obviously already started

ORDERING: list order is for prompt-cache stability, not priority. Judge urgency from each card's updated timestamp, each event's start time, and each stalled conversation's current silence duration and message content.

STALLED CONVERSATIONS: for each, READ the recent messages shown and judge whether it is genuinely WAITING or already CONCLUDED. actionable=true ONLY when the recent messages show a CONCRETE unanswered ask directed at someone, or an explicitly in-progress step plainly waiting on a next move. It is NOT actionable (false) when the thread has CONCLUDED or socially CLOSED — participants exchanging wrap-up / closing / acknowledgement remarks, a conclusion or result already reached, nothing pending and no one waiting on a specific next step — no matter how "quiet" it now is. A merely quiet conversation is NOT a stall; "someone spoke last and I didn't reply" is NOT by itself a reason (most messages need no reply). Resurrecting a finished conversation with a late reply is a failure — when in doubt that it's truly still waiting, choose false.

Reply ONLY as strict JSON: {"actionable": boolean, "focus": "one-line focus for the agent if actionable, else empty", "reason": "short factual reason"}.`
  const input = `Agent: ${persona.name}${persona.role ? `, ${persona.role}` : ''}
Persona / style:
${styleHint || '(none)'}

Current agenda for this agent:
${rendered}

Reply as strict JSON.`
  try {
    const client = await getTrackedLlmClient({
      purpose: 'agenda',
      companyId,
      agentId: args.agentId ?? null,
      extras: {
        cards: agenda.cards.length, events: agenda.events.length, stalls: agenda.stalls.length,
        persona: persona.name,
      },
    })
    const r = await client.responses.create({
      model: env.OPENAI_MODEL_SUPPORT,
      instructions,
      input,
      text: { format: { type: 'json_object' } },
      // DeepSeek V4 Flash regularly spends the first ~300 tokens on hidden
      // reasoning. A 300-token cap then truncates the JSON to one character,
      // which made every minute-level BYOA agenda check fail closed. Leave
      // enough room for reasoning plus the small structured verdict.
      max_output_tokens: 2000,
      reasoning: { effort: 'minimal' },
    })
    const parsed = parseAgendaVerdict(r.output_text ?? '')
    if (!parsed) throw new Error('agenda classifier returned no recoverable verdict')
    // Coerce to a real boolean *strictly*. `Boolean("no")` is `true`
    // because non-empty strings are truthy — so if the model replies
    // {"actionable": "no"} (treating it as natural language) we'd
    // wrongly wake the brain. Accept true/"true"/1 as actionable; treat
    // everything else (including "no", "false", undefined, 0) as not
    // actionable. Same for focus / reason — clamp via String + slice
    // even if the model returns a number or an array.
    const a = parsed.actionable
    const actionable = a === true || a === 'true' || a === 1
    return {
      actionable,
      focus: String(parsed.focus ?? '').slice(0, 240),
      reason: String(parsed.reason ?? '').slice(0, 240),
    }
  } catch (e) {
    console.warn('[agenda] classifier failed', e instanceof Error ? e.message : e)
    // ─── deterministic fallback ─────────────────────────────────────
    // When the cerebellum classifier is unavailable (sub2api 503 / model
    // outage / network), default fail-closed BUT carve out a narrow,
    // conservative case so the stall safety net isn't 100% broken during
    // an outage: a SINGLE recent stall where SOMEONE ELSE spoke last and
    // this agent owes a reply. The rationale:
    //   - we don't try to judge "concluded vs in-motion" without the LLM
    //     (that's exactly what the cerebellum is for); we just surface
    //     the simplest "you have an unread, nobody else has it" case.
    //   - bounded: ONE stall only (multi-stall ambiguity → fail-closed),
    //     SOMEONE-ELSE-spoke-last only (not "I spoke, nudge them" — that
    //     direction needs more judgment), minutesSilent ≤ STALL_FALLBACK_MAX
    //     (don't resurrect ancient threads), no card/event noise (those
    //     genuinely need LLM judgment on priority).
    //   - cost bounded: the per-conversation NX nudge claim (claimStallNudge)
    //     still applies downstream — at most ONE agent ever wakes the
    //     big brain for a given stall, even if all members' fallbacks
    //     fire simultaneously.
    //   - aligned with [[keep-hard-safety-backstops]]: a deterministic
    //     floor under the AI layer for the narrow case where the AI
    //     judgment is OBVIOUSLY consistent (unread message I owe a reply
    //     to, recent, alone on the agenda).
    const STALL_FALLBACK_MAX_MIN = 30
    const recentAwaitingMe = agenda.stalls.filter(
      (s) => !s.lastAuthorIsSelf && s.minutesSilent <= STALL_FALLBACK_MAX_MIN,
    )
    if (
      agenda.cards.length === 0 &&
      agenda.events.length === 0 &&
      recentAwaitingMe.length === 1
    ) {
      const s = recentAwaitingMe[0]
      return {
        actionable: true,
        focus: `Reply to ${s.lastAuthorName} in ${s.title ?? s.conversationId} — they spoke last (${s.minutesSilent}m ago) and you haven't responded.`,
        reason: `${AGENDA_CLASSIFIER_ERROR} (deterministic fallback: single recent awaiting-you stall)`,
      }
    }
    return { actionable: false, focus: '', reason: AGENDA_CLASSIFIER_ERROR }
  }
}

/** Render the agenda as the `backgroundBrief.body` we hand to the
 *  brain's turn. Includes enough specificity (ids, titles, slot
 *  times, agent_prompts) that the agent can act without re-querying,
 *  but stays terse — the agent will pull full card / event detail
 *  via the normal CLI tools if it needs them.
 *
 *  Note: the brain's default `background_scan` framing in turn.ts
 *  says "default to doing nothing," which is the right stance for
 *  generic activity scans. For agenda wakes that doctrine is too
 *  cautious — the cerebellum has already decided this is worth a
 *  brain call — so we open the body with an explicit "the system
 *  already triaged this; pick the most timely item and progress it"
 *  override. */
export function renderAgendaBrief(agenda: AgentAgenda, focus: string): string {
  const lines: string[] = [
    `This wake comes from your own agenda — Kanban cards assigned to you and Calendar slots that are due now. The system has already triaged that there is real work to progress here, so act: pick the most timely item, move it forward (write the card comment, ship the deliverable, send the DM, draft the doc), and call set_turn_status when done. Override the generic "default to doing nothing" stance for this wake.`,
    '',
  ]
  if (focus) {
    lines.push(`Focus from agenda triage: ${focus}`)
    lines.push('')
  }
  if (agenda.cards.length > 0) {
    lines.push(`Your active Kanban cards (${agenda.cards.length}):`)
    for (const c of agenda.cards) {
      const tag = c.assignee_id ? 'assigned to you' : '@you mentioned'
      lines.push(`- ${c.id}  [${c.board_title} / ${c.column_title}]  ${c.title}  (${tag})`)
      if (c.description) lines.push(`    ${c.description.replace(/\n/g, ' ').slice(0, 200)}`)
    }
    lines.push('')
    lines.push(`Inspect with: bash("cumora kanban show <board_id>") or bash("cumora card show <card_id>").`)
  }
  if (agenda.events.length > 0) {
    if (lines.length > 0) lines.push('')
    lines.push(`Calendar events in your current slot (${agenda.events.length}):`)
    for (const e of agenda.events) {
      lines.push(`- ${e.id}  at ${e.start_at}  ${e.title}`)
      if (e.agent_prompt) lines.push(`    prompt: ${e.agent_prompt.slice(0, 240)}`)
    }
  }
  if (agenda.stalls.length > 0) {
    if (lines.length > 0) lines.push('')
    lines.push(`Conversations that have gone quiet — possible follow-ups (${agenda.stalls.length}). FIRST decide if each is genuinely WAITING or already DONE. If the recent messages show the activity CONCLUDED or the thread socially closed (wrap-ups, closing / acknowledgement remarks, a result already reached, nothing pending, no one waiting on a specific next step) → it is FINISHED: do NOT post. Reviving a finished thread with a late message is noise, not teamwork. Only act when someone is plainly waiting:`)
    for (const s of agenda.stalls) {
      lines.push(`- ${s.conversationId} [${s.kind}] "${s.title ?? ''}" — ${s.lastAuthorIsSelf ? 'YOU spoke last' : `${s.lastAuthorName} spoke last`}, ${s.minutesSilent}m ago. Recent:`)
      for (const ln of (s.recentTail || s.lastBody).split('\n')) lines.push(`    ${ln}`)
    }
    lines.push(`If (and ONLY if) one is genuinely unfinished and someone is waiting: read the room (\`cumora messages <id>\`), then send AT MOST ONE message — answer it if it needs your answer, or a single brief nudge. Never nag, never pile on, never revive a finished thread.`)
  }
  return lines.join('\n')
}

/** Exported for unit-test access — never call from production code. */
export const __test = {
  DONE_COLUMN_PATTERNS,
  renderAgendaForClassifier,
}