diff --git a/telegram-openclaw-poc-plan.md b/telegram-openclaw-poc-plan.md new file mode 100644 index 0000000..439b115 --- /dev/null +++ b/telegram-openclaw-poc-plan.md @@ -0,0 +1,158 @@ +# Telegram + OpenClaw PoC Implementation Plan + +## Goal + +Build the first working proof of concept for `reply-end-controls` on the real OpenClaw Telegram path. + +The PoC only needs to prove three things: + +1. every assistant reply can include the two reply-end buttons +2. Telegram button clicks can be received as callback queries +3. the selected choice can be written into state and later read back + +## Buttons + +Required V1 buttons: + +- `A. 繼續` +- `B. 就這樣吧,不需要額外處理` + +Suggested callback payloads: + +- `rec:continue` +- `rec:stop` + +## Target OpenClaw integration points + +### Outbound injection layer + +Primary target area: + +- Telegram outbound payload construction + +Relevant runtime files already identified: + +- `channel-C2-7V9Dv.js` +- `send-sxDwUGaO.js` +- `delivery-CZV2kWBm.js` + +PoC intention: + +- locate the point where normal text replies become Telegram send payloads +- append `reply_markup.inline_keyboard` +- do not redesign all message types in V1 + +### Callback receive layer + +Primary target area: + +- Telegram callback query handler + +Relevant runtime file already identified: + +- `bot-Ce301bOE.js` + +PoC intention: + +- intercept callback query data matching `rec:*` +- normalize into internal state event +- store the result + +## State write strategy + +V1 should keep this simple. + +Write state into a dedicated conversation/session structure rather than trying to redesign all runtime state. + +Minimum stored fields: + +```json +{ + "replyEndControls": { + "lastChoice": "continue | stop", + "lastChoiceAt": "ISO timestamp", + "sourceMessageId": "string", + "sourceCallbackId": "string", + "active": true + } +} +``` + +## PoC phases + +### Phase 1 - visual proof + +Goal: + +- every assistant Telegram reply includes the two buttons + +Done when: + +- a real Telegram assistant reply visibly shows both buttons + +### Phase 2 - callback proof + +Goal: + +- clicking either button is received by OpenClaw + +Done when: + +- callback query with `rec:continue` or `rec:stop` is logged or persisted + +### Phase 3 - state proof + +Goal: + +- the click updates stored reply-end state + +Done when: + +- state can be read back and shows the latest user choice + +### Phase 4 - behavior proof + +Goal: + +- later assistant behavior changes based on that state + +Done when: + +- `stop` suppresses proactive continuation +- `continue` allows normal continuation + +## First implementation cut + +The very first code change should target only: + +- standard Telegram assistant text replies + +It does not need to cover: + +- media replies +- polls +- approval flows +- system notices +- every Telegram edge case + +## Safety rule + +Do not mix this with governance logic. + +The reply-end-controls PoC should be kept separate from the governance interceptor project and should not reuse its semantics. + +## Recommended implementation order + +1. Add inline keyboard to normal Telegram assistant replies +2. Receive callback queries for `rec:continue` / `rec:stop` +3. Persist state +4. Edit message buttons to resolved state +5. Read the state from a later turn + +## Immediate next task + +Implement the smallest visible PoC: + +- inject the two buttons into standard Telegram assistant replies + +That is the fastest path to proving the project is attached to the real Telegram reply chain.