Files
Evgeny @ SimpleX Chat 953389322f mcp: a list of every session and its state in the Main group (#8182)
* plan: mcp-activity

* plan: mcp-activity list format

* plan: mcp-activity answers and live step lines

* mcp: a silent line per step of Claude's work, completed at its end

* plan: mcp-activity as implemented

* mcp: finalize step lines within a day and load only the hook's modules

* plan: mcp-activity review decisions as implemented

* plan: mcp-session-list

* plan: mcp-session-list, every session in one message (Q2 B)

* mcp: end live step lines by the wall clock

* mcp: exact spec ranges and measured hook load time

* mcp: a list of every session and its state in the Main group

* plan: mcp-session-list as implemented

* mcp: list of sessions: unknown states count cards, bounded record reads, stop edit before the card wait

* plan: mcp-session-list merged with master

* mcp: ROADMAP marks the items delivered since 0.3.0 with ✅
2026-11-13 23:40:02 +00:00

321 lines
13 KiB
TypeScript

import {ChatEvent, T} from "@simplex-chat/types"
import {api} from "simplex-chat"
import {Command, createGroup, deleteGroup, isLost, joinedText, losesControl, parseCommand, safeName, updateGroupProfile} from "./control"
import {chatErrorOf, log, logError, oneLine} from "./log"
import {resetCommand} from "./owner"
import {isActive} from "./tools"
// spec: spec/architecture.md#main-group-maincommands
const mainCommands: T.ChatBotCommand[] = [
{type: "command", keyword: "sessions", label: "Claude Code sessions"},
{type: "command", keyword: "join", label: "Join the group of a session", params: "<session number>"},
]
// spec: spec/architecture.md#main-group-maincommands
const mainKey = "simplexMcpMain"
// spec: spec/api.md#main-group-profile
const listKey = "simplexMcpList"
// spec: spec/api.md#list-of-sessions
const listAge = 23 * 3_600_000
// spec: spec/architecture.md#main-group-maincommands
const greeting = "I'm Claude. Each Claude Code session has its own group, and you get its invitation here. /sessions lists the sessions; /join N joins the group of session N."
// spec: spec/api.md#main-group
const unknownCommand = "Unknown command."
// spec: spec/architecture.md#main-group-maincommands
const noOwners = "No owners in the Main group."
// spec: spec/architecture.md#main-group-maincommands
const welcome = "Everyone in this group can join the groups of your Claude Code sessions, prompt Claude and approve what it does. Invite only people you trust with that."
// spec: spec/architecture.md#main-group-maincommands
const joinRights = "They can join the group of any Claude Code session here, prompt Claude and approve its actions."
// spec: spec/architecture.md#main-group-maincommands
const shortDescr = "Everyone in this group can join the groups of your Claude Code sessions, prompt Claude and approve what it does."
// spec: spec/architecture.md#main-group-sessiongroups
export interface SessionGroups {
sessionsText(quote?: T.MsgContent): string
join(member: T.GroupMember, session: number): Promise<string>
inviteOwner(member: T.GroupMember): Promise<void>
}
// spec: spec/api.md#main-group-profile
interface SessionList {
item: number
at: number
}
export class MainGroup {
lost = false
private members: T.GroupMember[] = []
private events: Promise<unknown> = Promise.resolve()
private commands: Promise<unknown> = Promise.resolve()
private linkText?: string
private list?: SessionList
private shown?: string
private tooLarge?: string
constructor(
private readonly chat: api.ChatApi,
private group: T.GroupInfo,
private readonly userId: number,
private name: string,
private readonly sessions: SessionGroups,
) {
this.list = listOf(group.customData)
}
get groupId(): number {
return this.group.groupId
}
get displayName(): string {
return this.name
}
get link(): string | undefined {
return this.linkText
}
// spec: spec/architecture.md#main-group-maingroup-owners
owners(): T.GroupMember[] {
return this.lost ? [] : this.humans().filter(({memberRole}) => memberRole === T.GroupMemberRole.Owner)
}
// spec: spec/api.md#main-group-profile
async load(): Promise<void> {
if (isLost(this.group)) return this.lose()
const displayName = this.name
this.group = await updateGroupProfile(this.chat, this.group, profile =>
profile.displayName !== displayName || JSON.stringify(profile.groupPreferences?.commands) !== JSON.stringify(mainCommands)
? {...profile, displayName, groupPreferences: {...profile.groupPreferences, commands: mainCommands}}
: undefined,
)
await this.refreshMembers()
}
// spec: spec/architecture.md#main-group-maingroup-load
async start(): Promise<void> {
if (this.lost || this.owners().length > 0) return
if (this.humans().length > 0) log(noOwners)
this.linkText = await this.chat.apiGetGroupLinkStr(this.groupId).catch(error => {
if (!isMissingLink(error)) throw error
return undefined
})
if (this.linkText === undefined) await this.openLink()
}
rename(name: string): Promise<void> {
this.name = name
return this.serialize(() => this.load())
}
// spec: spec/architecture.md#main-group-maingroup-onmessage
onMessage(ci: T.AChatItem): void {
const {chatItem} = ci
if (this.lost || chatItem.chatDir.type !== "groupRcv" || chatItem.content.type !== "rcvMsgContent") return
const {msgContent} = chatItem.content
const command = parseCommand(msgContent.text)
if (command === undefined) return
const sender = chatItem.chatDir.groupMember
this.commands = this.commands
.then(() => this.command(sender, command, msgContent))
.then(reply => this.chat.apiSendTextReply(ci, reply))
.catch(error => logError("Main group command", error))
}
// spec: spec/architecture.md#main-group-maingroup-onevent
onEvent(event: ChatEvent): Promise<void> {
return this.serialize(() => this.handleEvent(event))
}
// spec: spec/architecture.md#main-group-maingroup-replace
replace(): Promise<string> {
return this.serialize(async () => {
this.lost = true
await deleteGroup(this.chat, this.group)
this.group = await createMainGroup(this.chat, this.userId, this.name)
this.list = undefined
this.lost = false
await this.load()
await this.openLink()
return this.linkText!
})
}
// spec: spec/architecture.md#main-group-maingroup-showlist
showList(text: string): Promise<void> {
return this.serialize(async () => {
if (this.lost || text === this.tooLarge) return
await this.renderList(text).catch(error => {
if (!isTooLarge(error)) throw error
this.tooLarge = text
logError("list of sessions", error)
})
})
}
// spec: spec/architecture.md#main-group-maingroup-showlist
private async renderList(text: string): Promise<void> {
const {list} = this
if (list === undefined) {
if (this.owners().length > 0) await this.postList(text)
return
}
if (list.at <= Date.now() - listAge) return this.replaceList(list, text)
if (text === this.shown) return
try {
await this.chat.apiUpdateChatItem(T.ChatType.Group, this.groupId, list.item, {type: "text", text})
this.shown = text
} catch (error) {
if (!isRefusedEdit(error)) throw error
await this.replaceList(list, text)
}
}
// spec: spec/architecture.md#main-group-maingroup-showlist
private async replaceList(old: SessionList, text: string): Promise<void> {
await this.postList(text)
await this.deleteItem(old.item, "old list of sessions")
}
// spec: spec/architecture.md#main-group-maingroup-showlist
private async postList(text: string): Promise<void> {
const list = {item: await this.post(text, -1), at: Date.now()}
const customData = {...this.group.customData, [mainKey]: true, [listKey]: list}
try {
await this.chat.apiSetGroupCustomData(this.groupId, customData)
} catch (error) {
await this.deleteItem(list.item, "new list of sessions")
throw error
}
this.list = list
this.shown = text
this.group = {...this.group, customData}
}
private async deleteItem(item: number, subject: string): Promise<void> {
await this.chat.apiDeleteChatItems(T.ChatType.Group, this.groupId, [item], T.CIDeleteMode.Broadcast).catch(error => logError(subject, error))
}
// spec: spec/api.md#main-group
private async command(sender: T.GroupMember, {keyword, params}: Command, quote: T.MsgContent): Promise<string> {
if (keyword === "sessions" && params === "") return this.sessions.sessionsText(quote)
if (keyword === "join" && /^\d+$/.test(params)) return this.sessions.join(sender, Number(params))
return unknownCommand
}
// spec: spec/architecture.md#main-group-maingroup-onevent
private async handleEvent(event: ChatEvent): Promise<void> {
if (this.lost) return
if (losesControl(event)) return this.lose()
const before = this.owners()
await this.refreshMembers()
if (event.type === "joinedGroupMember" && this.isHuman(event.member) && this.owners().length === 0) await this.ownerJoined(event.member)
else if (before.length > 0 && this.owners().length === 0) {
log(noOwners)
return this.openLink()
}
const joined = event.type === "joinedGroupMember" || event.type === "connectedToGroupMember" ? this.humans().find(({groupMemberId}) => groupMemberId === event.member.groupMemberId) : undefined
if (joined !== undefined) await this.post(`${safeName(joined.memberProfile.displayName)} joined. ${joinRights}`)
for (const owner of this.owners()) {
if (!before.some(({groupMemberId}) => groupMemberId === owner.groupMemberId)) await this.sessions.inviteOwner(owner)
}
}
// spec: spec/architecture.md#main-group-maingroup-onevent
private async ownerJoined(member: T.GroupMember): Promise<void> {
await this.deleteLink()
await this.chat.apiSetMembersRole(this.groupId, [member.groupMemberId], T.GroupMemberRole.Owner)
await this.refreshMembers()
await this.post(greeting)
log(`${joinedText(member, oneLine)} and is now an owner. The link is deleted.`)
}
// spec: spec/api.md#plugin-commands
private lose(): void {
this.lost = true
log(`The Main group is lost. Run ${resetCommand} in a terminal.`)
}
// spec: spec/architecture.md#main-group-maingroup-openlink
private async openLink(): Promise<void> {
await this.deleteLink()
this.linkText = await this.chat.apiCreateGroupLink(this.groupId, T.GroupMemberRole.Member)
log(`Main group link created. Whoever joins by it first becomes an owner of "${this.name}".`)
}
// spec: spec/architecture.md#main-group-maingroup-openlink
private async deleteLink(): Promise<void> {
this.linkText = undefined
try {
await this.chat.apiDeleteGroupLink(this.groupId)
} catch (error) {
if (!isMissingLink(error)) throw error
}
}
private async post(text: string, priority?: number): Promise<number> {
const message: T.ComposedMessage & {priority?: number} = {msgContent: {type: "text", text}, mentions: {}, priority}
const [sent] = await this.chat.apiSendMessages([T.ChatType.Group, this.groupId], [message])
return sent.chatItem.meta.itemId
}
private serialize<R>(work: () => Promise<R>): Promise<R> {
const result = this.events.then(work)
this.events = result.catch(() => undefined)
return result
}
private async refreshMembers(): Promise<void> {
this.members = await this.chat.apiListMembers(this.groupId)
}
private humans(): T.GroupMember[] {
return this.members.filter(member => this.isHuman(member))
}
private isHuman(member: T.GroupMember): boolean {
return member.groupMemberId !== this.group.membership.groupMemberId && isActive(member)
}
}
// spec: spec/architecture.md#main-group-findmaingroup
export async function findMainGroup(chat: api.ChatApi, userId: number): Promise<T.GroupInfo | undefined> {
const groups = (await chat.apiListGroups(userId)).filter(({customData}) => (customData as {[mainKey]?: boolean} | undefined)?.[mainKey] === true)
return groups.reduce<T.GroupInfo | undefined>((latest, group) => (latest === undefined || group.groupId > latest.groupId ? group : latest), undefined)
}
function isMissingLink(error: unknown): boolean {
const chatError = chatErrorOf(error)
return chatError?.type === "errorStore" && chatError.storeError.type === "groupLinkNotFound"
}
// spec: spec/architecture.md#main-group-maingroup-showlist
function isRefusedEdit(error: unknown): boolean {
const chatError = chatErrorOf(error)
return (chatError?.type === "error" && chatError.errorType.type === "invalidChatItemUpdate") || (chatError?.type === "errorStore" && chatError.storeError.type === "chatItemNotFound")
}
// spec: spec/architecture.md#main-group-maingroup-showlist
function isTooLarge(error: unknown): boolean {
const chatError = chatErrorOf(error)
return chatError?.type === "errorStore" && chatError.storeError.type === "largeMsg"
}
// spec: spec/api.md#main-group-profile
function listOf(customData: object | undefined): SessionList | undefined {
const list = (customData as {[listKey]?: Partial<SessionList>} | undefined)?.[listKey]
return typeof list?.item === "number" && typeof list.at === "number" ? {item: list.item, at: list.at} : undefined
}
// spec: spec/api.md#main-group-profile
export async function createMainGroup(chat: api.ChatApi, userId: number, displayName: string): Promise<T.GroupInfo> {
const group = await createGroup(chat, userId, {
displayName,
fullName: "",
shortDescr,
description: welcome,
groupPreferences: {history: {enable: T.GroupFeatureEnabled.On}, directMessages: {enable: T.GroupFeatureEnabled.On, role: T.GroupMemberRole.Owner}, commands: mainCommands},
}, {[mainKey]: true})
log(`Main group "${displayName}" created.`)
return group
}