AGENTS.md

1# openclaw-core — OpenClaw Gateway + Reply Daemon (Core)
2 
3**Generated:** 2026-06-16
4 
5## OVERVIEW
6 
7Package: `@oh-my-opencode/openclaw-core`. Harness-neutral Core for OpenClaw bidirectional integration. Outbound dispatch fires HTTP webhooks or shell commands on session events; inbound reply-listener daemon polls Discord/Telegram and injects replies into tracked tmux panes. Consumed by the OpenCode adapter at [`packages/omo-opencode/src/openclaw/`](../omo-opencode/src/openclaw/AGENTS.md) via re-export shims.
8 
9## KEY FILES
10 
11| File | Role |
12|------|------|
13| `src/index.ts` | Barrel: `wakeOpenClaw()`, `initializeOpenClaw()`, `startReplyListener`, `stopReplyListener` |
14| `src/types.ts` | `OpenClawConfig`, `OpenClawPayload`, `WakeResult` |
15| `src/config.ts` | Gateway resolution + reply listener config normalization |
16| `src/dispatcher.ts` | HTTP POST + shell command execution with variable interpolation |
17| `src/runtime-dispatch.ts` | Maps harness events to OpenClaw events; orchestrates dispatch |
18| `src/session-registry.ts` | JSONL registry correlating message IDs to sessions and panes (file-locked) |
19| `src/reply-listener.ts` | Daemon lifecycle barrel (start/stop/poll loop/status/log) |
20| `src/reply-listener-start.ts` | Spawns the daemon as a detached Bun process |
21| `src/reply-listener-poll-loop.ts` | Polls Discord/Telegram every 3s, prunes stale registry entries hourly |
22| `src/reply-listener-injection.ts` | Injects received replies into tmux panes with rate limiting |
23| `src/tmux.ts` | `captureTmuxPane()`, `sendToPane()`, `analyzePaneContent()` |
24| `src/daemon.ts` | Entry point for the detached daemon process |
25 
26## FLOW
27 
28```
29Discord/Telegram API → reply-listener-poll-loop.ts
30  → session-registry.ts: lookup tmux pane by message ID
31  → reply-listener-injection.ts: rate limit check → sanitize → send-keys into pane
32```
33 
34## NOTES
35 
36- URL validation requires HTTPS except localhost (`gateway-url-validation.ts`).
37- Session registry is a file-locked JSONL written via `session-registry-storage.ts`.
38- Daemon state persists to disk via `reply-listener-state.ts` (PID, config signature, poll tracking).
39- Rate limiter defaults to 10 injections per minute per pane.
40- `tmux.ts` pane confidence check skips injection if `analyzePaneContent()` returns below 0.3.
41 
42Parent: [`packages/AGENTS.md`](../AGENTS.md)
43