@ycodium-ai/plugin-im 0.2.2678 → 0.2.2694

package/README.md

@@ -1,25 +1,43 @@
 # @ycodium-ai/plugin-im
 
-Talk to your agents from Telegram, WeCom, or Lark. Mention the bot in a group
-and it starts a turn on this machine; the conclusion comes back to the group,
-and anything the agent needs approved lands there too.
+Talk to your agents from Telegram, WeCom, or Lark. Message the bot (or mention
+it in a group) and it starts a turn on this machine; the conclusion comes back
+to the chat, and anything the agent needs approved lands there too.
 
 ## What it does
 
-Each settings-card row is one group:
-
-- Pick a project and that group can start work there, and only hears that project.
-- Leave the project empty and the row only reports, on every project.
-- Archived projects are read-only. The project picker hides them unless a row is
-  already bound to one (shown as "(archived)"), and a message to a group bound
-  to an archived project gets a one-line reply that the project is archived
-  instead of starting work, at most once every ten minutes per group. Chat
-  commands such as help and status still work.
-  Restore the project to resume.
+Each settings-card row is one bot (platform, credentials, who may use it); the
+chats it talks in (private chats, groups) are not configured, they pick their own
+project:
+
+- **Allowed people** is an allow-list of that platform's user ids. Empty means
+  nobody can make the agent work. Someone who is not on it gets one reply with
+  their own user id and where to put it, at most once every ten minutes per
+  person (the table of who was told is bounded in memory).
+- A chat with no project starts nothing. The first message from an allowed
+  person gets a project picker (a card on Lark, an inline keyboard on Telegram,
+  a numbered text list on WeCom, which has no buttons: reply with the number or
+  `/repo <number>`). The pick is written as a plugin fact and survives restarts.
+  `/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
+  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
+  groups and answer so.
+- **In groups, answer** (per bot): only when mentioned (default), every message,
+  or every message except ones aimed at someone else. WeCom only delivers
+  mentions, so it has no effect there. Under the default, a group that holds only the
+  sender and the bot needs no mention (`soloGroup.ts`; Lark `im.v1.chat.get`, Telegram
+  `getChatMemberCount`, answer cached five minutes; WeCom unsupported).
+- Archived projects are read-only and are not offered by the picker. A message
+  to a chat whose project was archived or deleted gets a one-line reply that
+  says so and points at `/repo`, at most once every ten minutes per chat. Chat
+  commands such as help and status still work. Restore the project to resume.
 - Secrets (bot tokens, app credentials) stay in the environment secret store.
   The patch file keeps a reference, not the value.
-- Who may command the bot is an allow-list of that platform's user ids. Empty
-  means anyone in the group can make the agent run things on this machine.
 - A row can pick its own proxy. On a given machine one platform may be
   unreachable while another is fine.
 
@@ -62,7 +80,7 @@ optional `choiceCards` surface (`ImChoiceCard`, `src/adapter.ts`): Lark patches
 card, Telegram edits a message and its inline keyboard. A request is posted on
 `thread.user-input-pending` (read with `listPendingUserInputs`), one card per
 question, and answered with one `thread.user-input.respond` once every question
-has an answer; a free-form answer is the next ordinary message in the group, and
+has an answer; a free-form answer is the next ordinary message in the chat, and
 `thread.request-resolved` freezes the cards of a question answered elsewhere or
 closed unanswered. WeCom has no buttons: it writes the options as numbers and the
 reply is parsed in `src/questionCards.ts`. A message that lands behind a running
@@ -75,39 +93,41 @@ and `thread.turn-queue.resume`, and the card is the user's own action, so no
 and withdrawing need buttons (resuming is the `/continue` command). Editing a queued message is not offered:
 the host does not let a plugin dispatch `thread.turn-intent.edit`.
 
-A group keeps its place across restarts. Which thread a group is talking in, the
-team it is pointed at, the model and plan mode set from the group, the threads
-this plugin has opened, and the approval, question and queued-message buttons still
-waiting in the group are
+A chat keeps its place across restarts. Which project a chat picked, which thread
+it is talking in, the team it is pointed at, the model and plan mode set from the
+chat, the threads this plugin has opened, and the approval, question and
+queued-message buttons still waiting in the chat are
 written as plugin facts (`ctx.events.append`) and folded back by a pure function
 (`ctx.derivedState`, see `src/chatState.ts`). A saved thread that was deleted,
-archived or moved to another project is dropped on the next message.
+archived or no longer on the chat's project is dropped on the next message.
+The chat key is `<bot row id>:<chat id>`: two bots in the same person's private chat share
+the chat id, so the key has to carry the bot.
 
 Inbound attachments. An adapter reports a message's resources as `resources`
 (`ImInboundResource`, `src/adapter.ts`) and implements `fetchResource`, which must stop reading
 at `maxBytes` (`readBodyLimited`, `src/attachments.ts`) and throw `ImResourceTooLargeError`.
 An adapter whose platform caps bot downloads tighter than the host sets `downloadLimitBytes`
 (Telegram: 20 MB); a size the platform reports up front is checked before any download. The
-core (`collectResources` in `src/index.ts`) cleans the name (`sanitizeAttachmentName`: the host
+core (`collectResources` in `src/inboundAttachments.ts`) cleans the name (`sanitizeAttachmentName`: the host
 splices it into the `[Attached … "<name>" …]` line the agent reads, so newlines and double
 quotes must not survive), takes the type from the bytes (`resolveMime`: platforms self-report,
 Lark says PNG for every image), checks the host's limits (10 MiB image, 25 MiB other, 20 per
 turn, mirrored from the host because a plugin cannot import it) and stores each one with
 `ctx.attachments.store`; an image the host can inline reaches the agent as an image, anything
 else as a path. A failed one is reported in the chat and left as a line in the turn text.
-A message with attachments and no text starts no turn: the thread is created if the group has
+A message with attachments and no text starts no turn: the thread is created if the chat has
 none (attachments are stored per thread), the attachments wait in memory for that thread, and
-the next message with text carries them. Waiting attachments are dropped when the group's
+the next message with text carries them. Waiting attachments are dropped when the chat's
 thread changes and are not persisted. Lark does not require a mention for a message that is only
 a resource (`RESOURCE_MESSAGE_TYPES` in `src/larkInbound.ts`); the sender allow-list still
 applies. Lark rich text is read by `src/larkPost.ts` (every image, `<image N>` placeholders in
 order, the client's `md` field preferred). Known types we do not handle are reported with
-`unsupportedType` and answered with one line, rate-limited per group. A group pointed at a team
+`unsupportedType` and answered with one line, rate-limited per chat. A chat pointed at a team
 cannot carry attachments. WeCom reports `image`, `file`, `video` and the images of `mixed` (a group "mention plus picture"; text items and `<image N>` placeholders keep their order, and a mixed with only images still has content, so it starts a turn) in `resources`, with the download URL and `aeskey` packed into the resource key. `fetchResource` (`src/wecomMedia.ts`) GETs the URL (valid five minutes) and decrypts: `aeskey` is base64 for a 32-byte key, the IV is its first 16 bytes, AES-256-CBC with auto padding off, then PKCS#7 removed with a **32-byte block** (pad value 1 to 32, every pad byte equal, else the media is rejected). Without an `aeskey` the bytes are used as they are. The ciphertext is capped at limit + 32, the plaintext at the limit, and the file name comes from `Content-Disposition` (`filename*=UTF-8''…` first, then `filename="…"`) through `ImFetchedResource`. A WeCom `voice` message is its transcript as text, not an attachment. `quote` is not read on any platform.
 
 Outbound files. The plugin contributes one MCP tool, `im_send_file` (`src/sendFile.ts`;
 `ctx.toolkit` name `im`), with `path` and an optional `description` (the caption). It sends only
-to the group whose thread is the calling conversation (`chatOf(...).threadId`), never by
+to the chat whose thread is the calling conversation (`chatOf(...).threadId`), never by
 project, and fails with `not-in-chat` otherwise. The bytes come from `invocation.workspace`
 (`workspace.read`: realpath-bounded to the thread's folders, regular files, 50 MiB cap) and must
 be read before the handler returns, because every method rejects `invocation-ended` afterwards.
@@ -134,9 +154,10 @@ conversation and is left out when none has arrived since the plugin started, as
 A picture goes as `image` only when it is PNG, JPEG or GIF within 10 MB (`imageMimeTypes`).
 
 Chat commands: `/stop`, `/continue`, `/status`, `/new`, `/sessions`, `/resume`, `/model`,
-`/plan`, `/team`, `/thread`, `/help`, `/panel`. `/sessions` and `/resume` only list and
+`/plan`, `/repo`, `/group`, `/team`, `/thread`, `/help`, `/panel`. In a chat with no project
+`/sessions`, `/resume` and the team commands answer with the project picker. `/sessions` and `/resume` only list and
 switch threads this plugin opened, since the host lets a plugin send only into
-its own threads. `/continue` dispatches `thread.turn-queue.resume` for the group's thread
+its own threads. `/continue` dispatches `thread.turn-queue.resume` for the chat's thread
 when its queue is paused (a `/stop` or a failure pauses it), which is how WeCom, with
 no buttons, resumes; it is not `/resume`, which already switches threads.
 
@@ -147,7 +168,7 @@ a short `pn:<version>:<index>` token (`callback_data` is capped at 64 bytes);
 the action stays in memory and a tap on an older keyboard version counts as expired. Each card keeps its own view
 stack in memory (`src/panelController.ts`), so after a restart an old card only
 answers that it has expired. A tap runs the same handler as the typed command and
-waits in the same per-group queue as typed messages. Another platform opts in by
+waits in the same per-chat queue as typed messages. Another platform opts in by
 implementing the optional `panel` surface on its adapter (`src/adapter.ts`).
 
 The **Reply language** setting (Chinese by default, or English) picks the
@@ -173,18 +194,33 @@ ycodium plugin add @ycodium-ai/plugin-im
 The plugin ships enabled with Ycodium as `core.im`. Disabling it closes every
 chat connection. Uninstalling it writes a removal onto the home patch, so a
 restart or upgrade does not bring it back. Reinstalling the unversioned bundled
-package restores the same entry without an npm fetch. Group configuration and
+package restores the same entry without an npm fetch. Bot configuration and
 secrets stay until you clear them.
 
 ## Surfaces
 
-- **Web / Desktop** — Settings → Plugins → Chat. The groups table is the
+- **Web / Desktop** — Settings → Plugins → Chat. The bots table is the
   settings card this package registers.
 - **Mobile** — the same settings card, without platform option icons (mobile
   has no plugin icon pipeline).
 - Chat replies themselves go to Telegram, WeCom, or Lark, not into a Ycodium
   page.
 
+## Source layout
+
+`src/index.ts` only assembles: it builds the adapters, registers the settings card, builds the
+shared core and wires the feature modules together. Everything else is one module per
+responsibility, each receiving a small `core` object (a few host capabilities, the reply
+language, the saved-state mirror) plus an explicit `deps` object, never the whole `ctx`:
+
+- `botConfig` (settings card, reading bots, chat keys, allow-list), `core` (state mirror and
+  persistence, delivery, bot and chat lookup), `connections` (one long connection per bot)
+- `inbound` (per-bot message handlers), `chatQueue` (per-chat serial queue), `commands`,
+  `chatSetup` (picker, `/repo`, `/group`), `projectRows`/`projectList` (the project list),
+  `sessions`, `modelPlan`, `turns`, `inboundAttachments`, `teamRuns`
+- `approvals`, `interactions` (question and queue cards, button routing), `replyCards`,
+  `notifications`, `acknowledgements`, `panelWiring` (with `panelController`)
+
 ## Developing
 
 The package builds its own code and the Lark SDK into `dist/index.js`. The host