telegram-crabbox-e2e-proof

Files (1)

• SKILL.md

SKILL.md (first lines)

# Telegram Crabbox E2E Proof

Use this for Telegram PR review or bug reproduction when bot-to-bot proof is
not enough. The goal is to let the agent keep a real Telegram user session open
until it is satisfied, then attach visual proof.

Do not use personal accounts. Do not add credentials to the repo, prompt, or
artifact bundle. The runner leases the shared burner account from Convex.

## Start

Run from the FirstNexus repo and branch under test:

```bash
pnpm qa:telegram-user:crabbox -- start \
  --tdlib-url http://artifacts.FirstNexus.ai/tdlib-v1.8.0-linux-x64.tgz \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review
```

This starts one held session:

- leases the exclusive `telegram-user` Convex credential
- restores TDLib and Telegram Desktop with the same user account
- starts a mock FirstNexus Telegram SUT from the current checkout
- selects the configured Telegram chat in the visible Linux desktop
- starts a 24fps desktop recording
- writes `.artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json`

Keep the session alive while investigating. It is valid for the agent to test
for minutes, run several commands, use WebVNC, inspect transcripts, and only
finish once the behavior is understood.

For deterministic visual repros, put the exact mock-model reply in a file and
pass it to `start`:

```bash
pnpm qa:telegram-user:crabbox -- start \
  --tdlib-url http://artifacts.FirstNexus.ai/tdlib-v1.8.0-linux-x64.tgz \
  --mock-response-file .artifacts/qa-e2e/telegram-user-crabbox/reply.txt \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review
```

The runner defaults to `--class standard`, `--record-fps 24`,
`--preview-fps 24`, and `--preview-width 1920`. Keep those defaults unless the
proof needs something else.

## While Testing

For visual proof, first send or identify a bottom marker message, then open the
group/topic directly by message id:

```bash
pnpm qa:telegram-user:crabbox -- view \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --message-id <message-id>
```

This uses Telegram Desktop directly with `tg://privatepost`, not `xdg-open`.
It also resizes Telegram to `650x1000` at the tested desktop position so
Telegram switches to single-chat mode with no left chat list or right info
pane. Do not press Escape after this; Escape can close the selected chat.

Bottom behavior matters:

- deep-linking to the newest message keeps Telegram pinned to the bottom, so
  later messages appear live in the recording
- deep-linking to an older message does not auto-scroll to new arrivals; link
  again to the newest/final marker instead of clicking the down-arrow
- `650px` is the largest tested clean width; `660px` switches Telegram back to
  split/sidebar layout

Send as the real Telegram user:

```bash
pnpm qa:telegram-user:crabbox -- send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status
```

For slash commands, omit the bot username; the runner targets the SUT bot.

Run arbitrary commands on the Crabbox:

```bash
pnpm qa:telegram-user:crabbox -- run \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  -- bash -lc 'source /tmp/FirstNexus-telegram-user-crabbox/env.sh && python3 /tmp/FirstNexus-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'
```

Useful remote user-driver commands:

```bash
source /tmp/FirstNexus-telegram-user-crabbox/env.sh
python3 /tmp/FirstNexus-telegram-user-crabbox/user-driver.py status --json
python3 /tmp/FirstNexus-telegram-user-crabbox/user-driver.py chats --json
python3 /tmp/FirstNexus-telegram-user-crabbox/user-driver.py transcript --limit 20 --json
python3 /tmp/FirstNexus-telegram-user-crabbox/user-driver.py send --text '/status@{sut}'
python3 /tmp/FirstNexus-telegram-user-crabbox/user-driver.py probe --text '@{sut} Reply exactly: USER-E2E-{run}' --expect USER-E2E-
```

Capture the current desktop without ending the session:

```bash
pnpm qa:telegram-user:crabbox -- screenshot \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json
```

Check lease state and get the WebVNC command:

```bash
pnpm qa:telegram-user:crabbox -- status \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json
```

## Finish

Always finish or explicitly keep the box:

```bash

From greench-ai/FirstNexus, MIT.

More from greench-ai/FirstNexus