Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Runtime dependencies: `rg` (ripgrep) for `grep`; `python3` only for Code Mode (`

```
src/
├── main.rs # CLI (clap): args, subcommands (models/auth/sessions/daily), launch
├── main.rs # CLI (clap): args, subcommands (models/auth/sessions/daily/gateway/channels), launch
├── models.rs # Message, ToolCall, ToolResult, LlmEvent (serde, the shared vocabulary)
├── config.rs # ~/.limbo/config.toml: every section has defaults; toml_edit rewrites keep comments
├── auth.rs # ~/.limbo/auth.json (0600)
Expand Down Expand Up @@ -50,6 +50,13 @@ src/
├── recent_models.rs # Recently used models for the picker
├── integrations.rs # Herdr + OSC 7501 lifecycle reporting
├── headless.rs # --headless / --json / -p frontends on the same pump
├── conversation.rs # Frontend-neutral Conversation<S: Sink>: job/cancel/steer/slash commands, shared by headless and gateway
├── channels/ # mod.rs (Channel trait, PeerKey, Inbound/OutboundMessage, ChannelCaps), markdown.rs (render/split),
│ # store.rs (~/.limbo/channels: credentials 0600, cursors, gateway lock), telegram.rs (hand-written Bot API),
│ # weixin/ (api.rs iLink protocol, cdn.rs AES-128-ECB media, login.rs QR login)
├── gateway/ # mod.rs (router: dedup, access, one worker per chat; `limbo gateway`/`limbo channels`), access.rs (owners),
│ # sessions.rs (chat → session map), worker.rs (per-chat Conversation), render.rs (AgentEvent → chat messages),
│ # outbox.rs (rate limits, edit coalescing, retries), send_file.rs (tool), service.rs (launchd / systemd)
├── subagents/ # mod.rs (task board), supervisor.rs (scheduler, runners, notices),
│ # tools.rs (plan_tasks/task_*/answer; child: checkpoint/need/ask_main/finish/propose_task),
│ # profiles.rs (agent profiles + <project_facts> scan), policies.rs (read-only/no-edit/
Expand Down Expand Up @@ -110,6 +117,8 @@ Subagents (docs/subagents.md): the main agent's `plan_tasks` creates tasks on th

Daily mode (`limbo daily` / `--daily` / `/daily-mode on|off`, docs/daily-mode.md): a session posture like Code Mode — same loop, a general-assistant system prompt, plus the daily tools; persisted as `SessionMeta.daily_mode`. Memory is a snapshot taken when the agent is built: `USER.md` and `NOTES.md` enter daily prompts only; `memory` writes reach disk at once but the prompt changes only next session (prefix cache stays intact). `/learn` (and the automatic trigger in `learn.rs`) runs a `skill-reviewer` fork subagent whose only write tool is `skill_manage`.

Gateway (`limbo gateway`, docs/gateway.md): one process serves Telegram and personal WeChat (iLink) chats. Each `Channel` adapter long-polls and hands `InboundMessage`s to the router, which drops duplicates, strangers (owners only, per channel) and unaddressed group messages, then sends each chat to its own worker (one `Conversation<ChatSink>` per `PeerKey`, loaded lazily, unloaded after `idle_unload_secs`). A message while busy steers the running turn. `Renderer` turns `AgentEvent`s into `OutItem`s (streamed previews where the channel can edit, tool-progress slot, `ask_user` as numbered choices); the per-chat outbox applies `ChannelCaps` (rate limits, chunking, retries, parking on expired WeChat context). Background events reach the right worker through `background::route(session, tx)`. Chats default to daily posture; `send_file` (provider `channel`) is registered only there. `limbo gateway install` writes a launchd agent (macOS) or systemd user unit (Linux).

## Key Decisions

- tokio everywhere; tools are `async_trait` objects (`Arc<dyn Tool>`), blocking work goes through `spawn_blocking` or child processes
Expand Down
19 changes: 19 additions & 0 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,25 @@ proposals should name modules with these terms.
one `<subagent_updates>` steer item; questions and alerts wake an idle
main agent, results wait until the wave is done.

## Gateway

- **Gateway** — the long-running process (`limbo gateway`) that connects
chat apps to agents (`gateway/`). One per machine (`gateway.lock`).
- **Channel** — one chat platform account (Telegram bot, WeChat iLink
bot) behind the `Channel` trait: receive, send, fetch media, and
`ChannelCaps` (text limit, edit support, Markdown dialect, send rate).
- **Peer** — one chat on one channel (`PeerKey`: channel, account, chat,
thread). Every peer has its own current session and session history.
- **Owner** — a platform user id allowed to talk to the gateway. There
are no guests: everyone else is ignored.
- **Worker** — the task that owns one peer's Conversation, renderer and
outbox.
- **Outbox** — a worker's ordered sender: coalesces edits, respects rate
limits, retries, and parks messages while a WeChat context token is
expired.
- **Provider `channel`** — a capability that reaches the user's chat
(`send_file`).

## Safety

Limbo has no safety fences: file tools are not scoped to the workdir,
Expand Down
49 changes: 49 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,10 @@ regex = "1"
include_dir = "0.7"
sha1_smol = "1"
url = "2"
# chat gateway (WeChat iLink media: AES-128-ECB + MD5; terminal QR code for login)
aes = "0.8"
md-5 = "0.10"
qrcode = { version = "0.14", default-features = false }

[dev-dependencies]
tempfile = "3"
Expand Down
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,17 @@ non-coding work, in its own working directory:

See [docs/daily-mode.md](docs/daily-mode.md).

### From Telegram and WeChat

```bash
limbo channels login telegram --token <BotFather token> # then message the bot once
limbo channels login weixin # scan the QR code with WeChat
limbo gateway install # launchd on macOS, systemd on Linux
```

Each chat gets its own daily-mode session; only the owners recorded at
login can talk to it. See [docs/gateway.md](docs/gateway.md).

### Scriptable

`limbo --headless` gives the same agent as a line-oriented REPL, and
Expand Down Expand Up @@ -305,6 +316,8 @@ Limbo borrows openly from other agents. Thank you to:
self-learning skills
- [`docs/subagents.md`](docs/subagents.md): background subagents, the task
board and how to steer them
- [`docs/gateway.md`](docs/gateway.md): talk to limbo from Telegram and
WeChat; run it as a macOS launchd or Linux systemd service
- [`docs/learning-rust.md`](docs/learning-rust.md): code map and reading
order for learning Rust from this codebase
- [`design/`](design/): RFCs for headless mode, bang commands, and the UI
161 changes: 161 additions & 0 deletions docs/gateway.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
# Gateway: limbo in Telegram and WeChat

`limbo gateway` is a long-running process that lets you talk to limbo from
chat apps. It speaks two channels:

- **Telegram**, through the Bot API (long polling; the client is written by
hand on `reqwest`, no Telegram crate).
- **Personal WeChat**, through Tencent's iLink bot protocol
(`ilinkai.weixin.qq.com`), the same one the official WeChat ClawBot plugin
uses. You log in by scanning a QR code; no phone emulator, no hooking.

Every chat gets its own session, in **daily** posture by default (the
general assistant from [daily-mode.md](daily-mode.md)). Only the **owners**
recorded at login can talk to the gateway; messages from anyone else are
ignored without a reply.

## Quick start

```bash
# 1. Telegram: create a bot with @BotFather, then
limbo channels login telegram --token 123456:ABC...
# and send your bot any private message within 5 minutes: that makes
# you its owner.

# 2. WeChat: show a QR code in the terminal and scan it with WeChat
limbo channels login weixin
# The account that scans is the owner.

limbo channels status # what is configured
limbo gateway # run in the foreground (Ctrl-C stops)
limbo gateway install # or run it as a background service
```

The gateway needs an LLM key like any other limbo run (`limbo auth login`).

## In the chat

Write as you would in the TUI. While a reply is running, a new message
*steers* the running turn; `/queue <text>` waits for it to finish instead.
The usual slash commands work (`/new`, `/compact`, `/model`, `/btw`,
`/daily-mode`, `/help`, …), plus a few chat-only ones:

| Command | What it does |
|---|---|
| `/stop` | interrupt the running turn |
| `/sessions` | list this chat's sessions |
| `/resume <id>` | switch back to an older session of this chat |
| `/status` | session id, model, posture, tokens |

Photos, files and voice messages are downloaded into
`<session dir>/media/<session>/` and attached to your message (images go
inline to vision models). WeChat voice arrives as the server's transcript.
The agent can send files back with the `send_file` tool ("send me the
report as a file").

When the agent asks a multiple-choice question (`ask_user`), Telegram shows
buttons; WeChat shows a numbered list and you answer with the number.

### Differences between the channels

| | Telegram | WeChat |
|---|---|---|
| Streaming | the reply is edited in place as it streams | sent in pieces when each paragraph is done (no editing) |
| Formatting | Markdown rendered as Telegram HTML | plain text |
| Message length | 4096 characters, split above | about 2000 characters, split above |
| Groups | `channels.telegram.groups = "mention"`: reply when mentioned or replied to | private chats only |
| Files | up to 50 MB | through the encrypted CDN |

## Configuration

All settings have defaults; add only what you want to change to
`~/.limbo/config.toml`:

```toml
[gateway]
workdir = "~/limbo-chat" # working directory of chat sessions
posture = "daily" # or "coding"
model = "" # empty = [llm] model
idle_unload_secs = 1800 # drop an idle chat's agent from memory (0 = never)
max_attachment_mb = 20
show_tools = true # tool progress line (Telegram)

[channels.telegram]
enabled = true
owners = [] # extra owner ids, added to those from login
proxy = "" # e.g. "socks5://127.0.0.1:7890" where Telegram is blocked
groups = "mention" # "mention" or "off"

[channels.weixin]
enabled = true
owners = []
```

State lives under `~/.limbo/channels/`:

- `credentials.json` (mode 0600): bot tokens and owners from login;
- `sessions.json`: which session each chat is on, and its history;
- `cursor-*`: long-polling positions, so a restart neither loses nor
repeats messages;
- `gateway.lock`: only one gateway runs per machine;
- `gateway.log`: service output.

`limbo channels logout <telegram|weixin>` removes a channel's credentials.

## Running as a service

`limbo gateway install` registers the gateway with the system's service
manager, using the current binary and any `--config` / `--session-dir`
given, and starts it. `limbo gateway uninstall` stops and removes it.

**macOS** — a launchd user agent, `~/Library/LaunchAgents/dev.limbo.gateway.plist`
(`RunAtLoad`, `KeepAlive`), loaded with `launchctl bootstrap gui/<uid>`
(falling back to `launchctl load -w` on older systems). It runs while you
are logged in. Check it with:

```bash
launchctl print gui/$(id -u)/dev.limbo.gateway
tail -f ~/.limbo/channels/gateway.log
```

**Linux** — a systemd user unit, `~/.config/systemd/user/limbo-gateway.service`,
enabled with `systemctl --user enable --now`. To keep it running after you
log out, run `loginctl enable-linger $USER` once.

```bash
systemctl --user status limbo-gateway
journalctl --user -u limbo-gateway -f
```

The service gets `PATH`, `LANG`, `LIMBO_HOME`, `LIMBO_AUTH_FILE`, the proxy
variables and `SSL_CERT_FILE` from the shell you install it from; reinstall
after changing them.

## Risks and limits

- **WeChat iLink is not a public API.** It is the protocol behind
Tencent's own ClawBot plugin, documented only by that plugin's source.
Tencent can change it or restrict the account at any time. Use an account
you can afford to lose access to the bot feature on.
- WeChat replies need a recent message from you: the server hands out a
per-chat context token that expires. When it expires, the gateway holds
the pending replies and delivers them after your next message.
- When the WeChat login expires (`-14`), the gateway says so in the log;
run `limbo channels login weixin` again.
- Anyone who controls an owner account controls limbo on this machine,
including `bash` in coding posture. Limbo has no sandbox (see the
README's Safety section); keep `posture = "daily"` unless you need more.
- Bot tokens are stored in plain text in `credentials.json` (0600).

## How it fits together

```
Telegram adapter ─┐ ┌─ worker (chat A) ─ Conversation ─ Agent
├─ inbox ─ router ─ dedup ─ owners ─┤
WeChat adapter ──┘ └─ worker (chat B) ─ …
│
Renderer (AgentEvent → OutItem) ─ outbox ─ Channel::send
```

See `AGENTS.md` (Gateway) and `CONTEXT.md` (Gateway glossary) for the
code map.
Loading
Loading