@ycodium-ai/plugin-im 0.2.2596 → 0.2.2658

package/README.md

@@ -57,17 +57,88 @@ snapshot wins), `turnCards.ts` (per-thread queue and lifecycle),
 `plainTurnText.ts` (view model to plain text), `telegramTurn.ts` (message
 rollover).
 
+The agent's questions and the messages queued behind a running turn use the
+optional `choiceCards` surface (`ImChoiceCard`, `src/adapter.ts`): Lark patches a
+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
+`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
+turn gets a queued card (Steer, Withdraw, Resume sending) drawn from
+`getThreadExecution` and refreshed when the turn intents or the queue change
+(`src/queueCards.ts`, `src/queueFlow.ts`); the buttons dispatch
+`thread.turn-intent.run` (steer, with the active turn id), `thread.turn-intent.cancel`
+and `thread.turn-queue.resume`, and the card is the user's own action, so no
+`intentAction` is sent. WeCom only gets a one-line notice, since steering
+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 buttons still waiting in the group are
+this plugin has opened, and the approval, question and queued-message buttons still
+waiting in the group 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.
 
-Chat commands: `/stop`, `/status`, `/new`, `/sessions`, `/resume`, `/model`,
+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
+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
+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
+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
+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
+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.
+Order: `stat` (size against the adapter's `outboundLimits`, before reading), `readFile` with
+`maxBytes` = the file limit, type from the bytes (`resolveMime`), then the caption line, then
+`sendImage` (a picture within the image limit) or the optional adapter method `sendFile`. Audio
+and video go as files. Lark uploads `file_type=stream` to `im/v1/files`; Telegram uses
+`sendDocument` and falls back to it when `sendPhoto` answers 400. Failures return `isError` with
+`errorCode` (`not-in-chat`, `no-workspace`, `outside-workspace`, `not-a-file`, `not-found`,
+`empty`, `too-large`, `unsupported-platform`, `upload-failed`); the text for the agent is plain
+English, only the caption goes through the catalog. The limits are Lark 10 MB image / 30 MB file
+(Lark docs), WeCom 10 MB image (PNG, JPEG, GIF) / 20 MB file / at least 5 bytes (WeCom docs), and
+Telegram 10 MB / 50 MB (from memory of the Bot API docs, not checked in this repository).
+
+WeCom uploads over the existing long connection (`src/wecomUpload.ts`, `request` in
+`src/wecomApi.ts`): `aibot_upload_media_init` (type, filename, total_size, total_chunks, md5) gives
+an `upload_id`; `aibot_upload_media_chunk` sends each chunk of at most 512 KB as base64 (all chunks
+in parallel up to 4, three at a time up to 10, else two; two retries per chunk after 500 ms and
+1000 ms); `aibot_upload_media_finish` gives the `media_id`; then `aibot_send_msg` carries
+`{ chatid, chat_type, msgtype: "image" | "file", <msgtype>: { media_id } }`. Every request waits for
+its ack by `req_id` (15 s); an `errcode` other than 0 or a missing ack fails the upload, and nothing
+is sent to the chat. `chat_type` (1 single, 2 group) comes from the last inbound message of that
+conversation and is left out when none has arrived since the plugin started, as plain text does.
+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
 switch threads this plugin opened, since the host lets a plugin send only into
-its own threads.
+its own threads. `/continue` dispatches `thread.turn-queue.resume` for the group'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.
 
 On Lark and Telegram, `/panel` sends a command panel (`/help` stays text and ends with a pointer to it; on WeCom, which has no panel, it does not): every command above
 is a button (a card on Lark, an inline keyboard on Telegram), and the ones that take an argument (a thread, a team, a model) open
@@ -86,10 +157,12 @@ interface language instead. The copy lives in `locales/en.json` and
 
 ## Requirements
 
-A Ycodium server. The plugin asks to dispatch `thread.create`,
-`thread.meta.update`, `thread.turn.start`, `thread.turn.interrupt`, and
-`thread.approval.respond`. Those commands only land on threads this plugin
-started.
+A Ycodium server. The plugin asks to read files in the project of the conversation that
+calls its tool (`workspace.read`, used only by `im_send_file`) and to dispatch `thread.create`,
+`thread.meta.update`, `thread.turn.start`, `thread.turn.interrupt`,
+`thread.approval.respond`, `thread.user-input.respond`, `thread.turn-intent.run`,
+`thread.turn-intent.cancel` and `thread.turn-queue.resume`. Those commands only land
+on threads this plugin started.
 
 ## Install