@ycodium-ai/plugin-im 0.2.2596 → 0.2.2634

package/README.md

@@ -57,17 +57,38 @@ 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`,
+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
@@ -87,9 +108,10 @@ 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.
+`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