genswarms-telegram-use

name

genswarms-telegram-use

description

Wire the genswarms-telegram package into a GenSwarms swarm: Telegram ingress + sender objects, agent replies via priv/reply.sh, structured cards, and the bound-slot security model. Use when adding Telegram to a swarm, sending messages/cards/media from agents or objects, or debugging "why doesn't my agent's reply reach Telegram" (unbound slot, wrong sender source, getUpdates conflict). This is the importer's guide — to change the package itself, read CONTRIBUTING/README and the test suite.

genswarms-telegram — using the package

Reusable Telegram transport for GenSwarms: an Ingress object (updates in) and a Sender object (messages out), with no product persona, policy, quota logic, or domain commands — those stay in YOUR swarm. swarmidx:genlayerlabs/genswarms-telegram@0.6.2.

Install

# mix.exs of the host app
{:genswarms_telegram, github: "genlayerlabs/genswarms-telegram", tag: "v0.6.2"}

• genswarms is a peer/runtime dependency — the HOST app provides it; the package calls Genswarms.SwarmManager / AgentServer dynamically only when you use session_opts.swarm_name + agent_template.
• Runtime tools for the defaults: curl (Client.Curl), jq + swarm-msg (priv/reply.sh). No Telegram SDK — the default client is shell-native curl and keeps the bot token out of argv (short-lived config/body files).

Minimal wiring (the two objects)

See examples/minimal_bot.swarm.exs for the complete runnable shape:

• :telegram_sender → Genswarms.Telegram.Objects.Sender with bot_token, client: Client.Curl, binding_authority: :telegram_ingress, slot_prefix.
• :telegram_ingress → Genswarms.Telegram.Objects.Ingress with bot_token, client, sender: :telegram_sender, poll_enabled: true, session_opts (swarm_name + agent_template with connections: [:telegram_sender]), and binding_sinks: [:telegram_sender].

Ingress long-polls getUpdates (or takes inject_update from your webhook forwarder — examples/webhook_forwarder.exs), dedupes updates, spawns/binds a per-conversation agent through the session runtime, and delivers the user text.

How an agent replies

The agent NEVER picks a Telegram target. Inside the agent's shell context:

priv/reply.sh "the reply text"

It reads GENSWARMS_TELEGRAM_CONVERSATION_ID + GENSWARMS_TELEGRAM_SENDER_OBJECT from the env the runtime set, and sends via swarm-msg to the sender — with NO target in the payload. The sender resolves the target from the caller's bound slot: ingress binds slot ↔ conversation BEFORE user text is delivered, replies from a bound agent slot go to that conversation only, and an agent-like unbound slot fails closed. Explicit conversation_id targets are honored only from configured sources (send_sources, progress_sources, typing_sources, batch_sources, slot_reply_sources) — add YOUR object there if it must target conversations directly.

Sending from objects (the protocol)

Everything is a JSON action on the sender object. The full vocabulary (~150 actions: media, polls, cards, streaming drafts, inline queries, business accounts, stars/gifts, forum topics, invoices…) is enumerated in README §"Object Protocol"; the ones you reach for first:

• {"action":"send","conversation_id":"tg:123:0","text":"..."}
• {"action":"reply","text":"...","reply_to_message_id":123} (from a bound slot)
• {"action":"progress","text":"..."} — edit-coalesced progress line
• {"action":"stream_text","draft_id":123,"text":"Working..."} — draft streaming
• {"action":"send_card","conversation_id":"tg:123:0","card":{...}} — structured cards; grammar + block types in docs/telegram-cards.md, ready payloads in examples/card_actions.exs; {"action":"validate_card",...} checks one without sending; {"action":"capabilities"} / {"action":"examples"} are self-describing.

conversation_id format is tg:<chat_id>:<thread_id> (ConversationId module).

State, memory, workspaces

• Bot transport state (offsets, dedupe): Store.File under ${XDG_STATE_HOME:-~/.local/state}/genswarms/telegram.
• Slot workspaces are TEMPORARY (${TMPDIR:-/tmp}/genswarms-telegram) — safe to wipe. Durable per-conversation MEMORY.md (Context.MemoryMd) lives in the state dir, keyed by bot fingerprint + conversation; the agent sees a copy at <workspace>/MEMORY.md.
• memory_policy defaults to :none — nothing durable is written unless the host opts in (:dm_only for private chats, :all for groups/topics too).

Testing

Client.Fake is the deterministic test adapter (records Bot API calls, no network) — use it in CI, always. mix deps.get && mix format --check-formatted && mix compile --warnings-as-errors && mix test.

Gotchas

• getUpdates is single-consumer per bot token. A second poller (your laptop vs prod, or live smoke tests in CI) steals updates and the deployed bot goes silent intermittently. Live smoke = disposable credentials, explicit release step, never regular CI.
• "Reply never arrives" → the slot isn't bound (agent spawned outside the ingress flow, or reply sent from a non-slot identity). Binding is the ingress's job (binding_sinks); replies assume the GenSwarms agent slot identity, so priv/reply.sh must run INSIDE the bound agent's context.
• "Object X can't send" → it's not in send_sources (fail-closed by design); configure the source lists instead of routing through an agent.
• Webhook mode — Ingress still owns processing: forward the raw update as {"action":"inject_update","update":{...}} (see examples/webhook_forwarder.exs); Webhook has the decode/registration helpers.
• Rich sends degrade deliberately: parse-error retries as plain text, photo falls back, chunking is rate-limited — don't re-implement retry around the sender.