add-telegram

# Add Telegram Channel

Adds Telegram bot support via the Chat SDK bridge. NanoClaw doesn't ship
channels in trunk — this skill copies the Telegram adapter, its pairing helper,
and their tests in from the `channels` branch. The
`pair-telegram` setup step is maintained in trunk, so it is not copied here.

The mechanical steps under **Apply** carry `nc:` directive fences: an agent
reads the prose and applies them, and a parser can apply them deterministically
from the same document. Every directive is idempotent, so the whole skill is
safe to re-run; anything a parser can't apply falls back to the prose beside it.

Re-running with a bot already configured can add a second one instead of
re-pairing the first; see **Add another bot** under Credentials.

## Apply

### 1. Copy the adapter, helpers, and tests

Fetch the `channels` branch and copy the Telegram adapter, its pairing helper
(with its test), and the focused adapter tests into place (overwrite — the
branch is canonical):

```nc:copy from-branch:channels
src/channels/telegram.ts
src/channels/telegram-pairing.ts
src/channels/telegram-pairing.test.ts
src/channels/telegram-registration.test.ts
src/channels/telegram-connect-group.test.ts
src/channels/telegram-instances-registration.test.ts
src/channels/telegram-pairing-interceptor.test.ts
```

### 2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line
is already present). This one line is the skill's only reach-in into core:

```nc:append to:src/channels/index.ts
import './telegram.js';
```

### 3. Register the pairing setup step

Add the `pair-telegram` loader to the `STEPS` map in `setup/index.ts`, inside the
dormant marker region (skipped if already present — `pair-telegram` ships in core,
so this idempotent-skips on a normal install, but is expressed for a
clean-upstream rebuild). The pairing handshake below spawns this step:

```nc:append to:setup/index.ts at:nanoclaw:setup-steps
'pair-telegram': () => import('./pair-telegram.js'),
```

### 4. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:

```nc:dep
@chat-adapter/telegram@4.29.0
```

### 5. Build and validate

Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
the dependency is installed. Then run the focused tests.

```nc:run effect:build
pnpm run build
```
```nc:run effect:test
pnpm exec vitest run src/channels/telegram-registration.test.ts src/channels/telegram-connect-group.test.ts
```

`telegram-registration.test.ts` imports the real channel barrel and asserts the
registry contains `telegram`. It goes red if the import line is deleted or drifts,
if the barrel fails to evaluate, or if `@chat-adapter/telegram` isn't installed
(the import throws) — so it also covers the dependency from step 4. End-to-end
delivery against a real bot is verified manually once the service runs.

## Credentials

An install that already holds `TELEGRAM_BOT_TOKEN` can add a second bot instead of
re-pairing the first. Check which case this is; the answer steers the rest of the
flow:

```nc:run capture:has_default_bot
grep -qsE '^TELEGRAM_BOT_TOKEN=.+' .env && echo yes || echo no
```
```nc:run capture:add_another
[ "{{has_default_bot}}" = yes ] && echo ask || echo no
```

On a first install there is no bot to add another to, so `add_another` is `no` and
the steps below create and configure the first bot. When a bot is already configured, ask the
user whether to keep using it (`no`: the stored token stays as it is and the flow
re-pairs that bot) or to add another one (`yes`: the first bot's steps are satisfied
by the stored token and change nothing; the new bot is handled under **Add another
bot**):

```nc:prompt add_another validate:^(yes|no)$ normalize:lower when:add_another=ask
A Telegram bot is already configured (TELEGRAM_BOT_TOKEN in .env). Add another bot (yes), or keep using the existing one (no)?
```

Bot creation in Telegram is human and interactive — no parser can click through
BotFather. The adapter is installed and registered, but it can't receive a
message until the bot exists. On a first install, tell the user (a bot that is
already configured keeps its stored token below; a second one is created under
**Add another bot**):

```nc:operator when:has_default_bot=no
Create the Telegram bot:
1. Open Telegram and message @BotFather — Telegram's official bot for creating bots.
2. Send /newbot and follow the prompts: a friendly name, then a username that must end in "bot".
3. Copy the bot token it gives you (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11a).
4. Planning to use the bot in group chats? Send /mybots → your bot → Bot Settings → Group Privacy → Turn off, so the bot can see all messages and not just @mentions.
```

Collect the bot token and store it — the bridge reads it from `.env` (set-if-absent,
so a value you've already filled in is never overwritten) and syncs it to the
container:

```nc:prompt bot_token secret validate:^[0-9]+:[A-Za-z0-9_-]{35,}$
Paste the bot token from BotFather (looks like `123456:ABC-DEF...`).
```
```nc:env-set
TELEGRAM_BOT_TOKEN={{bot_token}}
```
Confirm the token works and capture the bot's handle — `getMe` returns the bot
account and fails here if the token is bad. You'll use the handle to open the
right chat just before pairing:

```nc:run capture:bot_username effect:fetch
curl -sf https://api.telegram.org/bot{{bot_token}}/getMe | jq -er '.result.username'
```

### Add another bot

Only when `add_another` is `yes`. The second bot is a named adapter instance: its
short name becomes the registry key `telegram-<name>` and, uppercased with dashes as
underscores, the token key suffix (`gh-bot` stores `TELEGRAM_BOT_TOKEN_GH_BOT`). A
name whose `TELEGRAM_BOT_TOKEN_<NAME>` key is already set is taken (storing under it
would overwrite that bot's token), so it is refused:

```nc:prompt bot_name validate:^[a-z0-9][a-z0-9-]*$ when:add_another=yes
Short name for the new bot