Core decision
+One normalized contract
++ Adapters expose an incoming stream and a discrete send effect. The gateway adds + authorization, routing, and a derived outgoing-stream consumer. +
+
+ 01
+ Implementation plan
+ /
+ apps/server/src/gateway
+
+
+
+
+
+ + Effect-native chat gateway +
++ A small, reusable boundary for adapter-qualified channels, finished messages, + local-file attachments, and resilient inbound streams—starting with a complete + Telegram Bot API polling adapter. +
+-
+
- Runtime +
- Effect v4 +
- Transport +
- Polling +
- First adapter +
- Telegram +
- Message mode +
- Finished only +
+
+
+
+
+
+
+
+ Access model
+Qualified channel IDs
+
+ telegram:<chat-id> is the
+ adapter-independent authorization key. Optional topic/thread identity stays separate.
+
Files
+Paths at the boundary
+
+ Outbound attachments reference local paths. Inbound media is downloaded before emission
+ and points into ~/.compass/files.
+
+
+
+
+ 01 / Boundary
+Public API shape
+
+
+
+
+ + Gateway.incoming + : Stream<IncomingMessage, GatewayError> +
++ Gateway.send(message) + : Effect<SentMessage, GatewayError> +
++ Gateway.sendAll(outgoing, options?) + : Stream<SentMessage, GatewayError | E, + R> +
+
+ send is the reliable primitive: one
+ finished message produces one delivery result or one typed failure.
+ sendAll is the stream-oriented
+ convenience requested by callers and uses explicit, bounded concurrency. It does not
+ silently detach fibers or swallow delivery errors.
+
+
+
+
+ Normalized message
+-
+
- Stable adapter message ID +
- Qualified channel plus optional thread +
- Sender identity and received timestamp +
- Optional text and zero-or-more files +
+
+ Attachment metadata
+-
+
- Absolute local path +
- Safe display filename +
- Optional media type and byte size +
- Kind: image, audio, video, or file +
+
+
+
+ 02 / Architecture
+Layers and ownership
+
+
+
+
+
+
+ Application
+Incoming consumer
+Outgoing message stream
+⇄
+
+
+ Gateway
+Authorize + route
+Merge adapter streams
+⇄
+
+
+ Adapter
+Telegram polling
+Bot API + file transfer
+
+
+
+
+ GatewayConfig
+Schema-decodes gateway.json
+
+
+ GatewayFiles
+Safe durable file writes
+
+
+ HttpClient
+Injected Bot API transport
++ The adapter contract contains no Telegram types. Each adapter supplies a stable name, + an incoming stream, and a send implementation. A scoped Telegram layer owns the + long-poll lifecycle, so closing the parent scope interrupts in-flight HTTP and retry + delays cleanly. +
+
+
+
+
+ 03 / Configuration
++ Non-secret, strict, predictable +
+
+
+ {
+ "version": 1,
+ "allowedChannels": [
+ "telegram:123456789",
+ "telegram:-100987654321"
+ ],
+ "adapters": {
+ "telegram": {
+ "pollingTimeoutSeconds": 30,
+ "pollingLimit": 100,
+ "maxInboundFileBytes": 52428800,
+ "deleteWebhook": true,
+ "dropPendingUpdates": false
+ }
+ }
+}
+
+
+ The default path is resolved portably from
+ HOME or
+ USERPROFILE. Missing or invalid
+ configuration fails layer construction with a typed configuration error.
+
+ The bot token remains outside the JSON file and is read through Effect Config from
+ TELEGRAM_BOT_TOKEN. An optional API
+ base URL may be injected for deterministic tests.
+
+ Authorization is exact-match and deny-by-default. Topics inherit their Telegram + chat’s qualified channel authorization; the optional thread identifier only controls + reply placement. +
+
+
+
+
+ 04 / Telegram
+Polling and media flows
+
+
+
+
+
+
+ Incoming
+-
+
-
+ 01Long-poll
+
getUpdateswith the current + offset. +
+ - + 02Advance offset monotonically for + every observed update. + +
- + 03Normalize message/channel/sender data + and select the largest photo rendition. + +
-
+ 04Resolve each attachment using
+
getFileand enforce its size + limit. +
+ -
+ 05Stream it into an atomic write under
+
~/.compass/fileswithout buffering + the full download. +
+ - + 06Emit only when the qualified channel + is allowed. + +
Outgoing
+-
+
- + 01Validate the destination and every + local attachment path. + +
- + 02Route by the channel’s adapter + prefix. + +
-
+ 03Use
+
sendMessage, +sendPhoto, +sendAudio, +sendVoice, or +sendDocument. +
+ - + 04Use text as a caption where + supported; otherwise send text separately. + +
- + 05Return normalized Telegram delivery + identifiers. + +
+ Poll failures retry with a capped exponential Effect
+
+ Schedule and structured logs.
+ Successful polls reset backoff. Telegram API envelopes and update payloads are
+ schema-decoded; malformed individual updates are logged and skipped without killing
+ the adapter stream. Authentication/configuration failures remain terminal.
+
+
+
+
+ 05 / Files
+Proposed module tree
+
+
+ apps/server/src/gateway/
+├── Gateway.ts # service, routing, authorization, stream helpers
+├── GatewayConfig.ts # gateway.json schema + default filesystem layer
+├── GatewayFiles.ts # inbound persistence + outbound path reads
+├── Models.ts # branded IDs, messages, attachments, errors
+├── Adapter.ts # platform-neutral adapter contract
+├── index.ts # public exports
+├── Gateway.test.ts
+├── GatewayConfig.test.ts
+├── GatewayFiles.test.ts
+└── adapters/
+ └── telegram/
+ ├── TelegramAdapter.ts # Effect service/layer + normalization + sending
+ ├── TelegramApi.ts # typed Bot API HttpClient boundary
+ ├── TelegramModels.ts # only the Bot API schemas needed here
+ ├── TelegramAdapter.test.ts
+ └── index.ts
+
+
+
+ 06 / Execution
+Implementation sequence
+-
+
-
+ 01
+ ++
Model the domain
++ Define Schema-based messages, qualified channel IDs, attachments, delivery + receipts, adapter contract, and tagged error families. +
+
+ -
+ 02
+ ++
Build configuration and file services
++ Decode gateway.json, resolve Compass paths, create the files directory, sanitize + filenames, and write downloads atomically. +
+
+ -
+ 03
+ ++
Implement the Telegram API boundary
++ Use Effect HttpClient and Schema for getMe, deleteWebhook, getUpdates, getFile, + downloads, JSON requests, and multipart uploads. +
+
+ -
+ 04
+ ++
Implement scoped polling
++ Create a lazy incoming stream, track offset, normalize supported messages, persist + attachments, and make interruption immediate and leak-free. +
+
+ -
+ 05
+ ++
Compose the gateway
++ Merge adapter streams, enforce allowlisting in both directions, route sends, and + expose bounded outgoing-stream processing. +
+
+ -
+ 06
+ ++
Test and publish
++ Exercise config, authorization, ordering, retry, interruption, media + download/upload, then run repository readiness and typecheck gates. +
+
+
+
+
+
+ 07 / Validation
+Acceptance matrix
+
+
+
+
+
+ | Area | +Proof | +Expected outcome | +
|---|---|---|
| Authorization | +Allowed and denied channel tests | +Exact-match, deny-by-default | +
| Polling | +Scripted getUpdates responses | ++ Offsets advance; duplicates are avoided + | +
| Resilience | +Transient failures + test clock | +Capped backoff and recovery | +
| Shutdown | +Scoped stream interruption | +Active long poll is cancelled | +
| Inbound files | +Photo, audio, voice, document fixtures | +Safe files exist before emission | +
| Outbound files | +Multipart request inspection | +Correct Bot API method and caption | +
| Repository | +
+ vp run ready vp run typecheck + |
+ Both commands pass | +
+
+
+
+ + 08 / Deliberate limits +
+Not in this slice
+
+
+
+ No token/message streaming or edit-in-place responses.
+
+
+ No mentions, reactions, commands, buttons, or webhook server.
+
+
+ No remote-URL or in-memory outbound attachment source.
+
+
+ No history, subscriptions, distributed state, or Chat SDK compatibility layer.
+
+