Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* Bot group chat wire contract shared by Desktop main, preload and renderer.
* Product rules: docs/product-rules/bot-group-chat.md.
*/
import type { BotGroupQuoteInput, BotGroupQuoteView } from './botGroupQuote';
import type { BotGroupTaskCardView } from './botGroupTask';
export * from './botGroupQuote';
export * from './botGroupTask';
export const BOT_GROUP_MIN_MEMBERS = 2;
export const BOT_GROUP_MAX_MEMBERS = 6;
export const BOT_GROUP_NAME_MAX_CHARS = 40;
export const BOT_GROUP_MESSAGE_MAX_CHARS = 8_000;
export const BOT_GROUP_PAGE_SIZE = 100;
/** 分工 (docs/product-rules/bot-group-chat.md §7). */
export const BOT_GROUP_PLAN_MAX_STEPS = 6;
export const BOT_GROUP_PLAN_TASK_MAX_CHARS = 80;
/** Files listed under one step's hand-off message. */
export const BOT_GROUP_STEP_FILES_MAX = 20;
/** Attachments on one user message (bot-group-chat.md §3.1); each one goes to every member. */
export const BOT_GROUP_ATTACHMENTS_MAX = 20;
/** A Bot whose final reply is exactly this sentinel (after trim) stays silent. */
export const BOT_GROUP_NO_REPLY_SENTINEL = 'NO_REPLY';
export type BotGroupReplyMode = 'all' | 'mentioned';
/** `auto`: a broadcast round's first circle thinks in parallel; `sequential`: always one at a time. */
export type BotGroupSpeakingMode = 'auto' | 'sequential';
export type BotGroupAuthorKind = 'user' | 'bot' | 'system';
/**
* `round-end` marks a naturally finished round; `notice` carries `noticeCode`;
* `plan` is the organizer's 安排卡 (see `planId`); `plan-end` closes a finished plan.
*/
export type BotGroupMessageKind = 'message' | 'round-end' | 'notice' | 'plan' | 'plan-end';
export type BotGroupNoticeCode =
| 'member-joined'
| 'member-failed'
| 'member-timeout'
| 'member-unavailable'
/** The organizer could not produce a plan for an explicit 安排分工. */
| 'plan-failed'
| 'plan-stopped'
| 'workdir-unavailable';
export type BotGroupMemberStatus = 'active' | 'paused' | 'error' | 'archived' | 'deleting' | 'missing';
/** Public failure categories only; never transport raw Agent errors into a group. */
export const BOT_GROUP_RUNTIME_FAILURE_CODES = [
'IMAGE_INPUT_UNSUPPORTED', 'MODEL_UNAVAILABLE', 'AUTH_REQUIRED', 'RATE_LIMITED', 'UPSTREAM_OVERLOADED',
'QUOTA_EXCEEDED', 'NETWORK_ERROR', 'RUNTIME_TIMEOUT', 'RUNTIME_ERROR',
'REMOTE_DEVICE_LIMIT', 'REMOTE_TOTAL_LIMIT',
] as const;
export type BotGroupRuntimeFailureCode = typeof BOT_GROUP_RUNTIME_FAILURE_CODES[number];
export function isBotGroupRuntimeFailureCode(value: unknown): value is BotGroupRuntimeFailureCode {
return typeof value === 'string' && BOT_GROUP_RUNTIME_FAILURE_CODES.some(code => code === value);
}
/** Current execution state, separate from persisted/paginated chat messages. */
export interface BotGroupExecutionFailureView {
executionId: string;
epoch: number;
sourceMessageId: string;
botId: string;
botName: string;
code: BotGroupRuntimeFailureCode;
planId: string | null;
updatedAt?: number;
}
/** Decode only public fields from Chat Server; legacy /executions rows also work. */
export function readBotGroupExecutionFailure(value: unknown, roomId: string): BotGroupExecutionFailureView | null {
if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
const row = value as Record<string, unknown>;
if ((row.status !== undefined && row.status !== 'failed')
|| (row.conversation_id !== undefined && row.conversation_id !== roomId)
|| typeof row.id !== 'string' || !row.id || typeof row.source_message_id !== 'string' || !row.source_message_id
|| typeof row.bot_id !== 'string' || !row.bot_id
|| typeof row.epoch !== 'number' || !Number.isSafeInteger(row.epoch) || row.epoch < 0) return null;
const updatedAt = typeof row.updated_at === 'string' ? Date.parse(row.updated_at) : NaN;
return { executionId: row.id, epoch: row.epoch, sourceMessageId: row.source_message_id,
botId: row.bot_id, botName: '', code: isBotGroupRuntimeFailureCode(row.failure_code) ? row.failure_code : 'RUNTIME_ERROR',
planId: typeof row.plan_id === 'string' ? row.plan_id : null,
...(Number.isFinite(updatedAt) ? { updatedAt } : {}) };
}
/** Persisted local notice marker; migration carries the category as card metadata. */
export const BOT_GROUP_RUNTIME_FAILURE_PREFIX = 'cindy-runtime-error:';
export function botGroupRuntimeFailureDetail(code: BotGroupRuntimeFailureCode): string {
return `${BOT_GROUP_RUNTIME_FAILURE_PREFIX}${code}`;
}
export function readBotGroupRuntimeFailureDetail(value: unknown): BotGroupRuntimeFailureCode | undefined {
if (typeof value !== 'string' || !value.startsWith(BOT_GROUP_RUNTIME_FAILURE_PREFIX)) return undefined;
const code = value.slice(BOT_GROUP_RUNTIME_FAILURE_PREFIX.length);
return isBotGroupRuntimeFailureCode(code) ? code : undefined;
}
/** Only a server-stamped import of a system notice can supply historical failure metadata. */
export function readImportedBotGroupRuntimeFailureCode(message: {
origin?: unknown; deleted?: unknown;
content: readonly { type?: unknown; namespace?: unknown; schemaRevision?: unknown; data?: unknown; text?: unknown; fallback?: unknown }[];
}): BotGroupRuntimeFailureCode | undefined {
if (message.origin !== 'import' || message.deleted === true) return undefined;
const card = message.content.find(block => block.type === 'card' && block.namespace === 'cindy.local-history' && block.schemaRevision === 1);
if (!card?.data || typeof card.data !== 'object' || Array.isArray(card.data)) return undefined;
const data = card.data as Record<string, unknown>;
if (data.kind !== 'notice' || data.authorKind !== 'system') return undefined;
if (isBotGroupRuntimeFailureCode(data.runtimeFailureCode)) return data.runtimeFailureCode;
// Compatibility with notices imported before the metadata projection existed.
for (const block of message.content) {
const code = readBotGroupRuntimeFailureDetail(block.type === 'text' ? block.text : block === card ? block.fallback : undefined);
if (code) return code;
}
return undefined;
}
export interface BotGroupMention {
all: boolean;
botIds: string[];
}
export interface BotGroupMemberView {
/** Present for Chat Server members; botId remains the composer mention key. */
actorId?: string;
role?: 'owner' | 'admin' | 'member' | 'guest';
displayName?: string;
nickname?: string | null;
ownerActorId?: string;
ownerName?: string;
isOwned?: boolean;
/** The computer running this owned companion (its Chat Server actor home); live task cards read there. */
homeDeviceId?: string | null;
avatarUrl?: string | null;
/** Explicit group-only override; null follows the account avatar. */
groupAvatar?: string | null;
defaultAvatarUrl?: string | null;
guestAccess?: 'none' | 'chat' | 'tools';
accessRevision?: number;
actorKind?: 'human' | 'bot' | 'integration';
isSelf?: boolean;
botId: string;
name: string;
avatar: string;
avatarColor: string;
status: BotGroupMemberStatus;
}
export interface BotGroupMessageView {
/** Server-stamped identity at send time; rebinding never rewrites history. */
maskAttribution?: { self: ChatMaskIdentity; companion: ChatMaskIdentity; sourceMessageId: string };
/** Server tombstone; it cannot anchor a runtime failure notice. */
deleted?: boolean;
isSelf?: boolean;
threadRootId?: string | null;
replyCount?: number;
/** 引用回复: the earlier main-timeline message this one quotes; not a Thread parent. */
quote?: BotGroupQuoteView;
/** An independent task this teammate started from the group (bot-group-chat.md §10). */
task?: BotGroupTaskCardView;
reactions?: Array<{ emoji: string; count: number; me: boolean }>;
id: string;
sequence: number;
/** Stable decimal server position; presentation indices can change when history is loaded. */
serverSequence?: string;
kind: BotGroupMessageKind;
authorKind: BotGroupAuthorKind;
authorBotId: string | null;
/** Name snapshot taken when the message was written. */
authorName: string;
content: string;
mentions: BotGroupMention;
noticeCode: BotGroupNoticeCode | null;
/** Localized cause and remedy for a failed execution; raw diagnostics stay on the executor. */
runtimeFailureCode?: BotGroupRuntimeFailureCode;
/** The plan this message belongs to: the 安排卡, a step hand-off or the plan's end. */
planId: string | null;
/** Step hand-off files, relative to the plan's work directory (POSIX separators). */
files: string[];
/** What the user attached to this message (images, files, videos). */
attachments: BotGroupAttachment[];
createdAt: number;
/** Thread roots only: the newest replies, shown in the main chat without opening the thread. */
threadPreview?: BotGroupThreadPreview;
/**
* Thread roots only: replies from others since this reader last opened the Thread, by the
* server's read state. Omitted when the server keeps no read state (older servers).
*/
threadUnread?: BotGroupThreadUnread;
/** A main-chat message that re-posts an existing thread reply by reference. */
threadShare?: BotGroupThreadShareView;
}
/** Unread replies of one Thread; `mentioned` when one of them names this reader. */
export interface BotGroupThreadUnread {
count: number;
mentioned: boolean;
/** Sequence of the newest unread reply; tells a new reply apart from the same ones counted again. */
latest?: number;
}
/**
* One Thread of the group for the in-chat 话题 list (bot-group-chat.md §10「话题未读与提示」).
* Root text and author come from the server's copy; empty while that copy is still being read.
*/
export interface BotGroupThreadSummary {
rootId: string;
rootAuthorName: string;
rootAuthorBotId: string | null;
rootText: string;
replyCount: number;
unread: BotGroupThreadUnread;
/** The reader chose to follow it; absent when the server keeps no read state. */
following?: boolean;
lastReply: { authorName: string; text: string; createdAt: number } | null;
}
/** Spoken summaries and distinct responders have independent limits. */
export const BOT_GROUP_THREAD_PREVIEW_REPLIES = 2;
export const BOT_GROUP_THREAD_PREVIEW_RESPONDERS = 3;
/**
* Main-chat share of a thread reply. The card stores only the two IDs; clients resolve the
* author, text and files from the server's copy of the reply, so a card cannot put words
* in someone else's name. `fallback` keeps older clients readable.
*/
export const BOT_GROUP_THREAD_SHARE_NAMESPACE = 'cindy.thread-share';
const THREAD_SHARE_REVISION = 1;
const THREAD_SHARE_FALLBACK_TEXT_MAX = 280;
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
/** One share per person and reply: retries and repeats replay the same server operation. */
export function botGroupThreadShareOperationId(messageId: string): string {
return `thread-share:${messageId}`;
}
export function buildBotGroupThreadShareCard(input: { messageId: string; threadRootId: string; authorName: string; text: string }) {
const text = input.text.replace(/\s+/g, ' ').trim();
const clipped = text.length > THREAD_SHARE_FALLBACK_TEXT_MAX ? `${text.slice(0, THREAD_SHARE_FALLBACK_TEXT_MAX)}…` : text;
const author = input.authorName.trim() || '…';
return {
type: 'card' as const, namespace: BOT_GROUP_THREAD_SHARE_NAMESPACE, schemaRevision: THREAD_SHARE_REVISION,
fallback: clipped ? `↪ ${author}: ${clipped}` : `↪ ${author}`,
data: { messageId: input.messageId, threadRootId: input.threadRootId },
};
}
export function readBotGroupThreadShareCard(message: {
deleted?: unknown; threadRootId?: unknown;
content: readonly { type?: unknown; namespace?: unknown; schemaRevision?: unknown; data?: unknown }[];
}): { messageId: string; threadRootId: string } | null {
// A share lives in the main chat; a card copied into a thread is just content.
if (message.deleted === true || (message.threadRootId !== null && message.threadRootId !== undefined)) return null;
// Classify the whole message, not a block: hiding mixed content would disagree with Agent history.
if (message.content.length !== 1) return null;
const card = message.content[0];
if (card?.type !== 'card' || card.namespace !== BOT_GROUP_THREAD_SHARE_NAMESPACE
|| card.schemaRevision !== THREAD_SHARE_REVISION) return null;
if (!card?.data || typeof card.data !== 'object' || Array.isArray(card.data)) return null;
const { messageId, threadRootId } = card.data as Record<string, unknown>;
if (typeof messageId !== 'string' || typeof threadRootId !== 'string' || !UUID.test(messageId) || !UUID.test(threadRootId)
|| messageId === threadRootId) return null;
return { messageId, threadRootId };
}
export interface BotGroupThreadPreviewReply {
id: string;
authorKind: BotGroupAuthorKind;
authorBotId: string | null;
authorName: string;
isSelf?: boolean;
/** Plain text; empty when the reply only carries attachments. */
text: string;
/** Names only: a preview never downloads the reply's files. */
attachments: Array<{ name: string; category: BotGroupAttachmentCategory }>;
createdAt: number;
}
export interface BotGroupThreadPreview {
/** Chronological, newest last. */
replies: BotGroupThreadPreviewReply[];
/** Distinct server authors from the fetched window, oldest last-reply first. Older hosts omit this. */
responders?: Array<Pick<BotGroupThreadPreviewReply, 'id' | 'authorKind' | 'authorBotId' | 'authorName'>>;
}
/**
* The reply a main-chat share points at. Everything except the IDs is read from the
* server's current copy of that reply, never from what the sharer's card claims.
*/
export interface BotGroupThreadShareView {
messageId: string;
/** The thread the reply stays in; sharing never moves it. */
threadRootId: string;
/**
* `loading`: the reply is still being read. `unavailable`: deleted, outside this reader's
* history, or not a reply in `threadRootId`. Neither shows the card's fallback text.
*/
status: 'available' | 'loading' | 'unavailable';
authorKind: BotGroupAuthorKind;
authorBotId: string | null;
authorName: string;
/** The sharer wrote the reply themselves (sent to the thread and the main chat). */
sharedByAuthor: boolean;
content: string;
attachments: BotGroupAttachment[];
createdAt: number | null;
edited: boolean;
/** Cache version this view was checked at; compare with `BotGroupDetail.threadShareVersion`. */
version?: number;
}
export type BotGroupAttachmentCategory = 'image' | 'pdf' | 'text' | 'office' | 'file';
/**
* An attachment as a composer hands it over, in the same serialized shape as a task
* message attachment. On this computer `path` is the local file (a pasted image has a
* placeholder) and an image carries its `cindy-media://` `url`; a phone sends its upload
* reference in `path` (and `url` for an image).
*/
export interface BotGroupAttachmentInput {
id: string;
name: string;
path: string;
ext?: string;
size?: number;
category: BotGroupAttachmentCategory;
mimeType: string;
url?: string;
originalName?: string;
/** The image carries the user's drawn annotations (same meaning as in task messages). */
annotated?: boolean;
}
/** An attachment kept with a group message. */
export interface BotGroupAttachment {
id: string;
name: string;
category: BotGroupAttachmentCategory;
mimeType: string;
size: number;
/** Images: the `cindy-media://` address; controllers read it through remote media. */
url: string | null;
/** The file on this computer; always null in a controller's copy. */
path: string | null;
annotated?: boolean;
/**
* A server attachment whose bytes are not on this computer yet: `loading` until the
* download settles, `unavailable` after it failed (a later read retries). `url` and
* `path` are null and only `id` and `name` are known. Absent once the file is here.
*/
state?: 'loading' | 'unavailable';
}
/**
* `proposed` waits for 开始; `running` has a step in progress; `waiting` stopped after a
* step (done → 继续, failed → 重试); `done`, `stopped`, `dismissed` and `superseded` are final.
*/
export type BotGroupPlanStatus =
| 'proposed'
| 'running'
| 'waiting'
| 'done'
| 'stopped'
| 'dismissed'
| 'superseded';
export type BotGroupPlanStepStatus = 'pending' | 'running' | 'done' | 'failed';
export interface BotGroupPlanStepView {
position: number;
botId: string;
/** Name snapshot; the Bot may have been renamed or removed since. */
botName: string;
task: string;
status: BotGroupPlanStepStatus;
/** The step's latest hand-off message (a redo replaces it); absent where the host does not report it. */
resultMessageId?: string | null;
}
export interface BotGroupPlanView {
id: string;
status: BotGroupPlanStatus;
organizerBotId: string;
organizerName: string;
steps: BotGroupPlanStepView[];
/** Step that is running, being redone, or last finished / failed; null before 开始. */
currentStep: number | null;
/** Absolute work directory once started; git plans run in their own worktree. */
workDir: string | null;
branch: string | null;
/** Server groups: `talk` queues teammates answering in turn (the first five go on by themselves); `work` divides work into steps. */
kind?: 'talk' | 'work';
/** Server groups: the viewer may continue or stop it (creator, owner or admin). */
canManage?: boolean;
/** Server groups: what the viewer sends without naming anyone goes to the step under way (creator, or a human owner/admin). */
canAdd?: boolean;
/**
* Server 分工: this computer starts the next step once one is done, instead of waiting for 继续.
* A choice of the computer that made it, not shared chat state; absent where unsupported.
*/
autoContinue?: boolean;
createdAt: number;
updatedAt: number;
}
export interface BotGroupOpenPlanSummary {
id: string;
status: BotGroupPlanStatus;
currentStep: number | null;
stepCount: number;
/** Bot of the current step (running, being redone, or last finished / failed). */
currentBotName: string | null;
currentStepStatus: BotGroupPlanStepStatus | null;
/** Server groups: a queue of teammates answering in turn (`talk`) or a division of work. */
kind?: 'talk' | 'work';
}
export function isBotGroupPlanOpen(status: BotGroupPlanStatus): boolean {
return status === 'proposed' || status === 'running' || status === 'waiting';
}
export interface BotGroupLastMessage {
isSelf?: boolean;
authorKind: BotGroupAuthorKind;
authorName: string;
/** Optional for older hosts; localize system notices in the reader's language. */
noticeCode?: BotGroupNoticeCode | null;
preview: string;
createdAt: number;
/** The latest message re-posts a thread reply; `preview` is then empty, never the card's text. */
threadShare?: boolean;
}
/** `reply`: answering in the chat; `planning`: the organizer is working out a plan; `step`: doing a plan step. */
export type BotGroupSpeakerActivity = 'reply' | 'planning' | 'step';
export interface BotGroupSpeaker {
botId: string;
/** Server execution identity: match the same work on its owning computer, never a bot's main chat. */
executionId?: string;
startedAt?: number;
stopping?: boolean;
executionStatus?: 'queued' | 'running' | 'needs_input' | 'stopping';
/** Hidden group lane or 分工 Session of the speaking Bot, for pending permission/question UI. */
sessionId: string | null;
activity: BotGroupSpeakerActivity;
}
export interface BotGroupRoundView {
status: 'idle' | 'running';
/** Bots currently taking their turn; several while a circle thinks in parallel. */
speakers: BotGroupSpeaker[];
/** True when the latest round ended naturally and may be continued. */
canContinue: boolean;
/** Server groups: someone else's request or teammate is also working, so stopping only yours leaves it running. */
othersActive?: boolean;
}
export interface BotGroupSummary {
/** Public roster state, optional for older hosts. */
teammateActivity?: { phase: string };
/** Explicit direct-message landing; group management remains unavailable. */
conversationKind?: 'direct' | 'group';
serverBacked?: boolean;
/** Authoritative unread window for this account, including followed thread replies. */
serverUnread?: { count: number; mentioned: boolean };
/** Explicit server capabilities; absent on old servers/hosts. */
supportsDissolve?: boolean;
/** Upgraded host forwards leave explicitly; absent on old compatibility hosts. */
supportsGroupLeave?: boolean;
supportsListRemoval?: boolean;
supportsMemberAvatar?: boolean;
dissolvedAt?: string | null;
archived?: boolean;
migrationPending?: boolean;
canInvite?: boolean;
/** Server groups: an owner or admin may also stop everyone's work, not only their own. */
canStopAll?: boolean;
/**
* Server groups whose server gives each request one teammate (the lead when nobody is named)
* and arranges turns itself; no speaking modes (bot-group-chat.md §4).
*/
singleSpeaker?: boolean;
/** A single-speaker group whose computer arranges 「安排分工」 (older computers answered it as a queue). */
supportsDivision?: boolean;
selfActorId?: string;
topic?: string;
description?: string;
revision?: number;
id: string;
name: string;
replyMode: BotGroupReplyMode;
speakingMode: BotGroupSpeakingMode;
members: BotGroupMemberView[];
/** Effective organizer (负责人): the chosen member, else the first available one. */
organizerBotId: string | null;
/** 项目文件夹; null means the group's own folder. */
projectDir: string | null;
/**
* Server groups: 分工 you start here go on to the next step by themselves instead of waiting
* for 继续 (§7.4). Kept on this computer like the project folder; absent where unsupported.
*/
autoContinue?: boolean;
lastMessage: BotGroupLastMessage | null;
/** Latest visible incoming message (Bot or another human), excluding self and runtime activity. Older hosts omit it. */
lastReplyAt?: number;
/**
* ISO `createdAt` of the newest (up to 99) messages from someone else — Bots and other people,
* not this account, notices, round/plan endings or system events — oldest first. Derived from
* the messages the host already read. Older hosts omit it.
*/
incomingMessageTimes?: string[];
speakingBotIds: string[];
/** The organizer while it works out a plan (sidebar 「正在安排」). */
planningBotId: string | null;
/** The group's open plan, if any (sidebar preview). */
openPlan: BotGroupOpenPlanSummary | null;
createdAt: number;
updatedAt: number;
}
export interface BotGroupDetail extends BotGroupSummary {
/** Durable cache generation. A changed value discards pages from a previous history/permission boundary. */
historyRevision?: string;
/** Current authorized versions of already displayed messages, including deletion tombstones. */
messageUpdates?: BotGroupMessageView[];
/** Room-wide; bumped when a reset skipped realtime events or the chat runtime was recreated, so every message's reactors count as changed. */
reactionRevision?: number;
/** Per message id; bumped by realtime reaction changes, so a same-count change of who reacted is noticed. */
reactionRevisions?: Record<string, number>;
/** Oldest first. */
messages: BotGroupMessageView[];
/** Authorized current failures, independent of message pagination. Local/older hosts omit this. */
executionFailures?: BotGroupExecutionFailureView[];
/** Current state of shares the reader listed in `shownShares`, keyed by the share's message ID. */
threadShareUpdates?: Record<string, BotGroupThreadShareView>;
/** Raised by every edit, deletion or reset; an older share view may no longer be true. */
threadShareVersion?: number;
hasMoreBefore: boolean;
round: BotGroupRoundView;
/** Plans referenced by the loaded messages, plus the open plan. */
plans: BotGroupPlanView[];
/**
* Threads with replies in the newest window, unread ones first. Omitted by local groups,
* older hosts and servers without read state.
*/
threads?: BotGroupThreadSummary[];
}
export type BotGroupErrorCode =
| 'INVALID_ATTACHMENT'
| 'ATTACHMENT_UNAVAILABLE'
| 'ATTACHMENT_TOO_LARGE'
| 'MEDIA_UPLOAD_FAILED'
| 'AUTH_REQUIRED'
| 'CHAT_UNAVAILABLE'
| 'IMPORT_PENDING'
| 'REQUEST_TIMEOUT'
| 'PERMISSION_DENIED'
| 'SERVICE_ERROR'
| 'GROUP_ARCHIVED'
| 'GROUP_DISSOLVED'
| 'LIFECYCLE_UNAVAILABLE'
| 'LAST_OWNER'
| 'INVALID_PARAMS'
| 'REVISION_CONFLICT'
| 'NOT_FOUND'
| 'MEMBER_LIMIT'
| 'MEMBER_UNAVAILABLE'
| 'MENTION_UNAVAILABLE'
| 'HOST_NOT_READY'
/** An explicit 安排分工 while a plan is running or waiting. */
| 'PLAN_OPEN'
/** The plan already ended, was replaced, or is in a state that does not allow the action. */
| 'PLAN_CLOSED'
/** The quoted message was deleted, moved out of reach or never belonged to this timeline. */
| 'QUOTE_UNAVAILABLE'
| 'INTERNAL';
export interface BotGroupFailure {
ok: false;
errorCode: BotGroupErrorCode;
message: string;
}
export type BotGroupListResult = { ok: true; groups: BotGroupSummary[] } | BotGroupFailure;
export type BotGroupGetResult = { ok: true; group: BotGroupDetail } | BotGroupFailure;
export type BotGroupCreateResult = { ok: true; groupId: string } | BotGroupFailure;
export type BotGroupMutationResult = { ok: true } | BotGroupFailure;
export type BotGroupSendResult = { ok: true; messageId: string } | BotGroupFailure;
export interface BotGroupCreateInput {
name: string;
botIds: string[];
}
export interface BotGroupUpdateInput {
groupId: string;
/** Optional optimistic precondition for server-backed settings. */
expectedRevision?: number;
name?: string;
replyMode?: BotGroupReplyMode;
speakingMode?: BotGroupSpeakingMode;
/** null resets to the first available member. */
organizerBotId?: string | null;
/** Absolute existing local directory; null uses the group's own folder. */
projectDir?: string | null;
/** Server groups: whether 分工 you start go on by themselves (kept on this computer). */
autoContinue?: boolean;
}
export interface BotGroupSetMembersInput {
groupId: string;
/** Complete ordered member list. */
botIds: string[];
/** Server-backed additive invite; preserves every existing member. */
addOnly?: boolean;
}
export interface BotGroupSendInput {
conversationKind?: 'direct';
groupId: string;
text: string;
mentions: BotGroupMention;
/** Renderer-generated idempotency key; a repeated id returns the original message. */
clientId: string;
/** 「+」→ 安排分工: always ask the organizer for a plan instead of deciding. */
division?: boolean;
/** At most `BOT_GROUP_ATTACHMENTS_MAX`; with attachments the text may be empty. */
attachments?: BotGroupAttachmentInput[];
/** 引用回复 on a server group; the host reads the message itself. A quote alone is not a message. */
quote?: BotGroupQuoteInput;
}
export interface BotGroupPlanActionInput {
groupId: string;
planId: string;
}
export type BotGroupPlanAction = 'start' | 'dismiss' | 'continue' | 'retry';
export interface BotGroupPlanEditInput extends BotGroupPlanActionInput {
position: number;
/** `reassign` needs `botId`; `remove` keeps at least one step. Proposed plans only. */
action: 'reassign' | 'remove';
botId?: string;
}
export interface BotGroupGetOptions {
/** Local display snapshot only; callers separately request current server state. */
cacheOnly?: boolean;
conversationKind?: 'direct';
/** Load messages with a smaller sequence (older page). */
beforeSequence?: number;
limit?: number;
/** Reconcile execution state for real messages already displayed on older pages. */
sourceMessageIds?: string[];
/** Shares already shown from older pages, so edits and deletions reach them without a reload. */
shownShares?: Array<{ id: string; messageId: string; threadRootId: string; sharerId?: string }>;
}
export type BotGroupChange = 'created' | 'updated' | 'deleted' | 'messages' | 'round' | 'plan' | 'list';
export interface BotGroupChangedPayload {
groupId: string;
change: BotGroupChange;
/** Personal state, only emitted after an authoritative account-scoped reply/event. */
listState?: { hidden: boolean; revision: number };
}
export function isBotGroupNoReplyText(text: string): boolean {
const trimmed = text.trim();
return trimmed.length === 0 || trimmed === BOT_GROUP_NO_REPLY_SENTINEL;
}
/** True while streamed text could still turn out to be the silence sentinel. */
export function isBotGroupNoReplyPrefix(text: string): boolean {
const trimmed = text.trim();
return trimmed.length === 0 || BOT_GROUP_NO_REPLY_SENTINEL.startsWith(trimmed);
}
// ---- Controllers (phones) — docs/product-rules/bot-group-chat.md §8 -------------
/**
* Groups reach controllers through the Remote Resource protocol (collection below), not
* dedicated channels. The host keeps every rule; controllers only render and invoke actions.
*/
export const BOT_GROUP_REMOTE_COLLECTION_ID = 'bot-groups';
export const BOT_GROUP_REMOTE_RESOURCE_KIND = 'bot-group';
/** Block primitive whose `data` is `BotGroupRemoteChatData`; only sent to controllers declaring it. */
export const BOT_GROUP_CHAT_PRIMITIVE = 'bot-group-chat';
/** Collection item link to each member (`teammates` resource), in member order. */
export const BOT_GROUP_MEMBER_LINK_REL = 'member';
/**
* Remote actions. `create` is collection-level ({ name, botIds }); the others target a group:
* `send` ({ text, mentions, clientId, division? }), `continue`, `stop`, `update`
* ({ name?, replyMode?, speakingMode?, organizerBotId? } — never a host path),
* `set-members` ({ botIds }), `dissolve` ({ expectedRevision }), `leave`, `hide`, `remove-member` ({ actorId }, capability-gated), `delete`, `plan-start` / `plan-dismiss` / `plan-continue` /
* `plan-retry` ({ planId }) and `plan-edit` ({ planId, position, action, botId? }).
* A refused action fails with the `BotGroupErrorCode` as its message.
*/
export type BotGroupRemoteActionId =
| 'create'
| 'read'
| 'mask'
| 'mask-mentions'
| 'send'
| 'continue'
| 'stop'
| 'update'
| 'set-members'
| 'add-member'
| 'remove-member'
| 'delete'
| 'dissolve'
| 'leave'
| 'hide'
| 'plan-start'
| 'plan-dismiss'
| 'plan-continue'
| 'plan-retry'
| 'plan-edit';
/**
* The group as a controller sees it. Host paths never leave the computer: `projectDir`
* and every plan `workDir` are null, and `projectDirName` names the folder.
*/
export interface BotGroupRemoteChatData extends BotGroupDetail {
projectDirName: string | null;
/** Host forwards a measured main-timeline read to the chat server. Older hosts omit it. */
supportsReadReceipts?: boolean;
supportsPersonalMask?: boolean;
/**
* The computer accepts attachments on `send` (absent on older computers, which would
* drop them). Attachment `path`s are always null here.
*/
supportsAttachments?: boolean;
/** Host supports removing one server actor, including a human. */
supportsMemberRemoval?: boolean;
/** Revision-checked settings and additive `add-member` ({ botId }) on server groups. */
supportsSettingsManagement?: boolean;
}
export const BOT_GROUP_CLIENT_ID_PREFIX = 'bot-group:';
export const BOT_GROUP_CLIENT_ID = {
memberTurn: (groupId: string, turnId: string, botId: string) =>
`${BOT_GROUP_CLIENT_ID_PREFIX}${groupId}:${turnId}:${botId}`,
planStep: (groupId: string, planId: string, position: number, turnId: string) =>
`${BOT_GROUP_CLIENT_ID_PREFIX}${groupId}:plan:${planId}:${position}:${turnId}`,
} as const;
export function isBotGroupClientId(clientId: string | null | undefined): boolean {
return typeof clientId === 'string' && clientId.startsWith(BOT_GROUP_CLIENT_ID_PREFIX);
}
/** The server chooses the grant. Different grants never reuse private model context. */
export interface ChatLaneAccess { mode: 'owner' | 'chat' | 'tools'; revision: number; maskOwnerId?: string }
export function chatGroupLaneRouteKey(groupId: string, access: ChatLaneAccess): string {
return `group:${groupId}:access:${access.mode}:${access.revision}${access.maskOwnerId ? `:mask:${access.maskOwnerId}` : ''}`;
}
export function isChatOnlyGroupLane(routeKey: string | null | undefined): boolean {
return /^group:[^:]+:access:chat:[1-9][0-9]*(?::mask:[^:]+)?(?::plan:[^:]+|:thread:[^:]+|:talk:[^:]+|:personal-digest)?$/.test(routeKey ?? '');
}
/**
* A queue's own lane (bot-group-chat.md §7.0): one hidden Session per queue, grant and teammate,
* so each turn reads only its card. It talks in the group lane's place, never a project folder.
*/
export function chatGroupTalkRouteKey(groupId: string, access: ChatLaneAccess, planId: string): string {
return `${chatGroupLaneRouteKey(groupId, access)}:talk:${planId}`;
}
/**
* A Thread's own lane: one hidden Session per Thread, grant and teammate, so a Thread
* keeps its own short context apart from the main group and other Threads (bot-group-chat.md §3).
*/
export function chatGroupThreadRouteKey(groupId: string, access: ChatLaneAccess, threadRootId: string): string {
return `${chatGroupLaneRouteKey(groupId, access)}:thread:${threadRootId}`;
}
/** Group and Thread root of a Thread lane route key, or null for other routes. */
export function parseBotGroupThreadRouteKey(routeKey: string | null | undefined): { groupId: string; threadRootId: string } | null {
const match = typeof routeKey === 'string' ? /^group:([^:]+):access:(?:owner|tools|chat):[1-9][0-9]*(?::mask:[^:]+)?:thread:([^:]+)$/.exec(routeKey) : null;
return match ? { groupId: match[1]!, threadRootId: match[2]! } : null;
}
/** The group lane a Thread or queue lane belongs to; both work in the same place as their group lane. */
export function groupLaneOfRouteKey(routeKey: string): string {
return routeKey.replace(/:(?:(?:thread|talk):[^:]+|personal-digest)$/, '');
}
export function botGroupLaneRouteKey(groupId: string): string {
return `group:${groupId}`;
}
/** 分工 Session of one Bot for one plan; shares the lane's `role = 'group'`. */
export function botGroupPlanRouteKey(groupId: string, planId: string): string {
return `${botGroupPlanRouteKeyPrefix(groupId)}${planId}`;
}
export function botGroupPlanRouteKeyPrefix(groupId: string): string {
return `group:${groupId}:plan:`;
}
/** Group id of any lane or 分工 Session route key (`group:<groupId>…`), or null for other routes. */
export function parseBotGroupIdFromRouteKey(routeKey: string | null | undefined): string | null {
const match = typeof routeKey === 'string' ? /^group:([^:]+)(?::|$)/.exec(routeKey) : null;
return match ? match[1]! : null;
}
/** Plan id of a 分工 Session route key, or null for lanes and other routes. */
export function parseBotGroupPlanRouteKey(routeKey: string | null | undefined): { groupId: string; planId: string } | null {
const match = typeof routeKey === 'string' ? /^group:([^:]+)(?::access:(?:owner|tools|chat):[1-9][0-9]*)?:plan:([^:]+)$/.exec(routeKey) : null;
return match ? { groupId: match[1]!, planId: match[2]! } : null;
}
/** Named, credential-free Desktop chat capabilities. Older/local-only hosts omit them. */
export type ChatServerResult<T> = ({ ok: true } & T) | { ok: false; errorCode: string };
export interface ChatMaskIdentity { id: string; name: string; avatarUrl: string | null }
export interface ChatMaskSettings {
access?: 'chat' | 'tools';
companionId: string | null; enabled: boolean; trigger: 'scheduled' | 'manual' | 'always';
start: string; end: string; timeZone: string; resumeMinutes: number; collectTodos: boolean; digest: 'daily' | 'manual';
}
export interface ChatMaskState {
homeDeviceId?: string | null;
defaultCompanionId?: string | null;
toolAccessSupported?: boolean;
settings: ChatMaskSettings; revision: number; status: 'unbound' | 'off' | 'offline' | 'paused' | 'waiting' | 'enabled';
manualRunning: boolean; self: ChatMaskIdentity; companions: ChatMaskIdentity[];
digestStatus?: 'idle' | 'queued' | 'running' | 'done' | 'failed' | 'cancelled' | 'empty';
}
export type ChatMaskAction = { type: 'save'; expectedRevision: number; settings: ChatMaskSettings }
| { type: 'participate' | 'resume' | 'stop' | 'digest' };
export interface ChatMaskMention {
messageId: string; sequence: string; threadRootId?: string; authorName: string; text: string;
reply?: { companion: ChatMaskIdentity; text: string };
}
/** One reacting actor. `name` is null when the group has no member record for it. */
export interface ChatReactor { actorId: string; name: string | null; isSelf: boolean; formerMember: boolean }
export interface ChatInvitePreview {
groupId: string; name: string; inviterName: string; expiresAt: string | null; joined: boolean;
/** Omitted by old servers, whose links remain dated and single-use. */
reusable?: boolean;
}
export type ChatGroupAction =
| { type: 'read'; messageId: string; conversationKind?: 'direct' }
| { type: 'update'; name: string; topic: string; description: string; expectedRevision: number; responseMode?: BotGroupReplyMode; speakingMode?: BotGroupSpeakingMode }
| { type: 'nickname'; actorId: string; nickname: string | null }
| { type: 'avatar'; actorId: string; avatar: { type: 'keep' | 'reset' } | { type: 'set'; data: Uint8Array; mimeType: string } }
| { type: 'member'; actorId: string; action: 'invite' | 'leave' | 'remove' | 'ban' | 'unban' | 'role'; role?: 'admin' | 'member' }
| { type: 'transfer'; actorId: string }
| { type: 'botAccess'; actorId: string; access: 'none' | 'chat' | 'tools'; expectedRevision: number }
| { type: 'dissolve'; expectedRevision: number }
| { type: 'hide' }
| { type: 'archive'; archived: boolean; expectedRevision: number };
export interface ChatServerApi {
mask?(input: { groupId: string; action?: ChatMaskAction; operationId?: string }): Promise<ChatServerResult<{ state: ChatMaskState }>>;
mentions?(input: { groupId: string; before?: string; readIds?: string[]; operationId?: string }): Promise<ChatServerResult<{ mentions: ChatMaskMention[]; hasMore: boolean }>>;
manage(input: { groupId: string; action: ChatGroupAction }): Promise<ChatServerResult<{ listState?: { conversationId: string; hidden: boolean; revision: number } }>>;
/** `botId` is the local teammate id behind each Chat Server actor. */
ownedBots(): Promise<ChatServerResult<{ bots: Array<{ actorId: string; botId?: string; name: string }> }>>;
refreshProfile(): Promise<ChatServerResult<Record<never, never>>>;
status(): Promise<{ enabled: boolean; connected: boolean; personalMask?: boolean }>;
/**
* `markRead` (latest page only): the reader is looking at the Thread, so its server read state
* moves to the newest reply read here; `readBefore` is where it stood before this read.
* `following` (latest page only) is whether the reader follows the Thread; absent when the
* server keeps no read state.
*/
thread(input: { groupId: string; rootId: string; before?: number; sourceMessageIds?: string[]; markRead?: boolean }): Promise<ChatServerResult<{
root: BotGroupMessageView; replies: BotGroupMessageView[]; hasMore: boolean;
/** Same room generation as the main timeline; reset before merging older pages. */
historyRevision?: string;
messageUpdates?: BotGroupMessageView[];
/** Same authoritative state as the main timeline; root and replies use one projection. */
executionFailures?: BotGroupExecutionFailureView[];
readBefore?: number;
following?: boolean;
}>>;
/**
* Sets whether the reader follows a Thread (bot-group-chat.md §10「关注开关」) and answers what
* the server saved. Only the reader's own choice ever follows a Thread.
*/
followThread(input: { groupId: string; rootId: string; following: boolean }): Promise<ChatServerResult<{ following: boolean }>>;
reply(input: { groupId: string; rootId: string; text: string; clientId: string; mentions: BotGroupMention }): Promise<ChatServerResult<{ messageId: string }>>;
/**
* Re-post a thread reply to the main chat as the current user. Repeating it for the same
* reply returns the existing share (`alreadyShared`); it never starts a companion round.
*/
shareToMain(input: { groupId: string; messageId: string }): Promise<ChatServerResult<{ messageId: string | null; alreadyShared: boolean }>>;
react(input: { groupId: string; messageId: string; emoji: string; present: boolean }): Promise<ChatServerResult<Record<never, never>>>;
/** Read-only: who added one emoji to a message. Names use the group member projection. */
reactors(input: { groupId: string; messageId: string; emoji: string }): Promise<ChatServerResult<{ reactors: ChatReactor[] }>>;
createInvite(input: { groupId: string; clientId: string }): Promise<ChatServerResult<{ link: string; expiresAt: string | null; reusable?: boolean }>>;
revokeInvite(input: { groupId: string; link: string; clientId: string }): Promise<ChatServerResult<{ revoked: true }>>;
previewInvite(input: { link: string }): Promise<ChatServerResult<ChatInvitePreview>>;
acceptInvite(input: { link: string; clientId: string }): Promise<ChatServerResult<{ groupId: string }>>;
}