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
/**
* Cumora CLI — programmatic introspection of the entire app.
*
* The same surface is callable two ways:
* 1. By agents via the `cli` tool: `cli({command: "groups --as iris"})`
* 2. By humans via `npx tsx server/src/cli-bin.ts ...`
*
* Output is plain text (agent-friendly, like reading `man`). Pass `--json`
* for structured output if the agent wants to parse fields.
*/
import { pool } from '../db/pool.js'
import type { PoolClient } from 'pg'
import { storage, freshenMessageAttachments, type StoredAttachment } from '../storage.js'
import { normalizeAttachments } from '../../../shared/attachments.js'
import { env } from '../env.js'
import type { CliAttachmentRead, CliResult, CliSideEffect } from './cli-result.js'
import { fetchImageBytes } from './image-fetcher.js'
import { stripLoneSurrogates } from './text-safety.js'
import { dispatchMessagePush } from '../push.js'
import {
asMemorySource,
memoryVisibleInScope,
memoryWritePath,
parseMemoryPath,
} from './memory-scope.js'
import { memoryMetaForWrite, resolveMemoryWriteSource } from './memory-write.js'
import { wakeKanbanAgents } from './kanban-wake.js'
import { isBoardDueOn } from './board-due-date.js'
import { grantAttachment } from '../attachments/grants.js'
import {
enqueueBroadcast,
nudgeRealtimeOutbox,
withOutboxTransaction,
} from '../realtime-outbox.js'
import {
CH_BOARDS,
CH_CALENDAR_EVENTS,
CH_CONVO_UPDATED,
CH_DOCS,
CH_MESSAGE_NEW,
CH_STATUS,
} from '../redis.js'
// Every CLI result flows through ok()/err(), so scrubbing lone UTF-16 surrogates
// here means CLI output (read by agents as tool results) can never carry a split
// emoji into a model transcript — the single chokepoint that covers all the
// body.slice(0, N) truncations below. See text-safety.ts.
function ok(text: string, sideEffects?: CliSideEffect[], attachmentReads?: CliAttachmentRead[]): CliResult {
text = stripLoneSurrogates(text)
return {
ok: true,
text,
exitCode: 0,
...(sideEffects && sideEffects.length > 0 ? { sideEffects } : {}),
...(attachmentReads && attachmentReads.length > 0 ? { attachmentReads } : {}),
}
}
function err(text: string, code = 1): CliResult {
return { ok: false, text: stripLoneSurrogates(text), exitCode: code }
}
/** Look up an agent's tenant. Used by anything that writes per-agent
* data tied to a workspace (`agent_workspace`, etc.) — without this,
* rows land with NULL `company_id` and the Observability view (which
* filters by the user's active company) can't see them.
*
* Agent ids are globally unique (partial unique index on
* `participants(id) WHERE kind='agent'` + server-side slugify on
* /agents POST), so id-only lookup returns the single correct row. */
async function agentCompany(agentId: string): Promise<string | null> {
const { rows } = await pool.query<{ company_id: string | null }>(
`SELECT company_id FROM participants
WHERE id = $1 AND kind = 'agent' AND departed_at IS NULL
LIMIT 1`,
[agentId],
)
return rows[0]?.company_id ?? null
}
/** Keep an active participant's tenant assignment stable for a command whose
* work spans multiple SQL statements (or a provider network call). Membership
* mutations, offboarding, and tenant moves all take a conflicting participant
* row lock, so they serialize before or after this command instead of changing
* authorization midway through it. */
async function withActiveParticipantLock<T>(args: {
participantId: string
companyId: string
kind?: 'agent' | 'human'
run: (client: PoolClient) => Promise<T>
}): Promise<T | null> {
const client = await pool.connect()
try {
await client.query('BEGIN')
const params: unknown[] = [args.participantId, args.companyId]
const kindPredicate = args.kind ? `AND kind = $3` : `AND kind IN ('agent', 'human')`
if (args.kind) params.push(args.kind)
const active = await client.query(
`SELECT id FROM participants
WHERE id = $1 AND company_id = $2
${kindPredicate} AND departed_at IS NULL
FOR SHARE`,
params,
)
if (!active.rowCount) {
await client.query('ROLLBACK')
return null
}
const result = await args.run(client)
await client.query('COMMIT')
return result
} catch (error) {
await client.query('ROLLBACK').catch(() => {})
throw error
} finally {
client.release()
}
}
async function withConversationActorLock<T>(args: {
participantId: string
companyId: string
conversationId: string
kind?: 'agent' | 'human'
conversationKind?: string
run: (client: PoolClient) => Promise<T>
}): Promise<T | null> {
return withActiveParticipantLock({
participantId: args.participantId,
companyId: args.companyId,
kind: args.kind,
run: async (client) => {
const params: unknown[] = [args.conversationId, args.companyId]
let kindPredicate = ''
if (args.conversationKind) {
params.push(args.conversationKind)
kindPredicate = `AND c.kind = $3`
}
const locked = await client.query(
`SELECT c.id FROM conversations c
WHERE c.id = $1 AND c.company_id = $2
${kindPredicate}
FOR UPDATE`,
params,
)
if (!locked.rowCount) return null
const authorized = await client.query(
`SELECT 1 FROM conversation_members
WHERE conversation_id = $1
AND company_id = $2
AND participant_id = $3`,
[args.conversationId, args.companyId, args.participantId],
)
if (!authorized.rowCount) return null
return args.run(client)
},
})
}
/* ============== argv parsing ============== */
import { parseArgs, unescapeChat, joinBodyArgs, tokenize, type ParsedArgs } from './cli-parse.js'
import { claimTargetColumn, type ColumnKind } from './board-columns.js'
export { tokenize }
// resolveAs lives in ./cli-identity for test-isolation (zero-side-effect
// import). See the docstring there for the priority order — especially
// the "ambient runtime id beats any --as the model could smuggle" rule.
import { resolveAs } from './cli-identity.js'
/* ============== Worklog plumbing ==============
*
* Heavy agent-runtime actions (browser research, document creation, image
* generation) stake a tenant-scoped claim before doing the work so peer agents
* who would otherwise duplicate the call yield instead. The claim
* lives in Redis and auto-expires; releaseWork() in a finally block
* cleans up on success or known failure.
*
* Failure of the claim subsystem fails open — a Redis hiccup must not
* block real work. The worst case is two agents do the same thing
* once, which is what we have today.
*/
import { inprocClient as worklogClient } from './runtime/inproc-client.js'
import type { WorkTaskType, WorklogEntry } from './runtime/client.js'
import {
recordSeen, getSeen, recordHold, consumeHold, clearHold,
readTurnPost, recordTurnPost, MAX_POSTS_PER_TURN_PER_CONVERSATION,
} from './seen-boundary.js'
function tenantScopeKey(companyId: string): string {
return `tenant:${companyId}`
}
/** Build the descriptive "someone else is doing this" error string. */
function duplicateWorkErrorMessage(existing: WorklogEntry): string {
const ageSec = Math.max(1, Math.round((Date.now() - existing.startedAt) / 1000))
return (
`${existing.agentId} started ${existing.taskType} on "${existing.subject}" ${ageSec}s ago — ` +
`don't duplicate. Wait for them to finish (claims auto-expire after 5 min if they stall), ` +
`or react on the relevant message and step back. If your angle is genuinely different from theirs, ` +
`rephrase your subject distinctly enough that the system sees it as a separate request.`
)
}
/** Try to take a tenant-scoped worklog claim. Returns null if the
* claim was accepted (caller should proceed and release at the end);
* returns a CliResult error if a peer already holds it (caller
* should propagate the error verbatim). */
async function tryClaimTenantWork(
companyId: string,
agentId: string,
taskType: WorkTaskType,
subject: string,
): Promise<CliResult | null> {
const r = await worklogClient.claimWork({
scopeKey: tenantScopeKey(companyId),
agentId,
taskType,
subject,
})
if (r.accepted) return null
return err(duplicateWorkErrorMessage(r.existing))
}
async function releaseTenantWork(
companyId: string,
agentId: string,
taskType: WorkTaskType,
subject: string,
): Promise<void> {
await worklogClient.releaseWork({
scopeKey: tenantScopeKey(companyId),
agentId,
taskType,
subject,
})
}
/** Re-sign one row's attachment from its stored key. Matches the
* pattern in api/router.ts so a storage hiccup on one row never
* fails the whole list — falls back to the stored (possibly stale)
* URL with a warning. */
async function freshenRowAttachment(row: { id: string; attachment?: StoredAttachment | null; attachments?: readonly StoredAttachment[] | null }): Promise<void> {
const stored = row.attachments?.length ? row.attachments : row.attachment
if (!stored) return
try {
Object.assign(row, await freshenMessageAttachments(stored))
} catch (e) {
console.warn(`[cli] freshenMessageAttachments failed for message ${row.id}; falling back to stored URL`, e)
}
}
/** One-line, agent-readable summary of an attachment. */
function renderAttachments(value: unknown): string[] {
return normalizeAttachments(value).map((att) => {
const size = typeof att.size === 'number' ? ` ${att.size}B` : ''
return ` ↳ [${att.kind}] ${att.name}${size} → ${att.url ?? '(no download URL)'}`
})
}
function attachmentReadsFor(
rows: ReadonlyArray<{ id: string; attachment?: StoredAttachment | null; attachments?: readonly StoredAttachment[] | null }>,
): CliAttachmentRead[] {
return rows.flatMap((row) => {
const attachments = normalizeAttachments(row.attachments ?? row.attachment)
return attachments.length > 0 ? [{ messageId: row.id, attachments }] : []
})
}
/* ============== commands ============== */
async function cmdHelp(): Promise<CliResult> {
return ok(
`cumora — introspect the whole app + manage your private workspace, memory, tasks, log
USAGE:
cumora <subcommand> [args...] [flags...]
MAILBOX (this is how you receive + send messages):
inbox [<convo_id>] — list new messages directed at you, grouped by conversation
ack <convo_id> — mark that conversation read up to NOW (clear from inbox)
ack --all — ack every conversation currently in your inbox
mute <convo_id> [--for 1h|1d|1w] — stop delivery from a group (direct @mentions and quote-replies still arrive)
mute <convo_id> --until <iso> — stop delivery until a wall-clock time; omit duration to mute forever
mute list — show your active muted groups and expiry times
follow <convo_id> — resume normal delivery from a muted group
ship list — list feature contracts and evidence-square progress
ship show <feature_id> — inspect invariants, squares, releases, friction, regressions
ship create "<title>" --problem "..." --outcome "..." --contract "..." [--builders a,b]
ship square <feature_id> <square_id> <running|passed|failed|waived> [--evidence "..."] [--notes "..."]
ship friction <feature_id|none> "<title>" [--description "..."] [--severity low|medium|high|critical]
ship regression <feature_id> "<title>" [--command "..."] [--expected "..."]
reply <convo_id> "<body>" — post a message to that conversation as you
reply <convo_id> "<body>" --quote <msg_id>
— post as a quote-reply to <msg_id> (same convo); inbox + messages
render the quoted-original inline so the room knows the context
thread <convo_id> <root_msg_id> — list every direct reply to one message (the thread under <root_msg_id>)
topic <convo_id> — read the conversation's topic line
topic-set <convo_id> "<text>" — write/update the topic (any member can; empty body clears it)
rename <convo_id> "<title>" — rename a group (members only; groups only)
INTROSPECTION:
whoami [--as <id>]
participants [--kind agent|human]
conversations [--as <id>]
groups [--as <id>]
directs [--as <id>]
members <convo_id>
messages <convo_id> [--tail N] [--thread <root_msg_id>]
search <query> [--in <convo_id>] [--limit N]
convening <convo_id>
tools-log [--agent <id>] [--limit N]
participants-status
PRIVATE TO EACH AGENT (these write/read state owned by --as):
memory list [--as <id>] [--about <subject>] [--kind <kind>] [--limit N] [--in <convo>] [--all]
memory note <body> [--as <id>] [--about <subject>] [--kind <kind>] [--in <convo>]
memory pin <id>
memory delete <id>
log [--as <id>] [--limit N]
log note <body> [--as <id>]
workspace ls [--as <id>]
workspace read <path> [--as <id>]
workspace write <path> <body> [--as <id>]
workspace edit <path> <old> <new> [--all] # surgical replace; default fails if old not unique
workspace grep <pattern> [-i] # regex across all your files
workspace delete <path> [--as <id>]
ws ... # alias for workspace
tasks list [--as <id>] [--status open|doing|done]
tasks add <title> [--as <id>]
tasks set <task_id> <status> # status ∈ open|doing|done|dropped
CALENDAR (shared schedule + your own self-scheduling tool):
# This is also how you SCHEDULE YOURSELF. Set --assignee to your own id
# and the dispatcher will wake YOU at --at with --prompt as the brief.
# Add --every for recurring schedules. Use this whenever you'd otherwise
# tell a user "I'll do X later / tomorrow / every morning" — instead of
# promising to come back, schedule the wake so future-you actually does.
calendar list [--as <id>] [--all] [--status active|paused|done|cancelled]
# default scope = events assigned to OR created by --as
calendar create "<title>" --at <iso> [--assignee <id>] [--prompt "..."]
[--in <convo_id>] [--every daily|weekly|monthly|yearly]
[--interval N] [--byweekday 0,1,2,3,4]
[--until <iso>] [--count N]
[--kind personal|agent_task]
[--remind <minutes>] [--remind-channel toast|email|both]
[--private]
# --assignee <self_id> + --prompt "..." = give future-you
# a wake-up with that prompt as the brief
# --every daily|weekly|monthly|yearly = recurring schedule;
# pair with --interval / --byweekday / --until / --count
# --remind 10 fires a heads-up 10 min before each occurrence
# --private hides the row from everyone except its creator
# and assignee (company owner can still see private rows
# that involve an agent). Use it for personal reminders
# you don't want to clutter the shared calendar.
# when start_at fires, the prompt is posted into <convo_id>
# (or the assignee's DM with you) and the assignee is woken
calendar update <event_id> [--title "..."] [--at <iso>] [--status active|cancelled|done]
[--private | --public] # flip the privacy flag
calendar run-now <event_id> # dispatch an event immediately
calendar dispatches <event_id> # inspect dispatch history
calendar cancel <event_id> # stop firings without dropping history
calendar delete <event_id> # hard delete (also wipes dispatch history)
ACTIONS (each writes to the world, not just your private state):
dm <partner_id> <topic> <opening> open a private 1-on-1 chat with another agent
pull-group <title> --members a,b,c --reason "..." --say "..." create a new group + post first msg
invite <convo_id> <member_id> pull a teammate into a group you're in
leave <convo_id> leave a group (no-op for direct chats)
kick <convo_id> <member_id> remove a member from a group you're in
KANBAN (shared boards — the same ones humans see in the Boards view):
kanban ls list every kanban board in this workspace
kanban show <board_id> full snapshot: columns + cards
kanban create "<title>" [--description "..."] new board, seeded with Todo/Doing/Done columns
kanban rename <board_id> --title "..." rename / re-describe a board
[--description "..."]
kanban columns <board_id> list column ids — needed for \`card add --column\`
kanban add-column <board_id> "<title>" append a new column to a board
[--kind todo|doing|done]
kanban edit-column <board_id> <column_id> rename / reorder a column
[--title "..."] [--position N] [--kind todo|doing|done|clear]
kanban delete-column <board_id> <column_id> delete a column and its cards
kanban delete <board_id> drop the board (and its columns + cards)
kanban mentions [--peek] [--json] list NEW cards/comments where someone @ed YOU since
your last check. Run this on every wake when your
inbox is empty — you may have been pinged here.
Advances a read cursor unless --peek is passed.
card ls <board_id> [--due-before YYYY-MM-DD] list cards (date filter is exclusive)
[--overdue-as-of YYYY-MM-DD] overdue todo/doing work + passed-date cards in unclassified columns
(JSON due_status distinguishes them)
card show <card_id> full card detail + comments
card add <board_id> "<title>" --column <col_id> create a card
[--description "..."] [--assign <id>] [--due YYYY-MM-DD]
card due <card_id> <YYYY-MM-DD|clear> set or clear a date-only deadline
card move <card_id> --to <column_id> move a card between columns (the way "done" happens)
card claim <card_id> ATOMICALLY claim a card before working it (exclusive;
fails if someone else already holds it → move on)
card assign <card_id> <participant_id|null> (re)assign a card (agents and humans both work)
card rename <card_id> --title "..." edit a card's title
[--description "..."] and/or its description
card comment <card_id> "<body>" append a comment (Markdown OK, @ids parsed)
card delete-comment <card_id> <comment_id> delete your own comment
card delete <card_id> drop a card
@mention any participant id (\`@iris\`, \`@yetone\`) in a card title /
description / comment — the renderer will chip them and toast the
recipient(s) so a human or another agent gets pinged. Agents are
first-class assignees too — assign a card to @iris and she'll see it
via \`cumora card show\` exactly the way a human does in the UI.
CONTACTS (workspace + email — use BEFORE assuming you know a name):
contacts [<query>] [--as <id>] list everyone in this workspace (agents +
humans + external mail correspondents),
with each teammate's role/function.
With a query: substring-search name/id/email/role
(e.g. "designer"). No match → ASK the user for the
address; DO NOT silently skip the request.
EMAIL (real external mail — every agent has an address):
email whoami [--as <id>] your own email address
email contacts [<query>] [--as <id>] same as top-level "contacts" (email-namespaced
alias kept for back-compat)
email inbox [--unread] [--limit N] [--as <id>] email threads you're on, latest first
email show <conversation_id> [--tail N] full thread (all messages in order)
email send --to <addr|id>[,...] [--cc <...>] --subject "..." --body "..."
email reply <message_id> --body "..." [--cc <...>]
threaded reply (sets In-Reply-To / References)
DOCUMENTS (live collaborative docs — humans + agents edit the same page):
doc ls [--as <id>] list docs in the workspace
doc create "<title>" [--body "<markdown>"] create a doc; body is Markdown
doc read <document_id> read doc as Markdown-like text
doc append <document_id> "<markdown>" append Markdown blocks
doc prepend <document_id> "<markdown>" prepend Markdown blocks
doc image <document_id> <url> [--alt "..."]
[--at end|start | --replace "<text>" | --after "<text>" | --before "<text>"]
insert an image block. Default
is end of doc. Anchored modes
place the image relative to
the first block whose text
contains the given snippet:
--replace : swap that
block for the
image (use to
fix a broken
""
markdown line)
--after : insert below
the matched
block
--before : insert above
the matched
block
An anchored mode that misses
is an ERROR — no image is
inserted. Re-read the doc
and pick a more specific
snippet.
Preferred over an
"" markdown block
when the URL might wrap onto
multiple lines (long presigned
CDN links etc.)
doc image-delete <document_id>
[--src <url> | --src-contains <substr> | --alt <text>]
remove every image block in
the doc matching the
criterion. Use to clean up
duplicate or unwanted
illustrations the CLI left
behind.
doc replace <document_id> --find "..." --replace "..."
replace text in existing content
(text only — cannot change block
structure; see replace-block)
doc replace-block <document_id> --anchor "<snippet>" "<markdown>"
swap the FIRST block whose text
contains the snippet for freshly
parsed Markdown blocks. Use to
fix structure: e.g. a table that
rendered as one flat "|...|"
paragraph. Anchor miss = error,
nothing changes.
doc delete <document_id> delete a doc you created
Markdown supports headings, lists, quotes, code, links, tables, and image blocks:

SKILLS (progressive-disclosure capability packs in your own workspace):
skills list list installed skills (name + description only)
skills read <name> [<sub-path>] load full SKILL.md (or a bundled file)
skills create <name> "<description>" scaffold a new skill
skills search <query> search SkillHub (requires SKILLHUB_URL)
skills install <id> install from the configured SkillHub
skills delete <name> remove a skill
react <message_id> <emoji> toggle an emoji reaction on any message
palette "<brief>" generate a 5-color hex palette
(web search/read runs via the in-pod browser — bash invokes
"cumora-web search", "cumora-web read", or "opencli browser ...")
image generate "<prompt>" [--size square|wide|tall]
generate an image (gpt-image-2), upload to storage,
return signed URL + key for later 'reply --attach <url>'
GLOBAL FLAGS:
--json
--as <id> run as another participant (agents query their own state)
EXAMPLES:
cumora groups --as iris
cumora memory note "Yetone prefers warm palettes" --about yetone --as iris
cumora workspace write drafts/v3.md "# Hero v3..." --as iris
cumora workspace edit drafts/v3.md "warmth" "Sunday-morning warmth"
cumora dm bram "hero copy" "Want to align before iris paints v4"
cumora pull-group "Aurora launch" --members iris,bram,nova --reason "Shipping next week" --say "Kickoff?"
cumora react msg-abc123 🌤️
bash: cumora-web search "warm palette inspiration" --limit 3
bash: opencli browser "$CUMORA_AGENT_ID" open https://example.com
cumora image generate "a quiet bauhaus poster, ochre and cobalt" --size wide
cumora tasks list --as bram --status open
cumora calendar create "Follow up with Wei on hero v3" --at 2026-05-25T15:00:00Z --assignee iris --prompt "DM wei and ask if v3 landed" # one-shot self-schedule
cumora calendar create "Daily standup digest" --at 2026-05-24T09:00:00Z --assignee iris --prompt "Summarize yesterday's group activity and post into <convo_id>" --every daily # recurring self-schedule
cumora calendar list --as iris # see what you've already scheduled for yourself`,
)
}
async function cmdWhoami(parsed: ParsedArgs): Promise<CliResult> {
const id = resolveAs(parsed)
const companyId = await agentCompany(id)
if (!companyId) return err(`cannot resolve active company for ${id}`)
const { rows } = await pool.query<{
id: string; kind: string; name: string; role: string | null;
status: string; bio: string | null; tools: string[] | null
}>(
`SELECT id, kind, name, role, status, bio, tools
FROM participants
WHERE id = $1 AND company_id = $2
AND kind = 'agent' AND departed_at IS NULL`,
[id, companyId],
)
const p = rows[0]
if (!p) return err(`unknown participant: ${id}`)
if (parsed.flags.json) return ok(JSON.stringify(p, null, 2))
const { rows: convos } = await pool.query<{ id: string; title: string; kind: string }>(
`SELECT id, title, kind FROM conversations
WHERE company_id = $2
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = conversations.id
AND member.participant_id = $1
)
AND EXISTS (
SELECT 1 FROM participants requester
WHERE requester.id = $1
AND requester.company_id = conversations.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
)
ORDER BY updated_at DESC`,
[id, companyId],
)
const lines = [
`id: ${p.id}`,
`name: ${p.name}`,
`kind: ${p.kind}`,
p.role ? `role: ${p.role}` : '',
`status: ${p.status}`,
p.bio ? `bio: ${p.bio}` : '',
p.tools && p.tools.length ? `tools: ${p.tools.join(', ')}` : '',
'',
`member of ${convos.length} conversation(s):`,
...convos.map((c) => ` · [${c.kind.padEnd(7)}] ${c.id.padEnd(28)} ${c.title}`),
].filter(Boolean)
return ok(lines.join('\n'))
}
async function cmdParticipants(parsed: ParsedArgs): Promise<CliResult> {
// TENANT SCOPE: only this agent's OWN company. Without the company_id filter
// this listed every participant in EVERY Cumora company (cross-tenant leak —
// agents reported "thousands of resting humans" = all users globally).
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve company for ${me}`)
const kind = parsed.flags.kind ? String(parsed.flags.kind) : null
const params: unknown[] = [companyId]
let where = `WHERE company_id = $1 AND departed_at IS NULL`
if (kind) { params.push(kind); where += ` AND kind = $2` }
const { rows } = await pool.query<{
id: string; kind: string; name: string; role: string | null; status: string; avatar_url: string | null
}>(
`SELECT id, kind, name, role, status, avatar_url FROM participants ${where} ORDER BY kind DESC, name ASC`,
params,
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
const lines = [
`id kind status role`,
`-----------------------------------------------------`,
]
for (const r of rows) {
lines.push(`${r.id.padEnd(15)} ${r.kind.padEnd(6)} ${r.status.padEnd(11)} ${r.role ?? ''}`)
// Surface the avatar URL on its own line when set, so an agent can fetch the
// image and view it (\`cumora avatar show <id>\` is the convenience wrapper).
if (r.avatar_url) lines.push(` ↳ avatar: ${r.avatar_url}`)
}
return ok(lines.join('\n'))
}
async function cmdConversations(parsed: ParsedArgs, kindFilter?: 'group' | 'direct'): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const params: unknown[] = [me, companyId]
let kindWhere = ''
if (kindFilter) {
params.push(kindFilter)
kindWhere = `AND c.kind = $3`
}
const { rows } = await pool.query<{
id: string; kind: string; title: string; subtitle: string | null;
members: string[]; tag: string | null;
updated_at: string; pulled_by: { agentId?: string } | null
}>(
`SELECT c.id, c.kind, c.title, c.subtitle, c.members, c.tag, c.updated_at, c.pulled_by
FROM conversations c
JOIN participants requester
ON requester.id = $1
AND requester.company_id = c.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
WHERE c.company_id = $2
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $1
) ${kindWhere}
ORDER BY c.updated_at DESC`,
params,
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no conversations for ${me})`)
const lines = [
`${me} is in ${rows.length} conversation(s):`,
``,
`id kind title members`,
`------------------------------------------------------------------------------------------------`,
...rows.map((r) => {
const tag = r.tag ? ` [${r.tag}]` : ''
const pulled = r.pulled_by?.agentId ? ` ← pulled by ${r.pulled_by.agentId}` : ''
return `${r.id.padEnd(28)} ${r.kind.padEnd(8)} ${r.title.slice(0, 42).padEnd(42)} ${r.members.join(',')}${tag}${pulled}`
}),
]
return ok(lines.join('\n'))
}
async function cmdMembers(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const id = parsed.positional[0]
if (!id) return err('usage: members <conversation_id>')
const { rows } = await pool.query<{ members: string[] }>(
`SELECT ARRAY_AGG(member.participant_id ORDER BY member.ordinal) AS members
FROM conversations c
JOIN conversation_members member ON member.conversation_id = c.id
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
WHERE c.id = $1
AND c.company_id = $3
AND EXISTS (
SELECT 1 FROM conversation_members actor
WHERE actor.conversation_id = c.id
AND actor.participant_id = $2
)
GROUP BY c.id`,
[id, me, companyId],
)
if (!rows[0]) return err(`unknown conversation: ${id}`)
const memberIds = rows[0].members
const { rows: peeps } = await pool.query<{
id: string; name: string; kind: string; role: string | null; status: string; avatar_url: string | null
}>(
`SELECT id, name, kind, role, status, avatar_url
FROM participants
WHERE id = ANY($1::text[]) AND company_id = $2`,
[memberIds, companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(peeps, null, 2))
const memberLines: string[] = []
for (const p of peeps) {
memberLines.push(` · ${p.id.padEnd(12)} ${p.kind.padEnd(6)} ${p.status.padEnd(10)} ${p.name}${p.role ? ` (${p.role})` : ''}`)
if (p.avatar_url) memberLines.push(` ↳ avatar: ${p.avatar_url}`)
}
const lines = [
`${id} has ${peeps.length} member(s):`,
``,
...memberLines,
]
return ok(lines.join('\n'))
}
async function cmdMessages(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const id = parsed.positional[0]
if (!id) return err('usage: messages <conversation_id> [--tail N] [--thread <root_id>]')
const tail = Math.min(200, Math.max(1, Number(parsed.flags.tail ?? 20)))
// `--thread <root_id>` filters to direct replies of one message. Useful
// when an agent wants to focus on what's happening in one sub-discussion
// before deciding how to respond.
const threadRootId = parsed.flags.thread ? String(parsed.flags.thread) : null
const params: unknown[] = [id, me, companyId]
let whereExtra = ''
if (threadRootId) {
params.push(threadRootId)
whereExtra = `AND m.quoted_message_id = $4`
}
params.push(tail)
const limitParam = `$${params.length}`
const { rows } = await pool.query<{
id: string; author_id: string; kind: string; body: string; sequence: number;
created_at: string; attachment: StoredAttachment | null; attachments: StoredAttachment[] | null;
poll: InboxPollPayload | null;
quoted_message_id: string | null;
quoted: { id: string; authorId: string; authorName: string; body: string } | null;
}>(
`WITH authorized_conversation AS MATERIALIZED (
SELECT c.id
FROM conversations c
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
WHERE c.id = $1
AND c.company_id = $3
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)
)
SELECT
m.id, m.author_id, m.kind, m.body, m.sequence, m.created_at,
COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
ELSE jsonb_build_array(m.attachment) END) AS attachments,
COALESCE(m.attachments->0, m.attachment) AS attachment, m.poll,
m.quoted_message_id,
(
SELECT jsonb_build_object(
'id', qm.id,
'authorId', qm.author_id,
'authorName', qm.author_id,
'body', LEFT(qm.body, 240)
)
FROM messages qm
WHERE qm.id = m.quoted_message_id
AND qm.conversation_id = m.conversation_id
) AS quoted
FROM messages m
JOIN authorized_conversation authorized ON authorized.id = m.conversation_id
WHERE TRUE
${whereExtra}
ORDER BY m.sequence DESC LIMIT ${limitParam}`,
params,
)
for (const row of rows) await freshenRowAttachment(row)
const inOrder = rows.reverse()
const attachmentReads = attachmentReadsFor(inOrder)
// Advance the Redis "seen" boundary — `cumora messages` just showed
// the agent these rows, so the highest seq here counts as "what I've
// seen" for the freshness preflight on its next `cumora reply`. Without
// this, the agent's typical flow `messages → reply` would HOLD on the
// very tail it just fetched. Redis-only, fail-open, monotonic.
if (inOrder.length > 0) {
await recordSeen(me, id, inOrder[inOrder.length - 1].sequence)
}
if (parsed.flags.json) return ok(JSON.stringify(inOrder, null, 2), undefined, attachmentReads)
if (inOrder.length === 0) {
return ok(threadRootId
? `(no replies in thread ${threadRootId})`
: `(no messages in ${id})`)
}
const header = threadRootId
? `${inOrder.length} reply(ies) in thread ${threadRootId}:`
: `last ${inOrder.length} message(s) in ${id}:`
const lines = [header, '']
for (const m of inOrder) {
const t = new Date(m.created_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
const body = m.kind === 'tool' ? `[tool call]` : m.body.slice(0, 280).replace(/\n/g, ' \\n ')
lines.push(` [${m.id}] [${t}] ${m.author_id.padEnd(8)} #${String(m.sequence).padStart(3, ' ')} ${body}`)
if (m.quoted_message_id) {
if (m.quoted) {
const qBody = m.quoted.body.slice(0, 180).replace(/\n/g, ' \\n ')
lines.push(` ↩ quoting [${m.quoted.id}] ${m.quoted.authorName}: ${qBody}`)
} else {
lines.push(` ↩ quoting [${m.quoted_message_id}] (original deleted)`)
}
}
if (m.kind === 'poll' && m.poll) {
for (const line of renderPollBlock(m.id, m.poll)) lines.push(line)
}
lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
return ok(lines.join('\n'), undefined, attachmentReads)
}
/** `cumora thread <convo_id> <root_msg_id> [--tail N]`
* Sugar around `messages <convo> --thread <root>`. Lists every direct
* reply to a single root in order, so an agent can catch up on a
* sub-discussion before deciding whether to chime in. */
async function cmdThread(parsed: ParsedArgs): Promise<CliResult> {
const convoId = parsed.positional[0]
const rootId = parsed.positional[1]
if (!convoId || !rootId) return err('usage: thread <convo_id> <root_msg_id> [--tail N]')
// Delegate to cmdMessages with --thread filled in. We mutate `parsed` in
// place since this command does nothing else; cleaner than reimplementing
// the same SELECT-with-quoted projection a second time.
const proxied: ParsedArgs = {
positional: [convoId],
flags: { ...parsed.flags, thread: rootId },
}
return cmdMessages(proxied)
}
async function cmdConvening(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const id = parsed.positional[0]
if (!id) return err('usage: convening <conversation_id>')
const { rows } = await pool.query<{
pulled_by_id: string; pulled_at: string; headline_lead: string; headline_tail: string;
subhead: string; who_and_why: unknown; reasoning: unknown; status: string
}>(
`SELECT ci.pulled_by_id, ci.pulled_at, ci.headline_lead, ci.headline_tail, ci.subhead,
ci.who_and_why, ci.reasoning, ci.status
FROM convening_info ci
JOIN conversations c ON c.id = ci.conversation_id
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
WHERE ci.conversation_id = $1
AND c.company_id = $3
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)`,
[id, me, companyId],
)
const c = rows[0]
if (!c) return err(`no convening info for ${id}`)
if (parsed.flags.json) return ok(JSON.stringify(c, null, 2))
const reasoning = Array.isArray(c.reasoning) ? c.reasoning.map((r, i) => ` ${i + 1}. ${r}`).join('\n') : ''
const who = Array.isArray(c.who_and_why)
? (c.who_and_why as Array<{ pid: string; reason: string }>).map((w) => ` · ${w.pid}${w.reason ? ` — ${w.reason}` : ''}`).join('\n')
: ''
return ok([
`headline: ${c.headline_lead}${c.headline_tail ? ' ' + c.headline_tail : ''}`,
`subhead: ${c.subhead}`,
`pulled by: ${c.pulled_by_id}`,
`pulled at: ${c.pulled_at}`,
`status: ${c.status}`,
'',
`who & why:`,
who,
'',
`reasoning:`,
reasoning,
].join('\n'))
}
async function cmdSearch(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const query = parsed.positional[0]
if (!query) return err('usage: search <query> [--in <convo_id>] [--limit N]')
const inConvo = parsed.flags.in ? String(parsed.flags.in) : null
const limit = Math.min(50, Math.max(1, Number(parsed.flags.limit ?? 10)))
const params: unknown[] = [me, companyId, `%${query}%`]
let whereExtra = ''
if (inConvo) {
params.push(inConvo)
whereExtra = `AND m.conversation_id = $4`
}
params.push(limit)
const limitParam = `$${params.length}`
const { rows } = await pool.query<{
id: string; conversation_id: string; author_id: string; body: string;
created_at: string; attachment: StoredAttachment | null; attachments: StoredAttachment[] | null
}>(
`SELECT m.id, m.conversation_id, m.author_id, m.body, m.created_at,
COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
ELSE jsonb_build_array(m.attachment) END) AS attachments,
COALESCE(m.attachments->0, m.attachment) AS attachment
FROM messages m
JOIN conversations c ON c.id = m.conversation_id
JOIN participants requester
ON requester.id = $1
AND requester.company_id = c.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
WHERE c.company_id = $2
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $1
)
AND m.body ILIKE $3 ${whereExtra}
ORDER BY m.created_at DESC LIMIT ${limitParam}`,
params,
)
for (const row of rows) await freshenRowAttachment(row)
const attachmentReads = attachmentReadsFor(rows)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2), undefined, attachmentReads)
if (rows.length === 0) return ok(`(no matches for "${query}"${inConvo ? ` in ${inConvo}` : ''})`)
const lines = [`${rows.length} match(es) for "${query}":`, '']
for (const m of rows) {
const t = new Date(m.created_at).toLocaleString()
const idx = m.body.toLowerCase().indexOf(query.toLowerCase())
const slice = m.body.slice(Math.max(0, idx - 20), idx + 100).replace(/\n/g, ' \\n ')
lines.push(` · [${t}] ${m.conversation_id} ${m.author_id}: …${slice}…`)
lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
return ok(lines.join('\n'), undefined, attachmentReads)
}
async function cmdToolsLog(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const agent = parsed.flags.agent ? String(parsed.flags.agent) : null
const limit = Math.min(50, Math.max(1, Number(parsed.flags.limit ?? 15)))
const params: unknown[] = [companyId]
let where = 'WHERE company_id = $1'
if (agent) { params.push(agent); where += ` AND agent_id = $2` }
params.push(limit)
const limitParam = `$${params.length}`
const { rows } = await pool.query<{
id: string; agent_id: string; name: string; status: string; duration_ms: number | null;
args: unknown; created_at: string
}>(
`SELECT id, agent_id, name, status, duration_ms, args, created_at
FROM tool_calls ${where}
ORDER BY created_at DESC LIMIT ${limitParam}`,
params,
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no tool calls)`)
return ok([
`last ${rows.length} tool call(s):`,
'',
...rows.map((r) => {
const t = new Date(r.created_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
const argsBrief = JSON.stringify(r.args).slice(0, 100)
return ` [${t}] ${r.agent_id.padEnd(8)} ${r.name.padEnd(22)} ${r.status.padEnd(7)} ${r.duration_ms ?? '-'}ms ${argsBrief}`
}),
].join('\n'))
}
async function cmdStatus(parsed: ParsedArgs): Promise<CliResult> {
// TENANT SCOPE: this agent's own company only (was leaking every agent in
// every company — same cross-tenant hole as cmdParticipants).
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve company for ${me}`)
const { rows } = await pool.query<{ id: string; name: string; status: string; kind: string }>(
`SELECT id, name, status, kind FROM participants
WHERE company_id = $1 AND kind = 'agent' AND departed_at IS NULL ORDER BY name ASC`,
[companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
return ok([
`agent status`,
`-----------------------------`,
...rows.map((r) => `${r.name.padEnd(8)} (${r.id.padEnd(6)}) ${r.status}`),
].join('\n'))
}
/* ============== mailbox: inbox / ack / reply ============== */
import { randomUUID } from 'node:crypto'
interface InboxQuotedSummary {
id: string
authorId: string
authorName: string
kind: string
body: string
sequence: number
}
interface InboxItem {
id: string
conversation_id: string
conversation_title: string
conversation_kind: string
conversation_topic: string | null
author_id: string
author_name: string
body: string
kind: string
sequence: number
created_at: string
attachment: StoredAttachment | null
attachments: StoredAttachment[] | null
poll: InboxPollPayload | null
quoted_message_id: string | null
quoted: InboxQuotedSummary | null
}
interface InboxPollPayload {
question: string
mode: 'single' | 'multi'
options: Array<{ id: string; text: string }>
expiresAt: string | null
closedAt: string | null
closedReason: 'expired' | 'manual' | null
}
/** Render a poll message as a multi-line block that gives the agent
* every fact it needs to vote in one read: the question, the option ids
* (so it can pick one without a second roundtrip), the mode, the
* open/closed/expired state, and the exact `cumora poll vote` line to
* copy-paste. Without this, polls look like a plain text message with
* a 📊 prefix and the agent has no idea options exist.
*
* Indented to match the surrounding `[id] hh:mm author: body` rows so
* it lines up visually inside both `cumora inbox` and `cumora messages`. */
function renderPollBlock(messageId: string, poll: InboxPollPayload): string[] {
const lines: string[] = []
const state = poll.closedAt
? `closed${poll.closedReason ? ` (${poll.closedReason})` : ''}`
: (poll.expiresAt ? `open · expires ${poll.expiresAt}` : 'open · no expiration')
lines.push(` 📊 POLL · ${poll.mode}-choice · ${state}`)
lines.push(` question: ${poll.question}`)
for (const o of poll.options) {
lines.push(` • ${o.id} — ${o.text}`)
}
if (!poll.closedAt) {
lines.push(` → to vote: cumora poll vote ${messageId} <option_id>${poll.mode === 'multi' ? '[,<option_id>...]' : ''}`)
lines.push(` → if the question doesn't apply to you or none of the options is your real answer, stay silent (no reply, no vote)`)
}
return lines
}
async function loadInbox(agentId: string): Promise<InboxItem[]> {
const { rows } = await pool.query<InboxItem>(
`SELECT
m.id,
m.conversation_id,
c.title AS conversation_title,
c.kind AS conversation_kind,
c.topic AS conversation_topic,
m.author_id,
COALESCE(p.name, m.author_id) AS author_name,
m.body,
m.kind,
m.sequence,
m.created_at,
COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
ELSE jsonb_build_array(m.attachment) END) AS attachments,
COALESCE(m.attachments->0, m.attachment) AS attachment,
m.poll,
m.quoted_message_id,
(
SELECT jsonb_build_object(
'id', qm.id,
'authorId', qm.author_id,
'authorName', COALESCE(qp.name, qm.author_id),
'kind', qm.kind,
'body', LEFT(qm.body, 240),
'sequence', qm.sequence
)
FROM messages qm
LEFT JOIN participants qp ON qp.id = qm.author_id AND qp.company_id = c.company_id
WHERE qm.id = m.quoted_message_id
AND qm.conversation_id = m.conversation_id
) AS quoted
FROM messages m
JOIN conversations c ON c.id = m.conversation_id
JOIN participants requesting_agent
ON requesting_agent.id = $1
AND requesting_agent.company_id = c.company_id
AND requesting_agent.kind = 'agent'
AND requesting_agent.departed_at IS NULL
LEFT JOIN participants p ON p.id = m.author_id AND p.company_id = c.company_id
WHERE (EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $1
) OR m.delivery_recipient_id = $1)
AND (m.author_id <> $1 OR m.delivery_recipient_id = $1)
AND m.created_at > COALESCE(
(SELECT last_read_at FROM conversation_reads
WHERE user_id = $1 AND conversation_id = c.id),
'1970-01-01T00:00:00Z'::timestamptz)
AND (
m.delivery_recipient_id = $1
OR c.kind = 'direct'
OR NOT EXISTS (
SELECT 1 FROM conversation_mutes mu
WHERE mu.user_id = $1 AND mu.conversation_id = c.id
AND (mu.muted_until IS NULL OR mu.muted_until > NOW())
)
OR EXISTS (
SELECT 1 FROM regexp_matches(m.body, '@([[:alnum:]_-]+)', 'g') mention
WHERE LOWER(mention[1]) = LOWER($1)
)
OR EXISTS (
SELECT 1 FROM messages quoted
WHERE quoted.id = m.quoted_message_id
AND quoted.conversation_id = m.conversation_id
AND quoted.author_id = $1
)
)
ORDER BY m.created_at ASC
LIMIT 200`,
[agentId],
)
for (const row of rows) await freshenRowAttachment(row)
return rows
}
async function cmdInbox(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const filterConvo = parsed.positional[0] ?? null
const items = await loadInbox(me)
const filtered = filterConvo ? items.filter((m) => m.conversation_id === filterConvo) : items
const attachmentReads = attachmentReadsFor(filtered)
if (parsed.flags.json) return ok(JSON.stringify(filtered, null, 2), undefined, attachmentReads)
if (filtered.length === 0) return ok(`(inbox empty for ${me})`)
// Group by conversation
const byConvo = new Map<string, InboxItem[]>()
for (const it of filtered) {
if (!byConvo.has(it.conversation_id)) byConvo.set(it.conversation_id, [])
byConvo.get(it.conversation_id)!.push(it)
}
const lines: string[] = [`${filtered.length} unread message(s) for ${me}, across ${byConvo.size} conversation(s):`, '']
for (const [convoId, msgs] of byConvo) {
const head = msgs[0]
lines.push(`# ${convoId} [${head.conversation_kind}] "${head.conversation_title}"`)
if (head.conversation_topic) lines.push(` Topic: ${head.conversation_topic}`)
for (const m of msgs) {
const t = new Date(m.created_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
const body = m.kind === 'tool' ? '[tool call]' : m.body.slice(0, 240).replace(/\n/g, ' \\n ')
lines.push(` [${m.id}] ${t} ${m.author_name}: ${body}`)
// Inline the quoted-original (one line, indented) so you can see what
// a reply is replying to without a second lookup. Pass `--quote <id>`
// to `reply` to quote a message back.
if (m.quoted_message_id) {
if (m.quoted) {
const qBody = m.quoted.body.slice(0, 180).replace(/\n/g, ' \\n ')
lines.push(` ↩ quoting [${m.quoted.id}] ${m.quoted.authorName}: ${qBody}`)
} else {
lines.push(` ↩ quoting [${m.quoted_message_id}] (original deleted)`)
}
}
if (m.kind === 'poll' && m.poll) {
for (const line of renderPollBlock(m.id, m.poll)) lines.push(line)
}
lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
lines.push('')
}
lines.push(`when you're done deciding what to do (reply / react / dm / nothing), run \`cumora ack <convo_id>\` to clear that conversation from your inbox so the next wake-up doesn't see it again. \`cumora ack --all\` clears everything in your inbox.`)
return ok(lines.join('\n'), undefined, attachmentReads)
}
/** `cumora glance <convo>` — read the room before committing a reply.
*
* Two things real teammates do that an LLM-driven agent doesn't get
* for free: (1) see what's just been said since they started thinking,
* (2) see who else is currently typing. This command surfaces both:
* recent messages in the convo (last ~12, with the agent's own
* replies tagged ▸ME) plus the set of peer agents that are currently
* marked "thinking" in this convo.
*
* The agent prompt teaches the model to glance once before each
* broadcast reply — so a peer can race past with their answer while
* the model was still composing and the model adjusts (yield, build
* on it, pick a different angle) instead of blurting the same thing. */
async function cmdGlance(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`cannot resolve active company for ${me}`)
const convoId = (typeof parsed.flags['conversation'] === 'string' ? parsed.flags['conversation'] : null)
?? parsed.positional[0]
if (!convoId) return err('usage: glance --conversation <id> (or: glance <id>)')
interface RecentRow {
id: string
author_id: string
author_name: string
kind: string
body: string
created_at: string
sequence: number
attachment: StoredAttachment | null
attachments: StoredAttachment[] | null
}
const { rows } = await pool.query<RecentRow>(
`SELECT m.id, m.author_id, COALESCE(p.name, m.author_id) AS author_name,
m.kind, m.body, m.created_at, m.sequence,
COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
ELSE jsonb_build_array(m.attachment) END) AS attachments,
COALESCE(m.attachments->0, m.attachment) AS attachment
FROM messages m
JOIN conversations c ON c.id = m.conversation_id
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
LEFT JOIN participants p ON p.id = m.author_id AND p.company_id = c.company_id
WHERE m.conversation_id = $1
AND c.company_id = $3
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)
ORDER BY m.created_at DESC
LIMIT 12`,
[convoId, me, companyId],
)
for (const row of rows) await freshenRowAttachment(row)
const recent = rows.reverse()
const attachmentReads = attachmentReadsFor(recent)
// Advance the Redis "seen" boundary — glance just showed the agent
// these messages, so they count as "seen" for the freshness preflight
// on its next `cumora reply`. Same Redis-only, fail-open path as
// cmdMessages — never touches conversation_reads.last_read_at.
if (recent.length > 0) {
await recordSeen(me, convoId, recent[recent.length - 1].sequence)
}
// NO composing/claim-order roster. Exposing "who's composing, ordered by
// who claimed first, [earlier/later than you]" is exactly what let an agent
// map its claim RANK to a task slot ("I'm 3rd to claim → I post 3") — a
// whole class of coordination bugs that then needed a wall of scenario-patch
// prompt rules. Exposing only the posted message stream + a private
// seen-cursor makes slot-by-position
// structurally unrepresentable: the only fact an agent can act on is "the
// latest thing actually posted", so it posts the real next item and races,
// and the server's freshness gate (cmdReply preflight) serializes collisions.
// glance now returns ONLY the stream, matching that model.
if (parsed.flags.json) {
return ok(JSON.stringify({ conversation_id: convoId, recent }, null, 2), undefined, attachmentReads)
}
const lines: string[] = []
lines.push(`Glance into ${convoId} — last ${recent.length} message(s):`)
lines.push('')
if (recent.length === 0) {
lines.push(' (no messages yet)')
} else {
for (const m of recent) {
const t = new Date(m.created_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
const tag = m.author_id === me ? '▸ME' : ' '
const body = m.kind === 'tool'
? '[tool call]'
: m.kind === 'system'
? '[system]'
: m.body.slice(0, 200).replace(/\n/g, ' \\n ')
lines.push(` [${m.id}] ${tag} ${t} ${m.author_name}: ${body}`)
lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
}
return ok(lines.join('\n'), undefined, attachmentReads)
}
async function cmdAck(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
if (parsed.flags.all) {
// Ack every conversation that currently has unread items for me
const items = await loadInbox(me)
const convoIds = [...new Set(items.map((i) => i.conversation_id))]
for (const id of convoIds) {
await pool.query(
`INSERT INTO conversation_reads (user_id, conversation_id, last_read_at)
VALUES ($1, $2, NOW())
ON CONFLICT (user_id, conversation_id) DO UPDATE SET last_read_at = NOW()`,
[me, id],
)
// Acking = standing down on this conversation. Any un-used HELD
// acknowledgement is void — it must not arm a later turn's
// preemptive --send-anyway (the 2026-07-08 stale-"6" path).
void clearHold(me, `reply:${id}`)
}
return ok(`acked ${convoIds.length} conversation(s)`)
}
const convoId = parsed.positional[0]
if (!convoId) return err('usage: ack <conversation_id> OR ack --all')
const activeAgentCompanyId = await agentCompany(me)
const { rowCount } = await pool.query(
`INSERT INTO conversation_reads (user_id, conversation_id, last_read_at)
SELECT $1, c.id, NOW()
FROM conversations c
JOIN participants requester
ON requester.id = $1
AND requester.company_id = c.company_id
AND requester.kind IN ('agent', 'human')
AND requester.departed_at IS NULL
WHERE c.id = $2
AND ($3::text IS NULL OR c.company_id = $3)
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $1
)
ON CONFLICT (user_id, conversation_id) DO UPDATE SET last_read_at = NOW()`,
[me, convoId, activeAgentCompanyId],
)
if (!rowCount) return err(`conversation ${convoId} not found or no longer authorized`)
// Standing down — see the --all branch above.
void clearHold(me, `reply:${convoId}`)
return ok(`acked ${convoId}`)
}
function parseMuteUntil(parsed: ParsedArgs): Date | null {
const untilRaw = typeof parsed.flags.until === 'string' ? parsed.flags.until : null
const forRaw = typeof parsed.flags.for === 'string' ? parsed.flags.for : null
if (untilRaw && forRaw) throw new Error('use either --until or --for, not both')
if (untilRaw) {
const until = new Date(untilRaw)
if (Number.isNaN(until.getTime())) throw new Error('invalid --until timestamp')
if (until.getTime() <= Date.now()) throw new Error('--until must be in the future')
return until
}
if (!forRaw) return null
const match = /^(\d+)(m|h|d|w)$/i.exec(forRaw.trim())
if (!match) throw new Error('invalid --for duration (use e.g. 30m, 2h, 1d, or 1w)')
const amount = Number(match[1])
const unitMs = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[match[2].toLowerCase() as 'm' | 'h' | 'd' | 'w']
if (amount < 1 || amount * unitMs > 90 * 86_400_000) throw new Error('--for duration must be between 1 minute and 90 days')
return new Date(Date.now() + amount * unitMs)
}
async function cmdMute(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
if (parsed.positional[0] === 'list') {
const { rows } = await pool.query<{ id: string; title: string; muted_until: string | null }>(
`SELECT c.id, c.title, mu.muted_until
FROM conversation_mutes mu
JOIN conversations c ON c.id = mu.conversation_id
WHERE mu.user_id = $1 AND c.company_id = $2
AND (mu.muted_until IS NULL OR mu.muted_until > NOW())
ORDER BY mu.muted_at DESC`,
[me, companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok('(no muted groups)')
return ok(rows.map((row) => `• ${row.id} "${row.title}" — ${row.muted_until ? `until ${new Date(row.muted_until).toISOString()}` : 'until you follow it'}`).join('\n'))
}
const conversationId = parsed.positional[0]
if (!conversationId) return err('usage: mute <conversation_id> [--for 30m|2h|1d|1w] [--until <iso>] OR mute list')
let until: Date | null
try { until = parseMuteUntil(parsed) } catch (error) { return err(error instanceof Error ? error.message : String(error)) }
const { rows } = await pool.query<{ kind: string; title: string; actor_is_member: boolean }>(
`SELECT c.kind, c.title,
EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $3
) AS actor_is_member
FROM conversations c
WHERE c.id = $1 AND c.company_id = $2`,
[conversationId, companyId, me],
)
const conversation = rows[0]
if (!conversation) return err(`conversation not found: ${conversationId}`)
if (!conversation.actor_is_member) return err(`you are not a member of ${conversationId}`)
if (conversation.kind === 'direct') return err('direct conversations always deliver; mute a group instead')
const muted = await withConversationActorLock({
participantId: me,
companyId,
conversationId,
kind: 'agent',
run: async (client) => {
await client.query(
`INSERT INTO conversation_mutes (user_id, conversation_id, muted_at, muted_until)
VALUES ($1, $2, NOW(), $3)
ON CONFLICT (user_id, conversation_id)
DO UPDATE SET muted_at = NOW(), muted_until = EXCLUDED.muted_until`,
[me, conversationId, until],
)
// Muting is a deliberate stand-down. Seal the current unread tail so
// following later resumes from that point instead of replaying a backlog.
await client.query(
`INSERT INTO conversation_reads (user_id, conversation_id, last_read_at)
VALUES ($1, $2, NOW())
ON CONFLICT (user_id, conversation_id) DO UPDATE SET last_read_at = NOW()`,
[me, conversationId],
)
return true
},
})
if (!muted) return err(`conversation ${conversationId} is no longer authorized`)
void clearHold(me, `reply:${conversationId}`)
const expiry = until ? ` until ${until.toISOString()}` : ' until you follow it again'
return ok(
`Muted ${conversationId} ("${conversation.title}")${expiry}. ` +
`New group messages will not wake you or enter your inbox. A direct @${me} mention or a reply quoting your message still gets through. ` +
`Resume with: cumora follow ${conversationId}`,
)
}
async function cmdFollow(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const conversationId = parsed.positional[0]
if (!conversationId) return err('usage: follow <conversation_id>')
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
const followed = await withConversationActorLock({
participantId: me,
companyId,
conversationId,
kind: 'agent',
run: (client) => client.query(
`DELETE FROM conversation_mutes
WHERE user_id = $1 AND conversation_id = $2`,
[me, conversationId],
),
})
if (!followed) return err(`conversation ${conversationId} is no longer authorized`)
const rowCount = followed.rowCount
return ok(rowCount
? `Following ${conversationId} again. New messages will resume normal inbox delivery.`
: `${conversationId} was not muted; normal delivery is already active.`)
}
async function cmdShip(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
const action = parsed.positional[0] ?? 'list'
if (action === 'list') {
const { rows } = await pool.query<{
id: string; title: string; status: string; priority: string; required: number; passed: number; failed: number; release_target: string | null
}>(
`SELECT f.id, f.title, f.status, f.priority, f.release_target,
count(v.id) FILTER (WHERE v.required)::int AS required,
count(v.id) FILTER (WHERE v.required AND v.status='passed')::int AS passed,
count(v.id) FILTER (WHERE v.status='failed')::int AS failed
FROM shipping_features f LEFT JOIN shipping_verifications v ON v.feature_id=f.id
WHERE f.company_id=$1 AND f.status <> 'archived'
GROUP BY f.id ORDER BY f.updated_at DESC`,
[companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok('(no active shipping contracts)')
return ok(rows.map((row) => `${row.id} [${row.status}] ${row.title}\n evidence ${row.passed}/${row.required}${row.failed ? ` · ${row.failed} failed` : ''}${row.release_target ? ` · target ${row.release_target}` : ''}`).join('\n'))
}
if (action === 'show') {
const featureId = parsed.positional[1]
if (!featureId) return err('usage: ship show <feature_id>')
const { rows: features } = await pool.query(
`SELECT id,title,problem,desired_outcome,status,priority,risk_level,release_target,builder_ids
FROM shipping_features WHERE id=$1 AND company_id=$2`,
[featureId, companyId],
)
if (!features[0]) return err(`shipping feature not found: ${featureId}`)
const [invariants, squares, releases, friction, regressions] = await Promise.all([
pool.query(`SELECT id,title,description,kind,required FROM shipping_invariants WHERE feature_id=$1 ORDER BY position`, [featureId]),
pool.query(`SELECT id,title,method,required,status,owner_id,verified_by_id,evidence,notes FROM shipping_verifications WHERE feature_id=$1 ORDER BY position`, [featureId]),
pool.query(`SELECT id,environment,status,version,commit_sha,readback_status,readback_due_at FROM shipping_releases WHERE feature_id=$1 ORDER BY created_at DESC`, [featureId]),
pool.query(`SELECT id,title,severity,frequency,status,occurrence_count FROM shipping_friction_reports WHERE feature_id=$1 ORDER BY last_seen_at DESC`, [featureId]),
pool.query(`SELECT id,title,kind,status,command,last_result FROM shipping_regressions WHERE feature_id=$1 ORDER BY updated_at DESC`, [featureId]),
])
const snapshot = { ...features[0], invariants: invariants.rows, squares: squares.rows, releases: releases.rows, friction: friction.rows, regressions: regressions.rows }
if (parsed.flags.json) return ok(JSON.stringify(snapshot, null, 2))
const lines = [`${snapshot.id} [${snapshot.status}] ${snapshot.title}`, `Problem: ${snapshot.problem || '—'}`, `Outcome: ${snapshot.desired_outcome || '—'}`, `Builders: ${(snapshot.builder_ids as string[]).map((id) => `@${id}`).join(', ') || '—'}`, '', 'Invariants:']
lines.push(...invariants.rows.map((i: any) => ` ${i.required ? '•' : '◦'} ${i.id} [${i.kind}] ${i.title}`))
lines.push('', 'Evidence squares:')
lines.push(...squares.rows.map((s: any) => ` ${s.status === 'passed' ? '✓' : s.status === 'failed' ? '!' : '·'} ${s.id} [${s.method}/${s.status}] ${s.title} · owner ${s.owner_id ? `@${s.owner_id}` : 'unassigned'}`))
lines.push('', `Releases: ${releases.rows.length} · Friction: ${friction.rows.length} · Regressions: ${regressions.rows.length}`)
return ok(lines.join('\n'))
}
if (action === 'create') {
const title = parsed.positional[1]?.trim()
if (!title) return err('usage: ship create "<title>" --problem "..." --outcome "..." --contract "..." [--builders a,b]')
const builderIds = typeof parsed.flags.builders === 'string'
? [...new Set(parsed.flags.builders.split(',').map((id) => id.trim()).filter(Boolean))]
: [me]
const { rows: builders } = await pool.query<{ id: string }>(`SELECT id FROM participants WHERE company_id=$1 AND id=ANY($2::text[]) AND departed_at IS NULL`, [companyId, builderIds])
if (builders.length !== builderIds.length) return err('one or more --builders are not active participants in this company')
const id = `ship-${randomUUID()}`
const client = await pool.connect()
try {
await client.query('BEGIN')
await client.query(
`INSERT INTO shipping_features
(id,company_id,title,problem,desired_outcome,contract_summary,builder_ids,created_by,updated_by)
VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,$8,$8)`,
[id, companyId, title, typeof parsed.flags.problem === 'string' ? parsed.flags.problem : '',
typeof parsed.flags.outcome === 'string' ? parsed.flags.outcome : '', typeof parsed.flags.contract === 'string' ? parsed.flags.contract : '',
JSON.stringify(builderIds), me],
)
for (const [squareTitle, method, position] of [
['Walk the critical user path', 'user_path', 10],
['Prove trace coverage and diagnostic evidence', 'trace', 20],
['Verify release notes and known gaps', 'release_note', 30],
] as const) {
await client.query(
`INSERT INTO shipping_verifications (id,feature_id,title,method,required,builder_ids,position,created_by)
VALUES ($1,$2,$3,$4,TRUE,$5::jsonb,$6,$7)`,
[`sv-${randomUUID()}`, id, squareTitle, method, JSON.stringify(builderIds), position, me],
)
}
await client.query(
`INSERT INTO shipping_events (id,company_id,feature_id,actor_id,kind,data)
VALUES ($1,$2,$3,$4,'feature.created',$5::jsonb)`,
[`se-${randomUUID()}`, companyId, id, me, JSON.stringify({ title, source: 'agent-cli' })],
)
await client.query('COMMIT')
} catch (error) {
await client.query('ROLLBACK').catch(() => {})
throw error
} finally { client.release() }
return ok(`Created shipping contract ${id} for “${title}”. Three required evidence squares were seeded. Add invariants and assign independent verifiers in the Ship workspace.`)
}
if (action === 'square') {
const [featureId, squareId, status] = parsed.positional.slice(1)
if (!featureId || !squareId || !['running','passed','failed','waived'].includes(status ?? '')) return err('usage: ship square <feature_id> <square_id> <running|passed|failed|waived> [--evidence "..."] [--notes "..."]')
const { rows } = await pool.query<{ builder_ids: string[]; title: string }>(
`SELECT v.builder_ids,v.title FROM shipping_verifications v JOIN shipping_features f ON f.id=v.feature_id
WHERE v.id=$1 AND v.feature_id=$2 AND f.company_id=$3`, [squareId, featureId, companyId],
)
const square = rows[0]
if (!square) return err('verification square not found')
const completing = status !== 'running'
if (completing && square.builder_ids.includes(me)) return err('builder/verifier separation: you cannot complete a square for work you built')
const evidence = typeof parsed.flags.evidence === 'string' ? parsed.flags.evidence.trim() : ''
const notes = typeof parsed.flags.notes === 'string' ? parsed.flags.notes.trim() : ''
if ((status === 'passed' || status === 'failed') && !evidence) return err(`${status} requires --evidence`)
if (status === 'waived' && !notes) return err('waived requires --notes with the written reason')
const proof = JSON.stringify([{ note: evidence, capturedAt: new Date().toISOString(), via: 'agent-cli' }])
const client = await pool.connect()
try {
await client.query('BEGIN')
await client.query(
`UPDATE shipping_verifications SET status=$1,owner_id=COALESCE(owner_id,$2),verified_by_id=CASE WHEN $3 THEN $2 ELSE verified_by_id END,
evidence=CASE WHEN $4<>'' THEN $5::jsonb ELSE evidence END,notes=CASE WHEN $6<>'' THEN $6 ELSE notes END,
completed_at=CASE WHEN $3 THEN NOW() ELSE NULL END,updated_at=NOW()
WHERE id=$7 AND feature_id=$8`,
[status, me, completing, evidence, proof, notes, squareId, featureId],
)
if (status === 'failed') {
await client.query(
`INSERT INTO shipping_regressions
(id,feature_id,source_verification_id,title,kind,expected,status,created_by)
VALUES ($1,$2,$3,$4,'manual_replay',$5,'failing',$6)
ON CONFLICT (source_verification_id) WHERE source_verification_id IS NOT NULL
DO UPDATE SET status='failing',updated_at=NOW()`,
[`rg-${randomUUID()}`, featureId, squareId, `Replay failed square: ${square.title}`,
'The behavior proven by this square remains true', me],
)
await client.query(
`INSERT INTO shipping_friction_reports
(id,company_id,feature_id,reporter_id,source,source_key,title,description,severity,frequency,status,evidence)
VALUES ($1,$2,$3,$4,'verification',$5,$6,$7,'high','once','open',$8::jsonb)
ON CONFLICT (company_id,source_key) WHERE source_key IS NOT NULL
DO UPDATE SET occurrence_count=shipping_friction_reports.occurrence_count+1,
last_seen_at=NOW(),updated_at=NOW(),status='open',evidence=EXCLUDED.evidence`,
[`fr-${randomUUID()}`, companyId, featureId, me, `verification:${squareId}`,
`Verification failed: ${square.title}`,
'An agent-reported proof failed and was promoted into friction plus a replayable regression.', proof],
)
}
await client.query(`INSERT INTO shipping_events (id,company_id,feature_id,actor_id,kind,data) VALUES ($1,$2,$3,$4,'verification.updated',$5::jsonb)`, [`se-${randomUUID()}`, companyId, featureId, me, JSON.stringify({ id: squareId, status, via: 'agent-cli' })])
await client.query('COMMIT')
} catch (error) {
await client.query('ROLLBACK').catch(() => {})
throw error
} finally { client.release() }
return ok(`${squareId} (${square.title}) → ${status}${evidence ? ' with evidence recorded' : ''}.`)
}
if (action === 'friction') {
const featureRaw = parsed.positional[1]
const title = parsed.positional[2]?.trim()
if (!featureRaw || !title) return err('usage: ship friction <feature_id|none> "<title>" [--description "..."] [--severity low|medium|high|critical]')
const featureId = featureRaw === 'none' ? null : featureRaw
if (featureId) {
const { rows } = await pool.query(`SELECT 1 FROM shipping_features WHERE id=$1 AND company_id=$2`, [featureId, companyId])
if (!rows[0]) return err('shipping feature not found')
}
const severity = typeof parsed.flags.severity === 'string' && ['low','medium','high','critical'].includes(parsed.flags.severity) ? parsed.flags.severity : 'medium'
const id = `fr-${randomUUID()}`
await pool.query(
`INSERT INTO shipping_friction_reports (id,company_id,feature_id,reporter_id,source,title,description,severity)
VALUES ($1,$2,$3,$4,'agent-cli',$5,$6,$7)`,
[id, companyId, featureId, me, title, typeof parsed.flags.description === 'string' ? parsed.flags.description : title, severity],
)
return ok(`Captured friction ${id}${featureId ? ` on ${featureId}` : ''}. It is now visible in the Ship workspace.`)
}
if (action === 'regression') {
const featureId = parsed.positional[1]
const title = parsed.positional[2]?.trim()
if (!featureId || !title) return err('usage: ship regression <feature_id> "<title>" [--command "..."] [--expected "..."]')
const { rows } = await pool.query(`SELECT 1 FROM shipping_features WHERE id=$1 AND company_id=$2`, [featureId, companyId])
if (!rows[0]) return err('shipping feature not found')
const id = `rg-${randomUUID()}`
await pool.query(
`INSERT INTO shipping_regressions (id,feature_id,title,kind,command,expected,status,created_by)
VALUES ($1,$2,$3,$4,$5,$6,'active',$7)`,
[id, featureId, title, typeof parsed.flags.command === 'string' ? 'automated' : 'manual_replay',
typeof parsed.flags.command === 'string' ? parsed.flags.command : null,
typeof parsed.flags.expected === 'string' ? parsed.flags.expected : 'Previously verified behavior remains true', me],
)
return ok(`Created regression asset ${id} on ${featureId}.`)
}
return err('usage: ship list|show|create|square|friction|regression (run cumora help for details)')
}
// Membership system-message + counter helpers live in
// `agents/membership.ts` so the HTTP endpoints (POST /members,
// POST /leave) and the agent CLI share one implementation. Importing
// here re-exposes the names this file already used.
import { addConversationMember, removeConversationMember } from './membership.js'
async function cmdLeave(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
if (!convoId) return err('usage: leave <conversation_id>')
const { rows } = await pool.query<{
kind: string; title: string; company_id: string | null; actor_is_member: boolean
}>(
`SELECT c.kind, c.title, c.company_id,
EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
) AS actor_is_member
FROM conversations c WHERE c.id = $1`,
[convoId, me],
)
const c = rows[0]
if (!c) return err(`unknown conversation ${convoId}`)
if (!c.company_id) return err(`conversation ${convoId} is not attached to a workspace`)
if (c.kind === 'direct') {
return err('cannot leave a direct conversation — use `cumora ack` to mute it from your inbox instead')
}
if (!c.actor_is_member) return err(`${me} is not a member of ${convoId}`)
// Bind authorization to the write itself. If another member revoked us
// after the SELECT above, this must fail closed and must not emit a false
// departure event.
const mutation = await removeConversationMember({
conversationId: convoId,
memberId: me,
actorId: me,
companyId: c.company_id,
allowSoleMember: true,
kind: 'left',
})
if (!mutation) return err(`${me} is no longer a member of ${convoId}`)
const next = mutation.members
return ok(`left "${c.title}" (${convoId}); ${next.length} member(s) remain`, [{
event: 'conversation.membership_changed',
command: 'leave',
action: 'left',
conversationId: convoId,
actorId: me,
participantId: me,
companyId: c.company_id ?? undefined,
systemMessageId: mutation.systemMessageId,
memberCount: next.length,
visibleToUser: true,
}])
}
async function cmdInvite(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
const target = parsed.positional[1]
if (!convoId || !target) return err('usage: invite <conversation_id> <member_id>')
if (target === me) return err(`${me} is already the one inviting`)
const { rows } = await pool.query<{
kind: string; title: string; company_id: string | null;
actor_is_member: boolean; target_is_member: boolean
}>(
`SELECT c.kind, c.title, c.company_id,
EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
) AS actor_is_member,
EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $3
) AS target_is_member
FROM conversations c WHERE c.id = $1`,
[convoId, me, target],
)
const c = rows[0]
if (!c) return err(`unknown conversation ${convoId}`)
if (!c.company_id) return err(`conversation ${convoId} is not attached to a workspace`)
if (c.kind === 'direct') {
return err('cannot invite into a direct conversation — use `cumora pull-group` to start a fresh thread')
}
if (!c.actor_is_member) return err(`${me} is not a member of ${convoId} — can't invite into a group you're not in`)
if (c.target_is_member) return ok(`${target} is already a member of ${convoId}`)
// Verify the invitee exists in this tenant.
const tenant = c.company_id
if (tenant) {
const { rows: pp } = await pool.query<{ id: string }>(
`SELECT id FROM participants WHERE id = $1 AND company_id = $2 LIMIT 1`,
[target, tenant],
)
if (!pp[0]) return err(`${target} is not a participant in this workspace`)
}
const mutation = await addConversationMember({
conversationId: convoId,
memberId: target,
actorId: me,
companyId: c.company_id,
})
if (!mutation) return err(`${me} is no longer a member of ${convoId} — invite cancelled`)
const next = mutation.members
return ok(`invited ${target} into "${c.title}" (${convoId}); ${next.length} member(s) total`, [{
event: 'conversation.membership_changed',
command: 'invite',
action: 'joined',
conversationId: convoId,
actorId: me,
participantId: target,
companyId: c.company_id ?? undefined,
systemMessageId: mutation.systemMessageId,
memberCount: next.length,
visibleToUser: true,
}])
}
async function cmdKick(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
const target = parsed.positional[1]
if (!convoId || !target) return err('usage: kick <conversation_id> <member_id>')
if (target === me) return err('use `cumora leave <convo_id>` to leave a group yourself')
const { rows } = await pool.query<{
kind: string; title: string; company_id: string | null; member_count: number;
actor_is_member: boolean; target_is_member: boolean
}>(
`SELECT c.kind, c.title, c.company_id,
(SELECT COUNT(*)::int FROM conversation_members member
WHERE member.conversation_id = c.id) AS member_count,
EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
) AS actor_is_member,
EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $3
) AS target_is_member
FROM conversations c WHERE c.id = $1`,
[convoId, me, target],
)
const c = rows[0]
if (!c) return err(`unknown conversation ${convoId}`)
if (!c.company_id) return err(`conversation ${convoId} is not attached to a workspace`)
if (c.kind === 'direct') return err('cannot kick from a direct conversation')
if (!c.actor_is_member) return err(`${me} is not a member of ${convoId} — can't kick from a group you're not in`)
if (!c.target_is_member) return err(`${target} is not a member of ${convoId}`)
const nextCount = c.member_count - 1
// Refuse to leave a group with just one member as a side-effect of kick —
// if there'd only be the actor left, that's "everyone else gone", which
// is fine, but require explicit confirmation via --confirm-empty for the
// case where the kick removes the LAST other member. Cheap guard against
// accidental group-clearing.
if (nextCount === 1 && !parsed.flags['confirm-empty']) {
return err(`kicking ${target} would leave only ${me} in this group; pass --confirm-empty if that's intended`)
}
// Report what the row actually holds now, not the array we predicted from a
// read taken before the guards above. The actor predicate is part of this
// UPDATE, so a concurrent revocation cannot leave this stale kick authorized.
const confirmedEmpty = Boolean(parsed.flags['confirm-empty'])
const mutation = await removeConversationMember({
conversationId: convoId,
memberId: target,
actorId: me,
companyId: c.company_id,
allowSoleMember: confirmedEmpty,
kind: 'kicked',
})
if (!mutation) {
return err(confirmedEmpty
? `membership changed or ${me} is no longer authorized in ${convoId} — kick cancelled`
: `membership changed, the kick is no longer authorized, or it would leave only ${me}; retry with --confirm-empty if intended`)
}
const remaining = mutation.members
return ok(`kicked ${target} from "${c.title}" (${convoId}); ${remaining.length} member(s) remain`, [{
event: 'conversation.membership_changed',
command: 'kick',
action: 'kicked',
conversationId: convoId,
actorId: me,
participantId: target,
companyId: c.company_id ?? undefined,
systemMessageId: mutation.systemMessageId,
memberCount: remaining.length,
visibleToUser: true,
}])
}
async function cmdReply(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
// Strip any hallucinated <tool_call> XML on the way in too — defense in depth.
const body = joinBodyArgs(parsed, 1)
.replace(/<tool_call>[\s\S]*?<\/tool_call>/gi, '')
.replace(/<function_call>[\s\S]*?<\/function_call>/gi, '')
.trim()
const hasAttachFlag = Boolean(
parsed.flags.attach ||
parsed.flags['generate-image'] ||
parsed.flags['attach-text'] ||
parsed.flags['attach-bytes'],
)
// `--quote / -q <message_id>` makes this reply a direct quote of that
// message. The target must live in the SAME conversation — cross-convo
// quotes would leak content, so the server-side path enforces that too.
const quoteFlag = parsed.flags.quote ?? parsed.flags.q
const quotedMessageId = quoteFlag ? String(quoteFlag).trim() : null
if (!convoId || (!body && !hasAttachFlag)) {
return err('usage: reply <convo_id> "<body>" [--quote <msg_id>] [--attach <url> | --generate-image "<prompt>" [--size square|wide|tall] | --attach-text "<filename>" "<content>" | --attach-bytes "<filename>" --bytes-b64 "<base64>" [--bytes-mime "<mime>"]]')
}
// Agent ids are globally unique, so pin their current tenant here. Human
// callers can belong to several companies; for them the conversation id +
// active participant membership below selects the tenant instead.
const activeAgentCompanyId = await agentCompany(me)
// Friendly preflight only. The final INSERT transaction repeats this
// authorization while holding both the active participant row and the
// conversation row, so a concurrent kick, offboarding, or tenant move
// cannot leave this snapshot authorized at the write boundary.
const { rows: cv } = await pool.query<{
member_count: number; company_id: string; kind: string; actor_is_agent: boolean
}>(
`SELECT (SELECT COUNT(*)::int FROM conversation_members member
WHERE member.conversation_id = c.id) AS member_count,
c.company_id, c.kind,
(requester.kind = 'agent') AS actor_is_agent
FROM conversations c
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind IN ('agent', 'human')
AND requester.departed_at IS NULL
WHERE c.id = $1
AND ($3::text IS NULL OR c.company_id = $3)
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)`,
[convoId, me, activeAgentCompanyId],
)
if (!cv[0]) return err(`conversation ${convoId} not found or no longer authorized`)
const companyId = cv[0].company_id
// ─── Anti-monologue gate ──────────────────────────────────────────
// In multi-party conversations (3+ members), an agent can't post a
// second message in a row before anyone else has spoken. The most
// common failure mode this catches: agent posts plan → same agent
// immediately posts continuation → next agent posts THEIR version of
// the same plan → loop. Group-chat real-people don't double-text
// their own thread before anyone responds; agents do, constantly,
// because each wake-up is a fresh "should I respond?" decision with
// no global stop-signal.
//
// Exemptions:
// - DMs (2-member convos): legit follow-ups like "oh also one more
// thing" happen naturally. Keep them open.
// - 10-minute escape valve: if your own last message has been
// sitting there for 10+ minutes without anyone biting, the thread
// has gone quiet and a nudge is fair game.
//
// Bypass via `--continue` / `--also`: rare cases where the agent
// genuinely has to add to its own previous message (e.g. an
// urgent correction, an attachment that didn't fit). The flag
// forces the agent to commit deliberately rather than absent-
// mindedly continuing to monologue.
const monologueBypass = Boolean(parsed.flags.continue || parsed.flags.also)
// Announce-then-deliver. The operating rules REQUIRE an intent message
// before long work ("Drafting the email now"), posted as a SEPARATE
// `cumora reply`, then the result in the SAME turn. In a group of three or
// more that intent message is the room's last message and seconds old,
// which is exactly what the gate below refuses — so the flow the product
// mandates was the flow it rejected, and the answer was lost.
//
// A second post from the SAME run is that delivery. A post from a LATER run
// is the agent waking up and deciding to talk again, which is what the gate
// was built to stop ("each wake-up is a fresh 'should I respond?' decision
// with no global stop-signal"). The run id is the only thing that tells them
// apart, so it now reaches this process as CUMORA_RUN_ID.
//
// Capped at two posts per turn per conversation: announce + deliver. A third
// is monologuing again and still needs --continue.
//
// Deliberately NOT folded into `monologueBypass`: that flag also disables
// the freshness preflight further down, and a continuation must still be
// checked against a room that moved while we were working.
const turnRunId = (process.env.CUMORA_RUN_ID ?? '').trim()
const sameTurnDelivery = !monologueBypass && turnRunId && cv[0].actor_is_agent
? await readTurnPost(me, convoId).then(
(rec) => Boolean(rec && rec.runId === turnRunId && rec.posts < MAX_POSTS_PER_TURN_PER_CONVERSATION),
)
: false
if (!monologueBypass && !sameTurnDelivery && cv[0].actor_is_agent && cv[0].member_count > 2) {
const { rows: lastMsg } = await pool.query<{ author_id: string; created_at: string }>(
`SELECT author_id, created_at FROM messages
WHERE conversation_id = $1
ORDER BY sequence DESC LIMIT 1`,
[convoId],
)
if (lastMsg[0] && lastMsg[0].author_id === me) {
const ageMs = Date.now() - new Date(lastMsg[0].created_at).getTime()
const MIN_GAP_MS = 10 * 60 * 1000
if (ageMs < MIN_GAP_MS) {
const ageSec = Math.max(1, Math.round(ageMs / 1000))
return err(
`you already posted in ${convoId} ${ageSec}s ago and nobody has replied yet — ` +
`you can't post again until someone else speaks. ` +
`If you have more to say, fold it into your next message when someone responds. ` +
`Right now: react on the relevant message (cumora react <message_id> 👀 / ✅ / 🎯), ` +
`or set_turn_status done and step back. ` +
`Override only if it's truly urgent: rerun with --continue.`
)
}
}
}
// Email conversations: auto-promote into a real email reply rather than
// writing a plain text message. The agent's LLM was previously expected
// to know to call `cumora email reply <message_id>` for email threads —
// unreliable, and the external recipient never saw the reply when it
// forgot. This converges both reply surfaces (chat + email) on the
// sendViaProvider path. autoSubmitted=true because every CLI reply is
// agent-driven by construction.
if (cv[0].kind === 'email') {
const attachmentError = rejectsEmailAttachmentFlags(parsed)
if (attachmentError) return attachmentError
if (!body) {
return err('email replies require a non-empty body')
}
try {
const { replyInEmailConversation } = await import('../email.js')
const result = await replyInEmailConversation({
conversationId: convoId, companyId, authorId: me, body, autoSubmitted: true,
})
const mockTag = result.mock ? ' (mock)' : ''
if (result.transportStatus !== 'sent') {
return err(`email reply persisted as failed: ${result.error} · ${result.messageId}`, 1)
}
return ok(`replied via email${mockTag} · ${result.messageId}`, [{
event: 'message.posted',
command: 'reply',
medium: 'email',
conversationId: convoId,
messageId: result.messageId,
authorId: me,
companyId,
visibleToUser: true,
transportStatus: result.transportStatus,
mock: result.mock,
}])
} catch (e) {
return err(`email auto-promote failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
// ─── FRESHNESS PREFLIGHT ───────────────────────────────────────────
// Goal: stop the classic collision (Iris and Marcus both posting "3" in
// a counting game). Mechanism: read this agent's "seen seq" boundary
// from Redis (the one loadInbox / cmdMessages / cmdGlance recorded), and
// if any non-self message in this conversation has a seq > baseline,
// HOLD the send and surface the held messages so the agent re-decides.
//
// Why this lives in Redis (NOT in conversation_reads.last_read_at like
// the a6e69aa attempt that we reverted): bumping last_read_at corrupted
// the inbox SELECT cursor and silent-hung the daemon. This version is
// strictly Redis-only with explicit fail-open semantics — if Redis is
// down or the key is unset, getSeen returns 0 and the preflight skips
// (we'd rather risk one collision than hang the agent).
//
// Bypasses match the monologue gate above + send-anyway override:
// - 2-member DMs: parallel typing is normal, both replies are valid
// - --continue / --also: agent has explicit "this is a follow-up" intent
// - --send-anyway: explicit override after the agent re-decided that
// the original draft is STILL correct given the new context.
// ARMED ONLY BY A PRIOR HOLD (hold token, see below) — a preemptive
// --send-anyway on a first attempt is ignored and the preflight runs.
// - email convos: already returned above via the auto-promote path
//
// What this does NOT catch (separate fix, 0eaf04c): brain-level out-of-
// order races where the SECOND agent hasn't INSERTed yet (Nova posting 6
// BEFORE Iris's 5 lands — both Nova's and Iris's prefights pass because
// neither has anything newer than Marcus's 4 in the messages table at
// their respective INSERT moments). That's the "NEVER SKIP AHEAD" prompt
// rule's job. This preflight catches POST-INSERT races (both already
// tried to insert the same slot — the second one sees the first).
//
// Why the hold token exists (2026-06-11/12 double-deliverable incidents):
// agents learned to pass --send-anyway PREEMPTIVELY to save a round-trip
// ("compile story → reply --send-anyway" with zero glances), which made
// this entire preflight a no-op exactly when it mattered — a peer had
// posted the same deliverable 40s earlier and the HELD envelope would
// have shown it. The token turns the flag from a free pass into an
// acknowledgement: it only works AFTER this server has actually shown
// the agent a HELD envelope for this conversation.
const sendAnywayFlag = Boolean(parsed.flags['send-anyway'])
const replyHoldScope = `reply:${convoId}`
const preflightApplies = !monologueBypass && cv[0].member_count > 2
const heldAck = sendAnywayFlag
? await consumeHold(me, replyHoldScope)
: { armed: false, heldUpToSeq: null }
let sendAnywayArmed = heldAck.armed
if (sendAnywayArmed && preflightApplies && heldAck.heldUpToSeq !== null) {
// The token acknowledges the room AS SHOWN in that HELD envelope — up
// to peer seq `heldUpToSeq`. If the room moved past it, the
// acknowledgement is void: the flag must never skip the gates for
// messages the agent has NOT been shown. (2026-07-08 counting game:
// Saga was HELD at 17:30 drafting "2", yielded — banking the token —
// and a NEW turn's preemptive --send-anyway consumed it at 17:34,
// shipping a stale "6" past Nova's 6 and Iris's 7 sight unseen.)
const { rows: newer } = await pool.query<{
sequence: number; author_id: string; author_name: string | null; body: string
}>(
`SELECT m.sequence, m.author_id, m.body,
COALESCE(p.name, u.display_name) AS author_name
FROM messages m
LEFT JOIN participants p ON p.id = m.author_id
LEFT JOIN users u ON u.id = m.author_id
WHERE m.conversation_id = $1
AND m.author_id <> $2
AND m.sequence > $3
ORDER BY m.sequence ASC
LIMIT 8`,
[convoId, me, heldAck.heldUpToSeq],
)
if (newer.length > 0) {
sendAnywayArmed = false
const maxHeldSeq = newer[newer.length - 1].sequence
// Shown ⇒ part of the agent's world-state: advance the SEEN CURSOR past
// what THIS envelope shows and arm a fresh token bound to the new
// high-water seq, so a considered re-run works without re-holding on
// these same rows (the hold envelope itself advances the seen cursor).
await recordSeen(me, convoId, maxHeldSeq)
await recordHold(me, replyHoldScope, maxHeldSeq)
const lines = newer.map((r) =>
` [seq=${r.sequence}] ${r.author_name || r.author_id}: ${r.body.replace(/\s+/g, ' ').slice(0, 200)}`
).join('\n')
return err(
`HELD — your reply NOT sent. Your --send-anyway acknowledged an EARLIER hold, but the room has moved since: ` +
`${newer.length} newer message(s) in ${convoId} you have not been shown:\n${lines}\n\n` +
`Re-decide against THIS state — usually your draft is now wrong ` +
`(counting: post the next number after the latest, not the one you drafted; ` +
`relay/chain: continue from the latest entry; if a peer above already delivered what you were about to deliver, stand down or react instead). ` +
`Run \`cumora reply <convoId> "<revised body>"\` with your new decision, ` +
`or rerun with --send-anyway only if your draft is STILL correct despite these messages (rare).`,
2,
)
}
}
if (!sendAnywayArmed && preflightApplies) {
// Freshness race detection — the SEEN-CURSOR model: a per-(agent,convo)
// SEEN CURSOR — "the highest peer
// seq this agent has actually been SHOWN" — advanced by every surface that
// puts rows in front of the model: the wake brief (/runtime/inbox), cumora
// glance, cumora messages, and HELD envelopes themselves. HOLD iff a peer
// message exists that the agent has NOT been shown; once shown, a plain
// re-send passes with no flag ritual (the hold envelope carries the
// cursor forward, so resend-after-shown goes through cleanly).
//
// This replaces the compose-anchor (turn-start timestamp, deliberately NOT
// advanced by glance). The anchor guaranteed a FIRST-attempt HOLD in any
// busy room even when the agent had already read everything — transcripts:
// "Same HELD — those messages are what I already glanced → send-anyway" —
// costing 1-2 extra big-model round-trips per reply. The
// one dup the anchor caught that a seen-cursor admits (glance shows a
// peer's just-landed post and the agent still posts the SAME item) is
// covered by the VERBATIM-DUP gate below.
//
// baseline === 0 (never read / Redis TTL expired / Redis down) fails OPEN,
// as before — the wake brief re-establishes the cursor at turn start.
const baseline = await getSeen(me, convoId)
if (baseline > 0) {
const { rows: newer } = await pool.query<{
sequence: number; author_id: string; author_name: string | null; body: string
}>(
`SELECT m.sequence, m.author_id, m.body,
COALESCE(p.name, u.display_name) AS author_name
FROM messages m
LEFT JOIN participants p ON p.id = m.author_id
LEFT JOIN users u ON u.id = m.author_id
WHERE m.conversation_id = $1
AND m.author_id <> $2
AND m.sequence > $3
ORDER BY m.sequence ASC
LIMIT 8`,
[convoId, me, baseline],
)
if (newer.length > 0) {
// Shown ⇒ seen: advance the cursor past what this envelope shows so a
// considered re-send passes instead of re-holding on the same rows —
// the hold envelope itself advances the cursor. If MORE peers
// post after this, the re-attempt holds again on the truly-new ones.
const maxHeldSeq = newer[newer.length - 1].sequence
await recordSeen(me, convoId, maxHeldSeq)
const lines = newer.map((r) =>
` [seq=${r.sequence}] ${r.author_name || r.author_id}: ${r.body.replace(/\s+/g, ' ').slice(0, 200)}`
).join('\n')
// Arm the hold token: NOW the agent has actually been shown the
// held context, so a follow-up --send-anyway is a real
// acknowledgement rather than a preemptive skip. Bound to the max
// shown seq — if the room moves again before the re-run, the
// acknowledgement is void (see the staleness check above).
await recordHold(me, replyHoldScope, maxHeldSeq)
return err(
`HELD — your reply NOT sent. ${newer.length} newer message(s) in ${convoId} you have not been shown:\n${lines}\n\n` +
(sendAnywayFlag
? `(Your --send-anyway was IGNORED: it only acknowledges a HOLD you have already been shown — passing it preemptively does nothing.)\n`
: '') +
`You have now seen these — re-decide against THIS state, then simply re-send: a plain \`cumora reply <convoId> "<revised body>"\` will go through (no flag needed). ` +
`Usually your draft is now wrong (counting: post the next number after the latest; relay/chain: continue from the latest entry; ` +
`if a peer above already delivered what you were about to deliver, the work is DONE — stand down or react instead).`,
2, // exit code 2 = "held, retry with different content" (distinct from 1 = generic error)
)
}
}
// ─── VERBATIM-DUP GATE ───────────────────────────────────────────
// The freshness preflight above catches "peer posted AFTER my baseline /
// anchor." But during aggressive lapping (team-adapts pushing multiple
// agents to cover) two agents can independently draft the SAME content
// before either's anchor or baseline is set against the other — both
// glance, see the same state, both decide on the same NEXT-ITEM.
// Seq-based preflight passes (no peer message > my baseline) but the
// draft is verbatim identical to a recent peer post. Real teammates
// would say "oh, X beat me to it" — they don't immediately repeat the
// most-recent thing said. Encode that as a HARD gate: if my draft body
// (trimmed) matches the IMMEDIATELY PREVIOUS non-self peer message
// verbatim, HOLD. This caught two T7 collisions (你-你, 了-了) where
// both rates of slot-coverage races would have shipped duplicate
// characters into the chain.
//
// Scope: only the LAST peer message — narrowest principled rule, no
// scenario examples. If a peer 5 messages ago said "yes" and you're
// also drafting "yes" in response to something new, that's not noise;
// only the immediately-prior dup is.
const draftBodyTrimmed = body.trim()
if (draftBodyTrimmed.length > 0) {
const { rows: lastPeer } = await pool.query<{ sequence: number; author_id: string; author_name: string | null; body: string }>(
`SELECT m.sequence, m.author_id, m.body,
COALESCE(p.name, u.display_name) AS author_name
FROM messages m
LEFT JOIN participants p ON p.id = m.author_id
LEFT JOIN users u ON u.id = m.author_id
WHERE m.conversation_id = $1
AND m.author_id <> $2
AND m.kind = 'text'
ORDER BY m.sequence DESC
LIMIT 1`,
[convoId, me],
)
if (lastPeer.length > 0 && lastPeer[0].body.trim() === draftBodyTrimmed) {
// Advance baseline past this peer post so re-attempt with NEW content
// doesn't HOLD on the same row again.
await recordSeen(me, convoId, lastPeer[0].sequence)
await recordHold(me, replyHoldScope, lastPeer[0].sequence)
const peer = lastPeer[0]
return err(
`HELD — your draft is VERBATIM IDENTICAL to the most recent peer post in ${convoId}:\n` +
` [seq=${peer.sequence}] ${peer.author_name || peer.author_id}: ${peer.body.replace(/\s+/g, ' ').slice(0, 200)}\n\n` +
`They beat you to it. Real teammates don't immediately repeat the same thing — pick a different angle, the NEXT item in a sequence, or stay silent if their post already covers what you wanted to say.`,
2,
)
}
}
}
// If quoting, prove the target exists in THIS conversation. If it doesn't,
// fail loudly — unlike the HTTP path (which is forgiving in case of a
// delete race), the agent should know its quote pointer is bad so it can
// fix the call rather than ship a silently-quoteless reply.
let resolvedQuotedId: string | null = null
let quotedSummary: { id: string; authorId: string; authorName: string; body: string; sequence: number } | null = null
if (quotedMessageId) {
// Resolve the quoted author's DISPLAY NAME, not just the id. The author can
// be an agent/human in `participants` OR a human keyed in `users` (their
// user id), so we COALESCE across both — otherwise the quote card shows a
// raw id like `u-f92aa4ac-...` instead of the person's name.
const { rows: qr } = await pool.query<{
id: string; author_id: string; author_name: string | null; body: string; sequence: number
}>(
`SELECT m.id, m.author_id, m.body, m.sequence,
COALESCE(p.name, u.display_name) AS author_name
FROM messages m
LEFT JOIN participants p ON p.id = m.author_id
LEFT JOIN users u ON u.id = m.author_id
WHERE m.id = $1 AND m.conversation_id = $2`,
[quotedMessageId, convoId],
)
if (!qr[0]) {
return err(`--quote target ${quotedMessageId} not found in ${convoId}`)
}
resolvedQuotedId = qr[0].id
quotedSummary = {
id: qr[0].id,
authorId: qr[0].author_id,
authorName: qr[0].author_name || qr[0].author_id,
body: qr[0].body.slice(0, 240),
sequence: qr[0].sequence,
}
}
// Optional attachment in three flavors:
// --attach <url> — share an existing URL (no key, won't re-sign)
// --generate-image "<prompt>" — call the image model, upload to storage,
// attach with signed URL + key
// --attach-text "<filename>" "..." — save the content as a real file and attach it
type AgentAttachment = {
url: string; name: string; kind: 'img' | 'file';
mime?: string; size?: number; key?: string;
}
let attachment: AgentAttachment | null = null
if (parsed.flags['generate-image']) {
const prompt = String(parsed.flags['generate-image']).trim()
if (!prompt) return err('--generate-image requires a non-empty prompt')
// Same tenant-scoped claim as `cumora image generate` — the image
// model doesn't care whether the call came via reply or as a
// standalone, but peer agents do.
const blocked = await tryClaimTenantWork(companyId, me, 'image-generate', prompt)
if (blocked) return blocked
try {
attachment = await generateAndUploadImage({
prompt,
size: String(parsed.flags.size ?? 'square'),
tenant: companyId,
agentId: me,
})
} catch (e) {
return err(`image generation failed: ${e instanceof Error ? e.message : String(e)}`)
} finally {
await releaseTenantWork(companyId, me, 'image-generate', prompt)
}
} else if (parsed.flags['attach-text']) {
const filename = String(parsed.flags['attach-text']).trim().slice(0, 200)
// Content comes from the body (which then gets cleared) OR from an
// explicit --attach-text-content. Common case: agent writes the file
// as the body and uses --attach-text to mark it as an attachment.
const content = String(parsed.flags['attach-text-content'] ?? body)
if (!filename || !content) return err('--attach-text requires a filename and content')
attachment = await saveTextAttachment(filename, content, companyId)
} else if (parsed.flags['attach-bytes']) {
const filename = String(parsed.flags['attach-bytes']).trim().slice(0, 200)
const b64 = String(parsed.flags['bytes-b64'] ?? '').trim()
const mime = parsed.flags['bytes-mime']
? String(parsed.flags['bytes-mime']).trim().toLowerCase()
: undefined
if (!filename || !b64) return err('--attach-bytes requires a filename and --bytes-b64 "<base64>"')
try {
attachment = await saveBytesAttachment(filename, b64, mime, companyId)
} catch (e) {
return err(`attach-bytes failed: ${e instanceof Error ? e.message : String(e)}`)
}
} else if (parsed.flags.attach) {
const url = String(parsed.flags.attach)
const name = parsed.flags['attach-name'] ? String(parsed.flags['attach-name']) : url.split('/').pop() ?? 'attachment'
attachment = { url, name, kind: 'img' }
}
// If the body was consumed as the text-file content (no separate
// --attach-text-content flag was passed), suppress it from the
// outgoing message — the file IS the message.
const consumedAsTextContent =
parsed.flags['attach-text'] && !parsed.flags['attach-text-content']
const finalBody = consumedAsTextContent ? '' : body
// Atomically claim next sequence + check verbatim-dup + INSERT, all in
// ONE transaction. The conversation_counters UPSERT takes a row-level
// lock (ON CONFLICT DO UPDATE), and that lock stays held until COMMIT —
// serializing every concurrent cumora-reply to the same convo through
// this critical section. While we hold the lock, we re-check the last
// peer message body against our draft (committed visibility — we'll
// see any peer INSERT that committed before our sequence claim).
// If verbatim-dup, ROLLBACK and return HELD. This closes the TOCTOU
// race that the pre-INSERT verbatim check has — two agents 2s apart
// both passing read-phase, then both writing.
const messageId = `m-${randomUUID()}`
let sequence: number
const txClient = await pool.connect()
try {
await txClient.query('BEGIN')
const activeActor = await txClient.query(
`SELECT id FROM participants
WHERE id = $1 AND company_id = $2
AND kind IN ('agent', 'human') AND departed_at IS NULL
FOR SHARE`,
[me, companyId],
)
const lockedConversation = activeActor.rowCount
? await txClient.query(
`SELECT c.id FROM conversations c
WHERE c.id = $1 AND c.company_id = $2
FOR SHARE OF c`,
[convoId, companyId],
)
: null
const { rows: authorizedRows } = lockedConversation?.rowCount
? await txClient.query<{ member_count: number }>(
`SELECT COUNT(*)::int AS member_count
FROM conversation_members
WHERE conversation_id = $1 AND company_id = $2
HAVING BOOL_OR(participant_id = $3)`,
[convoId, companyId, me],
)
: { rows: [] as Array<{ member_count: number }> }
if (!authorizedRows[0]) {
await txClient.query('ROLLBACK')
return err(`conversation ${convoId} no longer authorized; reply cancelled`)
}
const { rows: seqRow } = await txClient.query<{ seq: number }>(
`INSERT INTO conversation_counters (conversation_id, next_sequence)
VALUES ($1, 2)
ON CONFLICT (conversation_id) DO UPDATE SET next_sequence = conversation_counters.next_sequence + 1
RETURNING next_sequence - 1 AS seq`,
[convoId],
)
sequence = seqRow[0]?.seq ?? 1
// Atomic verbatim-dup re-check inside the lock: if a peer INSERT
// committed during our compose+pre-INSERT window, we see it now.
// The pre-INSERT check above is still useful — it short-circuits
// most cases and shows the held content; this one closes the race.
//
// NOTE: this check IGNORES --send-anyway and the 2-member-DM bypass.
// Posting content verbatim-identical to the immediately-prior peer
// message has NO legitimate use case — even in a DM, repeating the
// other party's last sentence verbatim is noise. The other preflight
// gate (the seq-baseline seen-cursor) IS bypassable by --send-anyway
// (the agent may legitimately answer a specific @-mention despite
// post-baseline side-traffic), but verbatim-content-dup is a hard no.
// T9 showed an agent using --send-anyway to force a verbatim dup that
// it had explicitly internalized as a "standing close play"; the
// server has to enforce.
// NOTE: this is deliberately NOT gated on !monologueBypass. --continue / --also
// is a "follow up on MY OWN messages" intent; it must never let an agent post a
// verbatim duplicate of a PEER's immediately-prior message. (Observed 2026-07-26:
// ethan was correctly HELD on "4", then re-sent with --continue and the dup landed
// next to olivia's "4" — because the old `!monologueBypass` here let it through,
// contradicting this check's own "verbatim-dup is a hard no, the server enforces"
// contract.) The peer-only query below already exempts genuine self-monologue: a
// real follow-up isn't verbatim-identical to a recent PEER post, so it still passes.
if (authorizedRows[0].member_count > 2) {
const draftBodyTrimmed = body.trim()
if (draftBodyTrimmed.length > 0) {
const { rows: lastPeer } = await txClient.query<{ sequence: number; author_id: string; body: string }>(
`SELECT sequence, author_id, body FROM messages
WHERE conversation_id = $1 AND author_id <> $2 AND kind = 'text'
ORDER BY sequence DESC LIMIT 1`,
[convoId, me],
)
if (lastPeer.length > 0 && lastPeer[0].body.trim() === draftBodyTrimmed) {
await txClient.query('ROLLBACK')
await recordSeen(me, convoId, lastPeer[0].sequence)
await recordHold(me, replyHoldScope, lastPeer[0].sequence)
return err(
`HELD — verbatim duplicate of the immediately-prior peer post in ${convoId}:\n` +
` [seq=${lastPeer[0].sequence}] ${lastPeer[0].author_id}: ${lastPeer[0].body.replace(/\s+/g, ' ').slice(0, 200)}\n\n` +
`They posted the exact same content${sendAnywayFlag ? ' (and --send-anyway does NOT bypass this check — verbatim-dup is never legitimate)' : ''}. Real teammates don't immediately repeat the same word. Pick the NEXT item, a different angle, or stay silent if their post already covers what you wanted.`,
2,
)
}
}
}
await txClient.query(
`INSERT INTO messages (id, conversation_id, author_id, kind, body, sequence, attachment, attachments, quoted_message_id, company_id)
VALUES ($1,$2,$3,'text',$4,$5,$6::jsonb,$7::jsonb,$8,$9)`,
[messageId, convoId, me, finalBody, sequence, attachment ? JSON.stringify(attachment) : null,
attachment ? JSON.stringify([attachment]) : '[]', resolvedQuotedId, companyId],
)
await txClient.query(`UPDATE conversations SET updated_at = NOW() WHERE id = $1`, [convoId])
await txClient.query(
`INSERT INTO conversation_reads (user_id, conversation_id, last_read_at)
VALUES ($1, $2, NOW())
ON CONFLICT (user_id, conversation_id) DO UPDATE SET last_read_at = NOW()`,
[me, convoId],
)
await enqueueBroadcast(txClient, CH_MESSAGE_NEW, {
type: 'message.new',
conversationId: convoId,
companyId,
message: {
id: messageId,
conversationId: convoId,
authorId: me,
kind: 'text',
body: finalBody,
sequence,
at: new Date().toISOString(),
attachment: attachment ?? undefined,
attachments: attachment ? [attachment] : [],
quotedMessageId: resolvedQuotedId ?? undefined,
quoted: quotedSummary
? {
id: quotedSummary.id,
authorId: quotedSummary.authorId,
authorName: quotedSummary.authorName,
kind: 'text',
body: quotedSummary.body,
sequence: quotedSummary.sequence,
}
: undefined,
},
})
await txClient.query('COMMIT')
nudgeRealtimeOutbox()
} catch (e) {
await txClient.query('ROLLBACK').catch(() => { /* already failed */ })
throw e
} finally {
txClient.release()
}
// The row is durable now, so the phone can be told. Fire-and-forget for the
// same reason the HTTP route's dispatch is: a push must never hold up the
// reply. Without this an agent's answer reached the websocket and the desktop
// toast and no phone at all — the surface a human is on when they ask a
// question and lock the screen.
void dispatchMessagePush({
conversationId: convoId,
authorId: me,
messageId,
body: finalBody,
companyId,
})
// Advance the Redis "seen" boundary to my own just-inserted seq, so the
// freshness preflight on my NEXT cumora reply compares against the post-
// insertion state (peer messages with seq <= mine are "things I obviously
// saw"; only seq > mine would trip a HOLD). Pure Redis side-effect — does
// NOT touch conversation_reads.last_read_at or anything else loadInbox
// depends on.
await recordSeen(me, convoId, sequence).catch((error) => {
console.warn(`[reply] message ${messageId} committed but seen-boundary update failed`, error)
})
// Remember which run posted this, so the announce-then-deliver exemption
// above can recognise the delivery that follows an intent message — and
// stop recognising it after the second post.
if (turnRunId) await recordTurnPost(me, convoId, turnRunId)
// Drop any lingering hold token: this send committed WITHOUT the
// override, so a hold acknowledged-but-unused must not arm a later
// preemptive --send-anyway in this conversation.
void clearHold(me, replyHoldScope)
// A new message advances the conversation — the stall-state has changed,
// so any prior "give up on this stalled state" fallback-decline counter
// is now stale; clear it so a future stall (if it stalls again later) gets
// a fresh budget of fallback attempts. Fire-and-forget; if it fails the
// worst case is the counter TTLs naturally in 45min.
void (await import('./agenda.js')).resetStallNudgeDeclines(convoId)
const attachmentNote = attachment
? ` · attached ${attachment.kind} "${attachment.name}"`
: ''
const quoteNote = resolvedQuotedId ? ` · quoted ${resolvedQuotedId}` : ''
return ok(`sent (${messageId}, seq ${sequence})${attachmentNote}${quoteNote}`, [{
event: 'message.posted',
command: 'reply',
medium: 'chat',
conversationId: convoId,
messageId,
sequence,
authorId: me,
companyId,
visibleToUser: true,
attachment: Boolean(attachment),
quotedMessageId: resolvedQuotedId,
}])
}
/* ─── Image / file generation helpers ───────────────────────────────────
* Both helpers return an AgentAttachment ready to drop into the messages
* row. They go through the storage abstraction so URLs are signed when R2
* + signing is active (production), or local paths in dev.
*
* Failure mode: throw — the caller wraps in a try/catch and returns
* a CLI error so the agent's bash() call exits non-zero and the agent
* can pick a different path. */
const IMAGE_SIZE_MAP: Record<string, '1024x1024' | '1536x1024' | '1024x1536'> = {
square: '1024x1024',
wide: '1536x1024',
tall: '1024x1536',
}
async function generateAndUploadImage(opts: {
prompt: string
size: string
/** Tenant for sub2api routing. When null, falls back to the legacy
* shared OPENAI_API_KEY. */
tenant: string | null
/** Agent invoking the tool (for ledger attribution). The peer-agent claim
* on this work uses the same id, so we already have it at every callsite. */
agentId: string
}): Promise<{ url: string; name: string; kind: 'img'; mime: string; size: number; key: string }> {
const size = IMAGE_SIZE_MAP[opts.size] ?? '1024x1024'
// The agent-tool image generation lives on its own purpose so it doesn't
// get pooled with avatar regeneration. Both ultimately hit the same image
// model but the spend driver is very different (per agent action vs per
// agent creation), and the operator will want to slice them apart.
const { getTrackedLlmClient } = await import('./llm-ledger.js')
const client = await getTrackedLlmClient({
purpose: 'agent-image',
companyId: opts.tenant, agentId: opts.agentId,
extras: { size: opts.size, promptPreview: opts.prompt.slice(0, 120) },
})
const r = await client.images.generate({
model: env.OPENAI_IMAGE_MODEL,
prompt: opts.prompt,
size,
n: 1,
})
const first = r.data?.[0]
const b64 = first?.b64_json
const remoteUrl = first?.url
let buf: Buffer
if (b64) {
buf = Buffer.from(b64, 'base64')
} else if (remoteUrl) {
const fetched = await fetchImageBytes(remoteUrl, {
maxBytes: 20 * 1024 * 1024,
timeoutMs: 30_000,
})
if (!fetched.ok) throw new Error(`image API download failed (${fetched.reason})`)
buf = fetched.buffer
} else {
throw new Error('image API returned no data')
}
const { randomUUID } = await import('node:crypto')
const id = randomUUID().replace(/-/g, '')
const key = `attachments/${id}.png`
const url = await storage.put(key, buf, 'image/png')
if (opts.tenant) await grantAttachment(pool, opts.tenant, key)
// Slug the prompt into a friendly filename for the bubble caption.
const slug = opts.prompt
.toLowerCase()
.replace(/[^a-z0-9\s-]+/g, '')
.trim()
.split(/\s+/)
.slice(0, 5)
.join('-')
.slice(0, 40) || 'image'
return {
url,
key,
name: `${slug}.png`,
kind: 'img',
mime: 'image/png',
size: buf.length,
}
}
/** `cumora image generate "<prompt>" [--size square|wide|tall] [--as <id>] [--json]`
* Generates an image with the configured image model (default
* gpt-image-2), uploads it to storage, and returns the signed URL + key
* so the caller can `cumora reply <c> "<body>" --attach <url>` later.
* Decoupled from `reply --generate-image` so an agent can test a
* prompt, look at the result, and discard / regenerate without shipping
* a half-baked image into a conversation. */
async function cmdImage(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const op = parsed.positional[0]
if (op !== 'generate') {
return err('usage: image generate "<prompt>" [--size square|wide|tall] [--as <id>] [--json]')
}
// Allow either `image generate "long prompt with spaces"` (the typical
// quoted form) or `image generate word1 word2 ...` (autocomplete-friendly);
// we just join positional tail.
const prompt = parsed.positional.slice(1).join(' ').trim()
if (!prompt) return err('image generate requires a non-empty prompt')
const size = String(parsed.flags.size ?? 'square')
// Look up the agent's company so sub2api per-user quota tracking works.
// LIMIT 1 — if an agent id exists in multiple companies, we pick any.
// That's a stop-gap; for now no agent runs cross-tenant standalone
// image gen, so a more principled choice is YAGNI.
const { rows: pr } = await pool.query<{ company_id: string | null }>(
`SELECT company_id FROM participants WHERE id = $1 LIMIT 1`,
[me],
)
const tenant = pr[0]?.company_id ?? null
// Tenant-scoped claim by prompt so peer agents don't independently
// burn a second image-gen call on the same idea. Only claim when
// we know the tenant — otherwise the action would slip past the
// dedup table.
if (tenant) {
const blocked = await tryClaimTenantWork(tenant, me, 'image-generate', prompt)
if (blocked) return blocked
}
try {
const att = await generateAndUploadImage({ prompt, size, tenant, agentId: me })
if (parsed.flags.json) return ok(JSON.stringify(att, null, 2))
const dim = size === 'wide' ? '1536×1024'
: size === 'tall' ? '1024×1536'
: '1024×1024'
return ok([
`generated ${dim} · ${Math.round(att.size / 1024)}KB · ${env.OPENAI_IMAGE_MODEL}`,
`name: ${att.name}`,
`url: ${att.url}`,
`key: ${att.key}`,
``,
`attach to a reply with:`,
` cumora reply <convo_id> "<body>" --attach "${att.url}" --attach-name "${att.name}"`,
].join('\n'))
} catch (e) {
return err(`image generation failed: ${e instanceof Error ? e.message : String(e)}`)
} finally {
if (tenant) await releaseTenantWork(tenant, me, 'image-generate', prompt)
}
}
/** Save a base64-encoded blob as a file attachment of ANY type. This is
* the universal escape hatch — text files have their own --attach-text
* helper, images get the --generate-image path, but anything else (PDF,
* zip, audio, binary blob the agent fetched) flows through here. The
* agent provides the bytes as base64 and optionally a mime hint. */
async function saveBytesAttachment(
filename: string,
base64: string,
mimeHint?: string,
tenant?: string,
): Promise<{ url: string; name: string; kind: 'img' | 'file'; mime: string; size: number; key: string }> {
// Generous 32 MB ceiling — same as the user-upload edge. The base64
// wire form is ~33% larger; we decode first then re-check.
const MAX_BYTES = 32 * 1024 * 1024
let buf: Buffer
try {
buf = Buffer.from(base64, 'base64')
} catch {
throw new Error('--bytes-b64 is not valid base64')
}
if (buf.length === 0) throw new Error('--bytes-b64 decoded to zero bytes')
if (buf.length > MAX_BYTES) throw new Error(`attachment too large (${buf.length} > ${MAX_BYTES})`)
const ext = filename.includes('.') ? filename.split('.').pop()!.toLowerCase() : 'bin'
// Mime resolution: explicit hint > ext-based guess > octet-stream.
const mime = mimeHint ?? extToMime(ext) ?? 'application/octet-stream'
// Render as image when the mime says so; everything else is a file card.
const kind: 'img' | 'file' = mime.startsWith('image/') ? 'img' : 'file'
const { randomUUID } = await import('node:crypto')
const id = randomUUID().replace(/-/g, '')
const key = `attachments/${id}.${ext}`
const url = await storage.put(key, buf, mime)
if (tenant) await grantAttachment(pool, tenant, key)
return { url, key, name: filename, kind, mime, size: buf.length }
}
/** Best-effort mime guess from a file extension. Returns null for
* unknowns so the caller can fall back to a generic octet-stream. */
function extToMime(ext: string): string | null {
switch (ext) {
// Images
case 'png': return 'image/png'
case 'jpg':
case 'jpeg': return 'image/jpeg'
case 'webp': return 'image/webp'
case 'gif': return 'image/gif'
case 'svg': return 'image/svg+xml'
// Docs
case 'pdf': return 'application/pdf'
case 'doc': return 'application/msword'
case 'docx': return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
case 'xls': return 'application/vnd.ms-excel'
case 'xlsx': return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
// Archives
case 'zip': return 'application/zip'
case 'tar': return 'application/x-tar'
case 'gz': return 'application/gzip'
// Text / code
case 'txt': return 'text/plain'
case 'md': return 'text/markdown'
case 'csv': return 'text/csv'
case 'json': return 'application/json'
case 'yml':
case 'yaml': return 'application/x-yaml'
case 'toml': return 'application/x-toml'
case 'html': return 'text/html'
// Media
case 'mp3': return 'audio/mpeg'
case 'wav': return 'audio/wav'
case 'mp4': return 'video/mp4'
case 'mov': return 'video/quicktime'
default: return null
}
}
/** Regenerate the calling agent's portrait via the image API. Composes
* the same prompt the HTTP endpoint uses, uploads to storage as
* `avatars/avatar-<id>-<rand>.png`, and stamps `participants.avatar_url`.
* Heavy — image-gen takes several seconds; the bash() tool call will
* block for that long. */
/** `cumora skills <op>` — manage Agent Skills (progressive-disclosure
* capability packs) stored in this agent's workspace under
* `skills/<name>/`. See server/src/agents/skills.ts for the spec. */
async function cmdSkills(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const op = parsed.positional[0] ?? 'list'
if (op === 'list') {
const { loadSkillsIndex } = await import('./skills.js')
const skills = await loadSkillsIndex(me)
if (parsed.flags.json) return ok(JSON.stringify(skills, null, 2))
if (skills.length === 0) {
return ok('(no skills installed — use `cumora skills create <name> "<description>"` to scaffold one)')
}
const lines = skills.map((s) =>
` ${s.name}\n ${s.description}\n → cumora skills read ${s.name}`,
)
return ok(lines.join('\n\n'))
}
if (op === 'read') {
const name = parsed.positional[1]
if (!name) return err('usage: skills read <name> [<sub-path>]')
const subPath = parsed.positional[2]
// No sub-path → load the SKILL.md entry-point. With a sub-path,
// load that bundled file (e.g. `scripts/extract.py`).
const fullPath = subPath ? `skills/${name}/${subPath}` : `skills/${name}/SKILL.md`
const { rows } = await pool.query<{ body: string }>(
`SELECT body FROM agent_workspace WHERE agent_id = $1 AND path = $2 LIMIT 1`,
[me, fullPath],
)
if (!rows[0]) return err(`no such file: ${fullPath}`)
return ok(rows[0].body)
}
if (op === 'create') {
const name = parsed.positional[1]
const description = parsed.positional[2]
if (!name || !description) {
return err('usage: skills create <name> "<description>" (name: lowercase a-z, 0-9, hyphens; description: ≤1024 chars)')
}
const { validateSkillName } = await import('./skills.js')
const nameError = validateSkillName(name)
if (nameError) return err(nameError)
if (description.length > 1024) return err('description must be ≤ 1024 characters')
const path = `skills/${name}/SKILL.md`
const { rows: existing } = await pool.query<{ path: string }>(
`SELECT path FROM agent_workspace WHERE agent_id = $1 AND path = $2 LIMIT 1`,
[me, path],
)
if (existing[0]) return err(`skill "${name}" already exists — use \`cumora workspace edit ${path}\` to modify it, or \`cumora skills delete ${name}\` first`)
const body = `---
name: ${name}
description: ${description}
---
# ${name}
_Write the skill instructions here. Recommended sections: overview,
step-by-step, examples, edge cases. Keep this file under ~500 lines —
move long reference material into \`references/\` files and load them
on demand via \`cumora skills read ${name} references/<file>\`._
`
await pool.query(
`INSERT INTO agent_workspace (agent_id, path, body, company_id, updated_at)
VALUES ($1, $2, $3, $4, NOW())`,
[me, path, body, await agentCompany(me)],
)
return ok(
`created skill "${name}" at ${path}\n\n` +
`flesh it out: cumora workspace edit ${path} "<old>" "<new>"\n` +
`add scripts: cumora workspace write skills/${name}/scripts/<file>.py "<body>"\n` +
`read it back: cumora skills read ${name}`,
[{
event: 'skill.created',
command: 'skills create',
agentId: me,
skillName: name,
path,
}],
)
}
if (op === 'delete') {
const name = parsed.positional[1]
if (!name) return err('usage: skills delete <name>')
const r = await pool.query(
`DELETE FROM agent_workspace
WHERE agent_id = $1 AND (path = $2 OR path LIKE $3)`,
[me, `skills/${name}/SKILL.md`, `skills/${likeLiteral(name)}/%`],
)
if ((r.rowCount ?? 0) === 0) return err(`no such skill: ${name}`)
return ok(`deleted skill "${name}" (${r.rowCount} files removed)`, [{
event: 'skill.deleted',
command: 'skills delete',
agentId: me,
skillName: name,
fileCount: r.rowCount ?? 0,
}])
}
if (op === 'search') {
const query = parsed.positional.slice(1).join(' ').trim()
if (!query) return err('usage: skills search <query>')
const { env } = await import('../env.js')
if (!env.SKILLHUB_URL) return err('SkillHub URL not configured — set SKILLHUB_URL on the server')
try {
const { searchSkillHub } = await import('./skills.js')
const hits = await searchSkillHub(query, env.SKILLHUB_URL)
if (parsed.flags.json) return ok(JSON.stringify(hits, null, 2))
if (hits.length === 0) return ok(`(no skills found matching "${query}")`)
// Two lines per hit so it's scannable; include install command
// verbatim so the agent can paste/run it without thinking.
return ok(hits.map((h) => {
const meta = [h.version && `v${h.version}`, h.author && `by ${h.author}`].filter(Boolean).join(' · ')
return ` ${h.name}${meta ? ` (${meta})` : ''}\n ${h.description}\n → cumora skills install ${h.name}`
}).join('\n\n'))
} catch (e) {
return err(`skills search failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
if (op === 'install') {
const skillId = parsed.positional[1]
if (!skillId) return err('usage: skills install <skill_id>')
try {
const { env } = await import('../env.js')
const { fetchSkillManifest, installSkillFromManifest } = await import('./skills.js')
const manifest = await fetchSkillManifest(skillId, env.SKILLHUB_URL)
const result = await installSkillFromManifest({ agentId: me, manifest })
return ok(
`installed skill "${result.name}" (${result.files} file${result.files === 1 ? '' : 's'})\n` +
`read it with: cumora skills read ${result.name}`,
[{
event: 'skill.installed',
command: 'skills install',
agentId: me,
skillName: result.name,
fileCount: result.files,
source: skillId,
}],
)
} catch (e) {
return err(`skills install failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
return err(
'usage:\n' +
' skills list list installed skills (name + description only)\n' +
' skills read <name> [<sub-path>] load full SKILL.md (or a bundled file)\n' +
' skills create <name> "<description>" scaffold a new skill\n' +
' skills search <query> search the configured SkillHub\n' +
' skills install <id> install a skill from the configured SkillHub\n' +
' skills delete <name> remove a skill and all its files',
)
}
/* ============== email subcommands ==============
* Real external mail. Each agent has an address (auto-minted from the
* agent id + their company slug — see server/src/email.ts). Outbound
* goes through Resend; inbound arrives via the Cloudflare Email Worker
* + /webhooks/email/inbound and is fanned out as `kind='email'`
* conversations. The CLI surface mirrors familiar webmail verbs: send,
* reply, inbox, show, contacts. */
interface EmailContact {
participantId: string | null
name: string
address: string
/** 'agent' | 'human' | 'external' — drives the "who is this" hint. */
kind: 'agent' | 'human' | 'external'
/** The member's function/title (participants.role, e.g. "Designer").
* Null for humans/external contacts who have no role on file. This is
* what lets an agent know WHAT a teammate does, not just their name. */
role?: string | null
}
async function listEmailContacts(
companyId: string,
viewerId: string,
query?: string,
client?: PoolClient,
): Promise<EmailContact[]> {
const out: EmailContact[] = []
const db = client ?? pool
const { computeAgentAddress } = await import('../email.js')
// Optional fuzzy filter. Applied uniformly across name / id / email so a
// single query like "wey" matches an agent's id, a human's display
// name, OR an external email-contacts row. We do the match in JS (after
// each block's SQL) rather than per-table SQL ILIKE so the assembled
// list stays consistent — and so the predicate matches both
// participants.name AND the computed agent address.
const q = query?.trim().toLowerCase() ?? ''
const matches = (c: EmailContact) => !q
|| c.name.toLowerCase().includes(q)
|| c.address.toLowerCase().includes(q)
|| (c.participantId?.toLowerCase().includes(q) ?? false)
|| (c.role?.toLowerCase().includes(q) ?? false)
// 1. Same-tenant agents (excluding the viewer themselves). Include those
// whose participants.email column is still NULL — `/participants` already
// exposes a deterministic address for un-minted agents, so the CLI
// contact list should match (otherwise a fresh agent is invisible until
// someone has emailed them, which is the bootstrap chicken-and-egg).
const { rows: agents } = await db.query<{ id: string; name: string; email: string | null; slug: string; role: string | null }>(
`SELECT p.id, p.name, p.email, p.role, c.slug
FROM participants p
JOIN companies c ON c.id = p.company_id
WHERE p.company_id = $1 AND p.kind = 'agent' AND p.departed_at IS NULL
AND p.id <> $2
ORDER BY p.name ASC`,
[companyId, viewerId],
)
for (const a of agents) {
// Top-level `contacts` is also the workspace roster. Keep local chat
// agents visible when email is disabled instead of silently dropping them.
const address = a.email ?? computeAgentAddress(a.id, a.slug) ?? '(chat only)'
const c: EmailContact = { participantId: a.id, name: a.name, address, kind: 'agent', role: a.role }
if (matches(c)) out.push(c)
}
// 2. Workspace humans (auth email).
const { rows: humans } = await db.query<{ id: string; display_name: string; email: string }>(
`SELECT u.id, u.display_name, u.email
FROM users u
JOIN company_members cm ON cm.user_id = u.id
WHERE cm.company_id = $1 AND u.email IS NOT NULL
ORDER BY u.display_name ASC`,
[companyId],
)
for (const h of humans) {
const c: EmailContact = { participantId: h.id, name: h.display_name, address: h.email, kind: 'human' }
if (matches(c)) out.push(c)
}
// 3. External addresses we've corresponded with. Without a filter we cap
// at the 30 most recent; with a filter we widen the net so a search
// can find older correspondents too (still capped to keep memory bounded).
const limit = q ? 200 : 30
const { rows: ext } = await db.query<{ address: string; display_name: string | null; message_count: number }>(
`SELECT address, display_name, message_count FROM email_contacts
WHERE company_id = $1
ORDER BY last_seen_at DESC LIMIT $2`,
[companyId, limit],
)
for (const e of ext) {
const c: EmailContact = {
participantId: null,
name: e.display_name ?? e.address,
address: e.address,
kind: 'external',
}
if (matches(c)) out.push(c)
}
return out
}
/** Resolve a recipient string the agent typed into a real email address.
* Accepts: a participant id (looked up in same company), a human user
* display id, an explicit "Name <addr>", or a bare address. Returns
* the parsed { addr, name } shape or null if unresolvable. */
async function resolveEmailRecipient(raw: string, viewerCompanyId: string): Promise<{ addr: string; name: string | null } | null> {
// Synthetic external:<addr> ids are inbound-author markers only — they
// come from senders we don't have a participants row for and have no
// routable target by themselves. The agent should write to the bare
// address instead (which lives in `email_contacts` and shows up under
// `cumora email contacts`).
if (raw.startsWith('external:')) return null
const { parseAddress, ensureParticipantAddress } = await import('../email.js')
const direct = parseAddress(raw)
if (direct) return direct
// Participant id lookup. Per-kind delivery target:
// - agent → cumora address (lazy-mint if column still NULL)
// - human → real auth email (so it lands in their personal inbox)
const { rows: pa } = await pool.query<{ name: string; email: string | null; kind: string }>(
`SELECT name, email, kind FROM participants
WHERE id = $1 AND company_id = $2 AND departed_at IS NULL LIMIT 1`,
[raw, viewerCompanyId],
)
if (pa[0]) {
if (pa[0].kind === 'agent') {
if (pa[0].email) return { addr: pa[0].email, name: pa[0].name }
const ensured = await ensureParticipantAddress(raw, viewerCompanyId)
if (ensured) return { addr: ensured.email, name: ensured.displayName }
}
if (pa[0].kind === 'human') {
const { rows: u } = await pool.query<{ email: string | null }>(
`SELECT email FROM users WHERE id = $1 LIMIT 1`, [raw],
)
if (u[0]?.email) return { addr: u[0].email, name: pa[0].name }
}
}
// Direct user-id lookup (caller passed users.id, not participants.id).
const { rows: us } = await pool.query<{ display_name: string; email: string }>(
`SELECT u.display_name, u.email
FROM users u
JOIN company_members cm ON cm.user_id = u.id
WHERE u.id = $1 AND cm.company_id = $2 LIMIT 1`,
[raw, viewerCompanyId],
)
if (us[0]) return { addr: us[0].email, name: us[0].display_name }
return null
}
interface EmailThreadRow {
conversation_id: string
title: string
updated_at: string
unread_count: number
last_subject: string | null
last_from: string | null
last_at: string | null
last_body: string | null
}
async function listAgentEmailThreads(args: {
agentId: string
companyId: string
unreadOnly: boolean
limit: number
client?: PoolClient
}): Promise<EmailThreadRow[]> {
// Threads = email conversations the agent is in. We surface the latest
// email_messages row per thread for the snippet, and an unread count
// computed against conversation_reads.last_read_at (same source of
// truth as the chat inbox uses). Keeps the agent's mental model
// consistent: "unread" means "you haven't acked this thread since".
const { rows } = await (args.client ?? pool).query<EmailThreadRow>(
`WITH my_threads AS (
SELECT c.id, c.title, c.updated_at
FROM conversations c
WHERE c.kind = 'email'
AND c.company_id = $1
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)
),
last_msg AS (
SELECT DISTINCT ON (em.conversation_id)
em.conversation_id, em.subject, em.from_addr,
m.body, m.created_at AS at
FROM email_messages em
JOIN messages m ON m.id = em.message_id
WHERE em.company_id = $1
ORDER BY em.conversation_id, em.created_at DESC
),
unread AS (
SELECT m.conversation_id, COUNT(*)::int AS n
FROM messages m
LEFT JOIN conversation_reads r
ON r.conversation_id = m.conversation_id AND r.user_id = $2
WHERE m.kind = 'email'
AND m.company_id = $1
AND m.author_id <> $2
AND (r.last_read_at IS NULL OR m.created_at > r.last_read_at)
GROUP BY m.conversation_id
)
SELECT t.id AS conversation_id, t.title, t.updated_at::text,
COALESCE(u.n, 0) AS unread_count,
l.subject AS last_subject, l.from_addr AS last_from,
l.at::text AS last_at, l.body AS last_body
FROM my_threads t
LEFT JOIN last_msg l ON l.conversation_id = t.id
LEFT JOIN unread u ON u.conversation_id = t.id
WHERE NOT $3 OR COALESCE(u.n, 0) > 0
ORDER BY t.updated_at DESC
LIMIT $4`,
[args.companyId, args.agentId, args.unreadOnly, args.limit],
)
return rows
}
/* ============== Polls ====================================================
* Agents can create polls, cast their own vote, and close polls they
* authored. All three call the shared core in ../polls.ts — the HTTP API
* for human users wraps the same functions, so renderer + agent paths
* stay in lockstep on validation + broadcast. */
async function cmdPoll(parsed: ParsedArgs): Promise<CliResult> {
const sub = parsed.positional[0]
if (!sub) {
return err(
'usage:\n' +
' poll create <convo_id> "<question>" "<opt1>" "<opt2>" [<opt3>...] [--mode single|multi] [--expires-in <minutes>]\n' +
' poll vote <message_id> <option_id>[,<option_id>...] # multi-choice: comma-separated. Pass --clear to retract\n' +
' poll close <message_id> # only the author can close\n' +
' poll show <message_id> # current tallies + your vote',
)
}
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
switch (sub) {
case 'create': return cmdPollCreate(parsed, me, companyId)
case 'vote': return cmdPollVote(parsed, me, companyId)
case 'close': return cmdPollClose(parsed, me, companyId)
case 'show': return cmdPollShow(parsed, me, companyId)
default: return err(`unknown poll subcommand: ${sub}`)
}
}
async function cmdPollCreate(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const convoId = parsed.positional[1]
const question = parsed.positional[2]
const options = parsed.positional.slice(3).map(unescapeChat)
if (!convoId || !question || options.length < 2) {
return err('usage: poll create <convo_id> "<question>" "<opt1>" "<opt2>" [<opt3>...] [--mode single|multi] [--expires-in <minutes>]')
}
const mode = String(parsed.flags.mode ?? 'single') === 'multi' ? 'multi' : 'single'
const expiresRaw = parsed.flags['expires-in']
const expiresInMinutes = expiresRaw != null && expiresRaw !== ''
? Number(expiresRaw)
: null
if (expiresInMinutes != null && !Number.isFinite(expiresInMinutes)) {
return err('--expires-in must be a number of minutes')
}
try {
const { createPoll } = await import('../polls.js')
const created = await createPoll({
conversationId: convoId,
companyId,
authorId: me,
question: unescapeChat(question),
mode,
options,
expiresInMinutes,
})
const optsTxt = created.poll.options.map((o) => ` ${o.id} → ${o.text}`).join('\n')
return ok(
`poll posted · ${created.messageId} (seq ${created.sequence})\n` +
`mode: ${created.poll.mode}${created.poll.expiresAt ? `\nexpires: ${created.poll.expiresAt}` : ''}\n` +
`options:\n${optsTxt}`,
[{
event: 'message.posted',
command: 'poll',
conversationId: convoId,
messageId: created.messageId,
authorId: me,
companyId,
visibleToUser: true,
}],
)
} catch (e) {
return err(`poll create failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
async function cmdPollVote(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const messageId = parsed.positional[1]
if (!messageId) return err('usage: poll vote <message_id> <option_id>[,<option_id>...] [--clear]')
const optsRaw = parsed.positional[2] ?? ''
const clear = Boolean(parsed.flags.clear)
const optionIds = clear
? []
: optsRaw.split(',').map((s) => s.trim()).filter(Boolean)
if (!clear && optionIds.length === 0) {
return err('provide at least one option id, or pass --clear to retract')
}
try {
const { castVote } = await import('../polls.js')
const event = await castVote({
messageId,
companyId,
voterParticipantId: me,
voterKind: 'agent',
optionIds,
})
const tallyTxt = event.tallies.length === 0
? '(no votes yet)'
: event.tallies.map((t) => ` ${t.optionId} · ${t.count} (${t.voterIds.join(', ')})`).join('\n')
return ok(
clear
? `vote retracted on ${messageId}\n${tallyTxt}`
: `vote cast on ${messageId} → ${optionIds.join(', ')}\n${tallyTxt}`,
)
} catch (e) {
return err(`poll vote failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
async function cmdPollClose(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const messageId = parsed.positional[1]
if (!messageId) return err('usage: poll close <message_id>')
try {
const { closePoll } = await import('../polls.js')
const event = await closePoll({ messageId, companyId, actorId: me, reason: 'manual' })
if (!event) return ok(`poll ${messageId} was already closed`)
return ok(`poll ${messageId} closed`)
} catch (e) {
return err(`poll close failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
async function cmdPollShow(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const messageId = parsed.positional[1]
if (!messageId) return err('usage: poll show <message_id>')
const { rows } = await pool.query<{ poll: { question: string; mode: string; options: Array<{ id: string; text: string }>; expiresAt: string | null; closedAt: string | null } | null; author_id: string }>(
`SELECT m.poll, m.author_id
FROM participants requester
JOIN conversations c
ON c.company_id = requester.company_id
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $3
)
JOIN messages m ON m.conversation_id = c.id AND m.company_id = c.company_id
WHERE m.id = $1 AND m.company_id = $2 AND m.kind = 'poll'
AND requester.id = $3
AND requester.kind = 'agent'
AND requester.departed_at IS NULL
LIMIT 1`,
[messageId, companyId, me],
)
const row = rows[0]
if (!row || !row.poll) return err(`poll ${messageId} not found`)
const { rows: tallyRows } = await pool.query<{ option_id: string; cnt: number; voter_ids: string[] }>(
`SELECT option_id, COUNT(*)::int AS cnt,
array_agg(voter_participant_id ORDER BY voter_participant_id) AS voter_ids
FROM poll_votes WHERE message_id = $1 GROUP BY option_id`,
[messageId],
)
const tallyMap = new Map(tallyRows.map((t) => [t.option_id, { cnt: t.cnt, voters: t.voter_ids }]))
const lines = row.poll.options.map((o) => {
const t = tallyMap.get(o.id) ?? { cnt: 0, voters: [] as string[] }
const mine = t.voters.includes(me) ? ' ← you' : ''
return ` ${o.id} (${t.cnt}) · ${o.text}${mine}`
}).join('\n')
const head = [
`poll ${messageId} · by ${row.author_id} · mode=${row.poll.mode}`,
row.poll.closedAt ? `closed at ${row.poll.closedAt}` : (row.poll.expiresAt ? `expires ${row.poll.expiresAt}` : 'open'),
row.poll.question,
].join('\n')
return ok(`${head}\n${lines}`)
}
async function cmdEmail(parsed: ParsedArgs): Promise<CliResult> {
const sub = parsed.positional[0]
if (!sub) {
return err(
'usage:\n' +
' email send --to <addr|id>[,<addr|id>...] [--cc <...>] --subject "..." --body "..." [--as <id>]\n' +
' email reply <message_id> --body "..." [--cc <addr|id>...] [--as <id>]\n' +
' email inbox [--unread] [--limit N] [--as <id>]\n' +
' email show <conversation_id> [--tail N] [--as <id>]\n' +
' email contacts [<query>] [--as <id>] (or just: cumora contacts [<query>])\n' +
' email whoami [--as <id>] — your own address',
)
}
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
switch (sub) {
case 'whoami': return cmdEmailWhoami(me)
case 'contacts': return cmdEmailContacts(parsed, me, companyId, Boolean(parsed.flags.json))
case 'inbox': return cmdEmailInbox(parsed, me, companyId)
case 'show': return cmdEmailShow(parsed, me, companyId)
case 'send': return cmdEmailSend(parsed, me, companyId)
case 'reply': return cmdEmailReply(parsed, me, companyId)
default:
return err(`unknown email subcommand: ${sub}`)
}
}
const EMAIL_ATTACHMENTS_UNSUPPORTED =
'outbound email attachments are not supported; --attach never accepts server filesystem paths'
function rejectsEmailAttachmentFlags(parsed: ParsedArgs): CliResult | null {
if (
parsed.flags.attach ||
parsed.flags['attach-text'] ||
parsed.flags['attach-bytes'] ||
parsed.flags['generate-image']
) {
return err(EMAIL_ATTACHMENTS_UNSUPPORTED)
}
return null
}
async function cmdEmailWhoami(me: string): Promise<CliResult> {
const { ensureAgentAddress } = await import('../email.js')
const { env } = await import('../env.js')
const addr = await ensureAgentAddress(me)
if (!addr) {
if (!env.EMAIL_DOMAIN) return err('email feature not configured (set EMAIL_DOMAIN)')
return err(`no email address available for ${me} (not an agent, or company missing)`)
}
return ok(`${addr.displayName} <${addr.email}>`)
}
async function cmdEmailContacts(
parsed: ParsedArgs,
me: string,
companyId: string,
json: boolean,
): Promise<CliResult> {
// Optional fuzzy filter: `cumora email contacts wey` matches against
// name / id / email (substring, case-insensitive). The empty-result
// path explicitly tells the caller that NO contact matches the query
// — the agent's LLM uses this signal to ask the user for the address
// instead of silently doing nothing.
const query = parsed.positional[1]?.trim() ?? ''
const lockedList = await withActiveParticipantLock({
participantId: me,
companyId,
kind: 'agent',
run: (client) => listEmailContacts(companyId, me, query, client),
})
if (!lockedList) return err(`cannot resolve active company for ${me}`)
const list = lockedList
if (json) return ok(JSON.stringify(list, null, 2))
if (list.length === 0) {
const { env } = await import('../env.js')
if (!env.EMAIL_DOMAIN) return ok('(email feature not configured — set EMAIL_DOMAIN to enable)')
if (query) {
return ok(`(no contacts match "${query}". If the user named someone you don't recognize, ASK them for the email address before guessing — don't silently skip the task.)`)
}
return ok('(no email contacts yet — invite someone or wait for inbound mail)')
}
// Width is driven by longest entry per column so long names / addresses
// don't get chopped. Cap so a pathological 300-char address can't blow
// up the layout — but the cap is generous (60) versus the previous 44.
const KIND_W = 8
const nameW = Math.min(40, Math.max(12, ...list.map((c) => c.name.length)))
// The role column tells the agent WHAT each teammate does — the whole point
// of a directory. Width tracks the longest role (capped); falls back to a
// header-width minimum so the column header always fits.
const roleW = Math.min(24, Math.max(4, ...list.map((c) => (c.role ?? '').length)))
const addrW = Math.min(60, Math.max(20, ...list.map((c) => c.address.length)))
const lines = [
`${'kind'.padEnd(KIND_W)} ${'name'.padEnd(nameW)} ${'role'.padEnd(roleW)} ${'address'.padEnd(addrW)} id`,
'-'.repeat(KIND_W + 1 + nameW + 2 + roleW + 2 + addrW + 2 + 6),
...list.map((c) =>
`${c.kind.padEnd(KIND_W)} ${c.name.slice(0, nameW).padEnd(nameW)} ${(c.role ?? '—').slice(0, roleW).padEnd(roleW)} ${c.address.slice(0, addrW).padEnd(addrW)} ${c.participantId ?? '—'}`,
),
]
return ok(lines.join('\n'))
}
async function cmdEmailInbox(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const unread = Boolean(parsed.flags.unread)
const limit = Math.min(50, Math.max(1, Number(parsed.flags.limit ?? 20)))
const lockedThreads = await withActiveParticipantLock({
participantId: me,
companyId,
kind: 'agent',
run: (client) => listAgentEmailThreads({ agentId: me, companyId, unreadOnly: unread, limit, client }),
})
if (!lockedThreads) return err(`cannot resolve active company for ${me}`)
const threads = lockedThreads
if (parsed.flags.json) return ok(JSON.stringify(threads, null, 2))
if (threads.length === 0) {
// Distinguish "feature not wired" from "feature wired, just empty" so
// a fresh agent isn't left guessing whether mail is broken vs quiet.
const { env } = await import('../env.js')
if (!env.EMAIL_DOMAIN) {
return ok('(email feature not configured — set EMAIL_DOMAIN to enable inbound + outbound)')
}
return ok(unread ? `(no unread email for ${me})` : `(no email threads for ${me} yet)`)
}
const lines: string[] = []
for (const t of threads) {
const unreadTag = t.unread_count > 0 ? ` ★${t.unread_count}` : ''
// Keep full subject + from — the LLM consumer reads better with all
// content visible; truncation only hurt narrow terminals, and those
// aren't our audience here.
const subject = t.last_subject ?? t.title ?? '(no subject)'
const from = t.last_from ?? '?'
const snippet = (t.last_body ?? '').slice(0, 240).replace(/\n+/g, ' \\n ')
const at = t.last_at ? new Date(t.last_at).toISOString().replace('T', ' ').slice(0, 16) : ''
lines.push(`# ${t.conversation_id}${unreadTag} [${at}]`)
lines.push(` from: ${from}`)
lines.push(` subject: ${subject}`)
if (snippet) lines.push(` body: ${snippet}`)
lines.push('')
}
lines.push(`run \`cumora email show <conversation_id>\` to read the full thread, then \`cumora email reply <message_id> --body "..."\` to respond. \`cumora ack <conversation_id>\` clears unread state.`)
return ok(lines.join('\n'))
}
async function cmdEmailShow(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const convoId = parsed.positional[1]
if (!convoId) return err('usage: email show <conversation_id> [--tail N]')
const tail = Math.min(50, Math.max(1, Number(parsed.flags.tail ?? 10)))
const result = await withConversationActorLock({
participantId: me,
companyId,
conversationId: convoId,
kind: 'agent',
conversationKind: 'email',
run: async (client) => {
const { rows: cv } = await client.query<{ title: string }>(
`SELECT title FROM conversations WHERE id = $1 AND company_id = $2`,
[convoId, companyId],
)
const { rows: msgs } = await client.query<{
id: string; created_at: string; body: string; from_addr: string;
to_addrs: string[]; cc_addrs: string[]; subject: string;
smtp_message_id: string | null; in_reply_to: string | null;
direction: 'in' | 'out'; transport_status: string;
}>(
`SELECT m.id, m.created_at::text, m.body,
em.from_addr, em.to_addrs, em.cc_addrs, em.subject,
em.smtp_message_id, em.in_reply_to, em.direction, em.transport_status
FROM messages m
JOIN email_messages em ON em.message_id = m.id AND em.company_id = $3
WHERE m.conversation_id = $1 AND m.company_id = $3
ORDER BY m.sequence DESC
LIMIT $2`,
[convoId, tail, companyId],
)
msgs.reverse()
if (parsed.flags.json) return ok(JSON.stringify({ thread: convoId, title: cv[0].title, messages: msgs }, null, 2))
if (msgs.length === 0) return ok(`(thread ${convoId} has no email messages)`)
const lines: string[] = [`thread ${convoId} "${cv[0].title}"`, '']
for (const m of msgs) {
const at = new Date(m.created_at).toISOString().replace('T', ' ').slice(0, 16)
const arrow = m.direction === 'in' ? '↓ in' : '↑ out'
lines.push(`──── [${m.id}] ${arrow} ${m.transport_status} ${at}`)
lines.push(`from: ${m.from_addr}`)
if (m.to_addrs?.length) lines.push(`to: ${m.to_addrs.join(', ')}`)
if (m.cc_addrs?.length) lines.push(`cc: ${m.cc_addrs.join(', ')}`)
lines.push(`subject: ${m.subject}`)
if (m.in_reply_to) lines.push(`in-reply-to: <${m.in_reply_to}>`)
lines.push('')
lines.push(m.body)
lines.push('')
}
lines.push(`reply with \`cumora email reply ${msgs[msgs.length - 1].id} --body "..."\`.`)
return ok(lines.join('\n'))
},
})
return result ?? err(`email thread ${convoId} not found or no longer authorized`)
}
async function cmdEmailSend(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const toRaw = parsed.flags.to ? String(parsed.flags.to) : ''
const ccRaw = parsed.flags.cc ? String(parsed.flags.cc) : ''
const {
ensureAgentAddress,
formatAddress,
sendViaProvider,
findOrCreateEmailConversation,
persistEmailMessage,
mintMessageId,
sanitizeSubject,
} = await import('../email.js')
const subject = sanitizeSubject(unescapeChat(String(parsed.flags.subject ?? '')))
const body = unescapeChat(String(parsed.flags.body ?? '')).trim()
if (!toRaw || !subject || !body) {
return err('usage: email send --to <addr|id>[,...] [--cc <...>] --subject "..." --body "..."')
}
const attachmentError = rejectsEmailAttachmentFlags(parsed)
if (attachmentError) return attachmentError
const sender = await ensureAgentAddress(me)
if (!sender) return err('agent has no email address (EMAIL_DOMAIN unset or company missing)')
const toItems = toRaw.split(',').map((s) => s.trim()).filter(Boolean)
const ccItems = ccRaw.split(',').map((s) => s.trim()).filter(Boolean)
const toResolved: { addr: string; name: string | null }[] = []
const ccResolved: { addr: string; name: string | null }[] = []
for (const t of toItems) {
const r = await resolveEmailRecipient(t, companyId)
if (!r) return err(`can't resolve recipient: ${t}`)
toResolved.push(r)
}
for (const c of ccItems) {
const r = await resolveEmailRecipient(c, companyId)
if (!r) return err(`can't resolve cc: ${c}`)
ccResolved.push(r)
}
if (toResolved.length === 0) return err('at least one --to recipient required')
// Recipient agents in this same company become conversation members.
const memberIds = new Set<string>([me])
for (const r of [...toResolved, ...ccResolved]) {
const inHouse = await pool.query<{ id: string }>(
`SELECT id FROM participants
WHERE LOWER(email) = $1 AND company_id = $2 AND departed_at IS NULL LIMIT 1`,
[r.addr, companyId],
)
if (inHouse.rows[0]) memberIds.add(inHouse.rows[0].id)
}
const messageId = mintMessageId()
const conv = await findOrCreateEmailConversation({
companyId,
inReplyTo: null,
references: [],
subject,
memberIds: [...memberIds],
})
// WRITE-FIRST: persist an authorized durable row before the network hop.
// persistEmailMessage locks the active author and current conversation
// membership in its transaction, so a revoked actor never reaches Resend.
const persisted = await persistEmailMessage({
conversationId: conv.conversationId,
companyId,
authorId: me,
direction: 'out',
transportStatus: 'sending',
transportError: null,
smtpMessageId: messageId,
inReplyTo: null,
references: [],
subject,
fromAddr: formatAddress(sender.email, sender.displayName),
toAddrs: toResolved.map((r) => formatAddress(r.addr, r.name)),
ccAddrs: ccResolved.map((r) => formatAddress(r.addr, r.name)),
body,
autoSubmitted: true,
})
const sendRes = await sendViaProvider({
from: formatAddress(sender.email, sender.displayName),
to: toResolved.map((r) => formatAddress(r.addr, r.name)),
cc: ccResolved.length ? ccResolved.map((r) => formatAddress(r.addr, r.name)) : undefined,
subject,
text: body,
messageId,
autoSubmitted: 'auto-generated',
})
const finalStatus = sendRes.ok ? 'sent' : 'failed'
await pool.query(
`UPDATE email_messages
SET transport_status = $1, transport_error = $2,
smtp_message_id = $3, next_retry_at = $4
WHERE message_id = $5 AND company_id = $6`,
[
finalStatus, sendRes.error, sendRes.smtpMessageId ?? messageId,
finalStatus === 'failed' ? new Date(Date.now() + 60_000) : null,
persisted.messageId, companyId,
],
).catch((error) => {
console.warn(`[email] post-send UPDATE failed for ${persisted.messageId}; retry worker will reconcile`, error)
})
if (!sendRes.ok) {
return err(`email persisted as failed: ${sendRes.error} · message_id=${persisted.messageId}`, 1)
}
const mockTag = sendRes.mock ? ' (mock — no real send)' : ''
return ok(`sent${mockTag} · ${persisted.messageId} · thread ${conv.conversationId}`, [{
event: 'email.sent',
command: 'email send',
conversationId: conv.conversationId,
messageId: persisted.messageId,
authorId: me,
companyId,
subject,
to: toResolved.map((r) => r.addr),
cc: ccResolved.map((r) => r.addr),
attachmentCount: 0,
transportStatus: 'sent',
mock: sendRes.mock,
visibleToUser: true,
}])
}
async function cmdEmailReply(parsed: ParsedArgs, me: string, companyId: string): Promise<CliResult> {
const replyTo = parsed.positional[1]
const body = unescapeChat(String(parsed.flags.body ?? '')).trim()
if (!replyTo || !body) return err('usage: email reply <message_id> --body "..." [--cc <addr|id>...]')
const attachmentError = rejectsEmailAttachmentFlags(parsed)
if (attachmentError) return attachmentError
const {
ensureAgentAddress, formatAddress,
sendViaProvider, persistEmailMessage, mintMessageId, normalizeMessageId,
sanitizeSubject, splitReplyAddresses,
} = await import('../email.js')
const sender = await ensureAgentAddress(me)
if (!sender) return err('agent has no email address (EMAIL_DOMAIN unset or company missing)')
const { rows: orig } = await pool.query<{
conversation_id: string
smtp_message_id: string | null
references_chain: string[]
subject: string
from_addr: string
to_addrs: string[]
cc_addrs: string[]
}>(
`SELECT conversation_id, smtp_message_id, references_chain,
subject, from_addr, to_addrs, cc_addrs
FROM email_messages WHERE message_id = $1 AND company_id = $2`,
[replyTo, companyId],
)
if (!orig[0]) return err(`unknown email message ${replyTo}`)
const o = orig[0]
// Reply-all split: TO = original From, CC = original To+Cc minus self.
// Earlier iterations collapsed everyone into TO; that read fine but
// dropped the informed-vs.-required signal real clients rely on.
const { to: toAddrs, cc: ccFromOriginal } = splitReplyAddresses({
originalFrom: o.from_addr,
originalTo: o.to_addrs ?? [],
originalCc: o.cc_addrs ?? [],
selfAddresses: [sender.email],
})
if (toAddrs.length === 0) return err('no other recipients to reply to')
// Extra cc from --cc, resolved like in `send` — appended to the
// original CC list (self is already filtered out by splitReplyAddresses;
// we de-dupe against toAddrs + ccFromOriginal below).
const ccItems = parsed.flags.cc ? String(parsed.flags.cc).split(',').map((s) => s.trim()).filter(Boolean) : []
const ccResolved: { addr: string; name: string | null }[] = []
for (const c of ccItems) {
const r = await resolveEmailRecipient(c, companyId)
if (!r) return err(`can't resolve cc: ${c}`)
ccResolved.push(r)
}
const extractAddr = (raw: string) => {
const m = /<([^>]+)>/.exec(raw)
return (m ? m[1] : raw).toLowerCase()
}
const ccSeen = new Set<string>([
sender.email.toLowerCase(),
...toAddrs.map(extractAddr),
...ccFromOriginal.map(extractAddr),
])
const ccCombined: string[] = [...ccFromOriginal]
for (const r of ccResolved) {
if (ccSeen.has(r.addr)) continue
ccSeen.add(r.addr)
ccCombined.push(formatAddress(r.addr, r.name))
}
const subject = /^(re|fwd|fw)\s*:/i.test(o.subject) ? sanitizeSubject(o.subject) : sanitizeSubject(`Re: ${o.subject}`)
const newReferences = [
...(o.references_chain ?? []),
...(o.smtp_message_id ? [o.smtp_message_id] : []),
].filter((x): x is string => Boolean(x))
const inReplyTo = o.smtp_message_id ? normalizeMessageId(o.smtp_message_id) : null
const messageId = mintMessageId()
// WRITE-FIRST. This is the authorization boundary: persistEmailMessage
// locks the current participant and verifies current conversation
// membership before committing the durable outbound row.
const persisted = await persistEmailMessage({
conversationId: o.conversation_id,
companyId,
authorId: me,
direction: 'out',
transportStatus: 'sending',
transportError: null,
smtpMessageId: messageId,
inReplyTo,
references: newReferences,
subject,
fromAddr: formatAddress(sender.email, sender.displayName),
toAddrs,
ccAddrs: ccCombined,
body,
autoSubmitted: true,
})
const sendRes = await sendViaProvider({
from: formatAddress(sender.email, sender.displayName),
to: toAddrs,
cc: ccCombined.length ? ccCombined : undefined,
subject,
text: body,
inReplyTo: inReplyTo ?? undefined,
references: newReferences,
messageId,
autoSubmitted: 'auto-replied',
})
const finalStatus = sendRes.ok ? 'sent' : 'failed'
await pool.query(
`UPDATE email_messages
SET transport_status = $1, transport_error = $2,
smtp_message_id = $3, next_retry_at = $4
WHERE message_id = $5 AND company_id = $6`,
[
finalStatus, sendRes.error, sendRes.smtpMessageId ?? messageId,
finalStatus === 'failed' ? new Date(Date.now() + 60_000) : null,
persisted.messageId, companyId,
],
).catch((error) => {
console.warn(`[email] post-send UPDATE failed for ${persisted.messageId}; retry worker will reconcile`, error)
})
// Auto-ack — replying definitionally means I read the original.
await pool.query(
`INSERT INTO conversation_reads (user_id, conversation_id, last_read_at)
VALUES ($1, $2, NOW())
ON CONFLICT (user_id, conversation_id) DO UPDATE SET last_read_at = NOW()`,
[me, o.conversation_id],
)
if (!sendRes.ok) return err(`email persisted as failed: ${sendRes.error} · ${persisted.messageId}`, 1)
const mockTag = sendRes.mock ? ' (mock)' : ''
return ok(`replied${mockTag} · ${persisted.messageId} · thread ${o.conversation_id}`, [{
event: 'email.sent',
command: 'email reply',
conversationId: o.conversation_id,
messageId: persisted.messageId,
authorId: me,
companyId,
replyToMessageId: replyTo,
subject,
to: toAddrs,
cc: ccCombined,
attachmentCount: 0,
transportStatus: 'sent',
mock: sendRes.mock,
visibleToUser: true,
}])
}
async function cmdAvatar(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0]
if (op !== 'regen' && op !== 'regenerate' && op !== 'set' && op !== 'show') {
return err(
'usage:\n' +
' avatar show <participant_id> view a teammate\'s portrait URL (download + open it to actually see the image)\n' +
' avatar regen [--as <id>] regenerate your portrait from your persona\n' +
' avatar set <image_url> [--as <id>] adopt an existing image URL as your portrait',
)
}
const me = resolveAs(parsed)
// Resolve the agent's tenant — avatar lookups are tenant-scoped (you can only
// look at teammates in your own workspace).
const { rows } = await pool.query<{ company_id: string; kind: string }>(
`SELECT company_id, kind FROM participants WHERE id = $1`, [me],
)
if (!rows[0]) return err(`unknown participant ${me}`)
// `show` is read-only and works for any caller (agent OR human); `regen`/`set`
// mutate the caller's OWN portrait, so they stay agent-only.
if (op !== 'show' && rows[0].kind !== 'agent') return err('avatar ops are only for agents')
const tenant = rows[0].company_id
if (op === 'show') {
const target = parsed.positional[1]
if (!target) return err('usage: avatar show <participant_id>')
const { rows: t } = await pool.query<{
id: string; name: string; role: string | null; kind: string; avatar_url: string | null
}>(
`SELECT id, name, role, kind, avatar_url FROM participants
WHERE id = $1 AND company_id = $2 AND departed_at IS NULL`,
[target, tenant],
)
if (!t[0]) return err(`unknown participant ${target} in this workspace`)
const r = t[0]
const who = `${r.name} (${r.id}) — ${r.kind}${r.role ? `, ${r.role}` : ''}`
if (!r.avatar_url) return ok(`${who}\n(no avatar set)`)
// We give the URL + a recipe. The CLI's tool-result text channel doesn't
// auto-feed vision (that's reserved for message attachments), so to ACTUALLY
// see the face the agent downloads the file and opens it with whatever image-
// reading tool the engine provides (Claude Code: \`Read <path>\` shows images
// inline; Codex: open the saved file).
return ok(
`${who}\n` +
`avatar URL: ${r.avatar_url}\n\n` +
`To actually SEE the image, save it locally then open it with your image-reading tool:\n` +
` curl -sL '${r.avatar_url}' -o /tmp/${r.id}-avatar\n` +
`then open \`/tmp/${r.id}-avatar\` with your Read / view-image tool.`,
)
}
if (op === 'set') {
const url = parsed.positional[1]
if (!url) return err('usage: avatar set <image_url> [--as <id>]')
try {
const result = await setAgentAvatarFromUrl({ agentId: me, tenant, sourceUrl: url })
return ok(`portrait set → ${result.url}`, [{
event: 'avatar.updated',
command: 'avatar set',
agentId: me,
companyId: tenant,
avatarUrl: result.url,
}])
} catch (e) {
return err(`avatar set failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
// op === 'regen' | 'regenerate'
try {
const { generateAndPersistAvatar } = await import('../api/router.js')
const { url } = await generateAndPersistAvatar({ agentId: me, tenant })
return ok(`new portrait → ${url}`, [{
event: 'avatar.updated',
command: 'avatar regen',
agentId: me,
companyId: tenant,
avatarUrl: url,
}])
} catch (e) {
return err(`avatar regen failed: ${e instanceof Error ? e.message : String(e)}`)
}
}
/** Fetch an image at `sourceUrl`, validate it, re-upload it under the
* agent's `avatars/` storage key, stamp participants.avatar_url, and
* broadcast the change so connected clients refresh. The source URL
* can be one of our own attachments (e.g. an image the user just sent
* the agent) or any external URL — we always re-upload so the canonical
* avatar lives under our storage and serves through our CDN. */
async function setAgentAvatarFromUrl(args: {
agentId: string
tenant: string
sourceUrl: string
}): Promise<{ url: string }> {
if (!/^https?:\/\//.test(args.sourceUrl)) {
throw new Error('avatar source must be an http(s) URL')
}
const MAX_BYTES = 8 * 1024 * 1024 // 8MB ceiling for portraits
const fetched = await fetchImageBytes(args.sourceUrl, {
maxBytes: MAX_BYTES,
timeoutMs: 15_000,
})
if (!fetched.ok) {
if (fetched.reason === 'http') throw new Error(`source URL returned ${fetched.status ?? 'an error'}`)
if (fetched.reason === 'bad-type') throw new Error('source URL is not an image')
if (fetched.reason === 'too-large') throw new Error(`source image exceeds ${MAX_BYTES} bytes`)
if (fetched.reason === 'blocked') throw new Error('source URL is not allowed')
if (fetched.reason === 'timeout') throw new Error('source URL timed out')
throw new Error('source URL could not be fetched')
}
const { buffer: buf, mime } = fetched
if (buf.length === 0) throw new Error('source image is empty')
// Pick a sensible extension from the mime so the stored object has a
// useful filename and the Worker serves the right content-type.
const ext = mime === 'image/jpeg' ? 'jpg'
: mime === 'image/webp' ? 'webp'
: mime === 'image/gif' ? 'gif'
: mime === 'image/svg+xml' ? 'svg'
: 'png'
const { storage } = await import('../storage.js')
const { randomUUID } = await import('node:crypto')
const key = `avatars/avatar-${args.agentId}-${randomUUID().slice(0, 8)}.${ext}`
const url = await storage.put(key, buf, mime)
await withOutboxTransaction(async (client) => {
await client.query(
`UPDATE participants SET avatar_url = $2 WHERE id = $1 AND company_id = $3`,
[args.agentId, url, args.tenant],
)
await enqueueBroadcast(client, CH_STATUS, {
type: 'participants.avatar',
participantId: args.agentId,
avatarUrl: url,
companyId: args.tenant,
})
})
const { invalidatePersonaCache } = await import('./personas.js')
invalidatePersonaCache(args.agentId)
return { url }
}
async function saveTextAttachment(
filename: string,
content: string,
tenant?: string,
): Promise<{ url: string; name: string; kind: 'file'; mime: string; size: number; key: string }> {
// Sniff a reasonable mime from the extension so the renderer + agent
// both know how to handle it (text/* gets inlined into context on read).
const ext = filename.includes('.') ? filename.split('.').pop()!.toLowerCase() : 'txt'
const mime = (() => {
switch (ext) {
case 'md': return 'text/markdown'
case 'json': return 'application/json'
case 'csv': return 'text/csv'
case 'html': return 'text/html'
case 'yml':
case 'yaml': return 'application/x-yaml'
case 'toml': return 'application/x-toml'
default: return 'text/plain'
}
})()
const buf = Buffer.from(content, 'utf8')
const { randomUUID } = await import('node:crypto')
const id = randomUUID().replace(/-/g, '')
const key = `attachments/${id}.${ext}`
const url = await storage.put(key, buf, mime)
if (tenant) await grantAttachment(pool, tenant, key)
return { url, key, name: filename, kind: 'file', mime, size: buf.length }
}
async function cmdTopicRead(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
if (!convoId) return err('usage: topic <conversation_id>')
const activeAgentCompanyId = await agentCompany(me)
const { rows } = await pool.query<{ topic: string | null; title: string }>(
`SELECT c.topic, c.title
FROM conversations c
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind IN ('agent', 'human')
AND requester.departed_at IS NULL
WHERE c.id = $1
AND ($3::text IS NULL OR c.company_id = $3)
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)`,
[convoId, me, activeAgentCompanyId],
)
if (!rows[0]) return err(`conversation ${convoId} not found or no longer authorized`)
const t = rows[0].topic
if (!t) return ok(`(no topic set on "${rows[0].title}")`)
return ok(t)
}
async function cmdTopicSet(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
if (!convoId) return err('usage: topic-set <conversation_id> "<text>" (empty body clears the topic)')
const raw = unescapeChat(parsed.positional.slice(1).join(' ')).trim()
const topic = raw.length > 0 ? raw.slice(0, 200) : null
const activeAgentCompanyId = await agentCompany(me)
const { rows: preflight } = await pool.query<{ company_id: string }>(
`SELECT c.company_id
FROM conversations c
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind IN ('agent', 'human')
AND requester.departed_at IS NULL
WHERE c.id = $1
AND ($3::text IS NULL OR c.company_id = $3)
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)`,
[convoId, me, activeAgentCompanyId],
)
if (!preflight[0]) return err(`conversation ${convoId} not found or no longer authorized`)
const updated = await withConversationActorLock({
participantId: me,
companyId: preflight[0].company_id,
conversationId: convoId,
run: async (client) => {
const result = await client.query<{ company_id: string }>(
`UPDATE conversations SET topic = $2, updated_at = NOW()
WHERE id = $1 AND company_id = $3
RETURNING company_id`,
[convoId, topic, preflight[0].company_id],
)
if (result.rows[0]) {
await enqueueBroadcast(client, CH_CONVO_UPDATED, {
type: 'conversation.updated',
conversationId: convoId,
companyId: result.rows[0].company_id,
patch: { topic },
})
}
return result
},
})
const companyId = updated?.rows[0]?.company_id
if (!companyId) return err(`conversation ${convoId} not found or no longer authorized`)
return ok(topic ? `topic set: "${topic}"` : '(topic cleared)', [{
event: 'conversation.topic_updated',
command: 'topic-set',
conversationId: convoId,
actorId: me,
companyId,
topic,
visibleToUser: true,
}])
}
/** Rename a group conversation. Members only; groups only (a DM/whisper title is
* the other person's name). Mirrors the human POST /conversations/:id/title. */
async function cmdRename(parsed: ParsedArgs): Promise<CliResult> {
const me = resolveAs(parsed)
const convoId = parsed.positional[0]
if (!convoId) return err('usage: rename <conversation_id> "<new title>"')
const title = unescapeChat(parsed.positional.slice(1).join(' ')).trim().slice(0, 80)
if (!title) return err('rename requires a non-empty title')
const activeAgentCompanyId = await agentCompany(me)
const { rows } = await pool.query<{ members: string[]; kind: string; company_id: string; title: string }>(
`SELECT c.members, c.kind, c.company_id, c.title
FROM conversations c
JOIN participants requester
ON requester.id = $2
AND requester.company_id = c.company_id
AND requester.kind IN ('agent', 'human')
AND requester.departed_at IS NULL
WHERE c.id = $1
AND ($3::text IS NULL OR c.company_id = $3)
AND EXISTS (
SELECT 1 FROM conversation_members member
WHERE member.conversation_id = c.id
AND member.participant_id = $2
)`,
[convoId, me, activeAgentCompanyId],
)
if (!rows[0]) return err(`conversation ${convoId} not found or no longer authorized`)
if (rows[0].kind !== 'group') return err(`only group chats can be renamed (${convoId} is a ${rows[0].kind})`)
const currentTitle = rows[0].title
// Optimistic-concurrency: --if-equals "<expected current title>" lets a caller
// declare what title they BELIEVE is current. A mismatch means someone else
// already renamed it (or it never matched) → reject so the caller re-reads the
// state rather than blindly overwriting. Catches the "I'll rename it for you,
// Yulemi" pile-on race where Atlas guesses a different name than Nova.
const ifEqualsRaw = parsed.flags['if-equals']
if (typeof ifEqualsRaw === 'string') {
const ifEquals = unescapeChat(ifEqualsRaw).trim().slice(0, 80)
if (currentTitle !== ifEquals) {
return err(`stale: current title is "${currentTitle}", you passed --if-equals "${ifEquals}". Re-read with \`cumora conversations\` and decide if you still want to rename.`)
}
}
// IDEMPOTENT no-op: if the title is already what you'd set, return success
// WITHOUT firing a conversation.renamed event or broadcasting an update. This
// suppresses the noise when N agents all decide to rename to the same string
// at the same instant — the chat doesn't see N identical rename events. Only
// a TRUE change writes through. (A divergent-names race still last-writer-wins
// for the storage; --if-equals is the lever against that.)
if (currentTitle === title) {
return ok(`(no-op — title was already "${title}")`)
}
const updated = await withConversationActorLock({
participantId: me,
companyId: rows[0].company_id,
conversationId: convoId,
run: async (client) => {
const result = await client.query(
`UPDATE conversations
SET title = $2, updated_at = NOW()
WHERE id = $1 AND company_id = $3
AND kind = 'group' AND title = $4`,
[convoId, title, rows[0].company_id, currentTitle],
)
if (result.rowCount) {
await enqueueBroadcast(client, CH_CONVO_UPDATED, {
type: 'conversation.updated',
conversationId: convoId,
companyId: rows[0].company_id,
patch: { title },
})
}
return result
},
})
if (!updated?.rowCount) return err(`conversation ${convoId} changed or is no longer authorized; rename cancelled`)
return ok(`renamed to "${title}" (${convoId})`, [{
event: 'conversation.renamed',
command: 'rename',
conversationId: convoId,
actorId: me,
companyId: rows[0].company_id,
title,
visibleToUser: true,
}])
}
/* ============== private agent state: memory / log / workspace / tasks ============== */
/** Whitelisted memory kinds. Becomes a path segment, so we keep it
* small + slug-safe — agents can't write `memory/Whatever-They-Want/`. */
const MEMORY_KINDS = ['observation', 'preference', 'fact', 'decision', 'note'] as const
type MemoryKind = typeof MEMORY_KINDS[number]
function normalizeMemoryKind(raw: unknown): MemoryKind {
const s = String(raw ?? '').trim().toLowerCase()
return (MEMORY_KINDS as readonly string[]).includes(s) ? s as MemoryKind : 'observation'
}
/** Memory is stored as files inside the agent's workspace under
* `memory/<kind>/<id>.md` (global) or `memory/projects/<projectId>/<kind>/<id>.md`.
* Structured fields (`kind`, `about`, `pinned`, `source`, `createdAt`) live
* in the `meta` JSONB column. New writes stamp `source.conversationId` /
* `source.projectId` (issue #45); existing `source: null` rows stay GLOBAL
* — we never guess-migrate them into a project. See memory-scope.ts. */
/** Escape LIKE metacharacters in a value that must match LITERALLY.
*
* These patterns are built from a positional argument the MODEL supplies, and
* `%` and `_` are wildcards to LIKE. `cumora memory delete %` became
* `path LIKE 'memory/%/%.md'` and removed every memory the agent had, then
* reported "deleted %" — verified against Postgres 16: three rows in, DELETE 3,
* none left. `cumora skills delete %` is the same shape one command over.
*
* Postgres's default LIKE escape is a backslash, and the pattern reaches it as
* a bound parameter, so escaping here is sufficient — no ESCAPE clause needed.
* Confirmed: `'…mem-aaa.md' LIKE 'memory/%/\%.md'` is false once escaped, and
* a literal `%` in a name still matches itself. */
export function likeLiteral(value: string): string {
return value.replace(/[\\%_]/g, (ch) => `\\${ch}`)
}
async function cmdMemory(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0]
const me = resolveAs(parsed)
const explicitConvo = (typeof parsed.flags.in === 'string' ? parsed.flags.in : null)
?? (typeof parsed.flags.conversation === 'string' ? parsed.flags.conversation : null)
if (op === 'list') {
const params: unknown[] = [me]
let where = `agent_id = $1 AND path LIKE 'memory/%'`
if (parsed.flags.about) {
params.push(String(parsed.flags.about))
where += ` AND meta->>'about' = $${params.length}`
}
if (parsed.flags.kind) {
const k = normalizeMemoryKind(parsed.flags.kind)
params.push(`memory/${k}/%`)
params.push(`memory/projects/%/${k}/%`)
where += ` AND (path LIKE $${params.length - 1} OR path LIKE $${params.length})`
}
const limit = Math.min(100, Math.max(1, Number(parsed.flags.limit ?? 20)))
// Fetch extra rows so in-memory project filtering can still fill `limit`.
// `--all` is the only path that skips isolation.
const fetchLimit = parsed.flags.all ? limit : Math.min(500, Math.max(limit * 10, 100))
params.push(fetchLimit)
const limitParam = `$${params.length}`
const { rows } = await pool.query<{
path: string; body: string; meta: Record<string, unknown> | null; updated_at: string
}>(
`SELECT path, body, meta, updated_at
FROM agent_workspace WHERE ${where}
ORDER BY COALESCE((meta->>'pinned')::boolean, false) DESC, updated_at DESC
LIMIT ${limitParam}`,
params,
)
const parsed_rows = rows.map((r) => {
const parsedPath = parseMemoryPath(r.path)
const kind = parsedPath?.kind ?? 'note'
const id = parsedPath?.id ?? ''
const about = (r.meta?.about as string | undefined) ?? null
const pinned = Boolean(r.meta?.pinned)
const source = asMemorySource(r.meta?.source)
return {
id, kind, about, body: r.body, pinned, created_at: r.updated_at,
path: r.path,
projectId: parsedPath?.projectId ?? source?.projectId ?? null,
meta: r.meta,
source,
}
})
const showAll = Boolean(parsed.flags.all)
let scoped = parsed_rows
if (!showAll) {
const writeSource = await resolveMemoryWriteSource(me, { conversationId: explicitConvo })
const projectIds = writeSource.projectId ? [writeSource.projectId] : []
scoped = parsed_rows.filter((r) => memoryVisibleInScope(
{ pinned: r.pinned, source: r.source },
r.path,
{ projectIds },
))
scoped = scoped.slice(0, limit)
}
if (parsed.flags.json) return ok(JSON.stringify(scoped.map(({ meta, path, ...rest }) => rest), null, 2))
if (scoped.length === 0) return ok(`(${me} has no memory yet)`)
return ok([
`${scoped.length} memory record(s) for ${me}:`,
'',
...scoped.map((m) => {
const t = new Date(m.created_at).toLocaleDateString()
const pin = m.pinned ? '★ ' : ' '
const proj = m.projectId ? ` proj:${m.projectId}` : ' global'
return ` ${pin}[${m.id}] ${m.kind.padEnd(11)} ${(m.about ?? '-').padEnd(10)} ${t}${proj}\n ${m.body.slice(0, 280).replace(/\n/g, ' \\n ')}`
}),
].join('\n'))
}
if (op === 'note') {
const body = parsed.positional[1]
if (!body) return err('usage: memory note <body> [--about subject] [--kind kind] [--in convo] [--as id]')
const kind = normalizeMemoryKind(parsed.flags.kind ?? 'observation')
const about = parsed.flags.about ? String(parsed.flags.about) : null
const id = `mem-${randomUUID().slice(0, 12)}`
const source = await resolveMemoryWriteSource(me, { conversationId: explicitConvo })
const path = memoryWritePath(kind, id, source.projectId)
const tenant = await agentCompany(me)
const meta = await memoryMetaForWrite(me, {
path, kind, about, conversationId: explicitConvo, projectId: source.projectId,
})
// Compute the embedding before INSERT so the row lands with both
// body + vector in one shot. `embedText` returns null on failure
// (rate limit, network blip, etc.) — we still write the row so the
// memory isn't lost; the next background backfill will fill it in.
const { embedText } = await import('./embeddings.js')
const embedding = await embedText(body)
if (embedding) {
await pool.query(
`INSERT INTO agent_workspace (agent_id, path, body, meta, embedding, company_id, updated_at)
VALUES ($1, $2, $3, $4::jsonb, $5::vector, $6, NOW())`,
[me, path, body, JSON.stringify(meta), embedding, tenant],
)
} else {
await pool.query(
`INSERT INTO agent_workspace (agent_id, path, body, meta, company_id, updated_at)
VALUES ($1, $2, $3, $4::jsonb, $5, NOW())`,
[me, path, body, JSON.stringify(meta), tenant],
)
}
await pool.query(
`INSERT INTO agent_log (id, agent_id, company_id, kind, body, ref) VALUES ($1, $2, $3, 'note', $4, $5::jsonb)`,
[`log-${randomUUID().slice(0, 12)}`, me, tenant, `noted: ${body.slice(0, 120)}`, JSON.stringify({ memoryId: id, path })],
)
return ok(`saved memory ${id}`, [{
event: 'memory.written',
command: 'memory note',
memoryId: id,
path,
agentId: me,
kind,
about,
}])
}
if (op === 'pin') {
const id = parsed.positional[1]
if (!id) return err('usage: memory pin <id>')
const r = await pool.query<{ meta: Record<string, unknown> }>(
`UPDATE agent_workspace
SET meta = COALESCE(meta, '{}'::jsonb)
|| jsonb_build_object('pinned', NOT COALESCE((meta->>'pinned')::boolean, false))
WHERE agent_id = $1 AND path LIKE $2
RETURNING meta`,
[me, `memory/%/${likeLiteral(id)}.md`],
)
if ((r.rowCount ?? 0) === 0) return err(`no memory ${id} for ${me}`)
return ok(`pinned: ${r.rows[0].meta?.pinned}`, [{
event: 'memory.pinned',
command: 'memory pin',
memoryId: id,
agentId: me,
pinned: Boolean(r.rows[0].meta?.pinned),
}])
}
if (op === 'delete') {
const id = parsed.positional[1]
if (!id) return err('usage: memory delete <id>')
const r = await pool.query(
`DELETE FROM agent_workspace WHERE agent_id = $1 AND path LIKE $2`,
[me, `memory/%/${likeLiteral(id)}.md`],
)
if ((r.rowCount ?? 0) === 0) return err(`no memory ${id} for ${me}`)
return ok(`deleted ${id}`, [{
event: 'memory.deleted',
command: 'memory delete',
memoryId: id,
agentId: me,
}])
}
return err(`usage: memory <list|note|pin|delete> [...]`)
}
/* ============== Climate (情感系统) — per-agent feelings about people ============== */
/** Clamp to [-1, 1]; coerces strings/numbers; falls back to 0 on garbage. */
function clamp01(v: unknown): number {
const n = typeof v === 'number' ? v : Number(v)
if (!Number.isFinite(n)) return 0
return Math.max(-1, Math.min(1, n))
}
async function cmdClimate(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'read'
const me = resolveAs(parsed)
if (op === 'read') {
const about = parsed.positional[1]
const params: unknown[] = [me]
let where = `agent_id = $1`
if (about) { params.push(about); where += ` AND about_id = $${params.length}` }
const { rows } = await pool.query<{
about_id: string; affinity: number; trust: number; last_note: string; updated_at: string
}>(
`SELECT about_id, affinity, trust, last_note, updated_at
FROM agent_climate WHERE ${where}
ORDER BY updated_at DESC LIMIT 50`,
params,
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) {
return ok(about
? `(no climate noted for ${me} → ${about})`
: `(no climate notes saved yet for ${me})`)
}
const fmt = (n: number) => (n >= 0 ? `+${n.toFixed(2)}` : n.toFixed(2))
return ok([
`Climate around ${me} (${rows.length} relationship${rows.length === 1 ? '' : 's'}):`,
'',
...rows.map((r) => {
const t = new Date(r.updated_at).toLocaleDateString()
return ` ${r.about_id.padEnd(10)} affinity=${fmt(r.affinity)} trust=${fmt(r.trust)} ${t}\n ${r.last_note.slice(0, 240).replace(/\n/g, ' \\n ')}`
}),
].join('\n'))
}
if (op === 'note') {
// usage: climate note <about_id> "<note>" [--affinity n] [--trust n] [--as id]
const aboutId = parsed.positional[1]
const note = unescapeChat(parsed.positional.slice(2).join(' ')).trim()
if (!aboutId || !note) {
return err('usage: climate note <about_id> "<note>" [--affinity -1..1] [--trust -1..1]')
}
const affinityFlag = parsed.flags.affinity
const trustFlag = parsed.flags.trust
// Read prior so we can seed the deltas if the agent didn't supply them.
const { rows: prior } = await pool.query<{
affinity: number; trust: number; history: unknown
}>(
`SELECT affinity, trust, history FROM agent_climate WHERE agent_id = $1 AND about_id = $2`,
[me, aboutId],
)
const prevAffinity = prior[0]?.affinity ?? 0
const prevTrust = prior[0]?.trust ?? 0
const nextAffinity = affinityFlag !== undefined ? clamp01(affinityFlag) : prevAffinity
const nextTrust = trustFlag !== undefined ? clamp01(trustFlag) : prevTrust
// Append a small history entry. Cap history length so it doesn't grow
// unbounded — keep only the last 20 notes.
const prevHistory = Array.isArray(prior[0]?.history) ? prior[0]!.history as Array<unknown> : []
const newHistory = [
...prevHistory.slice(-19),
{ at: new Date().toISOString(), affinity: nextAffinity, trust: nextTrust, note: note.slice(0, 400) },
]
const tenant = (await agentCompany(me)) ?? 'personal'
await pool.query(
`INSERT INTO agent_climate (agent_id, about_id, company_id, affinity, trust, last_note, history, updated_at)
VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, NOW())
ON CONFLICT (agent_id, about_id) DO UPDATE
SET company_id = EXCLUDED.company_id,
affinity = EXCLUDED.affinity,
trust = EXCLUDED.trust,
last_note = EXCLUDED.last_note,
history = EXCLUDED.history,
updated_at = NOW()`,
[me, aboutId, tenant, nextAffinity, nextTrust, note.slice(0, 400), JSON.stringify(newHistory)],
)
return ok(`climate updated: ${me} → ${aboutId} affinity=${nextAffinity.toFixed(2)} trust=${nextTrust.toFixed(2)}`, [{
event: 'climate.updated',
command: 'climate note',
agentId: me,
aboutId,
affinity: nextAffinity,
trust: nextTrust,
}])
}
if (op === 'forget') {
const aboutId = parsed.positional[1]
if (!aboutId) return err('usage: climate forget <about_id>')
const r = await pool.query(
`DELETE FROM agent_climate WHERE agent_id = $1 AND about_id = $2`,
[me, aboutId],
)
if ((r.rowCount ?? 0) === 0) return err(`no climate to forget for ${me} → ${aboutId}`)
return ok(`forgot climate ${me} → ${aboutId}`, [{
event: 'climate.deleted',
command: 'climate forget',
agentId: me,
aboutId,
}])
}
return err('usage: climate <read|note|forget> [...]')
}
async function cmdLog(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'list'
const me = resolveAs(parsed)
if (op === 'note') {
const body = parsed.positional[1]
if (!body) return err('usage: log note <body> [--as id]')
const id = `log-${randomUUID().slice(0, 12)}`
const tenant = await agentCompany(me)
await pool.query(
`INSERT INTO agent_log (id, agent_id, company_id, kind, body) VALUES ($1, $2, $3, 'note', $4)`,
[id, me, tenant, body],
)
return ok(`logged ${id}`)
}
// list (default)
const limit = Math.min(100, Math.max(1, Number(parsed.flags.limit ?? 30)))
const { rows } = await pool.query<{
id: string; kind: string; body: string; ref: unknown; created_at: string
}>(
`SELECT id, kind, body, ref, created_at
FROM agent_log WHERE agent_id = $1
ORDER BY created_at DESC LIMIT $2`,
[me, limit],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no log entries for ${me})`)
return ok([
`last ${rows.length} log entries for ${me}:`,
'',
...rows.map((r) => {
const t = new Date(r.created_at).toLocaleString()
return ` [${t}] ${r.kind.padEnd(10)} ${r.body.slice(0, 200)}`
}),
].join('\n'))
}
async function cmdWorkspace(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0]
const me = resolveAs(parsed)
// Resolve the agent's tenant once — every write needs to carry the
// company_id so the Observability view (which filters by tenant)
// can actually see what the agent stores. Reads are agent-scoped
// (agent_id is globally unique) so they don't need it.
const tenant = await agentCompany(me)
if (op === 'ls') {
const { rows } = await pool.query<{ path: string; updated_at: string }>(
`SELECT path, updated_at FROM agent_workspace WHERE agent_id = $1 ORDER BY path ASC`,
[me],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(${me}'s workspace is empty)`)
return ok([
`${rows.length} file(s) in ${me}'s workspace:`,
'',
...rows.map((r) => ` ${r.path.padEnd(40)} ${new Date(r.updated_at).toLocaleString()}`),
].join('\n'))
}
if (op === 'read') {
const path = parsed.positional[1]
if (!path) return err('usage: workspace read <path> [--as id]')
const { rows } = await pool.query<{ body: string; updated_at: string }>(
`SELECT body, updated_at FROM agent_workspace WHERE agent_id = $1 AND path = $2`,
[me, path],
)
if (!rows[0]) return err(`no file at ${path} in ${me}'s workspace`)
return ok(rows[0].body)
}
if (op === 'write') {
const path = parsed.positional[1]
const body = parsed.positional.slice(2).join(' ')
if (!path || !body) return err('usage: workspace write <path> <body> [--as id]')
const memMeta = path.startsWith('memory/')
? await memoryMetaForWrite(me, { path })
: null
await pool.query(
`INSERT INTO agent_workspace (agent_id, path, body, meta, company_id, updated_at)
VALUES ($1, $2, $3, $4::jsonb, $5, NOW())
ON CONFLICT (agent_id, path) DO UPDATE
SET body = EXCLUDED.body,
company_id = EXCLUDED.company_id,
meta = COALESCE(agent_workspace.meta, EXCLUDED.meta),
updated_at = NOW()`,
[me, path, body, memMeta ? JSON.stringify(memMeta) : null, tenant],
)
return ok(`wrote ${path} (${body.length} chars)`, [{
event: 'workspace.file_written',
command: 'workspace write',
agentId: me,
companyId: tenant ?? undefined,
path,
bodyLength: body.length,
}])
}
if (op === 'delete') {
const path = parsed.positional[1]
if (!path) return err('usage: workspace delete <path> [--as id]')
const r = await pool.query(`DELETE FROM agent_workspace WHERE agent_id = $1 AND path = $2`, [me, path])
if ((r.rowCount ?? 0) === 0) return err(`no file at ${path}`)
return ok(`deleted ${path}`, [{
event: 'workspace.file_deleted',
command: 'workspace delete',
agentId: me,
companyId: tenant ?? undefined,
path,
}])
}
if (op === 'edit') {
const path = parsed.positional[1]
const oldStr = parsed.positional[2]
const newStr = parsed.positional[3] ?? ''
if (!path || oldStr === undefined) return err('usage: workspace edit <path> <old> <new> [--as id]')
const { rows } = await pool.query<{ body: string }>(
`SELECT body FROM agent_workspace WHERE agent_id = $1 AND path = $2`, [me, path],
)
if (!rows[0]) return err(`no file at ${path}`)
const body = rows[0].body
const occurrences = body.split(oldStr).length - 1
if (occurrences === 0) return err(`old string not found in ${path}`)
if (occurrences > 1 && !parsed.flags.all) return err(`old string appears ${occurrences} times in ${path} — pass --all or include more context to make it unique`)
const next = parsed.flags.all ? body.split(oldStr).join(newStr) : body.replace(oldStr, newStr)
await pool.query(
`UPDATE agent_workspace SET body = $3, updated_at = NOW() WHERE agent_id = $1 AND path = $2`,
[me, path, next],
)
return ok(`edited ${path} (${occurrences} replacement${occurrences === 1 ? '' : 's'})`, [{
event: 'workspace.file_updated',
command: 'workspace edit',
agentId: me,
companyId: tenant ?? undefined,
path,
replacements: occurrences,
bodyLength: next.length,
}])
}
if (op === 'grep') {
const pattern = parsed.positional[1]
if (!pattern) return err('usage: workspace grep <pattern> [--as id]')
let re: RegExp
try { re = new RegExp(pattern, parsed.flags.i ? 'gi' : 'g') } catch { return err(`bad regex: ${pattern}`) }
const { rows } = await pool.query<{ path: string; body: string }>(
`SELECT path, body FROM agent_workspace WHERE agent_id = $1 ORDER BY path ASC`, [me],
)
const hits: string[] = []
for (const r of rows) {
const lines = r.body.split('\n')
lines.forEach((line, i) => {
if (re.test(line)) hits.push(` ${r.path}:${i + 1}: ${line.slice(0, 200)}`)
re.lastIndex = 0
})
}
if (parsed.flags.json) return ok(JSON.stringify(hits, null, 2))
if (hits.length === 0) return ok(`(no matches for /${pattern}/ in ${me}'s workspace)`)
return ok([`${hits.length} match(es):`, '', ...hits].join('\n'))
}
return err(`usage: workspace <ls|read|write|edit|grep|delete> [...]`)
}
async function cmdTasks(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'list'
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (op === 'list') {
const params: unknown[] = [me]
let where = `agent_id = $1`
if (parsed.flags.status) { params.push(String(parsed.flags.status)); where += ` AND status = $${params.length}` }
const { rows } = await pool.query<{
id: string; title: string; status: string; due_at: string | null;
created_at: string; updated_at: string
}>(
`SELECT id, title, status, due_at, created_at, updated_at
FROM agent_tasks WHERE ${where} ORDER BY status ASC, updated_at DESC`,
params,
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no tasks for ${me})`)
return ok([
`${rows.length} task(s) for ${me}:`,
'',
...rows.map((t) => ` [${t.status.padEnd(7)}] ${t.id.slice(0, 12).padEnd(13)} ${t.title}`),
].join('\n'))
}
if (op === 'add') {
const title = parsed.positional.slice(1).join(' ')
if (!title) return err('usage: tasks add <title> [--as id]')
const id = `task-${randomUUID().slice(0, 12)}`
await pool.query(
`INSERT INTO agent_tasks (id, agent_id, company_id, title) VALUES ($1, $2, $3, $4)`,
[id, me, companyId, title],
)
return ok(`added task ${id}: ${title}`, [{
event: 'task.created',
command: 'tasks add',
taskId: id,
agentId: me,
companyId: companyId ?? undefined,
title,
status: 'open',
visibleToUser: true,
}])
}
if (op === 'set') {
const id = parsed.positional[1]
const status = parsed.positional[2]
if (!id || !status) return err('usage: tasks set <task_id> <status>')
if (!['open', 'doing', 'done', 'dropped'].includes(status)) return err(`bad status: ${status}`)
const r = await pool.query(
`UPDATE agent_tasks SET status = $3, updated_at = NOW() WHERE id = $1 AND agent_id = $2`,
[id, me, status],
)
if ((r.rowCount ?? 0) === 0) return err(`no task ${id} for ${me}`)
return ok(`task ${id} → ${status}`, [{
event: 'task.status_changed',
command: 'tasks set',
taskId: id,
agentId: me,
companyId: companyId ?? undefined,
status,
visibleToUser: true,
}])
}
return err(`usage: tasks <list|add|set> [...]`)
}
/* ============== calendar ==============
*
* Same calendar humans see — agents read upcoming events assigned to them
* (so "what's on my plate today" is a single command) and create new
* events to schedule work for themselves or another agent. All rows live
* in the agent's company; cross-tenant safety is enforced the same way as
* tasks/email above.
*/
/** Visibility predicate for the agent CLI. Mirrors the REST helper but
* with one simplification: agents can't be company owners, so the
* owner-override branch never applies — the predicate collapses to the
* basic "public OR I am the author / assignee" form. Caller binds its
* participant id at `meIdx`. */
function cliCalendarVisibilityClause(meIdx: number): string {
return `(is_private = false OR created_by = $${meIdx} OR assignee_id = $${meIdx})`
}
/** Queue the calendar invalidation alongside the CLI mutation. */
async function enqueueCalendarCli(db: PoolClient, args: {
companyId: string
kind: 'event.created' | 'event.updated' | 'event.deleted' | 'event.dispatched'
eventId: string
actorId: string
}): Promise<void> {
await enqueueBroadcast(db, CH_CALENDAR_EVENTS, {
type: 'calendar.changed',
companyId: args.companyId,
kind: args.kind,
eventId: args.eventId,
actorId: args.actorId,
})
}
async function cmdCalendar(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'list'
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
if (op === 'list') {
// Default scope: events assigned to `me` OR created by `me`. The
// `--all` flag widens to every event in the workspace (parity with
// the UI's "Workspace" filter).
const all = Boolean(parsed.flags.all)
const params: unknown[] = [companyId, me]
let where = `company_id = $1`
if (all) {
// --all widens to the whole workspace, BUT we still hide private
// rows the caller isn't authorized to read. The default (narrow)
// path is already self-filtered via assignee_id/created_by.
where += ` AND ${cliCalendarVisibilityClause(2)}`
} else {
where += ` AND (assignee_id = $2 OR created_by = $2)`
}
if (parsed.flags.status) {
params.push(String(parsed.flags.status))
where += ` AND status = $${params.length}`
}
const { rows } = await pool.query<{
id: string; title: string; kind: string; status: string;
assignee_id: string | null; start_at: Date; recurrence: { freq: string; interval: number } | null;
target_conversation_id: string | null; is_private: boolean
}>(
`SELECT id, title, kind, status, assignee_id, start_at, recurrence,
target_conversation_id, is_private
FROM calendar_events WHERE ${where}
ORDER BY start_at ASC LIMIT 200`,
params,
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no calendar events for ${me}${all ? ' [workspace]' : ''})`)
return ok([
`${rows.length} calendar event(s)${all ? ' in workspace' : ` for ${me}`}:`,
'',
...rows.map((r) => {
const rep = r.recurrence ? `every ${r.recurrence.interval || 1} ${r.recurrence.freq}` : 'one-shot'
const who = r.assignee_id ? ` → @${r.assignee_id}` : ''
const lock = r.is_private ? ' 🔒' : ''
return ` [${r.status.padEnd(7)}] ${r.id.slice(0, 14).padEnd(15)} ${r.start_at.toISOString().slice(0, 16)} · ${rep}${who}${lock} ${r.title}`
}),
].join('\n'))
}
if (op === 'create') {
// usage: calendar create "<title>" --at <iso> [--assignee <id>] [--prompt "..."]
// [--in <convo_id>] [--every daily|weekly|monthly|yearly]
// [--interval N] [--byweekday 0,1,2] [--until <iso>] [--count N]
// [--kind personal|agent_task]
const title = parsed.positional.slice(1).join(' ').trim()
if (!title) return err('usage: calendar create "<title>" --at <iso> [flags]')
const startStr = parsed.flags.at ? String(parsed.flags.at) : ''
if (!startStr) return err('--at <iso-timestamp> is required')
const start = new Date(startStr)
if (Number.isNaN(start.getTime())) return err(`invalid --at: ${startStr}`)
const assigneeId = parsed.flags.assignee ? String(parsed.flags.assignee) : null
const agentPrompt = parsed.flags.prompt ? String(parsed.flags.prompt) : null
const targetConvo = parsed.flags.in ? String(parsed.flags.in) : null
const kind = parsed.flags.kind === 'personal' ? 'personal' : (assigneeId || agentPrompt ? 'agent_task' : 'personal')
if (kind === 'agent_task' && !assigneeId) {
return err('agent_task events need an --assignee')
}
let recurrence: Record<string, unknown> | null = null
if (parsed.flags.every) {
const freq = String(parsed.flags.every)
if (!['daily', 'weekly', 'monthly', 'yearly'].includes(freq)) {
return err(`--every must be daily|weekly|monthly|yearly (got: ${freq})`)
}
const interval = parsed.flags.interval ? Math.max(1, Math.floor(Number(parsed.flags.interval))) : 1
const byweekday = parsed.flags.byweekday
? String(parsed.flags.byweekday).split(',').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n >= 0 && n <= 6)
: undefined
const until = parsed.flags.until ? String(parsed.flags.until) : null
const count = parsed.flags.count ? Math.floor(Number(parsed.flags.count)) : null
recurrence = { freq, interval, byweekday, until, count }
}
// Optional reminder. `--remind <minutes>` pairs with `--remind-channel
// toast|email|both` (defaults to toast). Either both flags or neither.
// --private hides this row from everyone in the workspace except its
// created_by (the calling agent) and assignee_id. Useful for personal
// reminders an agent sets for itself that would otherwise clutter the
// shared calendar.
const isPrivate = Boolean(parsed.flags.private)
let reminderMinutes: number | null = null
let reminderChannel: 'toast' | 'email' | 'both' | null = null
if (parsed.flags.remind !== undefined) {
const n = Math.floor(Number(parsed.flags.remind))
if (!Number.isFinite(n) || n < 0) return err(`--remind must be minutes (got: ${parsed.flags.remind})`)
reminderMinutes = n
const ch = parsed.flags['remind-channel'] ? String(parsed.flags['remind-channel']) : 'toast'
if (ch !== 'toast' && ch !== 'email' && ch !== 'both') {
return err(`--remind-channel must be toast|email|both (got: ${ch})`)
}
reminderChannel = ch
}
// Same two-layer anti-duplicate shape as `doc create`: an in-flight
// tenant claim against a CONCURRENT peer creating the same event, plus
// a recently-created check against a SEQUENTIAL duplicate (peer created
// it seconds ago and already released the claim). One team meeting
// scheduled twice is the calendar analog of the double-doc incident.
const calBlocked = await tryClaimTenantWork(companyId, me, 'calendar-create', title)
if (calBlocked) return calBlocked
try {
// Private events are exempt on BOTH sides: a private reminder is not
// shared work, and we must not leak another agent's private event
// title through a HELD envelope.
if (!isPrivate) {
const { normalizeWorkSubject } = await import('./runtime/inproc-client.js')
const normTitle = normalizeWorkSubject(title)
const calHoldScope = `calendar-create:${normTitle}`
const forceArmed = Boolean(parsed.flags.force) && (await consumeHold(me, calHoldScope)).armed
if (!forceArmed) {
const { rows: recentDups } = await pool.query<{
id: string; title: string; created_by: string; created_at: Date
}>(
`SELECT id, title, created_by, created_at FROM calendar_events
WHERE company_id = $1 AND created_by <> $2
AND status = 'active' AND is_private = FALSE
AND created_at > NOW() - INTERVAL '15 minutes'
ORDER BY created_at DESC LIMIT 50`,
[companyId, me],
)
const dup = recentDups.find((d) => normalizeWorkSubject(d.title) === normTitle)
if (dup) {
await recordHold(me, calHoldScope)
const ageSec = Math.max(1, Math.round((Date.now() - dup.created_at.getTime()) / 1000))
return err(
`HELD — event NOT created. ${dup.created_by} already scheduled "${dup.title}" (${dup.id}) ${ageSec}s ago — ` +
`this work is DONE; a second copy double-books everyone. ` +
`Inspect theirs instead: \`cumora calendar list\` / \`cumora calendar update ${dup.id} ...\` if it needs changes. ` +
`If you GENUINELY need a separate same-title event, rerun with --force ` +
`(--force only works after you've been shown this hold — passing it preemptively does nothing).`,
2,
)
}
}
}
const id = `ce-${randomUUID()}`
await withOutboxTransaction(async (client) => {
await client.query(
`INSERT INTO calendar_events
(id, company_id, created_by, kind, title, assignee_id,
target_conversation_id, agent_prompt, start_at, recurrence,
reminder_minutes_before, reminder_channel, status, is_private)
VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11,$12,'active',$13)`,
[id, companyId, me, kind, title, assigneeId, targetConvo, agentPrompt, start,
recurrence ? JSON.stringify(recurrence) : null,
reminderMinutes, reminderChannel, isPrivate],
)
await enqueueCalendarCli(client, { companyId, kind: 'event.created', eventId: id, actorId: me })
})
return ok(`scheduled ${id}: "${title}" at ${start.toISOString()}${recurrence ? ` · every ${recurrence.interval} ${recurrence.freq}` : ''}${assigneeId ? ` → @${assigneeId}` : ''}${reminderMinutes != null ? ` · remind ${reminderMinutes}m before (${reminderChannel})` : ''}${isPrivate ? ' · 🔒 private' : ''}`, [{
event: 'calendar.event_created',
command: 'calendar create',
calendarEventId: id,
actorId: me,
companyId,
title,
kind,
assigneeId,
targetConversationId: targetConvo,
startAt: start.toISOString(),
recurrence,
reminderMinutesBefore: reminderMinutes,
reminderChannel,
visibleToUser: true,
}])
} finally {
await releaseTenantWork(companyId, me, 'calendar-create', title)
}
}
if (op === 'update' || op === 'edit') {
const id = parsed.positional[1]
if (!id) return err(`usage: calendar ${op} <event_id> [--title "..."] [--at <iso>] [--status active|cancelled|done] [flags]`)
// Privacy guard: same visibility rule as list. Callers who can't see
// the row can't modify it. The check is folded into the UPDATE so we
// don't pay an extra round trip.
{
const { rows } = await pool.query(
`SELECT 1 FROM calendar_events
WHERE id = $1 AND company_id = $2 AND ${cliCalendarVisibilityClause(3)}
LIMIT 1`,
[id, companyId, me],
)
if (!rows[0]) return err(`no event ${id}`)
}
const sets: string[] = []
const params: unknown[] = []
const push = (column: string, value: unknown) => {
params.push(value)
sets.push(`${column} = $${params.length}`)
}
if (parsed.flags.title !== undefined) {
const title = String(parsed.flags.title).trim().slice(0, 200)
if (!title) return err('--title cannot be empty')
push('title', title)
}
if (parsed.flags.description !== undefined) {
push('description', String(parsed.flags.description).slice(0, 4000) || null)
}
if (parsed.flags.kind !== undefined) {
const kind = String(parsed.flags.kind)
if (!['personal', 'agent_task'].includes(kind)) return err('--kind must be personal|agent_task')
push('kind', kind)
}
if (parsed.flags.assignee !== undefined) {
const assignee = String(parsed.flags.assignee).trim()
push('assignee_id', !assignee || assignee === 'null' || assignee === '-' ? null : assignee)
}
if (parsed.flags.prompt !== undefined) {
push('agent_prompt', String(parsed.flags.prompt).slice(0, 8000) || null)
}
if (parsed.flags.in !== undefined) {
const target = String(parsed.flags.in).trim()
push('target_conversation_id', !target || target === 'null' || target === '-' ? null : target)
}
if (parsed.flags.at !== undefined) {
const start = new Date(String(parsed.flags.at))
if (Number.isNaN(start.getTime())) return err(`invalid --at: ${parsed.flags.at}`)
push('start_at', start)
}
if (parsed.flags.end !== undefined) {
const raw = String(parsed.flags.end).trim()
if (!raw || raw === 'null' || raw === '-') push('end_at', null)
else {
const end = new Date(raw)
if (Number.isNaN(end.getTime())) return err(`invalid --end: ${raw}`)
push('end_at', end)
}
}
if (parsed.flags.status !== undefined) {
const status = String(parsed.flags.status)
if (!['active', 'cancelled', 'done'].includes(status)) return err('--status must be active|cancelled|done')
push('status', status)
}
if (parsed.flags.remind !== undefined) {
const raw = String(parsed.flags.remind).trim()
if (!raw || raw === 'null' || raw === '-') push('reminder_minutes_before', null)
else {
const n = Math.floor(Number(raw))
if (!Number.isFinite(n) || n < 0 || n > 14 * 24 * 60) return err(`--remind must be minutes in [0, 20160] (got: ${raw})`)
push('reminder_minutes_before', n)
}
}
if (parsed.flags['remind-channel'] !== undefined) {
const ch = String(parsed.flags['remind-channel']).trim()
if (!ch || ch === 'null' || ch === '-') push('reminder_channel', null)
else {
if (ch !== 'toast' && ch !== 'email' && ch !== 'both') return err('--remind-channel must be toast|email|both')
push('reminder_channel', ch)
}
}
// --private flips the row to private; --public flips it back. Either
// wins if both are passed; --private takes precedence (defensive).
if (parsed.flags.private !== undefined) push('is_private', true)
else if (parsed.flags.public !== undefined) push('is_private', false)
if (parsed.flags.every !== undefined || parsed.flags['clear-recurrence'] !== undefined) {
if (parsed.flags['clear-recurrence'] !== undefined) {
params.push(null)
sets.push(`recurrence = $${params.length}::jsonb`)
} else {
const freq = String(parsed.flags.every)
if (!['daily', 'weekly', 'monthly', 'yearly'].includes(freq)) {
return err(`--every must be daily|weekly|monthly|yearly (got: ${freq})`)
}
const interval = parsed.flags.interval ? Math.max(1, Math.floor(Number(parsed.flags.interval))) : 1
const byweekday = parsed.flags.byweekday
? String(parsed.flags.byweekday).split(',').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n >= 0 && n <= 6)
: undefined
const until = parsed.flags.until ? String(parsed.flags.until) : null
const count = parsed.flags.count ? Math.floor(Number(parsed.flags.count)) : null
params.push(JSON.stringify({ freq, interval, byweekday, until, count }))
sets.push(`recurrence = $${params.length}::jsonb`)
}
}
if (sets.length === 0) return err('nothing to update — pass at least one calendar field flag')
sets.push('updated_at = NOW()')
params.push(id, companyId)
const rows = await withOutboxTransaction(async (client) => {
const updated = await client.query<{
id: string; title: string; kind: string; status: string;
assignee_id: string | null; target_conversation_id: string | null; start_at: Date
}>(
`UPDATE calendar_events SET ${sets.join(', ')}
WHERE id = $${params.length - 1} AND company_id = $${params.length}
RETURNING id, title, kind, status, assignee_id, target_conversation_id, start_at`,
params,
)
if (updated.rows[0]) {
await enqueueCalendarCli(client, { companyId, kind: 'event.updated', eventId: id, actorId: me })
}
return updated.rows
})
const row = rows[0]
if (!row) return err(`no event ${id}`)
return ok(`updated ${id}: "${row.title}" at ${row.start_at.toISOString()} (${row.status})`, [{
event: 'calendar.event_updated',
command: `calendar ${op}`,
calendarEventId: id,
actorId: me,
companyId,
title: row.title,
kind: row.kind,
status: row.status,
assigneeId: row.assignee_id,
targetConversationId: row.target_conversation_id,
startAt: row.start_at.toISOString(),
visibleToUser: true,
}])
}
if (op === 'run-now') {
const id = parsed.positional[1]
if (!id) return err('usage: calendar run-now <event_id>')
// Privacy gate: only people who can see the row can dispatch it.
const { rows } = await pool.query(
`SELECT id, company_id, created_by, kind, title, description, assignee_id,
target_conversation_id, agent_prompt, start_at, end_at, all_day,
recurrence, status, last_fired_at,
reminder_minutes_before, reminder_channel,
is_private,
created_at, updated_at
FROM calendar_events
WHERE id = $1 AND company_id = $2 AND ${cliCalendarVisibilityClause(3)}`,
[id, companyId, me],
)
if (!rows[0]) return err(`no event ${id}`)
const { dispatchEvent } = await import('../calendar.js')
const result = await dispatchEvent(rows[0] as import('../calendar.js').CalendarEventRow, new Date())
await withOutboxTransaction((client) => enqueueCalendarCli(
client,
{ companyId, kind: 'event.dispatched', eventId: id, actorId: me },
))
return ok(`dispatched ${id}: ${JSON.stringify(result)}`, [{
event: 'calendar.event_dispatched',
command: 'calendar run-now',
calendarEventId: id,
actorId: me,
companyId,
result,
visibleToUser: true,
}])
}
if (op === 'dispatches') {
const id = parsed.positional[1]
if (!id) return err('usage: calendar dispatches <event_id>')
const { rows } = await pool.query<{
id: string; event_id: string; scheduled_for: Date; dispatched_at: Date;
status: string; conversation_id: string | null; message_id: string | null; error: string | null
}>(
`SELECT cd.id, cd.event_id, cd.scheduled_for, cd.dispatched_at, cd.status,
cd.conversation_id, cd.message_id, cd.error
FROM calendar_dispatches cd
JOIN calendar_events ce ON ce.id = cd.event_id
WHERE cd.event_id = $1 AND ce.company_id = $2
ORDER BY cd.scheduled_for DESC LIMIT 200`,
[id, companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no dispatches for ${id})`)
return ok([
`${rows.length} dispatch(es) for ${id}:`,
'',
...rows.map((r) =>
` [${r.status}] ${r.scheduled_for.toISOString()} → ${r.conversation_id ?? '-'} ${r.message_id ?? ''}${r.error ? ` · ${r.error}` : ''}`,
),
].join('\n'))
}
if (op === 'cancel' || op === 'delete') {
const id = parsed.positional[1]
if (!id) return err(`usage: calendar ${op} <event_id>`)
// Visibility guard folded into the WHERE clause: rowCount === 0 maps
// to "no event found" regardless of whether the row is missing or
// privacy-filtered, so we don't leak existence to non-authorized
// callers.
const r = await withOutboxTransaction(async (client) => {
const changed = await client.query(
op === 'delete'
? `DELETE FROM calendar_events
WHERE id = $1 AND company_id = $2 AND ${cliCalendarVisibilityClause(3)}`
: `UPDATE calendar_events SET status = 'cancelled', updated_at = NOW()
WHERE id = $1 AND company_id = $2 AND ${cliCalendarVisibilityClause(3)}`,
[id, companyId, me],
)
if ((changed.rowCount ?? 0) > 0) {
await enqueueCalendarCli(client, {
companyId,
kind: op === 'delete' ? 'event.deleted' : 'event.updated',
eventId: id,
actorId: me,
})
}
return changed
})
if ((r.rowCount ?? 0) === 0) return err(`no event ${id}`)
// `cancel` flips status → updated; `delete` drops the row → deleted.
// Clients listening on calendar.changed will refetch (or drop the row
// from local state) accordingly.
return ok(`${op === 'delete' ? 'deleted' : 'cancelled'} ${id}`, [{
event: op === 'delete' ? 'calendar.event_deleted' : 'calendar.event_cancelled',
command: `calendar ${op}`,
calendarEventId: id,
actorId: me,
companyId,
visibleToUser: true,
}])
}
return err(`usage: calendar <list|create|update|run-now|dispatches|cancel|delete> [...]`)
}
/* ============== kanban boards ==============
*
* Same shape as the rest of this file: the agent operates as `me` (the
* --as participant) inside that participant's tenant. All inserts /
* updates enqueue on the `boards` channel so the desktop client + every
* other connected member sees the change in real time. */
type KanbanMentionTarget = { id: string; name: string }
function cliMentionStartBoundary(text: string, index: number): boolean {
if (index <= 0) return true
return !/[\w@]/.test(text[index - 1])
}
function cliMentionEndBoundary(text: string, index: number): boolean {
const next = text[index]
return !next || !/[a-z0-9_-]/i.test(next)
}
function cliParseMentionTargets(text: string, targets: KanbanMentionTarget[]): string[] {
if (!text) return []
const out: string[] = []
const seen = new Set<string>()
const candidates = targets
.flatMap((p) => [
{ id: p.id, token: p.id },
{ id: p.id, token: p.name.trim() },
])
.filter((candidate) => candidate.token.length > 0)
.sort((a, b) => b.token.length - a.token.length)
const lower = text.toLowerCase()
for (let i = 0; i < text.length; i++) {
if (text[i] !== '@' || !cliMentionStartBoundary(text, i)) continue
const rest = lower.slice(i + 1)
const match = candidates.find((candidate) =>
rest.startsWith(candidate.token.toLowerCase()) &&
cliMentionEndBoundary(text, i + 1 + candidate.token.length)
)
const fallback = match ? null : /^@([a-z0-9][a-z0-9_-]{0,63})/i.exec(text.slice(i))
const id = match?.id ?? fallback?.[1]?.toLowerCase()
if (!id) continue
if (id === 'all') continue
if (seen.has(id)) continue
seen.add(id)
out.push(id)
i += (match ? match.token.length : fallback![0].length - 1)
}
return out
}
/** Same parsing contract as the REST router uses — keep them aligned so an
* agent's `card add` and a human's card form parse mentions the same. */
async function cliParseMentions(companyId: string, text: string): Promise<string[]> {
const { rows } = await pool.query<KanbanMentionTarget>(
`SELECT id, name
FROM participants
WHERE company_id = $1
AND departed_at IS NULL`,
[companyId],
)
return cliParseMentionTargets(text, rows)
}
async function enqueueBoardCli(db: PoolClient, args: {
companyId: string
kind:
| 'board.created' | 'board.updated' | 'board.deleted'
| 'column.created' | 'column.updated' | 'column.deleted'
| 'card.created' | 'card.updated' | 'card.moved' | 'card.deleted'
| 'comment.created' | 'comment.deleted'
boardId: string
cardId?: string
columnId?: string
commentId?: string
mentions?: string[]
actorId: string
}): Promise<void> {
await enqueueBroadcast(db, CH_BOARDS, {
type: 'board.changed',
companyId: args.companyId,
kind: args.kind,
boardId: args.boardId,
cardId: args.cardId,
columnId: args.columnId,
commentId: args.commentId,
mentions: args.mentions,
actorId: args.actorId,
})
}
async function cmdBoard(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'ls'
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
if (op === 'ls' || op === 'list') {
const { rows } = await pool.query<{
id: string; title: string; description: string | null; updated_at: string
}>(
`SELECT id, title, description, updated_at FROM boards
WHERE company_id = $1 ORDER BY updated_at DESC`,
[companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok(`(no boards in this workspace)`)
return ok([
`${rows.length} board(s):`,
'',
...rows.map((b) => ` ${b.id.padEnd(20)} ${b.title}`),
].join('\n'))
}
if (op === 'show' || op === 'view') {
const boardId = parsed.positional[1]
if (!boardId) return err('usage: kanban show <board_id>')
const b = await pool.query<{
id: string; title: string; description: string | null; company_id: string
}>(`SELECT id, title, description, company_id FROM boards WHERE id = $1 LIMIT 1`, [boardId])
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const cols = await pool.query<{
id: string; title: string; position: number; kind: string | null
}>(`SELECT id, title, position, kind FROM board_columns WHERE board_id = $1 ORDER BY position ASC`, [boardId])
const cards = await pool.query<{
id: string; column_id: string; title: string; assignee_id: string | null
mentions: string[]; position: number; due_on: string | null
}>(
`SELECT id, column_id, title, assignee_id, mentions, position, due_on::text AS due_on
FROM board_cards WHERE board_id = $1 ORDER BY column_id, position ASC`,
[boardId],
)
if (parsed.flags.json) {
return ok(JSON.stringify({
board: b.rows[0], columns: cols.rows, cards: cards.rows,
}, null, 2))
}
const cardsByCol = new Map<string, typeof cards.rows>()
for (const c of cards.rows) {
const arr = cardsByCol.get(c.column_id) ?? []
arr.push(c); cardsByCol.set(c.column_id, arr)
}
const lines: string[] = [`# ${b.rows[0].title} (${b.rows[0].id})`]
if (b.rows[0].description) lines.push(b.rows[0].description)
for (const col of cols.rows) {
const list = cardsByCol.get(col.id) ?? []
// Name the column's MEANING, not just its title: an agent moving a card
// should not have to infer which column counts as done from prose.
const meaning = col.kind ? ` [${col.kind}]` : ''
lines.push('', `## ${col.title}${meaning} (${col.id}) · ${list.length} card(s)`)
for (const c of list) {
const who = c.assignee_id ? `@${c.assignee_id}` : '(unassigned)'
const mentions = Array.isArray(c.mentions) && c.mentions.length > 0
? ` · mentions: ${c.mentions.map((m) => '@' + m).join(' ')}`
: ''
lines.push(` - ${c.id.padEnd(20)} ${who.padEnd(16)} ${c.title}${c.due_on ? ` (due ${c.due_on})` : ''}${mentions}`)
}
}
return ok(lines.join('\n'))
}
if (op === 'create' || op === 'new') {
const title = parsed.positional.slice(1).join(' ').trim()
|| (typeof parsed.flags.title === 'string' ? parsed.flags.title : '')
if (!title) return err('usage: kanban create "<title>" [--description "..."]')
const description = typeof parsed.flags.description === 'string'
? unescapeChat(parsed.flags.description).slice(0, 4000) : null
const id = `board-${randomUUID().slice(0, 12)}`
await withOutboxTransaction(async (client) => {
await client.query(
`INSERT INTO boards (id, company_id, title, description, created_by) VALUES ($1, $2, $3, $4, $5)`,
[id, companyId, title.slice(0, 200), description, me],
)
// Seed the MEANING alongside the title, so an agent asked to advance a
// card never has to infer "which column is Doing" from prose.
const seeds: Array<[string, ColumnKind]> = [['Todo', 'todo'], ['Doing', 'doing'], ['Done', 'done']]
for (let i = 0; i < seeds.length; i++) {
await client.query(
`INSERT INTO board_columns (id, board_id, title, position, kind) VALUES ($1, $2, $3, $4, $5)`,
[`col-${randomUUID().slice(0, 12)}`, id, seeds[i][0], (i + 1) * 1000, seeds[i][1]],
)
}
await enqueueBoardCli(client, { companyId, kind: 'board.created', boardId: id, actorId: me })
})
return ok(`created board ${id}: ${title}`, [{
event: 'kanban.board_created',
command: 'kanban create',
boardId: id,
actorId: me,
companyId,
title,
visibleToUser: true,
}])
}
if (op === 'rename' || op === 'edit' || op === 'update') {
const boardId = parsed.positional[1]
if (!boardId) return err(`usage: kanban ${op} <board_id> --title "..." [--description "..."]`)
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`,
[boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const sets: string[] = []
const params: unknown[] = []
let nextTitle: string | undefined
if (typeof parsed.flags.title === 'string' || parsed.positional.length > 2) {
nextTitle = (typeof parsed.flags.title === 'string'
? unescapeChat(parsed.flags.title)
: parsed.positional.slice(2).join(' ')).trim().slice(0, 200)
if (!nextTitle) return err('--title cannot be empty')
params.push(nextTitle); sets.push(`title = $${params.length}`)
}
let nextDescription: string | null | undefined
if (typeof parsed.flags.description === 'string') {
nextDescription = unescapeChat(parsed.flags.description).trim().slice(0, 4000) || null
params.push(nextDescription); sets.push(`description = $${params.length}`)
}
if (sets.length === 0) return err('nothing to update — pass --title or --description')
params.push(boardId, companyId)
const rows = await withOutboxTransaction(async (client) => {
const updated = await client.query<{ title: string; description: string | null }>(
`UPDATE boards SET ${sets.join(', ')}, updated_at = NOW()
WHERE id = $${params.length - 1} AND company_id = $${params.length}
RETURNING title, description`,
params,
)
if (updated.rows[0]) {
await enqueueBoardCli(client, { companyId, kind: 'board.updated', boardId, actorId: me })
}
return updated.rows
})
if (rows.length === 0) return err(`board ${boardId} not found`)
return ok(`updated board ${boardId}: ${rows[0].title}`, [{
event: 'kanban.board_updated',
command: `kanban ${op}`,
boardId,
actorId: me,
companyId,
title: rows[0].title,
description: rows[0].description,
visibleToUser: true,
}])
}
if (op === 'columns' || op === 'cols') {
const boardId = parsed.positional[1]
if (!boardId) return err('usage: kanban columns <board_id>')
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`, [boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const { rows } = await pool.query<{ id: string; title: string; kind: string | null }>(
`SELECT id, title, kind FROM board_columns WHERE board_id = $1 ORDER BY position ASC`,
[boardId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
return ok(rows.map((c) => ` ${c.id.padEnd(20)} ${c.title}${c.kind ? ` [${c.kind}]` : ''}`).join('\n') || '(no columns)')
}
if (op === 'add-column' || op === 'add-col') {
const boardId = parsed.positional[1]
const title = parsed.positional.slice(2).join(' ').trim()
if (!boardId || !title) return err('usage: kanban add-column <board_id> "<title>"')
const kind = parsed.flags.kind === undefined ? null : parsed.flags.kind
if (kind !== null && !['todo', 'doing', 'done'].includes(kind as string)) return err('--kind must be todo, doing, or done')
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`, [boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const { rows: posRows } = await pool.query<{ max: number | null }>(
`SELECT MAX(position) AS max FROM board_columns WHERE board_id = $1`, [boardId],
)
const position = (Number(posRows[0]?.max ?? 0)) + 1000
const id = `col-${randomUUID().slice(0, 12)}`
await withOutboxTransaction(async (client) => {
await client.query(
`INSERT INTO board_columns (id, board_id, title, position, kind) VALUES ($1, $2, $3, $4, $5)`,
[id, boardId, title.slice(0, 100), position, kind],
)
await enqueueBoardCli(client, { companyId, kind: 'column.created', boardId, columnId: id, actorId: me })
})
return ok(`added column ${id}: ${title}`, [{
event: 'kanban.column_created',
command: 'kanban add-column',
boardId,
columnId: id,
actorId: me,
companyId,
title,
visibleToUser: true,
}])
}
if (op === 'edit-column' || op === 'rename-column' || op === 'update-column') {
const boardId = parsed.positional[1]
const columnId = parsed.positional[2]
if (!boardId || !columnId) {
return err(`usage: kanban ${op} <board_id> <column_id> [--title "..."] [--position N] [--kind todo|doing|done|clear]`)
}
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`,
[boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const sets: string[] = []
const params: unknown[] = []
if (typeof parsed.flags.title === 'string' || parsed.positional.length > 3) {
const title = (typeof parsed.flags.title === 'string'
? unescapeChat(parsed.flags.title)
: parsed.positional.slice(3).join(' ')).trim().slice(0, 100)
if (!title) return err('--title cannot be empty')
params.push(title); sets.push(`title = $${params.length}`)
}
if (parsed.flags.position !== undefined) {
const position = Number(parsed.flags.position)
if (!Number.isFinite(position)) return err(`invalid --position: ${parsed.flags.position}`)
params.push(position); sets.push(`position = $${params.length}`)
}
if (parsed.flags.kind !== undefined) {
const kind = parsed.flags.kind === 'clear' ? null : parsed.flags.kind
if (kind !== null && !['todo', 'doing', 'done'].includes(kind as string)) return err('--kind must be todo, doing, done, or clear')
params.push(kind); sets.push(`kind = $${params.length}`)
}
if (sets.length === 0) return err('nothing to update — pass --title, --position, or --kind')
params.push(columnId, boardId)
const rows = await withOutboxTransaction(async (client) => {
const updated = await client.query<{ title: string; position: number }>(
`UPDATE board_columns SET ${sets.join(', ')}
WHERE id = $${params.length - 1} AND board_id = $${params.length}
RETURNING title, position`,
params,
)
if (updated.rows[0]) {
await enqueueBoardCli(client, { companyId, kind: 'column.updated', boardId, columnId, actorId: me })
}
return updated.rows
})
if (rows.length === 0) return err(`column ${columnId} not in board ${boardId}`)
return ok(`updated column ${columnId}: ${rows[0].title}`, [{
event: 'kanban.column_updated',
command: `kanban ${op}`,
boardId,
columnId,
actorId: me,
companyId,
title: rows[0].title,
position: rows[0].position,
visibleToUser: true,
}])
}
if (op === 'delete-column' || op === 'rm-column') {
const boardId = parsed.positional[1]
const columnId = parsed.positional[2]
if (!boardId || !columnId) return err(`usage: kanban ${op} <board_id> <column_id>`)
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`,
[boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const r = await withOutboxTransaction(async (client) => {
const deleted = await client.query(
`DELETE FROM board_columns WHERE id = $1 AND board_id = $2`,
[columnId, boardId],
)
if ((deleted.rowCount ?? 0) > 0) {
await enqueueBoardCli(client, { companyId, kind: 'column.deleted', boardId, columnId, actorId: me })
}
return deleted
})
if ((r.rowCount ?? 0) === 0) return err(`column ${columnId} not in board ${boardId}`)
return ok(`deleted column ${columnId}`, [{
event: 'kanban.column_deleted',
command: `kanban ${op}`,
boardId,
columnId,
actorId: me,
companyId,
visibleToUser: true,
}])
}
if (op === 'delete' || op === 'rm') {
const boardId = parsed.positional[1]
if (!boardId) return err('usage: kanban delete <board_id>')
const r = await withOutboxTransaction(async (client) => {
const deleted = await client.query(
`DELETE FROM boards WHERE id = $1 AND company_id = $2`,
[boardId, companyId],
)
if ((deleted.rowCount ?? 0) > 0) {
await enqueueBoardCli(client, { companyId, kind: 'board.deleted', boardId, actorId: me })
}
return deleted
})
if ((r.rowCount ?? 0) === 0) return err(`board ${boardId} not found`)
return ok(`deleted board ${boardId}`, [{
event: 'kanban.board_deleted',
command: 'kanban delete',
boardId,
actorId: me,
companyId,
visibleToUser: true,
}])
}
if (op === 'mentions') {
// Who @-mentioned me on a kanban (cards + comments) since I last
// checked? Reads the read-cursor in board_mention_reads, returns
// the unread set, and (unless --peek) advances the cursor to NOW
// so the next call only shows what's truly new.
const peek = Boolean(parsed.flags.peek)
const { rows: cur } = await pool.query<{ last_read_at: string }>(
`SELECT last_read_at FROM board_mention_reads WHERE user_id = $1 LIMIT 1`,
[me],
)
const since = cur[0]?.last_read_at ?? '1970-01-01T00:00:00Z'
const cardsR = await pool.query<{
id: string; board_id: string; column_id: string; title: string
updated_at: string; created_by: string
board_title: string
}>(
`SELECT c.id, c.board_id, c.column_id, c.title, c.updated_at, c.created_by,
b.title AS board_title
FROM board_cards c
JOIN boards b ON b.id = c.board_id
WHERE b.company_id = $1
AND c.updated_at > $2
AND c.mentions @> to_jsonb($3::text)
ORDER BY c.updated_at DESC
LIMIT 50`,
[companyId, since, me],
)
const commentsR = await pool.query<{
id: string; card_id: string; body: string; author_id: string
created_at: string; board_id: string; card_title: string; board_title: string
}>(
`SELECT cm.id, cm.card_id, cm.body, cm.author_id, cm.created_at,
c.board_id, c.title AS card_title, b.title AS board_title
FROM board_card_comments cm
JOIN board_cards c ON c.id = cm.card_id
JOIN boards b ON b.id = c.board_id
WHERE b.company_id = $1
AND cm.created_at > $2
AND cm.mentions @> to_jsonb($3::text)
ORDER BY cm.created_at DESC
LIMIT 50`,
[companyId, since, me],
)
if (!peek) {
await pool.query(
`INSERT INTO board_mention_reads (user_id, last_read_at)
VALUES ($1, NOW())
ON CONFLICT (user_id) DO UPDATE SET last_read_at = NOW()`,
[me],
)
}
if (parsed.flags.json) {
return ok(JSON.stringify({
since, cards: cardsR.rows, comments: commentsR.rows,
}, null, 2))
}
if (cardsR.rows.length === 0 && commentsR.rows.length === 0) {
return ok(`(no new kanban @-mentions for ${me} since ${since})`)
}
const lines: string[] = [
`${cardsR.rows.length + commentsR.rows.length} new kanban @-mention(s) for ${me}:`,
]
if (cardsR.rows.length > 0) {
lines.push('', '--- cards ---')
for (const c of cardsR.rows) {
lines.push(` ${c.id} [${c.board_title} / ${c.column_id}] ${c.title} · by ${c.created_by} at ${c.updated_at}`)
}
}
if (commentsR.rows.length > 0) {
lines.push('', '--- comments ---')
for (const cm of commentsR.rows) {
lines.push(` ${cm.id} on card ${cm.card_id} [${cm.board_title}] · by ${cm.author_id} at ${cm.created_at}`)
lines.push(` "${cm.body.replace(/\n/g, ' ').slice(0, 200)}"`)
}
}
if (!peek) lines.push('', `(read cursor advanced — next call shows only newer mentions; use --peek to keep it)`)
return ok(lines.join('\n'))
}
return err(`usage: kanban <ls|show|create|rename|columns|add-column|edit-column|delete-column|delete|mentions> [...]`)
}
/** `cumora claim "<unit of work>"` / `cumora unclaim "..."` — the GENERIC, atomic,
* exclusive claim (the #1 primitive for
* non-divergent collaboration). Before doing any non-trivial unit a peer could
* also pick up — running an activity/game, producing a shared deliverable, taking
* a phase — CLAIM it. Exactly one agent wins (Redis HSETNX is the atomic gate);
* everyone else is told who holds it and to move on. Content-agnostic; coordinate
* by giving the SAME unit the SAME name. `--in <convo>` scopes it to a conversation
* (so the same name in different rooms doesn't collide); otherwise it's company-wide. */
async function cmdClaim(parsed: ParsedArgs, mode: 'claim' | 'unclaim'): Promise<CliResult> {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
const key = (parsed.positional[0] ?? '').trim()
if (!key) return err(`usage: ${mode} "<what you're claiming>" [--in <conversation_id>]${mode === 'claim' ? ' [--ttl <seconds>]' : ''}`)
const _convo = typeof parsed.flags['in'] === 'string' ? parsed.flags['in'] : null
// The generic string-lock is GONE. A generic conversation/activity claim is
// exactly what let agents reserve a counting slot ("claim count-8") and then
// sleep-wait for it — both slow and wrong. The only claim that should exist
// is a task-claim on a real unit of work. So claiming a
// turn / game slot / activity no longer grants a lock: just post the real next
// item; the server HOLDs your reply and shows you the newer messages if a peer
// moved the room. For a shared DELIVERABLE a peer could duplicate (one doc, one
// plan), use a board CARD (`cumora card claim`). unclaim is a harmless no-op.
if (mode === 'unclaim') {
return ok(`ok — nothing to release. Cumora no longer uses generic claims; just post, the server settles races.`)
}
return err(
`Claiming a turn / game slot / activity is not a thing anymore. ` +
`Do NOT reserve a position and wait for it. Read the latest posts and send the REAL next item (\`cumora reply\`); ` +
`if a peer moved the room while you composed, the reply comes back HELD with the newer messages — re-read and resend. ` +
`That IS the coordination. The only claim that exists is for a genuine shared DELIVERABLE on the board: \`cumora card claim <cardId>\`.`,
)
}
async function cmdCard(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'ls'
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
/** Look up the boardId behind a cardId AND verify it's in our tenant.
* Returns null if the card doesn't exist or is cross-tenant. */
async function resolveCardBoard(cardId: string): Promise<{ boardId: string; columnId: string; title: string } | null> {
const r = await pool.query<{ board_id: string; column_id: string; title: string; company_id: string }>(
`SELECT c.board_id, c.column_id, c.title, b.company_id
FROM board_cards c JOIN boards b ON b.id = c.board_id
WHERE c.id = $1 LIMIT 1`,
[cardId],
)
if (r.rows.length === 0 || r.rows[0].company_id !== companyId) return null
return { boardId: r.rows[0].board_id, columnId: r.rows[0].column_id, title: r.rows[0].title }
}
if (op === 'ls' || op === 'list') {
const boardId = parsed.positional[1]
if (!boardId) return err('usage: card ls <board_id>')
const dueBefore = parsed.flags['due-before']
if (dueBefore !== undefined && !isBoardDueOn(dueBefore)) {
return err('--due-before must be a valid YYYY-MM-DD date (exclusive)')
}
const overdueAsOf = parsed.flags['overdue-as-of']
if (overdueAsOf !== undefined && !isBoardDueOn(overdueAsOf)) {
return err('--overdue-as-of must be a valid YYYY-MM-DD date')
}
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`, [boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const { rows } = await pool.query<{
id: string; column_id: string; title: string; assignee_id: string | null
mentions: string[]; due_on: string | null; column_kind: string | null
due_status: 'overdue' | 'status_unknown' | null
}>(
`SELECT c.id, c.column_id, c.title, c.assignee_id, c.mentions,
c.due_on::text AS due_on, col.kind AS column_kind,
CASE WHEN $3::date IS NULL THEN NULL
WHEN col.kind IS NULL THEN 'status_unknown'
ELSE 'overdue' END AS due_status
FROM board_cards c JOIN board_columns col ON col.id = c.column_id
WHERE c.board_id = $1
AND ($2::date IS NULL OR c.due_on < $2::date)
AND ($3::date IS NULL OR (c.due_on < $3::date AND (col.kind IN ('todo', 'doing') OR col.kind IS NULL)))
ORDER BY c.column_id, c.position ASC`,
[boardId, dueBefore ?? null, overdueAsOf ?? null],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok('(no cards)')
return ok(rows.map((c) => {
const who = c.assignee_id ? `@${c.assignee_id}` : '(unassigned)'
const due = c.due_on
? ` (due ${c.due_on}${c.due_status === 'status_unknown' ? '; column status unknown' : c.due_status === 'overdue' ? '; overdue' : ''})`
: ''
return ` ${c.id.padEnd(20)} [${c.column_id.slice(0, 16).padEnd(16)}${c.column_kind ? `:${c.column_kind}` : ''}] ${who.padEnd(16)} ${c.title}${due}`
}).join('\n'))
}
if (op === 'show') {
const cardId = parsed.positional[1]
if (!cardId) return err('usage: card show <card_id>')
const r = await pool.query<{
id: string; board_id: string; column_id: string; title: string
description: string | null; assignee_id: string | null; mentions: string[]; due_on: string | null
created_by: string; created_at: string; updated_at: string; company_id: string
}>(
`SELECT c.id, c.board_id, c.column_id, c.title, c.description,
c.assignee_id, c.due_on::text AS due_on, c.mentions, c.created_by, c.created_at, c.updated_at,
b.company_id
FROM board_cards c JOIN boards b ON b.id = c.board_id
WHERE c.id = $1 LIMIT 1`,
[cardId],
)
if (r.rows.length === 0 || r.rows[0].company_id !== companyId) return err(`card ${cardId} not found`)
const c = r.rows[0]
const comments = await pool.query<{
id: string; author_id: string; body: string; created_at: string
}>(
`SELECT id, author_id, body, created_at
FROM board_card_comments WHERE card_id = $1 ORDER BY created_at ASC`,
[cardId],
)
if (parsed.flags.json) return ok(JSON.stringify({ card: c, comments: comments.rows }, null, 2))
const lines = [
`# ${c.title} (${c.id})`,
` board: ${c.board_id}`,
` column: ${c.column_id}`,
` assignee: ${c.assignee_id ?? '(unassigned)'}`,
` due: ${c.due_on ?? '(none)'}`,
` created: ${c.created_at} by ${c.created_by}`,
]
if (Array.isArray(c.mentions) && c.mentions.length > 0) {
lines.push(` mentions: ${c.mentions.map((m) => '@' + m).join(' ')}`)
}
if (c.description) lines.push('', c.description)
if (comments.rows.length > 0) {
lines.push('', `--- ${comments.rows.length} comment(s) ---`)
for (const cm of comments.rows) {
lines.push(` ${cm.created_at} ${cm.author_id}: ${cm.body}`)
}
}
return ok(lines.join('\n'))
}
if (op === 'add' || op === 'create') {
const boardId = parsed.positional[1]
const title = parsed.positional.slice(2).join(' ').trim()
|| (typeof parsed.flags.title === 'string' ? parsed.flags.title : '')
if (!boardId || !title) {
return err('usage: card add <board_id> "<title>" --column <col_id> [--description "..."] [--assign <id>] [--due YYYY-MM-DD]')
}
const columnId = String(parsed.flags.column ?? parsed.flags.col ?? '').trim()
if (!columnId) return err('--column <col_id> required (run `cumora kanban columns <board_id>` to list)')
const b = await pool.query<{ company_id: string }>(
`SELECT company_id FROM boards WHERE id = $1 LIMIT 1`, [boardId],
)
if (b.rows.length === 0 || b.rows[0].company_id !== companyId) return err(`board ${boardId} not found`)
const colCheck = await pool.query(
`SELECT 1 FROM board_columns WHERE id = $1 AND board_id = $2 LIMIT 1`,
[columnId, boardId],
)
if (colCheck.rows.length === 0) return err(`column ${columnId} not in board ${boardId}`)
const description = typeof parsed.flags.description === 'string'
? unescapeChat(parsed.flags.description).slice(0, 8000) : null
const assignee = typeof parsed.flags.assign === 'string'
? String(parsed.flags.assign).trim() : null
const dueOn = parsed.flags.due === undefined ? null : parsed.flags.due
if (dueOn !== null && !isBoardDueOn(dueOn)) return err('--due must be a valid YYYY-MM-DD date')
const { rows: posRows } = await pool.query<{ max: number | null }>(
`SELECT MAX(position) AS max FROM board_cards WHERE column_id = $1`, [columnId],
)
const position = (Number(posRows[0]?.max ?? 0)) + 1000
const mentions = await cliParseMentions(companyId, `${title}\n${description ?? ''}`)
const id = `card-${randomUUID().slice(0, 12)}`
await withOutboxTransaction(async (client) => {
await client.query(
`INSERT INTO board_cards
(id, board_id, column_id, title, description, position, assignee_id, due_on, mentions, created_by)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8::date, $9::jsonb, $10)`,
[id, boardId, columnId, title.slice(0, 200), description, position, assignee, dueOn, JSON.stringify(mentions), me],
)
await client.query(`UPDATE boards SET updated_at = NOW() WHERE id = $1`, [boardId])
await enqueueBoardCli(client, {
companyId, kind: 'card.created', boardId, cardId: id, columnId, mentions, actorId: me,
})
})
void wakeKanbanAgents({
companyId, mentions, actorId: me,
card: {
boardId, cardId: id, columnId, title,
what: 'You were mentioned on a new board card',
},
})
if (assignee && assignee !== me) {
void wakeKanbanAgents({
companyId, mentions: [assignee], actorId: me,
card: {
boardId, cardId: id, columnId, title,
what: 'A board card was assigned to you',
},
})
}
return ok(`added card ${id}: ${title}${mentions.length > 0 ? ` · mentions: ${mentions.map((m) => '@' + m).join(' ')}` : ''}`, [{
event: 'kanban.card_created',
command: 'card add',
boardId,
cardId: id,
columnId,
actorId: me,
companyId,
assigneeId: assignee,
mentions,
title,
visibleToUser: true,
}])
}
if (op === 'due') {
const cardId = parsed.positional[1]
const value = parsed.positional[2]
if (!cardId || !value) return err('usage: card due <card_id> <YYYY-MM-DD|clear>')
const dueOn = value === 'clear' ? null : value
if (dueOn !== null && !isBoardDueOn(dueOn)) return err('due date must be a valid YYYY-MM-DD date or clear')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
await withOutboxTransaction(async (client) => {
await client.query(
`UPDATE board_cards SET due_on = $1::date, updated_at = NOW() WHERE id = $2`,
[dueOn, cardId],
)
await client.query(`UPDATE boards SET updated_at = NOW() WHERE id = $1`, [home.boardId])
await enqueueBoardCli(client, {
companyId, kind: 'card.updated', boardId: home.boardId, cardId, actorId: me,
})
})
return ok(dueOn ? `card ${cardId} due ${dueOn}` : `cleared due date on card ${cardId}`, [{
event: 'kanban.card_updated',
command: 'card due',
boardId: home.boardId,
cardId,
actorId: me,
companyId,
dueOn,
visibleToUser: true,
}])
}
if (op === 'move') {
const cardId = parsed.positional[1]
const toCol = String(parsed.flags.to ?? parsed.flags.column ?? parsed.flags.col ?? '').trim()
if (!cardId || !toCol) return err('usage: card move <card_id> --to <column_id>')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
const colCheck = await pool.query(
`SELECT 1 FROM board_columns WHERE id = $1 AND board_id = $2 LIMIT 1`,
[toCol, home.boardId],
)
if (colCheck.rows.length === 0) return err(`column ${toCol} not in board ${home.boardId}`)
const { rows: posRows } = await pool.query<{ max: number | null }>(
`SELECT MAX(position) AS max FROM board_cards WHERE column_id = $1`, [toCol],
)
const position = (Number(posRows[0]?.max ?? 0)) + 1000
await withOutboxTransaction(async (client) => {
await client.query(
`UPDATE board_cards SET column_id = $1, position = $2, updated_at = NOW() WHERE id = $3`,
[toCol, position, cardId],
)
await client.query(`UPDATE boards SET updated_at = NOW() WHERE id = $1`, [home.boardId])
await enqueueBoardCli(client, {
companyId, kind: 'card.moved', boardId: home.boardId, cardId, columnId: toCol, actorId: me,
})
})
return ok(`moved card ${cardId} → ${toCol}`, [{
event: 'kanban.card_moved',
command: 'card move',
boardId: home.boardId,
cardId,
fromColumnId: home.columnId,
columnId: toCol,
actorId: me,
companyId,
visibleToUser: true,
}])
}
if (op === 'assign') {
const cardId = parsed.positional[1]
const who = parsed.positional[2] // pass "null" or omit to unassign
if (!cardId) return err('usage: card assign <card_id> <participant_id|null>')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
const assignee = (!who || who.toLowerCase() === 'null' || who === '-') ? null : who.trim()
await withOutboxTransaction(async (client) => {
await client.query(
`UPDATE board_cards SET assignee_id = $1, updated_at = NOW() WHERE id = $2`,
[assignee, cardId],
)
await enqueueBoardCli(client, {
companyId, kind: 'card.updated', boardId: home.boardId, cardId, actorId: me,
})
})
if (assignee && assignee !== me) {
void wakeKanbanAgents({
companyId, mentions: [assignee], actorId: me,
card: {
boardId: home.boardId, cardId, columnId: home.columnId, title: home.title,
what: 'A board card was assigned to you',
},
})
}
return ok(assignee ? `assigned card ${cardId} → @${assignee}` : `unassigned card ${cardId}`, [{
event: 'kanban.card_assigned',
command: 'card assign',
boardId: home.boardId,
cardId,
actorId: me,
companyId,
assigneeId: assignee,
visibleToUser: true,
}])
}
if (op === 'claim') {
// ATOMIC EXCLUSIVE CLAIM (the single most
// important primitive for non-divergent collaboration). Win ONLY if the card
// is unclaimed, already yours, or its claim has gone STALE (the claimant likely
// died / went idle ≥20min without touching it). The WHERE guard is the gate and
// rowCount is the SINGLE SOURCE OF TRUTH, so two agents racing the same card can
// NEVER both win — exactly one claims it; everyone else is told to move on.
const cardId = parsed.positional[1]
if (!cardId) return err('usage: card claim <card_id>')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
const claim = await withOutboxTransaction(async (client) => {
const claimed = await client.query<{ id: string }>(
`UPDATE board_cards SET assignee_id = $1, updated_at = NOW()
WHERE id = $2
AND (assignee_id IS NULL OR assignee_id = $1
OR updated_at < NOW() - INTERVAL '20 minutes')
RETURNING id`,
[me, cardId],
)
if ((claimed.rowCount ?? 0) === 0) return { claimed: false, advanceTo: null as string | null }
const cols = await client.query<{ id: string; position: number; kind: string | null }>(
`SELECT id, position, kind FROM board_columns WHERE board_id = $1`, [home.boardId],
)
const advanceTo = claimTargetColumn({ columns: cols.rows, currentColumnId: home.columnId })
if (advanceTo) {
await client.query(
`UPDATE board_cards SET column_id = $1, updated_at = NOW() WHERE id = $2`,
[advanceTo, cardId],
)
}
await enqueueBoardCli(client, {
companyId,
kind: advanceTo ? 'card.moved' : 'card.updated',
boardId: home.boardId,
cardId,
actorId: me,
})
return { claimed: true, advanceTo }
})
if (!claim.claimed) {
const cur = await pool.query<{ assignee_id: string | null }>(
`SELECT assignee_id FROM board_cards WHERE id = $1 LIMIT 1`, [cardId],
)
const holder = cur.rows[0]?.assignee_id
return err(`claim failed: card ${cardId} is already being worked by @${holder ?? '?'} — move on to another task`)
}
// Claiming IS the moment work starts, so reflect it on the board instead of
// relying on the agent to remember a second command — that gap is why a
// board could read Todo 2 / Doing 1 / Done 0 while the work was finished and
// delivered in chat (#69). Only ever forward, and only on a board whose
// columns declare what they mean; see claimTargetColumn.
const advanceTo = claim.advanceTo
return ok(`claimed card ${cardId} — it's yours${advanceTo ? ' and moved to Doing' : ''}. Do the work, post progress with \`card comment\`, move it with \`card move\`, and release with \`card assign ${cardId} null\` (or move to a done column) when finished.`, [{
event: 'kanban.card_claimed',
command: 'card claim',
boardId: home.boardId,
cardId,
actorId: me,
companyId,
assigneeId: me,
visibleToUser: true,
}])
}
if (op === 'rename' || op === 'edit') {
const cardId = parsed.positional[1]
if (!cardId) return err('usage: card rename <card_id> --title "..." [--description "..."]')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
const cur = await pool.query<{ title: string; description: string | null }>(
`SELECT title, description FROM board_cards WHERE id = $1 LIMIT 1`, [cardId],
)
let nextTitle = cur.rows[0].title
let nextDesc = cur.rows[0].description
const sets: string[] = []
const params: unknown[] = []
if (typeof parsed.flags.title === 'string') {
nextTitle = unescapeChat(parsed.flags.title).slice(0, 200)
params.push(nextTitle); sets.push(`title = $${params.length}`)
}
if (typeof parsed.flags.description === 'string') {
nextDesc = unescapeChat(parsed.flags.description).slice(0, 8000) || null
params.push(nextDesc); sets.push(`description = $${params.length}`)
}
if (sets.length === 0) return err('nothing to update — pass --title or --description')
const mentions = await cliParseMentions(companyId, `${nextTitle}\n${nextDesc ?? ''}`)
params.push(JSON.stringify(mentions)); sets.push(`mentions = $${params.length}::jsonb`)
params.push(cardId)
await withOutboxTransaction(async (client) => {
await client.query(
`UPDATE board_cards SET ${sets.join(', ')}, updated_at = NOW() WHERE id = $${params.length}`,
params,
)
await enqueueBoardCli(client, {
companyId, kind: 'card.updated', boardId: home.boardId, cardId, mentions, actorId: me,
})
})
void wakeKanbanAgents({
companyId, mentions, actorId: me,
card: {
boardId: home.boardId, cardId, columnId: home.columnId, title: nextTitle,
what: 'You were mentioned on a board card',
},
})
return ok(`updated card ${cardId}${mentions.length > 0 ? ` · mentions: ${mentions.map((m) => '@' + m).join(' ')}` : ''}`, [{
event: 'kanban.card_updated',
command: op === 'rename' ? 'card rename' : 'card edit',
boardId: home.boardId,
cardId,
actorId: me,
companyId,
mentions,
title: nextTitle,
visibleToUser: true,
}])
}
if (op === 'comment') {
const cardId = parsed.positional[1]
const body = parsed.positional.slice(2).join(' ').trim()
|| (typeof parsed.flags.body === 'string' ? unescapeChat(parsed.flags.body) : '')
if (!cardId || !body) return err('usage: card comment <card_id> "<body>"')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
const mentions = await cliParseMentions(companyId, body)
const id = `cmt-${randomUUID().slice(0, 12)}`
await withOutboxTransaction(async (client) => {
await client.query(
`INSERT INTO board_card_comments (id, card_id, author_id, body, mentions)
VALUES ($1, $2, $3, $4, $5::jsonb)`,
[id, cardId, me, body.slice(0, 8000), JSON.stringify(mentions)],
)
await client.query(`UPDATE board_cards SET updated_at = NOW() WHERE id = $1`, [cardId])
await client.query(`UPDATE boards SET updated_at = NOW() WHERE id = $1`, [home.boardId])
await enqueueBoardCli(client, {
companyId, kind: 'comment.created', boardId: home.boardId, cardId, commentId: id, mentions, actorId: me,
})
})
void wakeKanbanAgents({
companyId, mentions, actorId: me,
card: {
boardId: home.boardId, cardId, columnId: home.columnId, title: home.title,
what: 'You were mentioned in a board card comment',
},
})
return ok(`commented on ${cardId}${mentions.length > 0 ? ` · mentions: ${mentions.map((m) => '@' + m).join(' ')}` : ''}`, [{
event: 'kanban.comment_created',
command: 'card comment',
boardId: home.boardId,
cardId,
commentId: id,
actorId: me,
companyId,
mentions,
visibleToUser: true,
}])
}
if (op === 'delete-comment' || op === 'rm-comment') {
const cardId = parsed.positional[1]
const commentId = parsed.positional[2]
if (!cardId || !commentId) return err(`usage: card ${op} <card_id> <comment_id>`)
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
const r = await withOutboxTransaction(async (client) => {
const deleted = await client.query(
`DELETE FROM board_card_comments
WHERE id = $1 AND card_id = $2 AND author_id = $3`,
[commentId, cardId, me],
)
if ((deleted.rowCount ?? 0) > 0) {
await enqueueBoardCli(client, {
companyId, kind: 'comment.deleted', boardId: home.boardId, cardId, commentId, actorId: me,
})
}
return deleted
})
if ((r.rowCount ?? 0) === 0) return err(`comment ${commentId} not found or not authored by ${me}`)
return ok(`deleted comment ${commentId}`, [{
event: 'kanban.comment_deleted',
command: `card ${op}`,
boardId: home.boardId,
cardId,
commentId,
actorId: me,
companyId,
visibleToUser: true,
}])
}
if (op === 'delete' || op === 'rm') {
const cardId = parsed.positional[1]
if (!cardId) return err('usage: card delete <card_id>')
const home = await resolveCardBoard(cardId)
if (!home) return err(`card ${cardId} not found`)
await withOutboxTransaction(async (client) => {
await client.query(`DELETE FROM board_cards WHERE id = $1`, [cardId])
await enqueueBoardCli(client, {
companyId, kind: 'card.deleted', boardId: home.boardId, cardId, actorId: me,
})
})
return ok(`deleted card ${cardId}`, [{
event: 'kanban.card_deleted',
command: 'card delete',
boardId: home.boardId,
cardId,
actorId: me,
companyId,
visibleToUser: true,
}])
}
return err(`usage: card <ls|show|add|move|assign|rename|comment|delete-comment|delete> [...]`)
}
/* ============== action subcommands → executeTool() ============== */
/**
* Map (subcommand, parsed args) to the tool's expected argument shape.
* Returns the JSON args for executeTool, or an error string.
*/
function buildToolArgs(toolName: string, parsed: ParsedArgs): { argsJson: string } | { error: string } {
const pos = parsed.positional
const f = parsed.flags
switch (toolName) {
case 'react': {
const messageId = pos[0]
const emoji = pos[1]
if (!messageId || !emoji) return { error: 'usage: react <message_id> <emoji>' }
return { argsJson: JSON.stringify({ message_id: messageId, emoji }) }
}
case 'dm_with': {
const partnerId = pos[0]
const topic = pos[1] ?? (f.topic ? String(f.topic) : '')
const opening = pos[2] ?? (f.say ? String(f.say) : (f.message ? String(f.message) : ''))
if (!partnerId) return { error: 'usage: dm <partner_id> <topic> <opening> OR dm <partner_id> --topic "..." --say "..."' }
if (!topic || !opening) return { error: 'dm requires both topic and opening message (positional or --topic/--say)' }
return { argsJson: JSON.stringify({ partner_id: partnerId, topic, opening_message: opening }) }
}
case 'pull_group': {
const title = pos[0]
if (!title) return { error: 'usage: pull-group <title> --members a,b,c --reason "..." --say "..."' }
const membersFlag = f.members ? String(f.members) : ''
const members = membersFlag.split(',').map((s) => s.trim()).filter(Boolean)
if (members.length === 0) return { error: 'pull-group requires --members a,b,c' }
const reason = f.reason ? String(f.reason) : ''
const opening = f.say ? String(f.say) : (f.message ? String(f.message) : '')
if (!reason || !opening) return { error: 'pull-group requires --reason "..." and --say "..."' }
return { argsJson: JSON.stringify({ title, members, reason, opening_message: opening }) }
}
case 'palette': {
const brief = pos.join(' ').trim() || (f.brief ? String(f.brief) : '')
if (!brief) return { error: 'usage: palette <brief>' }
return { argsJson: JSON.stringify({ brief }) }
}
default:
return { error: `unknown tool: ${toolName}` }
}
}
/* ============== Collaborative documents (CRDT) ==============
*
* Agents drive the same Y.Doc rooms the humans see. Edits are applied
* through the in-process room manager so the WS fan-out + persistence
* happens automatically — the human's editor sees the agent's cursor
* + insertion live, as if a remote teammate just typed it.
*/
async function enqueueDocChanged(
db: PoolClient,
companyId: string,
documentId: string,
kind: 'document.created' | 'document.updated' | 'document.deleted',
actorId: string,
): Promise<void> {
await enqueueBroadcast(db, CH_DOCS, {
type: 'doc.changed',
kind,
companyId,
documentId,
actorId,
})
}
async function cmdDoc(parsed: ParsedArgs): Promise<CliResult> {
const op = parsed.positional[0] ?? 'ls'
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
const finalizers: Array<() => Promise<void>> = []
let locked: CliResult | null
try {
locked = await withActiveParticipantLock({
participantId: me,
companyId,
kind: 'agent',
run: async (client) => cmdDocAsActiveAgent(
parsed,
op,
me,
companyId,
client,
(kind, documentId) => enqueueDocChanged(client, companyId, documentId, kind, me),
(finalizer) => finalizers.push(finalizer),
),
})
} finally {
for (const finalize of finalizers) {
await finalize().catch((error) => {
console.warn('[doc] post-transaction cleanup failed', error)
})
}
}
if (!locked) return err(`agent ${me} is no longer active in ${companyId}`)
return locked
}
async function cmdDocAsActiveAgent(
parsed: ParsedArgs,
op: string,
me: string,
companyId: string,
dbClient: PoolClient,
onChanged: (
kind: 'document.created' | 'document.updated' | 'document.deleted',
documentId: string,
) => Promise<void>,
onFinally: (finalizer: () => Promise<void>) => void,
): Promise<CliResult> {
if (op === 'ls' || op === 'list') {
const { rows } = await dbClient.query<{
id: string; title: string; created_by: string; updated_at: Date
}>(
`SELECT id, title, created_by, updated_at FROM documents
WHERE company_id = $1 ORDER BY updated_at DESC LIMIT 200`,
[companyId],
)
if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
if (rows.length === 0) return ok('(no documents in this workspace)')
return ok([
`${rows.length} document(s):`,
'',
...rows.map((d) => ` ${d.id.padEnd(24)} ${d.title}`),
].join('\n'))
}
if (op === 'create' || op === 'new') {
const title = parsed.positional.slice(1).join(' ').trim()
|| (typeof parsed.flags.title === 'string' ? parsed.flags.title : '')
|| 'Untitled'
// Tenant-scoped claim by title so two agents don't independently
// create overlapping docs ("Q3 plan v1", "Q3 plan v2", "Q3 plan
// draft"). The title is the dedup key — close-enough titles will
// still collide thanks to subject normalization.
const blocked = await tryClaimTenantWork(companyId, me, 'doc-create', title)
if (blocked) return blocked
onFinally(() => releaseTenantWork(companyId, me, 'doc-create', title))
{
// The claim above only guards work IN FLIGHT — it's released the
// moment the first creator finishes, so it cannot stop a SEQUENTIAL
// duplicate (2026-06-12: nova created+released 《第七天的猫》 at
// :17, saga's claim sailed through clean at :22 → two docs). Check
// the authoritative table for a same-title doc another agent just
// created: if one exists, the work is DONE — point at it instead of
// duplicating. This runs inside the claim window, so against a
// CONCURRENT creator we either lose the claim (handled above) or
// see their committed row here.
const { normalizeWorkSubject } = await import('./runtime/inproc-client.js')
const normTitle = normalizeWorkSubject(title)
const docHoldScope = `doc-create:${normTitle}`
const forceArmed = Boolean(parsed.flags.force) && (await consumeHold(me, docHoldScope)).armed
if (!forceArmed) {
const { rows: recentDups } = await dbClient.query<{
id: string; title: string; created_by: string; created_at: Date
}>(
`SELECT id, title, created_by, created_at FROM documents
WHERE company_id = $1 AND created_by <> $2
AND created_at > NOW() - INTERVAL '15 minutes'
ORDER BY created_at DESC LIMIT 50`,
[companyId, me],
)
const dup = recentDups.find((d) => normalizeWorkSubject(d.title) === normTitle)
if (dup) {
await recordHold(me, docHoldScope)
const ageSec = Math.max(1, Math.round((Date.now() - dup.created_at.getTime()) / 1000))
return err(
`HELD — document NOT created. ${dup.created_by} already created "${dup.title}" (${dup.id}) ${ageSec}s ago — ` +
`this work is DONE; a second copy is duplicate clutter. ` +
`Build on theirs instead: \`cumora doc read ${dup.id}\` / \`cumora doc append ${dup.id} "..."\`. ` +
`If you GENUINELY need a separate doc with this same title, rerun with --force ` +
`(--force only works after you've been shown this hold — passing it preemptively does nothing).`,
2,
)
}
}
const id = `doc_${randomUUID().replace(/-/g, '').slice(0, 16)}`
await dbClient.query(
`INSERT INTO documents (id, company_id, title, created_by) VALUES ($1, $2, $3, $4)`,
[id, companyId, title.slice(0, 200), me],
)
// If --body was supplied, seed the doc as one or more paragraphs.
// Newlines split, so a multi-line body lands as proper block
// structure (not a single 1500-char paragraph) in the rich editor.
const body = typeof parsed.flags.body === 'string' ? unescapeChat(parsed.flags.body) : ''
if (body) {
const { applyAgentEdit } = await import('../documents/rooms.js')
await applyAgentEdit(id, companyId, me, [{ kind: 'append', text: body }], dbClient)
}
await onChanged('document.created', id)
return ok(`created document ${id}: ${title}`, [{
event: 'document.created',
command: 'doc create',
documentId: id,
actorId: me,
companyId,
title,
bodyLength: body.length,
visibleToUser: true,
}])
}
}
if (op === 'read' || op === 'show') {
const docId = parsed.positional[1]
if (!docId) return err('usage: doc read <document_id>')
const { rows } = await dbClient.query<{ company_id: string; title: string }>(
`SELECT company_id, title FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const { readDocumentText } = await import('../documents/rooms.js')
const body = await readDocumentText(docId, companyId, dbClient)
if (parsed.flags.json) return ok(JSON.stringify({ id: docId, title: rows[0].title, body }, null, 2))
return ok([
`# ${rows[0].title} (${docId})`,
'',
body || '(empty)',
].join('\n'))
}
if (op === 'append') {
const docId = parsed.positional[1]
const text = parsed.positional.slice(2).join(' ').trim()
|| (typeof parsed.flags.text === 'string' ? unescapeChat(parsed.flags.text) : '')
if (!docId || !text) return err('usage: doc append <document_id> "<text>"')
const { rows } = await dbClient.query<{ company_id: string }>(
`SELECT company_id FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const { applyAgentEdit } = await import('../documents/rooms.js')
await applyAgentEdit(docId, companyId, me, [{ kind: 'append', text }], dbClient)
await onChanged('document.updated', docId)
return ok(`appended ${text.length} chars to ${docId}`, [{
event: 'document.updated',
command: 'doc append',
documentId: docId,
actorId: me,
companyId,
editKind: 'append',
bodyLength: text.length,
visibleToUser: true,
}])
}
if (op === 'prepend') {
const docId = parsed.positional[1]
const text = parsed.positional.slice(2).join(' ').trim()
|| (typeof parsed.flags.text === 'string' ? unescapeChat(parsed.flags.text) : '')
if (!docId || !text) return err('usage: doc prepend <document_id> "<text>"')
const { rows } = await dbClient.query<{ company_id: string }>(
`SELECT company_id FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const { applyAgentEdit } = await import('../documents/rooms.js')
await applyAgentEdit(docId, companyId, me, [{ kind: 'insertParagraph', at: 'start', text }], dbClient)
await onChanged('document.updated', docId)
return ok(`prepended ${text.length} chars to ${docId}`, [{
event: 'document.updated',
command: 'doc prepend',
documentId: docId,
actorId: me,
companyId,
editKind: 'prepend',
bodyLength: text.length,
visibleToUser: true,
}])
}
if (op === 'image') {
// Direct image-block insert. The markdown route (`doc append ""`)
// is the more idiomatic affordance but it goes through a line-based regex
// that struggles when the URL wraps mid-emit (long presigned attachment
// links do this routinely). This subcommand bypasses parsing — agents
// pass src + optional alt and get a guaranteed image node.
//
// Placement is layered: absolute (`--at end|start`, default end) gives
// a coarse "drop it somewhere" insert, while anchored placements
// (`--replace`, `--after`, `--before`) take a snippet of existing
// text and place the image relative to the block containing it. The
// killer use case for `--replace` is swapping a previously-emitted
// but inert `` markdown paragraph for a real image node:
// the agent passes the exact markdown text as the anchor and the
// broken text gets replaced by the image inline.
const docId = parsed.positional[1]
const src = parsed.positional[2]
|| (typeof parsed.flags.src === 'string' ? unescapeChat(parsed.flags.src) : '')
const alt = typeof parsed.flags.alt === 'string' ? unescapeChat(parsed.flags.alt).trim() : ''
const replaceAnchor = typeof parsed.flags.replace === 'string' ? unescapeChat(parsed.flags.replace) : ''
const afterAnchor = typeof parsed.flags.after === 'string' ? unescapeChat(parsed.flags.after) : ''
const beforeAnchor = typeof parsed.flags.before === 'string' ? unescapeChat(parsed.flags.before) : ''
const atRaw = typeof parsed.flags.at === 'string' ? parsed.flags.at.trim().toLowerCase() : 'end'
if (!docId || !src) return err('usage: doc image <document_id> <url> [--alt "..."] [--at end|start | --replace "..." | --after "..." | --before "..."]')
if (!/^https?:\/\//i.test(src)) return err('image url must be http(s)://')
// Pick the placement mode. Anchored flags win over `--at`. If more
// than one anchor is supplied we surface an error rather than pick
// arbitrarily — the agent should declare intent unambiguously.
const anchors = [
['replace', replaceAnchor],
['after', afterAnchor],
['before', beforeAnchor],
].filter(([, v]) => v) as Array<['replace' | 'after' | 'before', string]>
if (anchors.length > 1) {
return err(`pass only one of --replace / --after / --before (got ${anchors.length})`)
}
let placement: { mode: 'start' | 'end' } | { mode: 'replace' | 'after' | 'before'; anchorText: string }
if (anchors.length === 1) {
placement = { mode: anchors[0][0], anchorText: anchors[0][1] }
} else {
placement = { mode: atRaw === 'start' ? 'start' : 'end' }
}
const { rows } = await dbClient.query<{ company_id: string }>(
`SELECT company_id FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const { applyAgentEdit, isAnchoredImagePlacement } = await import('../documents/rooms.js')
const result = await applyAgentEdit(docId, companyId, me, [{ kind: 'image', src, alt: alt || null, placement }], dbClient)
// Anchor miss is a HARD error now — falling back to end-of-doc on a
// missed snippet is how the doc collected duplicate inert images
// in the first place. Return without firing the change event so the
// agent's bash exit code reflects the failure and it knows to retry
// with a different snippet (or stop trying).
if (isAnchoredImagePlacement(placement) && result.imagePlaced === 'anchor-missed') {
const snippet = placement.anchorText.slice(0, 60)
return err(`anchor not found in ${docId}: "${snippet}". Re-read the doc and pick a snippet that uniquely identifies the target block — no image was inserted.`)
}
await onChanged('document.updated', docId)
let where: string
if (isAnchoredImagePlacement(placement)) {
where = `${placement.mode} block containing "${placement.anchorText.slice(0, 60)}"`
} else {
where = placement.mode === 'start' ? 'at start' : 'at end'
}
return ok(`inserted image into ${docId} ${where}`, [{
event: 'document.updated',
command: 'doc image',
documentId: docId,
actorId: me,
companyId,
editKind: 'image',
visibleToUser: true,
}])
}
if (op === 'image-delete') {
// Counterpart to `doc image`. Used when a doc has duplicate or
// unwanted image blocks (e.g. earlier attempts that fell back to
// end-of-doc when --replace missed, before the fallback was
// removed). Match by exact src, src substring, or alt text.
const docId = parsed.positional[1]
const srcExact = typeof parsed.flags.src === 'string' ? unescapeChat(parsed.flags.src) : ''
const srcContains = typeof parsed.flags['src-contains'] === 'string' ? unescapeChat(parsed.flags['src-contains']) : ''
const altMatch = typeof parsed.flags.alt === 'string' ? unescapeChat(parsed.flags.alt) : ''
const provided = [srcExact, srcContains, altMatch].filter(Boolean)
if (!docId || provided.length === 0) {
return err('usage: doc image-delete <document_id> [--src <exact_url> | --src-contains <substr> | --alt <text>]')
}
if (provided.length > 1) {
return err('pass only one of --src / --src-contains / --alt')
}
const { rows } = await dbClient.query<{ company_id: string }>(
`SELECT company_id FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const match: import('../documents/rooms.js').AgentImageDeleteMatch =
srcExact ? { by: 'src', src: srcExact }
: srcContains ? { by: 'src-contains', substring: srcContains }
: { by: 'alt', alt: altMatch }
const { applyAgentEdit } = await import('../documents/rooms.js')
const result = await applyAgentEdit(docId, companyId, me, [{ kind: 'imageDelete', match }], dbClient)
if (result.imagesDeleted === 0) {
return err(`no images in ${docId} matched the criterion`)
}
if (result.deletedStorageKeys && result.deletedStorageKeys.length > 0) {
const { enqueueWorkspaceCleanup, nudgeWorkspaceCleanupWorker } = await import('../workspace-cleanup.js')
await enqueueWorkspaceCleanup(dbClient, { companyId, agentIds: [], storageKeys: result.deletedStorageKeys })
onFinally(() => {
nudgeWorkspaceCleanupWorker()
return Promise.resolve()
})
}
await onChanged('document.updated', docId)
return ok(`deleted ${result.imagesDeleted} image${result.imagesDeleted === 1 ? '' : 's'} from ${docId}`, [{
event: 'document.updated',
command: 'doc image-delete',
documentId: docId,
actorId: me,
companyId,
editKind: 'image-delete',
imagesDeleted: result.imagesDeleted,
visibleToUser: true,
}])
}
if (op === 'replace') {
const docId = parsed.positional[1]
const find = typeof parsed.flags.find === 'string' ? unescapeChat(parsed.flags.find) : ''
const replace = typeof parsed.flags.replace === 'string' ? unescapeChat(parsed.flags.replace) : ''
if (!docId || !find) return err('usage: doc replace <document_id> --find "..." --replace "..."')
const { rows } = await dbClient.query<{ company_id: string }>(
`SELECT company_id FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const { applyAgentEdit } = await import('../documents/rooms.js')
const r = await applyAgentEdit(docId, companyId, me, [{ kind: 'replace', find, replace }], dbClient)
if (r.replaced === 0) return err(`text not found in ${docId}: ${JSON.stringify(find).slice(0, 80)}`)
await onChanged('document.updated', docId)
return ok(`replaced ${r.replaced} occurrence in ${docId}`, [{
event: 'document.updated',
command: 'doc replace',
documentId: docId,
actorId: me,
companyId,
editKind: 'replace',
replaced: r.replaced,
visibleToUser: true,
}])
}
if (op === 'replace-block') {
const docId = parsed.positional[1]
const anchor = typeof parsed.flags.anchor === 'string' ? unescapeChat(parsed.flags.anchor) : ''
const text = parsed.positional.slice(2).join(' ').trim()
|| (typeof parsed.flags.text === 'string' ? unescapeChat(parsed.flags.text) : '')
if (!docId || !anchor || !text) return err('usage: doc replace-block <document_id> --anchor "<snippet in the block>" "<replacement markdown>"')
const { rows } = await dbClient.query<{ company_id: string }>(
`SELECT company_id FROM documents WHERE id = $1 LIMIT 1`, [docId],
)
if (rows.length === 0 || rows[0].company_id !== companyId) return err(`document ${docId} not found`)
const { applyAgentEdit } = await import('../documents/rooms.js')
const r = await applyAgentEdit(docId, companyId, me, [{ kind: 'replaceBlock', anchorText: anchor, text }], dbClient)
if (r.blocksReplaced === 0) return err(`no block containing ${JSON.stringify(anchor).slice(0, 80)} in ${docId}`)
await onChanged('document.updated', docId)
return ok(`replaced 1 block in ${docId}`, [{
event: 'document.updated',
command: 'doc replace-block',
documentId: docId,
actorId: me,
companyId,
editKind: 'replace-block',
visibleToUser: true,
}])
}
if (op === 'rename') {
const docId = parsed.positional[1]
const title = parsed.positional.slice(2).join(' ').trim()
|| (typeof parsed.flags.title === 'string' ? parsed.flags.title : '')
if (!docId || !title) return err('usage: doc rename <document_id> "<title>"')
const r = await dbClient.query(
`UPDATE documents SET title = $1, updated_at = NOW()
WHERE id = $2 AND company_id = $3`,
[title.slice(0, 200), docId, companyId],
)
if (!r.rowCount) return err(`document ${docId} not found`)
await onChanged('document.updated', docId)
return ok(`renamed ${docId} to "${title}"`, [{
event: 'document.updated',
command: 'doc rename',
documentId: docId,
actorId: me,
companyId,
editKind: 'rename',
title,
visibleToUser: true,
}])
}
if (op === 'delete' || op === 'rm') {
const docId = parsed.positional[1]
if (!docId) return err('usage: doc delete <document_id>')
const { rows } = await dbClient.query<{ created_by: string }>(
`SELECT created_by FROM documents WHERE id = $1 AND company_id = $2 LIMIT 1`,
[docId, companyId],
)
if (rows.length === 0) return err(`document ${docId} not found`)
if (rows[0].created_by !== me) return err(`only the creator can delete document ${docId}`)
const { collectDocumentStorageKeys, evictDocumentRoom } = await import('../documents/rooms.js')
const storageKeys = await collectDocumentStorageKeys(docId, dbClient)
await dbClient.query(`DELETE FROM documents WHERE id = $1`, [docId])
if (storageKeys.length > 0) {
const { enqueueWorkspaceCleanup, nudgeWorkspaceCleanupWorker } = await import('../workspace-cleanup.js')
await enqueueWorkspaceCleanup(dbClient, { companyId, agentIds: [], storageKeys })
onFinally(() => {
nudgeWorkspaceCleanupWorker()
return Promise.resolve()
})
}
evictDocumentRoom(docId)
await onChanged('document.deleted', docId)
return ok(`deleted document ${docId}`, [{
event: 'document.deleted',
command: 'doc delete',
documentId: docId,
actorId: me,
companyId,
visibleToUser: true,
}])
}
return err(`unknown doc op: ${op}\nusage: doc {ls|create|read|append|prepend|image|image-delete|replace|rename|delete} ...`)
}
async function runTool(toolName: string, parsed: ParsedArgs): Promise<CliResult> {
const built = buildToolArgs(toolName, parsed)
if ('error' in built) return err(built.error)
const me = resolveAs(parsed)
const { executeTool } = await import('./tools.js')
const r = await executeTool({ agentId: me, name: toolName, argsJson: built.argsJson })
const sideEffects = cliToolSideEffects(toolName, r.output, me)
if (parsed.flags.json) {
return r.ok
? ok(JSON.stringify(r.output, null, 2), sideEffects)
: { ok: false, text: JSON.stringify({ error: r.error, display: r.display }, null, 2), exitCode: 1 }
}
const detail = r.display.detail || (r.output ? JSON.stringify(r.output, null, 2) : '(no output)')
if (!r.ok) return err(`${r.display.name} failed: ${r.error ?? r.display.status}\n${detail}`)
const head = `${r.display.name} → ${r.display.status}`
return ok(`${head}\n\n${detail}`, sideEffects)
}
function cliToolSideEffects(toolName: string, output: unknown, agentId: string): CliSideEffect[] | undefined {
if (!output || typeof output !== 'object' || Array.isArray(output)) return undefined
const o = output as Record<string, unknown>
switch (toolName) {
case 'react':
return [{
event: 'reaction.updated',
command: 'react',
visibleToUser: true,
actorId: agentId,
messageId: String(o.messageId ?? ''),
emoji: String(o.emoji ?? ''),
action: String(o.action ?? ''),
}]
case 'dm_with':
return [{
event: 'conversation.created',
command: 'dm',
actorId: agentId,
conversationId: String(o.conversationId ?? ''),
partnerId: String(o.partnerId ?? ''),
topic: String(o.topic ?? ''),
visibleToUser: true,
}]
case 'pull_group':
return [{
event: 'conversation.created',
command: 'pull-group',
actorId: agentId,
conversationId: String(o.conversationId ?? ''),
members: Array.isArray(o.members) ? o.members.map((m) => String(m)) : [],
visibleToUser: true,
}]
default:
return undefined
}
}
/* ============== entry point ============== */
export async function runCli(argv: string[]): Promise<CliResult> {
// Pull a leading global `--as <id>` (or `--as=<id>`) off. Runtime `/cli`
// prepends identity this way, and direct dev/test callers often do too.
// Re-attach it to the subcommand args so per-command parsers still see
// `parsed.flags.as`.
let asFlag: string | null = null
while (argv.length > 0 && (argv[0] === '--as' || argv[0].startsWith('--as='))) {
if (argv[0] === '--as') {
asFlag = argv[1] ?? null
argv = argv.slice(2)
} else {
asFlag = argv[0].slice('--as='.length)
argv = argv.slice(1)
}
}
if (argv.length === 0) return cmdHelp()
const sub = argv[0]
const rest = argv.slice(1)
const parsed = parseArgs(rest)
if (asFlag !== null && parsed.flags.as === undefined) {
parsed.flags.as = asFlag
}
try {
switch (sub) {
case 'help':
case '--help':
case '-h':
return await cmdHelp()
case 'whoami': return await cmdWhoami(parsed)
case 'participants': return await cmdParticipants(parsed)
case 'conversations': return await cmdConversations(parsed)
case 'groups': return await cmdConversations(parsed, 'group')
case 'directs': return await cmdConversations(parsed, 'direct')
case 'members': return await cmdMembers(parsed)
case 'messages': return await cmdMessages(parsed)
case 'thread': return await cmdThread(parsed)
case 'convening': return await cmdConvening(parsed)
case 'search': return await cmdSearch(parsed)
case 'tools-log': return await cmdToolsLog(parsed)
case 'participants-status': return await cmdStatus(parsed)
case 'memory': return await cmdMemory(parsed)
case 'climate': return await cmdClimate(parsed)
case 'log': return await cmdLog(parsed)
case 'workspace':
case 'ws': return await cmdWorkspace(parsed)
case 'tasks': return await cmdTasks(parsed)
case 'calendar': return await cmdCalendar(parsed)
// ====== mailbox: how an agent reads + writes the world ======
case 'inbox': return await cmdInbox(parsed)
case 'glance': return await cmdGlance(parsed)
case 'ack': return await cmdAck(parsed)
case 'mute': return await cmdMute(parsed)
case 'follow': return await cmdFollow(parsed)
case 'ship': return await cmdShip(parsed)
case 'reply': return await cmdReply(parsed)
case 'leave': return await cmdLeave(parsed)
case 'kick': return await cmdKick(parsed)
case 'invite': return await cmdInvite(parsed)
case 'topic': return await cmdTopicRead(parsed)
case 'topic-set': return await cmdTopicSet(parsed)
case 'rename': return await cmdRename(parsed)
case 'avatar': return await cmdAvatar(parsed)
case 'skills': return await cmdSkills(parsed)
case 'email': return await cmdEmail(parsed)
case 'poll': return await cmdPoll(parsed)
// Top-level alias for `email contacts` — promotes contact lookup
// to a discoverable verb. Same logic, same output. Use this when a
// user names a person you don't recognize: BEFORE assuming or
// silently skipping, run `cumora contacts <query>`.
case 'contacts': {
const me = resolveAs(parsed)
const companyId = await agentCompany(me)
if (!companyId) return err(`unknown agent ${me} (no company)`)
// cmdEmailContacts reads positional[1] as the query (it expects
// to be invoked as `email contacts <query>`, where positional[0]
// is 'contacts'). For top-level `cumora contacts <query>` the
// outer dispatch has already consumed 'contacts', so positional
// is just [<query>]. Prepend a placeholder so the offset lines up.
const shimmed = { ...parsed, positional: ['contacts', ...parsed.positional] }
return await cmdEmailContacts(shimmed, me, companyId, Boolean(parsed.flags.json))
}
// ====== other actions (each wraps a tool implementation) ======
// `kanban` is the canonical verb for the shared boards feature.
// `card` for the cards inside them. No CJK aliases — easier to
// type in any keyboard mode.
case 'claim': return await cmdClaim(parsed, 'claim')
case 'unclaim': return await cmdClaim(parsed, 'unclaim')
case 'kanban': return await cmdBoard(parsed)
case 'card': return await cmdCard(parsed)
case 'doc': return await cmdDoc(parsed)
case 'react': return await runTool('react', parsed)
case 'dm': return await runTool('dm_with', parsed)
case 'pull-group': return await runTool('pull_group', parsed)
case 'palette': return await runTool('palette', parsed)
case 'image': return await cmdImage(parsed)
default:
return err(`unknown subcommand: ${sub}\nrun "cumora help" for usage`)
}
} catch (e) {
// 1, not 2. Exit 2 means HELD — "your write was deliberately declined,
// re-decide and retry" — and five call sites use it that way. An
// unexpected exception is not that, and turn.ts now reads the code to tell
// a stand-down apart from a crash.
return err(`error: ${e instanceof Error ? e.message : String(e)}`, 1)
}
}
// tokenize is re-exported from ./cli-parse — see the import block at the
// top of this file.