Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

CLI: a Lead tags a person in a post (--mention) (#1677)

0xken15374d397aaab1
diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.ts
index 29737ee81..21e9e1859 100644
--- a/cli/src/lib/swarmSkills.spec.ts
+++ b/cli/src/lib/swarmSkills.spec.ts
@@ -48,6 +48,8 @@ describe('built-in Swarm skills', () => {
// The Local models line (owner, 2026-10-23: the Lead considers Builders on local models; docs/plans/2026-10-23-swarm-local-models.md).
const local = '- Local models: when the Swarm serves one (a member\'s model, a shared API, a model shared with a member), the route may pick it for low-difficulty, well-specified work; it costs no subscription. Set "local":true in the route only when a person asks for a local model. When a person names a model, set "model" to their words ("deepseek 4.1 flash"): the route then offers that model alone. Start the pick with the gridModel and gridName the route gives, never a model or effort.\n'
const localDefault = '- Local models: the route may pick one for low-difficulty, well-specified work; set "local":true only when a person asks for one, set "model" to a model a person names, and start it with the route\'s gridModel and gridName.\n'
+ // The approved mention line (spec/2026-10-24-lead-mentions.md, call 5), the Lead's alone, in both modes.
+ const mention = '- When you need a person to act or decide, tag them in the message.\n'
const twoHours = '- A Builder or Reviewer that has been down for 2 hours (machine offline, session gone or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).\n'
it.each([
['lead', '5fc83d8c43b66b44cdab27b48235dbc86b7ab11a57153edc1ae7e92831642a8e'],
@@ -64,7 +66,8 @@ describe('built-in Swarm skills', () => {
expect(text.split(terminal)).toHaveLength(role === 'lead' ? 2 : 1)
expect(text.split(overlap)).toHaveLength(role === 'lead' ? 2 : 1)
expect(text.split(local)).toHaveLength(role === 'lead' ? 2 : 1)
- expect(sha(text.replace(twoHours, '').replace(terminal, '').replace(overlap, '').replace(local, ''))).toBe(sha256)
+ expect(text.split(mention)).toHaveLength(role === 'lead' ? 2 : 1)
+ expect(sha(text.replace(twoHours, '').replace(terminal, '').replace(overlap, '').replace(local, '').replace(mention, ''))).toBe(sha256)
}
})
it('adds the 2-hour line to section 7 right after the 6-hour rule', () => {
@@ -83,6 +86,12 @@ describe('built-in Swarm skills', () => {
const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')
expect(plain).toContain(`- The brief is all a Builder gets; never rely on chat history.\n${overlap}\n## 4. Keep work moving`)
})
+ it('adds the mention line right after each Lead skill\'s needs-a-person rule', () => {
+ const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session' }).file, 'utf8')
+ expect(orchestration).toContain(`- Needs-human: get the person's decision now.\n${mention}- Blocked: change something.`)
+ const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')
+ expect(plain).toContain(`- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.\n${mention}- Settle ambiguities`)
+ })
// The owner's approved Default texts (attached to the spec, 2026-10-23), byte for byte.
it.each([
['lead', 'a7b8aed240f38edda8a461d87ce83499696588b2da41ed261821985caa63e415'],
@@ -95,7 +104,8 @@ describe('built-in Swarm skills', () => {
expect(text.split(terminal)).toHaveLength(role === 'lead' ? 2 : 1)
expect(text.split(overlap)).toHaveLength(role === 'lead' ? 2 : 1)
expect(text.split(localDefault)).toHaveLength(role === 'lead' ? 2 : 1)
- expect(sha(text.replace(terminal, '').replace(overlap, '').replace(localDefault, ''))).toBe(sha256)
+ expect(text.split(mention)).toHaveLength(role === 'lead' ? 2 : 1)
+ expect(sha(text.replace(terminal, '').replace(overlap, '').replace(localDefault, '').replace(mention, ''))).toBe(sha256)
expect(prepared.instructions).toBe(`Use the swarm-${role} skill for this session: the team process; otherwise work your usual way. Before working, read ${JSON.stringify(prepared.file)} with your file or shell tool.`)
})
diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.ts
index c2858bc1a..78c25efc6 100644
--- a/cli/src/lib/swarmSkills.ts
+++ b/cli/src/lib/swarmSkills.ts
@@ -115,6 +115,7 @@ For large work, post the group plan and get the owner's ok before assigning; onc
## 7. Run the work
- When a restart interrupts active work, read the recovery notice and its last recorded checkpoint, then check the agent’s actual session and saved work. Ask it to continue from that checkpoint and report working; either you or the assigned agent can clear the recovery block. Never replay old input or commands: they may already have taken effect. A delayed recording gap after fresh progress is not a new interruption. Keep work already in review in review while you inspect the session. Ordinary typed input, an expired recording view, a missing recorded prompt, or an unclassified gap from an older recorder does not establish that work was interrupted.
- Needs-human: get the person's decision now.
+- When you need a person to act or decide, tag them in the message.
- Blocked: change something. Give more context, re-route to a stronger model, cut the work smaller, or fix the plan. Never resend the same thing to the same model.
- Rulings, not stalls: when a Builder hits an ambiguity you can settle, settle it and record "Ruling: what — why — cost if wrong". Ask the person only what changes what gets built.
- Each time you are woken, look at active work. Ask a worker with active work that has said nothing for 20 minutes; reassign work that has not moved for 6 hours; report on-screen trust, sign-in or permission questions in chat, naming the machine owner who can answer.
@@ -394,6 +395,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir
- A Builder or Reviewer that has been down for 2 hours (its machine offline, its session gone, or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).
- Work with no progress for 6 hours goes back to you: reassign it or cut it smaller.
- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.
+- When you need a person to act or decide, tag them in the message.
- Settle ambiguities you can and record "Ruling: what — why — cost if wrong".
- When a worker finishes: reuse, keep or stop. Prefer stop.
diff --git a/cli/src/superTabs/command.spec.ts b/cli/src/superTabs/command.spec.ts
index cf7353a62..aef76134d 100644
--- a/cli/src/superTabs/command.spec.ts
+++ b/cli/src/superTabs/command.spec.ts
@@ -212,3 +212,40 @@ it('refuses to remove a machine for an agent: a Swarm agent\'s pane, an outside
}
expect(request.mock.calls.some(c => c[0] === 'super_tabs')).toBe(false)
})
+// Lead mentions (spec 2026-10-24-lead-mentions): each --mention names a person by id or email; the service maps them.
+it('passes each --mention as written, and leaves a post without one unchanged', () => {
+ expect(parseSuperTabArgs([...prefix, 'post', 'lead', 'Please confirm', 'op-1', '--mention', '[email protected]', '--reply-to', 'm1', '--mention', 'person-2'], where).payload.command)
+ .toEqual({ type: 'message.send', conversationId: 'lead', text: 'Please confirm', replyTo: 'm1', recipientIds: [], mentions: ['[email protected]', 'person-2'] })
+ expect(parseSuperTabArgs([...prefix, 'post', 'lead', 'Ready', 'op-1'], where).payload.command).not.toHaveProperty('mentions')
+ for (const tail of [['--mention'], ['--mention', ''], ['--mention', ' ']]) {
+ expect(() => parseSuperTabArgs([...prefix, 'post', 'lead', 'Ready', 'op-1', ...tail], where)).toThrow('harness super-tab')
+ }
+})
+it('asks for help as the calling harness, so a Lead sees its own options, and still answers outside one', async () => {
+ const request = vi.fn(async (type: string) => type === 'agents_list'
+ ? { agents: [{ id: 'native', engine: 'claude', tmuxPane: '%42', status: 'active' }] } : { ok: true, help: {} })
+ const deps = { where: () => where, pane: '%42', open: async () => ({ request, close: vi.fn(), machineId: 'machine' }), print: vi.fn() }
+ expect(await superTabCommand(['--tab', 'tab', 'help'], deps)).toBe(0)
+ expect(request).toHaveBeenLastCalledWith('super_tabs', expect.objectContaining({ action: 'help', tabId: 'tab', harnessId: 'native' }), 30_000)
+ expect(await superTabCommand(['--tab', 'tab', 'help'], { ...deps, pane: '%43' })).toBe(0)
+ expect(request).toHaveBeenLastCalledWith('super_tabs', expect.not.objectContaining({ harnessId: expect.anything() }), 30_000)
+ request.mockClear()
+ expect(await superTabCommand(['help'], deps)).toBe(0)
+ expect(request).not.toHaveBeenCalledWith('agents_list')
+})
+it('keeps the mentioned people on a post that sends files', async () => {
+ const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs')
+ const { join } = await import('node:path')
+ const { tmpdir } = await import('node:os')
+ const dir = mkdtempSync(join(tmpdir(), 'super-tab-mention-'))
+ try {
+ writeFileSync(join(dir, 'shot.png'), Buffer.from([1, 2, 3]))
+ const request = vi.fn(async (_type: string, payload: Record<string, unknown> = {}): Promise<Record<string, unknown>> =>
+ payload.step === 'sent' ? { ok: true, value: { agentId: 'agent-1', attachmentIds: null } } : { ok: true, value: { revision: 9, result: { messageId: 'm' } } })
+ const fetch = vi.fn(async () => new Response(JSON.stringify({ success: true, data: { attachment: { id: 'f1' } } }), { status: 200 }))
+ const deps = { where: () => where, open: async () => ({ request, close: vi.fn(), machineId: 'machine' }), print: vi.fn(),
+ fetch: fetch as unknown as typeof globalThis.fetch }
+ expect(await superTabCommand([...prefix, 'post', 'lead', 'Please check', 'op', '--attach', join(dir, 'shot.png'), '--mention', 'person-ken'], deps)).toBe(0)
+ expect(request.mock.calls.at(-1)![1]).toMatchObject({ action: 'command', command: { type: 'message.send', attachmentIds: ['f1'], mentions: ['person-ken'] } })
+ } finally { rmSync(dir, { recursive: true, force: true }) }
+})
diff --git a/cli/src/superTabs/command.ts b/cli/src/superTabs/command.ts
index 412f5c029..9f8baa2ef 100644
--- a/cli/src/superTabs/command.ts
+++ b/cli/src/superTabs/command.ts
@@ -9,7 +9,7 @@ import { uploadAttachments } from './attach.js'
import { keyName } from './terminal.js'
import { randomUUID } from 'node:crypto'
-const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... | command OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | remove-machine MACHINE_ID [--yes] | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'
+const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | command OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | remove-machine MACHINE_ID [--yes] | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'
export function parseSuperTabArgs(argv: readonly string[], where: Where) {
const positional: string[] = []
let tabId = '', agentId = ''
@@ -32,17 +32,19 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {
}
else if (action === 'post' && identifier(first) && typeof second === 'string' && identifier(third)) {
let replyTo: string | null = null
- const attach: string[] = []
+ const attach: string[] = [], mentions: string[] = []
for (let i = 4; i < positional.length; i += 2) {
const [flag, value] = [positional[i], positional[i + 1]]
if (flag === '--reply-to' && identifier(value) && replyTo === null) replyTo = value
else if (flag === '--attach' && value && attach.length < 10) attach.push(resolve(value))
+ // A person's id or email, as written; the service maps it to the person (spec 2026-10-24-lead-mentions).
+ else if (flag === '--mention' && value?.trim()) mentions.push(value.trim())
else throw new Error(USAGE)
}
// A screenshot or a log may go without words.
if (!second.trim() && !attach.length) throw new Error(USAGE)
Object.assign(payload, { action: 'command', operationId: third, ...(attach.length ? { attach } : {}),
- command: { type: 'message.send', conversationId: first, text: second, replyTo, recipientIds: [] } })
+ command: { type: 'message.send', conversationId: first, text: second, replyTo, recipientIds: [], ...(mentions.length ? { mentions } : {}) } })
} else if (action === 'command' && identifier(first) && second && positional.length === 3) {
Object.assign(payload, { operationId: first, command: JSON.parse(second) })
} else if (action === 'start' && identifier(first) && second && positional.length === 3) {
@@ -100,12 +102,14 @@ export async function superTabCommand(argv: readonly string[], deps: {
throw new Error('Remove a machine from your own terminal or from Desktop, not from an agent.')
}
}
- if (!['help', 'backend'].includes(String(request.payload.action)) && !request.payload.agentId) {
+ // Help names the caller when it can, so a Lead also reads its own options; outside a harness it is the plain help.
+ const help = request.payload.action === 'help'
+ if (request.payload.action !== 'backend' && !request.payload.agentId && (!help || request.payload.tabId)) {
const listed = await daemon.request('agents_list')
const frames = Array.isArray(listed.agents) ? listed.agents as Frame[] : []
const caller = callerOf(frames, deps.pane ?? process.env.TMUX_PANE, request.where.machineId)
- if (!caller) throw new Error('Run this command inside the participating harness, or supply its --agent ID.')
- request.payload.harnessId = caller.agentId
+ if (caller) request.payload.harnessId = caller.agentId
+ else if (!help) throw new Error('Run this command inside the participating harness, or supply its --agent ID.')
}
const source = daemon
const scoped = (payload: Record<string, unknown>) => source.request('super_tabs', {
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 1b3fc5ba2..edf86afb2 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -660,3 +660,70 @@ describe('a Lead\'s terminal result', () => {
expect(await t.ask({ action: 'terminalResult', tabId: 'tab', agentId: t.agentId, terminalRequestId: '../x' }, owner)).toEqual({ error: 'INVALID_REQUEST' })
})
})
+
+// Lead mentions (spec 2026-10-24-lead-mentions): a post names people by id or email; the backend gets their person ids,
+// and only a Lead's help offers it.
+describe('mentions on a post', () => {
+ const people = [{ id: 'person-ken', email: '[email protected]', role: 'owner' }, { id: 'person-dee', email: '[email protected]', role: 'collaborator' }]
+ const swarm = (t: ReturnType<typeof setup>, leadId: string | null) => {
+ const state = { agents: [t.agent], people, projects: [{ id: 'pilot', name: 'Pilot', leadConversationId: 'pilot' }],
+ conversations: [{ id: 'pilot', leadId, agentIds: [t.agentId] }, { id: 'work', projectId: 'pilot', leadId: t.agentId, agentIds: [t.agentId] }] }
+ t.call.mockImplementation(async () => ({ status: 200, body: { success: true, data: { revision: 7, state } } }))
+ }
+ const post = (t: ReturnType<typeof setup>, mentions: unknown) => t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'op',
+ command: { type: 'message.send', conversationId: 'pilot', text: 'Please confirm', replyTo: null, recipientIds: [], mentions } }, owner)
+ const posted = (t: ReturnType<typeof setup>) => t.call.mock.calls.filter(([method]) => method === 'POST')
+
+ it('sends the person ids of people named by id or by email, each once', async () => {
+ const t = setup()
+ swarm(t, t.agentId)
+ expect(await post(t, ['[email protected]', 'person-dee', '[email protected]'])).toMatchObject({ ok: true, operationId: 'op' })
+ expect(posted(t)).toEqual([['POST', '/api/super-tabs/tab/commands', { operationId: 'op', asAgentId: t.agentId,
+ command: { type: 'message.send', conversationId: 'pilot', text: 'Please confirm', replyTo: null, recipientIds: [], mentions: ['person-ken', 'person-dee'] } }]])
+ })
+
+ it('refuses a person who is not in the Swarm before anything is sent', async () => {
+ const t = setup()
+ swarm(t, t.agentId)
+ expect(await post(t, ['[email protected]', '[email protected]'])).toEqual({ error: 'MENTION_UNKNOWN',
+ detail: '[email protected] is not a person in this Swarm. Tag a person by the id or email shown in status.', status: 400 })
+ expect(await post(t, [42])).toMatchObject({ error: 'MENTION_UNKNOWN' })
+ expect(posted(t)).toEqual([])
+ })
+
+ it('explains a server from before mentions', async () => {
+ const t = setup()
+ swarm(t, t.agentId)
+ const read = t.call.getMockImplementation()!
+ t.call.mockImplementation(async (...args) => args[0] === 'POST'
+ ? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message: 'command: Unrecognized key: "mentions"' } } } as never : read(...args))
+ expect(await post(t, ['person-ken'])).toEqual({ error: 'MENTIONS_UNSUPPORTED', detail: 'This Swarm\'s server does not support tagging people yet.' })
+ })
+
+ const help = async (t: ReturnType<typeof setup>, payload: Record<string, unknown>) => object(object(await t.ask({ action: 'help', ...payload }, owner)).help)
+ const mention = '[--mention PERSON]...'
+ it('offers --mention in help to a project\'s Lead only', async () => {
+ const t = setup()
+ swarm(t, t.agentId)
+ const lead = await help(t, { tabId: 'tab', agentId: t.agentId })
+ expect(lead.post).toContain(`post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... ${mention}:`)
+ expect(lead.post).toContain('--mention tags a person, by the id or email shown in status (up to 5), when you need them to act or decide; it shows in their notifications.')
+ expect(await help(t, { tabId: 'tab', harnessId: 'native' })).toEqual(lead)
+ // A former Lead still named on an older work group is not one, as in status.
+ swarm(t, 'new-lead')
+ expect(String((await help(t, { tabId: 'tab', agentId: t.agentId })).post)).not.toContain('--mention')
+ })
+
+ it('answers help without --mention outside a tab, or when the caller cannot be read', async () => {
+ const t = setup()
+ swarm(t, t.agentId)
+ const plain = await help(t, {})
+ expect(String(plain.post)).not.toContain('--mention')
+ expect(plain.leadOptions).toBe('Leads: run help with --tab ID for options only a Lead has.')
+ expect(String((await help(t, { tabId: 'tab' })).post)).not.toContain('--mention')
+ t.call.mockRejectedValue(new Error('Offline'))
+ expect(String((await help(t, { tabId: 'tab', agentId: t.agentId })).post)).not.toContain('--mention')
+ t.call.mockResolvedValue({ status: 200, body: { success: true, data: { state: { agents: [] } } } })
+ expect(String((await help(t, { tabId: 'tab', agentId: t.agentId })).post)).not.toContain('--mention')
+ })
+})
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 7c5f9f63f..25cd04e11 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -11,12 +11,15 @@ import { ContributionPreparations, prepareContribution } from './contribution.js
import { messageIdOf } from './attach.js'
import { cardId, SwarmCards } from './cards.js'
+const POST_HELP = 'reply in that conversation. Use a unique ID per message and reuse it after an interrupted request. Answer a message once, with --reply-to its ID. --attach sends a file (a screenshot, a log; up to 10 files of 10 MB each), and TEXT may then be empty.'
const HELP = {
status: 'Read the shared tab roster and work. Its rules are the project owners\' routing rules, each in the owner\'s own words; each binds only the agents of its projectId. A Lead\'s status also lists otherProjectsWork: the active work of the Swarm\'s other projects (group, project, title, owned code, status, Engineer, PR), read only. A project on Custom skills lists its roles (id, name, kind) in status.',
leads: 'The Leads conversation (leadsConversationId in a Lead\'s status) is one conversation for the whole Swarm, outside every project. Only Leads and people post there, and only Leads among agents receive it. Before assigning, look at otherProjectsWork; if your task touches the same code, say so there and agree an order first, then tell your own project. The Swarm posts there by itself when two projects\' active tasks own the same code.',
+ // Help without --tab cannot tell who asks, so it does not list a Lead's own options; this tells a Lead where they are.
+ leadOptions: 'Leads: run help with --tab ID for options only a Lead has.',
messages: 'messages GROUP: read recent messages in a conversation.',
message: 'message GROUP MESSAGE_ID: read one exact message, including an earlier question or result referenced by a reply.',
- post: 'post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]...: reply in that conversation. Use a unique ID per message and reuse it after an interrupted request. Answer a message once, with --reply-to its ID. --attach sends a file (a screenshot, a log; up to 10 files of 10 MB each), and TEXT may then be empty.',
+ post: `post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]...: ${POST_HELP}`,
start: 'start OPERATION_ID JSON: create one agent in a conversation on a machine in this Swarm\'s Machines list; to use another machine, a person adds it to the Swarm first. Repeat exactly after an interruption; it follows the same native creation receipt. It does not assign work. With worktree true, the agent starts from the repository\'s default branch, fetched first, unless you set branchRef (refs/heads/BRANCH, or refs/remotes/origin/BRANCH to fetch it first) to start from another branch, such as the one this work builds on. Set role "reviewer" to start a Reviewer; leave role out for a Builder. The role is kept for the session. On Custom skills, add "roleId" to the start request to start the agent in that role of its kind (a builder or reviewer role from status); without it the agent takes the first role of its kind. A Reviewer runs on claude or codex and is assigned only review groups (conversation.create with reviewOf naming the group it reviews); a review group is assigned only to a Reviewer. Add the Reviewer to the reviewed group with conversation.agent so it is told when that work is ready for review and can pass its independent check. Start one with a routeDecisionId like any agent.',
release: 'When a Builder finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. Reuse assigns new work; agent.release records keep or requests stop. Wait for the execution host to confirm a stop. A person can withdraw a stuck stop; the session cannot receive new work in that Swarm. Its native capacity stays reserved until its host confirms stopping. Other Swarms wait up to two minutes for an in-flight close, then may reuse it.',
resume: 'resume START_ID: finish a pending start without creating another agent.',
@@ -55,15 +58,21 @@ const HELP = {
}
const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []
+/** Only a project's Lead may tag people (spec 2026-10-24-lead-mentions), so only a Lead's help offers it. */
+const LEAD_HELP = { ...HELP, post: `post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]...: ${POST_HELP} --mention tags a person, by the id or email shown in status (up to 5), when you need them to act or decide; it shows in their notifications.` }
const OTHER_WORK_FIELDS = ['conversationId', 'projectName', 'title', 'owns', 'status', 'agentName', 'pr'] as const
+/** A project's Lead is its Lead conversation's, as the backend reads it; a Swarm from before projects has one, 'lead'. */
+function isLead(state: Record<string, unknown>, agentId: string): boolean {
+ const leads = Array.isArray(state.projects) ? list(state.projects).map(p => p.leadConversationId) : ['lead']
+ return list(state.conversations).some(c => leads.includes(c.id) && c.leadId === agentId)
+}
+
/** Leads see each other's work and talk (spec 2026-10-23): a Lead reads other projects' active work in the backend's
* fields alone; any other agent reads neither it nor the Leads conversation, even from a server that sent it. */
function statusView(answer: Record<string, unknown>, agentId: string): Record<string, unknown> {
const { otherProjectsWork, leadsConversationId, ...state } = object(answer.state)
- // A project's Lead is its Lead conversation's, as the backend reads it; a Swarm from before projects has one, 'lead'.
- const leads = Array.isArray(state.projects) ? list(state.projects).map(p => p.leadConversationId) : ['lead']
- if (list(state.conversations).some(c => leads.includes(c.id) && c.leadId === agentId)) {
+ if (isLead(state, agentId)) {
return { ...answer, state: { ...state, ...(leadsConversationId !== undefined ? { leadsConversationId } : {}),
...(Array.isArray(otherProjectsWork) ? { otherProjectsWork: list(otherProjectsWork).map(work =>
Object.fromEntries(OTHER_WORK_FIELDS.filter(key => key in work).map(key => [key, work[key]]))) } : {}) } }
@@ -71,6 +80,19 @@ function statusView(answer: Record<string, unknown>, agentId: string): Record<st
return { ...answer, state: { ...state, conversations: list(state.conversations).filter(c => c.kind !== 'leads' && c.id !== leadsConversationId) } }
}
+/** A post's mentions name people by id or email; the backend takes person ids. A name that is nobody in the Swarm is refused
+ * here, before anything is sent. Whether this agent may tag them in this conversation is the backend's to judge. */
+function mentionCommand(command: Record<string, unknown>, state: Record<string, unknown>): Record<string, unknown> {
+ if (command.type !== 'message.send' || !Array.isArray(command.mentions)) return command
+ const people = list(state.people)
+ const ids = command.mentions.map(name => {
+ const person = people.find(p => p.id === name || typeof name === 'string' && typeof p.email === 'string' && p.email.toLowerCase() === name.toLowerCase())
+ if (!person) throw new SuperTabHostError('MENTION_UNKNOWN', `${String(name)} is not a person in this Swarm. Tag a person by the id or email shown in status.`, 400)
+ return person.id
+ })
+ return { ...command, mentions: [...new Set(ids)] }
+}
+
function taskCommand(command: Record<string, unknown>): Record<string, unknown> {
if (command.type !== 'conversation.create' && command.type !== 'work.define') return command
const task = object(command.task), missing: string[] = []
@@ -201,9 +223,9 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
const value = await backend(core, method as string, path, payload.body)
return { ok: true, value }
}
- if (payload.action === 'help') return { ok: true, help: HELP }
let agentId = identifier(payload.agentId) ? payload.agentId
: identifier(payload.harnessId) ? createHash('sha256').update(JSON.stringify([core.daemon.machineId(), payload.harnessId])).digest('hex').slice(0, 24) : null
+ if (payload.action === 'help' && (!identifier(payload.tabId) || !agentId)) return { ok: true, help: HELP }
if (!identifier(payload.tabId) || !agentId) return { error: 'INVALID_REQUEST' }
if (!identifier(payload.agentId) && identifier(payload.harnessId)) {
const rows = await backend(core, 'GET', `/api/super-tabs/hosts/${core.daemon.machineId()}`)
@@ -218,8 +240,9 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
const agent = Array.isArray(state.agents) ? state.agents.map(object).find(a => a.id === agentId) : undefined
if (!agent || agent.machineId !== core.daemon.machineId() || typeof agent.harnessId !== 'string'
|| identifier(payload.harnessId) && agent.harnessId !== payload.harnessId || !core.agents.byAgent(agent.harnessId)) {
- return { error: 'AGENT_UNAVAILABLE', detail: 'This agent is not a running contribution on this machine.' }
+ return payload.action === 'help' ? { ok: true, help: HELP } : { error: 'AGENT_UNAVAILABLE', detail: 'This agent is not a running contribution on this machine.' }
}
+ if (payload.action === 'help') return { ok: true, help: isLead(state, agentId) ? LEAD_HELP : HELP }
wake()
if (payload.action === 'startStatus' && identifier(payload.startId)) {
return { ok: true, value: await backend(core, 'GET', `${path}/starts/${payload.startId}?${identity}`) }
@@ -283,7 +306,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
} catch { return { ok: true, value: page } }
}
if (payload.action === 'command' && identifier(payload.operationId) && payload.command && typeof payload.command === 'object' && !Array.isArray(payload.command)) {
- const command = taskCommand(object(payload.command))
+ const command = mentionCommand(taskCommand(object(payload.command)), state)
const send = (command: Record<string, unknown>) => backend(core, 'POST', `${path}/commands`,
{ operationId: payload.operationId, command, asAgentId: agentId })
let value: unknown
@@ -295,6 +318,10 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
if (['rule.set', 'rule.remove'].includes(String(command.type)) && error instanceof SuperTabHostError && error.status === 400 && /discriminator/i.test(error.message)) {
return { error: 'RULES_UNSUPPORTED', detail: 'This Swarm\'s server does not support rules yet.' }
}
+ if (command.mentions && error instanceof SuperTabHostError && error.status === 400 && error.code === 'VALIDATION_ERROR'
+ && /Unrecognized (?:key: "mentions"|key\(s\) in object: 'mentions')/.test(error.message)) {
+ return { error: 'MENTIONS_UNSUPPORTED', detail: 'This Swarm\'s server does not support tagging people yet.' }
+ }
if (!['conversation.create', 'work.define'].includes(String(command.type)) || !command.task || !(error instanceof SuperTabHostError)) throw error
const oldSchema = error.status === 400 && error.code === 'VALIDATION_ERROR'
&& /^(?:command: )?Unrecognized (?:key: "task"|key\(s\) in object: 'task')$/.test(error.message)
@@ -316,6 +343,8 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
}
return { error: 'INVALID_REQUEST' }
} catch (error) {
+ // Help never fails for an unreadable caller: it is then the plain help.
+ if (payload.action === 'help') return { ok: true, help: HELP }
return error instanceof SuperTabHostError
? { error: error.code, detail: error.message, status: error.status }
: { error: 'SUPER_TAB_UNAVAILABLE', detail: error instanceof Error ? error.message : 'This Super Tab is unavailable.' }
diff --git a/desktop/lib/super_tabs/roles_editor.dart b/desktop/lib/super_tabs/roles_editor.dart
index e2491d375..cea6d0c5e 100644
--- a/desktop/lib/super_tabs/roles_editor.dart
+++ b/desktop/lib/super_tabs/roles_editor.dart
@@ -47,6 +47,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir
## 3. Route, start, assign
- Route each group; reuse an idle agent before starting one; start only on the Swarm's machines.
+- Local models: the route may pick one for low-difficulty, well-specified work; set "local":true only when a person asks for one, set "model" to a model a person names, and start it with the route's gridModel and gridName.
- The brief is all a Builder gets; never rely on chat history.
- Before assigning, look at other projects' active work; if your task touches the same code, say so in the Leads conversation and agree an order first.
@@ -57,6 +58,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir
- A Builder or Reviewer that has been down for 2 hours (its machine offline, its session gone, or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).
- Work with no progress for 6 hours goes back to you: reassign it or cut it smaller.
- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.
+- When you need a person to act or decide, tag them in the message.
- Settle ambiguities you can and record "Ruling: what — why — cost if wrong".
- When a worker finishes: reuse, keep or stop. Prefer stop.