# Telegram Leo x402 Priority And Spec

## Definition Of Working

Working target: a user can DM or tag `@TeleoHumanBot`; the Telegram Leo process
forwards the message to `https://leo.livingip.xyz/api/agents/leo/chat`; the user
receives a Leo answer; retained logs prove the request hit the public Leo HTTP
route.

Operator path:

```sh
/opt/teleo-eval/pipeline/.venv/bin/python3 /opt/teleo-eval/telegram/agent_runner.py --agent leo --validate
systemctl start teleo-agent@leo
journalctl -u teleo-agent@leo -n 100 --no-pager
```

Done means:

- `teleo-agent@leo.service` is active on `77.42.65.182`.
- A real Telegram message to `@TeleoHumanBot` receives a Leo reply.
- Retained proof includes Telegram message/readback, `journalctl` proxy log, and
  `leo.livingip.xyz` HTTP access/readback.
- Rio and Theseus remain unaffected.

Not done:

- HTTP-only proof without a live Telegram delivery.
- Candidate/local proof without the public bot service active.
- Payment evidence reused as Telegram delivery evidence.

Required tier: `T3_live_readonly` for the Telegram transport; payment claims use
the separately retained x402/Faremeter/AgentCash evidence tiers.

Current tier: `T3_live_readonly` for bridge-to-public-HTTP proof only. The bot
token exists on the VPS, `getMe` identifies `@TeleoHumanBot`, and temporary VPS
config validation passed. The live `teleo-agent@leo.service` deployment has not
been started by this PR-shaped patch.

Promotion gate: current VPS readback showed `teleo-agent@leo.service` uses
`/opt/teleo-eval/telegram/agent_runner.py`, while deploy scripts historically
synced `telegram/` only into `/opt/teleo-eval/pipeline/telegram/`. This patch
updates both manual and auto deploy scripts to sync `telegram/` into the runtime
path too. Do not start `teleo-agent@leo` until `leo.yaml` and
`http_chat_proxy.py` read back from `/opt/teleo-eval/telegram/`.

## Priority Matrix

| Priority | Lane | Current State | Ship Decision |
| --- | --- | --- | --- |
| P0 | Telegram Leo bridge deploy/readback | PR-shaped patch exists; public HTTP proof is retained; VPS token and config validation are confirmed; deploy-path mismatch is patched locally. | Push/merge the bridge, confirm runtime files read back under `/opt/teleo-eval/telegram`, start `teleo-agent@leo`, and retain Telegram delivery logs. |
| P0 | Self-hosted Faremeter seller rail | Retained public and hosted mainnet canary receipts exist, and direct `77.42.65.182:3118` currently serves a valid 0.01 USDC mainnet challenge. Fresh `https://leo.livingip.xyz` readback currently returns a Devnet `payment_challenge_unavailable` response, so public host routing is not proving the mainnet Faremeter rail right now. | Keep Faremeter as the default seller rail, but repair/repoint public `leo.livingip.xyz` to the working mainnet route before claiming current public mainnet seller readiness. |
| P1 | Leo paid research outbound loop | AgentCash/StableEnrich paid answer and Leo analysis proof already exist. | Expose the result through Telegram after bridge deploy; add per-provider approval packets for new services. |
| P1 | Public Leo HTTP behavior | `https://leo.livingip.xyz/api/agents/leo/chat` returns a parseable Leo reply under the current schema. | Treat as the bridge backend; avoid duplicating Leo logic inside Telegram. |
| P2 | Corbits/Herd/payable external services | Corbits moved payment but failed upstream API-key validation; Herd still needs an authenticated/payable endpoint proof. | Keep as provider-specific follow-up; do not block Telegram/Faremeter shipping on it. |
| P2 | All inbound service coverage | Sponsor-research has the strongest retained x402 receipts; other catalog rows need per-service canaries. | Broaden after Telegram bridge is live. |

## Spec Tickets

### TLG-001: Merge And Deploy Telegram Leo Bridge

Surface: `telegram/agent_config.py`, `telegram/bot.py`,
`telegram/http_chat_proxy.py`, `telegram/agents/leo.yaml`.

Acceptance:

- Deploy scripts sync `telegram/` into `/opt/teleo-eval/telegram/`, matching
  `teleo-agent@.service`.
- Leo config validates in the production venv.
- `teleo-agent@leo.service` starts without restarting Rio or Theseus.
- A Telegram DM/tag reaches the HTTP proxy branch.
- Failure from the HTTP route returns a clear fail-closed Telegram response.

Evidence:

- `docs/reports/telegram-leo-x402-bridge-proof.json`
- `journalctl -u teleo-agent@leo -n 100 --no-pager`
- Telegram screenshot/export for the delivered reply.

### TLG-002: Retain Live Telegram Proof

Surface: `scripts/check_telegram_leo_x402_bridge.py` plus a live deployment
proof artifact after promotion.

Acceptance:

- Proof names the public Telegram bot handle and public Leo HTTP URL.
- Proof says whether the message was Telegram-delivered or HTTP-only.
- Proof includes no token values, secrets, chat-private content beyond the test
  prompt and Leo reply.

### X402-FARE-001: Make Faremeter The Default Seller Rail

Surface: Living IP x402 route configuration and operator docs in the x402
worktree.

Acceptance:

- Public sponsor-research route keeps using the self-hosted Faremeter path.
- Fresh public readback for `https://leo.livingip.xyz/api/initiatives/sponsor-research`
  returns the intended mainnet 0.01 USDC challenge, not the stale Devnet
  `payment_challenge_unavailable` response.
- A repeat public canary command is documented with the smallest safe spend cap.
- No PayAI/CDP dependency is required for the default seller rail.

Existing evidence:

- `ops/x402-faremeter-mainnet-public-payment-proof.json`
- `ops/x402-faremeter-hosted-candidate-payment-proof.json`
- `ops/x402-faremeter-direct-payment-proof.json`

### LEO-OUT-001: Telegram Surface For Paid Research Results

Surface: Telegram Leo bridge plus retained paid-source artifacts.

Acceptance:

- Telegram Leo can answer a question using the same public Leo HTTP behavior
  that already consumed paid AgentCash research.
- The answer references retained paid-source evidence without claiming a fresh
  payment unless a fresh payment receipt exists.

Existing evidence:

- `ops/x402-agentcash-paid-readback-proof.json`
- `ops/x402-leo-paid-research-analysis-proof.json`

## Reviewer CTA

Approve the PR-shaped Telegram bridge and then run the production promotion
commands from `docs/telegram-leo-x402-bridge-pr-packet.md`. Do not wait on
Corbits/Herd broadening to ship the Telegram transport and self-hosted Faremeter
seller rail.