@justfortytwo/telegram

The Telegram channel adapter for fortytwo — a standalone, always-on bridge that connects a Telegram bot to a headless claude turn loop.

It does three jobs:

1. Turn loop. Long-poll Telegram, and for each authorized inbound message drive a headless claude -p --output-format json turn (resuming the per-chat session), then transport the assistant's reply back.
2. Approval UX. When the safety gate defers an external/irreversible tool call, the turn ends with stop_reason: tool_deferred. The bridge surfaces an inline-keyboard approval card (Approve / Deny, plus "Allow _N_h" for exact Bash commands). The tap records the decision and resumes the turn so the one-shot allow fires.
3. Proactive wakes. A scheduler invokes claude -p at fixed cron-like slots (daily briefing, open-thread sweeps, weekly learn-review).

Pairing / login binding model

The bot is locked down: an unbound sender that does not present a valid /login gets no response at all. Access is earned through a channel-agnostic challenge/verify pairing flow:

owner side:    adapter.issueChallenge(owner)  ->  { code, ttl }
channel side:  /login <code>                  ->  verify(chatId, code) -> binding

• issueChallenge(owner) mints a single-use, short-TTL code (default 6 digits, 5 minutes). The owner relays it out-of-band to the chat they want to bind.
• /login <code> verifies the code and, on success, persists a binding (channelType, channelUserId) -> owner.
• /logout removes the binding.
• Every inbound message is authorized against persisted bindings ∪ the optional ALLOWED_CHAT_IDS bootstrap set. The bootstrap set lets the first owner chat reach the bridge before any binding exists; it is not required once bindings exist.

Pending challenges are persisted in the binding store (not in process memory), so a code minted by one process — e.g. the fortytwo pair CLI — is redeemable by the separately-running bridge. They are single-use and short-TTL.

The contract is intentionally channel-agnostic (ChannelAdapter in src/adapter.ts) so a future Slack / email / SMS adapter implements the same issueChallenge / verify shape.

Binding store

Authorization must work even when the memory package is absent, so the binding store is self-owned and does not assume the @justfortytwo/memory sqlite db exists:

• SqliteBindingStore — default; a tiny better-sqlite3 db in its own file (state/telegram-bindings.db by default) holding bindings + pending challenges, so a CLI-issued pairing code reaches the bridge.
• MemoryBindingStore — in-process Map, for tests / ephemeral use.
• BindingStore — the injectable interface. Supply a memory-backed implementation later without touching the login flow.

Cross-repo reconciliation: if fortytwo standardizes a shared identity table, swap the default store for a memory-backed BindingStore. The login flow is unaffected.

Peer dependencies

This package orchestrates two peer packages — they are referenced, not bundled:

| Peer | Used for | Contract | | --- | --- | --- | | @justfortytwo/memory | Memory store, jobs, pending-decision records, embeddings | MEMORY_TOOL_CONTRACT_VERSION (tools mcp__fortytwo-memory__*) | | @justfortytwo/gate | Bash exact-command allowlist behind "Allow _N_h"; provenance envelopes | POLICY_SCHEMA_VERSION |

Install them alongside this package:

npm install @justfortytwo/telegram @justfortytwo/memory @justfortytwo/gate

The memory data path is wired: the bridge opens + migrates the memory DB at startup and persists each channel event to @justfortytwo/memory; recall happens inside the headless claude turn via the Memory MCP tools. If the memory peer is absent, the bridge degrades to channel-only (messages relay but are not persisted) rather than refusing to start. The gate "Allow _N_h" path still uses a local bash-allowlist fallback; wiring it to @justfortytwo/gate's exact-command allowlist is the remaining seam.

Environment

| Var | Required | Meaning | | --- | --- | --- | | TELEGRAM_BOT_TOKEN | yes | Bot token. The bridge is the only long-poller on this bot. | | ALLOWED_CHAT_IDS | bootstrap | Comma-separated chat IDs allowed before any binding exists. Optional once bindings exist. | | CLAUDE_BIN | no | Path to the claude binary (default claude). | | FORTYTWO_TURN_TIMEOUT | no | Hard cap (seconds) on a single turn so a stalled model can't wedge the bridge (default 300). | | FORTYTWO_BASH_ALLOW_TTL_HOURS | no | Default TTL (hours) for "Allow _N_h" bash approvals (default 8). | | TELEGRAM_BINDINGS_DB | no | Path to the self-owned bindings db (default state/telegram-bindings.db). | | DB_PATH | no | Path to the memory DB the bridge opens/migrates at startup (default db/fortytwo.db, relative to FORTYTWO_ROOT). | | EMBED_MODEL | no | When set, the bridge uses the Ollama embedder for memory (otherwise a deterministic fallback). | | OLLAMA_BASE_URL | no | Base URL for the Ollama embedder (default http://localhost:11434; may be remote). | | ASSISTANT_NAME / ASSISTANT_ACTOR / OWNER_ACTOR | no | Display name + journal actor labels. | | FORTYTWO_ROOT | no | Working root for the headless claude process + state files. |

The historical FORD_* names (FORD_ROOT, FORD_TURN_TIMEOUT, FORD_BASH_ALLOW_TTL_HOURS) are still honored as deprecated aliases — set the FORTYTWO_* equivalents in new deployments.

Proxy auth for the headless claude session is not read here — the claude CLI reads ANTHROPIC_* from its own config.

Usage

Prerequisites / first run

• The bridge spawns the claude binary, so Claude Code's claude must be on your PATH (or point CLAUDE_BIN at it).
• It loads config/adapters.toml from $FORTYTWO_ROOT/config/.
• On first run it requires TELEGRAM_BOT_TOKEN and either ALLOWED_CHAT_IDS or a pre-existing binding — with no authorized chat to reach, the bridge exits immediately rather than long-polling a bot nobody can talk to.

npm run build
node dist/bridge.js

Run it under a restart loop (tmux/systemd) so it survives transient errors and crashes. Example launcher (adapted from the monolith's wakeup.sh):

set -a; source .env; set +a
while true; do
  node node_modules/@justfortytwo/telegram/dist/bridge.js
  echo "[telegram] bridge exited (rc=$?) — restarting in 3s"; sleep 3
done

License

MIT © 2026 Enrico Deleo

Created and maintained by Enrico Deleo.