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
fix(kanban): stop dropping the wake that assigning a card sends
Xialie Zhuangd88b9e0dd08e
diff --git a/server/src/__tests__/agents-wake-classify.test.ts b/server/src/__tests__/agents-wake-classify.test.tsnew file mode 100644index 0000000..3106393--- /dev/null+++ b/server/src/__tests__/agents-wake-classify.test.ts@@ -0,0 +1,68 @@+/**+ * Which wakes survive an EMPTY chat inbox.+ *+ * Most wakes exist to answer unread messages, so an empty inbox means there is+ * nothing to do. The exceptions carry their own brief. The board case is why+ * this is pinned: assigning or @-mentioning an agent on a card wakes it as+ * `manual`, which was not exempt — so `runAgentTurn` returned before the agent+ * ever looked at the card, and the board sat in Todo while the work was+ * reported complete in chat (#69).+ *+ * Pure like turn-compaction's tests — no DB, no runtime client.+ *+ * Run: node --import tsx --test server/src/__tests__/agents-wake-classify.test.ts+ */+import { test } from 'node:test'+import assert from 'node:assert/strict'++import { classifyWake } from '../agents/turn-wake.js'++const brief = { source: 'kanban', title: 'A board card was assigned to you', body: 'card id: card-1' }++test('an ordinary message wake with an empty inbox does not run', () => {+ assert.equal(classifyWake({ trigger: 'message.new' }, 0).survivesEmptyInbox, false)+})++test('a board wake carrying a card brief runs on an empty inbox', () => {+ const w = classifyWake({ trigger: 'manual', backgroundBrief: brief }, 0)+ assert.equal(w.briefedManual, true)+ assert.equal(w.survivesEmptyInbox, true)+})++test('a bare manual wake with no brief still does not run', () => {+ // The exemption is earned by carrying something to act on, not by the+ // trigger name — otherwise any manual poke would burn a big-brain turn on+ // nothing.+ const w = classifyWake({ trigger: 'manual' }, 0)+ assert.equal(w.briefedManual, false)+ assert.equal(w.survivesEmptyInbox, false)+})++test('a briefed manual wake is not misfiled as a background scan', () => {+ // It must stay `manual`: the synthetic-wake rate limiter and the cerebellum+ // gate both key off these flags, and a human assigning a card should pass+ // through both.+ const w = classifyWake({ trigger: 'manual', backgroundBrief: brief }, 0)+ assert.equal(w.backgroundScan, false)+ assert.equal(w.idle, false)+ assert.equal(w.pollUpdate, false)+})++test('idle only counts as an idle wake when the inbox is actually empty', () => {+ assert.equal(classifyWake({ trigger: 'idle' }, 0).idle, true)+ assert.equal(classifyWake({ trigger: 'idle' }, 3).idle, false)+})++test('background scan and poll wakes still need their briefs', () => {+ assert.equal(classifyWake({ trigger: 'background_scan' }, 0).survivesEmptyInbox, false)+ assert.equal(classifyWake({ trigger: 'poll.updated' }, 0).survivesEmptyInbox, false)+ assert.equal(+ classifyWake({ trigger: 'background_scan', backgroundBrief: brief }, 0).survivesEmptyInbox,+ true,+ )+})++test('a non-empty inbox runs regardless of how it was woken', () => {+ // The guard only fires on an empty inbox; classification must not change that.+ assert.equal(classifyWake({ trigger: 'message.new' }, 5).survivesEmptyInbox, false)+})diff --git a/server/src/agents/turn-wake.ts b/server/src/agents/turn-wake.tsnew file mode 100644index 0000000..cbe9eb3--- /dev/null+++ b/server/src/agents/turn-wake.ts@@ -0,0 +1,42 @@+/**+ * Wake classification for `runAgentTurn`.+ *+ * Lives in its own module for the same reason `turn-compaction.ts` does: it is+ * pure decision logic, and a unit test should be able to reach it without+ * dragging turn.ts's runtime client / DB graph into the process.+ */+import type { AgentTurnOptions } from './turn.js'++/** Classify a wake, and decide whether it still deserves a turn when the chat+ * inbox is EMPTY.+ *+ * Most wakes exist to answer unread messages, so an empty inbox means there is+ * nothing to do. The exceptions are wakes that arrive carrying their own brief+ * — an idle heartbeat, a background scan, a poll update, or a person acting on+ * a board card. Those have something concrete to act on without a message.+ *+ * The board case is the one this was extracted for: assigning or @-mentioning+ * an agent on a card wakes it as `manual`, which was NOT exempt, so the turn+ * returned before the agent ever looked at the card. The board then sat in Todo+ * while the work was reported complete in chat.+ *+ * Exported for tests — pure. */+export function classifyWake(options: AgentTurnOptions, inboxCount: number): {+ idle: boolean+ backgroundScan: boolean+ pollUpdate: boolean+ briefedManual: boolean+ survivesEmptyInbox: boolean+} {+ const idle = options.trigger === 'idle' && inboxCount === 0+ const backgroundScan = options.trigger === 'background_scan' && Boolean(options.backgroundBrief)+ const pollUpdate = options.trigger === 'poll.updated' && Boolean(options.pollBrief)+ // Stays `manual` rather than borrowing `background_scan`: a person moving a+ // card is a real user action, and the synthetic-wake rate limiter and the+ // cerebellum gate both deliberately leave those alone.+ const briefedManual = options.trigger === 'manual' && Boolean(options.backgroundBrief)+ return {+ idle, backgroundScan, pollUpdate, briefedManual,+ survivesEmptyInbox: idle || backgroundScan || pollUpdate || briefedManual,+ }+}diff --git a/server/src/agents/turn.ts b/server/src/agents/turn.tsindex 31541b5..2d12c20 100644--- a/server/src/agents/turn.ts+++ b/server/src/agents/turn.ts@@ -114,6 +114,8 @@ interface InboxRow {quoted: QuotedSummary | null}+import { classifyWake } from './turn-wake.js'+export interface AgentTurnOptions {/** Why this turn was started. Message-driven turns remain the default. */trigger?: 'message.new' | 'idle' | 'manual' | 'background_scan' | 'poll.updated'@@ -1553,10 +1555,12 @@ export async function runAgentTurn(agentId: string, options: AgentTurnOptions =if (!persona) returnconst inbox = await loadInbox(agentId)- const isIdleWake = options.trigger === 'idle' && inbox.length === 0- const isBackgroundScanWake = options.trigger === 'background_scan' && Boolean(options.backgroundBrief)- const isPollUpdateWake = options.trigger === 'poll.updated' && Boolean(options.pollBrief)- if (inbox.length === 0 && !isIdleWake && !isBackgroundScanWake && !isPollUpdateWake) return+ const wake = classifyWake(options, inbox.length)+ const isIdleWake = wake.idle+ const isBackgroundScanWake = wake.backgroundScan+ const isPollUpdateWake = wake.pollUpdate+ const isBriefedManualWake = wake.briefedManual+ if (inbox.length === 0 && !wake.survivesEmptyInbox) returnconst fingerprint = isIdleWake? `idle:${new Date().toISOString()}`@@ -1564,6 +1568,8 @@ export async function runAgentTurn(agentId: string, options: AgentTurnOptions =? `background_scan:${options.backgroundBrief?.source ?? 'scanner'}:${new Date().toISOString()}`: isPollUpdateWake? `poll:${options.pollBrief?.messageId}:${options.pollBrief?.phase}:${options.pollBrief?.totalVotes ?? 0}:${new Date().toISOString()}`+ : isBriefedManualWake+ ? `manual:${options.backgroundBrief?.source ?? 'brief'}:${new Date().toISOString()}`: inbox.map((m) => m.id).join(',')const convoIds = [...new Set([...inbox.map((m) => m.conversation_id),@@ -1595,7 +1601,7 @@ export async function runAgentTurn(agentId: string, options: AgentTurnOptions =source: options.trigger ?? 'scheduler',conversationIds: convoIds,idle: isIdleWake ? { reason: options.idleReason ?? 'idle heartbeat' } : undefined,- backgroundScan: isBackgroundScanWake+ backgroundScan: (isBackgroundScanWake || isBriefedManualWake)? {source: options.backgroundBrief?.source ?? 'scanner',title: options.backgroundBrief?.title ?? 'Background scan',@@ -1927,7 +1933,7 @@ export async function runAgentTurn(agentId: string, options: AgentTurnOptions =// agent up. For message wakes, use newest unread bodies. For idle// synthetic wakes, retrieve broad self/team memories without inventing// a fake message.- const memoryQuery = (isBackgroundScanWake+ const memoryQuery = ((isBackgroundScanWake || isBriefedManualWake)? [options.backgroundBrief?.title ?? 'background scan',options.backgroundBrief?.body ?? '',@@ -2105,6 +2111,14 @@ export async function runAgentTurn(agentId: string, options: AgentTurnOptions =const renderedConversationContext = renderContext(context, inbox.length, convoIds.length, textExcerpts, agentId)const wakeContext = isPollUpdateWake && options.pollBrief? renderPollUpdateWakeContext(options.pollBrief, renderedConversationContext)+ : isBriefedManualWake+ ? `Someone just put this on you directly — it is a deliberate human action, not a scan or a heartbeat.++${options.backgroundBrief?.title ?? 'Assigned work'}++${options.backgroundBrief?.body ?? ''}++Your chat inbox is empty; this wake exists because of the action above, so act on THAT rather than looking for a message to answer. Handle the work, or say plainly why you are not the right owner. If you genuinely have nothing to do here, call set_turn_status({ status: "done", reason: "...", next_step: "" }) and explain — do not silently drop it.`: isBackgroundScanWake? `You just got an internal background scan brief. This is not a user chat message, and there is no obligation to interrupt anyone.diff --git a/server/src/api/router.ts b/server/src/api/router.tsindex 5f07bcb..e1b1d7d 100644--- a/server/src/api/router.ts+++ b/server/src/api/router.ts@@ -4922,6 +4922,13 @@ async function wakeMentionedAgents(args: {companyId: stringmentions: string[] | undefinedactorId: string+ /** What on the board caused this wake. Without it the agent is woken with an+ * empty chat inbox and `runAgentTurn` returns before it looks at anything —+ * which is why an assigned card could sit in Todo while the work itself was+ * reported done in chat. The brief is what gives the turn something to act+ * on, and it names the ids so the agent can drive the card with+ * `cumora card …` rather than guess. */+ card?: { boardId: string; cardId: string; columnId?: string | null; title?: string | null; what: string }}): Promise<void> {if (!args.mentions || args.mentions.length === 0) returnconst targets = args.mentions.filter((id) => id !== args.actorId)@@ -4936,8 +4943,27 @@ async function wakeMentionedAgents(args: {)if (rows.length === 0) returnconst { wakeAgent } = await import('../agents/scheduler.js')+ const brief = args.card+ ? {+ source: 'kanban',+ title: args.card.what,+ body: [+ args.card.title ? `Card: ${args.card.title}` : null,+ `card id: ${args.card.cardId}`,+ `board id: ${args.card.boardId}`,+ args.card.columnId ? `column id: ${args.card.columnId}` : null,+ '',+ 'Drive it with the board tools rather than only replying in chat:',+ ` cumora card claim ${args.card.cardId}`,+ ` cumora card comment ${args.card.cardId} "<progress / evidence>"`,+ ` cumora card move ${args.card.cardId} <column_id>`,+ '',+ 'If the work finishes here, leave the card in a state that says so — a board that still reads Todo while the work is done is worse than no board.',+ ].filter((l) => l !== null).join('\n'),+ }+ : undefinedfor (const r of rows) {- void wakeAgent(r.id, 'manual', null).catch((e) => {+ void wakeAgent(r.id, 'manual', null, null, brief ? { backgroundBrief: brief } : {}).catch((e) => {console.warn(`[boards] wake ${r.id} failed`, e)})}@@ -5264,11 +5290,17 @@ api.post('/boards/:id/cards', async (req, res) => {await publishBoardEvent({companyId, kind: 'card.created', boardId, cardId: id, columnId, mentions, actorId: me,})- void wakeMentionedAgents({ companyId, mentions, actorId: me })+ void wakeMentionedAgents({+ companyId, mentions, actorId: me,+ card: { boardId, cardId: id, columnId, title, what: 'You were mentioned on a new board card' },+ })// Assignment counts as a mention even without an @-token in prose:// when you `assignee_id = someone`, that someone should know about it.if (assigneeId && assigneeId !== me) {- void wakeMentionedAgents({ companyId, mentions: [assigneeId], actorId: me })+ void wakeMentionedAgents({+ companyId, mentions: [assigneeId], actorId: me,+ card: { boardId, cardId: id, columnId, title, what: 'A board card was assigned to you' },+ })}res.json({ id, position, mentions })})@@ -5342,12 +5374,18 @@ api.patch('/boards/:bid/cards/:cid', async (req, res) => {kind: columnChanged ? 'card.moved' : 'card.updated',boardId, cardId, mentions, actorId: me,})- void wakeMentionedAgents({ companyId, mentions, actorId: me })+ void wakeMentionedAgents({+ companyId, mentions, actorId: me,+ card: { boardId, cardId, what: 'You were mentioned on a board card' },+ })// A re-assignment also wakes the new assignee.if (typeof req.body?.assigneeId === 'string') {const newAssignee = String(req.body.assigneeId).trim()if (newAssignee && newAssignee !== me) {- void wakeMentionedAgents({ companyId, mentions: [newAssignee], actorId: me })+ void wakeMentionedAgents({+ companyId, mentions: [newAssignee], actorId: me,+ card: { boardId, cardId, what: 'A board card was assigned to you' },+ })}}res.json({ ok: true, mentions })