AGENTS.md

1# src/openclaw/ — Bidirectional External Integration
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7This module provides a bidirectional integration system: **outbound** session event notifications (Discord/Telegram/HTTP webhook/shell command) AND **inbound** reply handling (daemon polls chat apps, injects replies back into tmux session). Harness-neutral gateway, daemon, session registry, and tmux injection primitives are extracted to [`packages/openclaw-core/`](../../../../packages/openclaw-core); this directory keeps OpenCode startup/event wiring stable.
8 
9## BIDIRECTIONAL FLOW
10 
11### Outbound (OpenCode → External)
12```
13OpenCode session event → dispatchOpenClawEvent()
14  → runtime-dispatch.ts: map event to OpenClaw event
15  → dispatcher.ts: execute gateway (HTTP POST or shell command)
16  → session-registry.ts: record message ID ↔ sessionID ↔ tmux pane
17```
18 
19### Inbound (External → OpenCode)
20```
21Discord/Telegram API → reply-listener daemon (separate Bun process)
22  → reply-listener-{discord,telegram}.ts: poll every 3s
23  → session-registry.ts: look up target tmux session from message ID
24  → reply-listener-injection.ts: send-keys into tmux pane (rate limited)
25```
26 
27## KEY FILES
28 
29| File | Purpose |
30|------|---------|
31| `index.ts` | `wakeOpenClaw()`, `initializeOpenClaw()` — main entry |
32| `types.ts` | `OpenClawConfig`, `OpenClawPayload`, `WakeResult` types |
33| `config.ts` | Gateway resolution + URL validation (HTTPS required, localhost exception) |
34| `dispatcher.ts` | HTTP POST + shell command execution with variable interpolation |
35| `runtime-dispatch.ts` | Maps OpenCode events → OpenClaw events, orchestrates dispatch |
36| `session-registry.ts` | JSONL registry correlating message IDs ↔ sessions ↔ panes (file-locked) |
37| `reply-listener.ts` | Daemon lifecycle: start/stop, poll loop, state persistence |
38| `reply-listener-discord.ts` | Discord API polling |
39| `reply-listener-telegram.ts` | Telegram API polling |
40| `reply-listener-injection.ts` | Inject received reply into tmux pane (rate limiting + user filtering) |
41| `reply-listener-state.ts` | Daemon state: PID, config signature, poll tracking |
42| `daemon.ts` | Daemon entry point (runs as detached Bun process) |
43| `tmux.ts` | `capturePane()`, `sendToPane()` utilities |
44 
45## GATEWAY TYPES
46 
47| Type | Config | Execution |
48|------|--------|-----------|
49| **HTTP webhook** | `url` field | POST with JSON payload |
50| **Shell command** | `command` field | Execute with env vars (OPENCLAW_*) |
51 
52## PAYLOAD VARIABLES (interpolation)
53 
54`{sessionId}`, `{projectPath}`, `{tmuxSession}`, `{timestamp}`, `{eventType}` (session.created/deleted/idle), `{messageContent}`, `{promptSummary}`
55 
56## INTEGRATION POINTS
57 
58- `src/index.ts` — calls `initializeOpenClaw(pluginConfig.openclaw)` at plugin startup (if `enabled`)
59- `src/plugin/event.ts` — calls `dispatchOpenClawEvent()` for session.created/deleted/idle
60- `src/config/schema/openclaw.ts` — Zod config schema
61 
62## DAEMON LIFECYCLE
63 
64```
65initializeOpenClaw(config)
66  → wakeOpenClaw() if reply_listener.enabled
67  → spawn daemon.ts as detached process
68  → daemon writes PID to .opencode/openclaw.state.json
69  → daemon polls Discord/Telegram every 3s
70  → on reply: lookup in session-registry → inject into tmux via send-keys
71```
72 
73## SECURITY
74 
75- **URL validation**: HTTPS required except localhost (config.ts)
76- **Authorized users**: Inbound replies filtered by allowed user ID list
77- **Token redaction**: Secrets masked in logs and error messages
78- **Rate limiting**: Reply injection throttled per pane
79