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

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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) return
const 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) return
const 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.ts
index 5f07bcb..e1b1d7d 100644
--- a/server/src/api/router.ts
+++ b/server/src/api/router.ts
@@ -4922,6 +4922,13 @@ async function wakeMentionedAgents(args: {
companyId: string
mentions: string[] | undefined
actorId: 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) return
const targets = args.mentions.filter((id) => id !== args.actorId)
@@ -4936,8 +4943,27 @@ async function wakeMentionedAgents(args: {
)
if (rows.length === 0) return
const { 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'),
+ }
+ : undefined
for (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 })