# 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.