@ycodium-ai/plugin-im 0.2.2968 → 0.2.2974

package/README.md

@@ -35,8 +35,61 @@ they pick their own project:
   `/repo` switches the project: the old thread is kept (still under that
   project's `/sessions`), the chat forgets it, and a running turn blocks the
   switch. The panel has a Pick project button.
-- A chat only hears the project it picked: one conclusion per finished turn and
-  thread failures go to the chats that picked that project; a chat with no
+- On Telegram a forum topic is a chat of its own: its chat id is `chat:topic`
+  (`chatIdOf`, only when Telegram marks the message `is_topic_message`; a reply
+  chain in an ordinary supergroup also carries `message_thread_id` and stays the
+  group), so each topic picks its own project and keeps its own thread. Sends to a
+  topic carry `message_thread_id`; edits, reactions and the member count use the
+  group id. General is the group itself. An adapter reports the chat a chat hangs
+  under as `parentChatId` on the inbound message (a topic's group); a chat with no
+  project yet copies the parent's project, model and plan mode on its first message
+  (`inheritFromParent` in `inbound.ts`, one `chat-updated` fact) and is on its own
+  from then on.
+- On Lark every answer is a reply to the message that caused it. An adapter opts in
+  with `quotesReplies`; only then does `inbound.ts` put a reply anchor
+  (`ImReplyAnchor`: message id, in a topic or not) on the binding it handles a message
+  with, so command replies and the panel card quote the command, and only threads that
+  have an anchor are looked up at all. `bindingOf` drops the anchor, since a binding
+  built for another chat (`/group`) must not reply into the old one. `turns.ts` records
+  the anchor against the user message it dispatches (`replyAnchors.ts`, in memory,
+  bounded), and the reply card, approval and question cards, the settled
+  attachments and `im_send_file` look it up through the host's own record of which
+  user message started the turn (`getThreadExecution`: the turn intent carrying that
+  turn id), not through the order of the message list, because a message queued
+  behind a running turn is already in that list. The queued-message card replies to
+  the queued message itself. A turn continued from the app, or one that outlives a
+  restart, has no anchor and is posted with the plain send. `larkApi.ts` calls the reply endpoint and falls back to the
+  plain send when Lark rejects the reply (the quoted message was withdrawn, the chat
+  does not take topic replies); a network error is not retried, since the message may
+  have gone out. `reply_in_thread` is set when the inbound message already sits in a
+  topic (`thread_id`) or mentions the bot while the per-bot **Open a topic when
+  mentioned** column (`larkTopicOnMention`, on unless set to `off`, read only by the
+  Lark adapter) is on.
+- On Lark a topic in a group is a chat of its own, like a Telegram forum topic. Its
+  chat id is `chat:rootMessage` (`topicChatIdOf` in `larkAdapter.ts`): the root message
+  is known before the topic exists, the platform's own topic id only after the first
+  reply. Later messages in the topic carry the topic id, and usually the root; the
+  adapter reports the topic id as `chatAlias`, and the core keeps a persisted
+  alias-to-chat table (`chat-aliased` facts, first one wins, `chatAliasOf` in
+  `chatState.ts`) so a message that carries only the topic id still lands in the same
+  chat. The adapter also learns the topic id when a topic reply goes out (the reply
+  response, or a read-back of the root message when the response has none) and reports
+  it through `noteChatAlias`; every send takes its target from one helper
+  (`sendTarget`), so no send path can skip that. A send to a topic chat with nothing to
+  quote replies to the topic's root, since Lark cannot address a topic directly. A
+  card callback names only the group, so a panel click is matched to the chat that
+  opened the card when that chat sits under the clicked group (`handlePanelClick`
+  asks the adapter's `parentChatIdOf`; how a chat id is encoded stays in the adapter).
+  Private chats are never split by topic. A main-window message that mentions the
+  bot does not yet belong to a topic: the adapter reports it under the group with
+  `branchChatId`, and `inbound.ts` moves it to that chat only at the point where a
+  turn is about to start, after commands, the project picker, pending questions and
+  team routing were handled for the group, so `/repo` typed in the group still changes
+  the group.
+- A finished turn or a failed thread is reported to the chat that is talking in that
+  thread and to nobody else (`notificationTargets.ts`). Only a thread no chat is
+  talking in (opened in the app) is reported by project: one conclusion per finished
+  turn and thread failures go to the chats that picked that project; a chat with no
   project hears nothing.
 - `/group <name>` (Lark only): the bot creates a group, adds the sender as owner
   and posts the project picker in it. Telegram and WeCom bots cannot create
@@ -88,7 +141,12 @@ An adapter opts in with the optional `turnCards` surface (`src/adapter.ts`).
 Approval messages are posted for every pending request on platforms with
 buttons and replaced with a settled notice when the request is answered, here or
 elsewhere (`thread.request-resolved`); WeCom, which answers by number, posts only
-the first and just stops accepting its number. Cards that were still open when the
+the first and just stops accepting its number. On a platform whose `turnCards` set
+`rotatesOnInteraction` (Lark: patching a card does not move it), an approval or
+question that someone answered seals the open reply card as "continues below" and the
+next tick opens a new one under the interaction card (`rotate` in `turnCards.ts`, on
+the same per-thread queue as the ticks), so the settled reply is the last card in the
+chat. Cards that were still open when the
 plugin restarted are marked interrupted. The pieces are pure and separate:
 `turnView.ts` (ticks to a view model), `larkCards.ts` (view model to card JSON),
 `larkMarkdown.ts`, `larkCardStream.ts` (throttle, one update in flight, newest