# reply-end-controls - Telegram V1 Design

## Scope

This project is Telegram-only.

No Discord, Slack, or cross-channel abstraction is part of V1.

## Product behavior

At the end of every assistant reply sent to Telegram, attach two inline buttons:

- `A. 繼續`
- `B. 就這樣吧，不需要額外處理`

Button selection must be captured and stored in conversation/session state.

If the user types a new message instead of pressing a button, the typed message takes priority.

## V1 rules

### Rule 1

Every assistant reply gets reply-end buttons.

### Rule 2

If the user taps `繼續`:

- store `lastChoice=continue`
- allow follow-up behavior on later turns

### Rule 3

If the user taps `就這樣吧，不需要額外處理`:

- store `lastChoice=stop`
- suppress unnecessary continuation behavior on later turns

### Rule 4

If the user sends a new typed message, that input overrides the button state.

### Rule 5

After a button is clicked, the original message buttons should be updated so the selection is visually resolved and repeated clicks are reduced.

## State model

Store this in Telegram conversation/session state:

```json
{
  "replyEndControls": {
    "lastChoice": "continue | stop",
    "lastChoiceAt": "ISO timestamp",
    "sourceMessageId": "telegram message id",
    "sourceCallbackId": "telegram callback query id",
    "active": true
  }
}
```

## Telegram callback payloads

Suggested callback data format:

- `rec:continue`
- `rec:stop`

If message-scoped state is needed later, extend to:

- `rec:continue:<messageId>`
- `rec:stop:<messageId>`

## Technical flow

### Outbound reply flow

1. Assistant reply text is produced.
2. Telegram reply payload is decorated with inline keyboard.
3. Message is sent to Telegram.

### Callback flow

1. User clicks button.
2. Telegram sends callback query.
3. Callback handler parses `continue` or `stop`.
4. State is persisted.
5. Original message buttons are updated to reflect the chosen option.

### Next-turn behavior

1. A later turn begins.
2. Runtime checks `replyEndControls.lastChoice`.
3. If `stop`, do not proactively extend or continue the previous thread unless the user explicitly asks.
4. If `continue`, normal continuation behavior is allowed.

## Suggested implementation modules

### 1. Reply decorator

Responsibility:

- append Telegram inline keyboard to every assistant reply

### 2. Callback handler

Responsibility:

- receive Telegram callback queries
- parse reply-end action
- update state

### 3. State storage helper

Responsibility:

- persist and retrieve the latest reply-end selection for the current conversation/session

### 4. Behavior policy hook

Responsibility:

- inspect `lastChoice`
- suppress proactive continuation when `stop` is active

## Acceptance criteria for V1

V1 is complete when all of the following are true:

1. A normal Telegram assistant reply shows both buttons.
2. Clicking `繼續` is received and stored.
3. Clicking `就這樣吧，不需要額外處理` is received and stored.
4. After click, the original message is updated to show the choice state.
5. A new typed user message still works without pressing any button.
6. A later turn can read the stored choice and alter continuation behavior.

## Non-goals for V1

- multi-channel abstraction
- governance integration
- analytics dashboard
- complex branching controls beyond `continue` and `stop`