LemonGateway

Multi-engine execution gateway for Elixir. It sits behind router-owned conversations and handles execution-slot scheduling, per-conversation launch isolation, session resumption, and streaming engine output via the event bus.

Part of the lemon Elixir umbrella project.

Architecture

                        +-----------------------------------------+
                        |   Router / Explicit Legacy Ingress       |
                        | Email  SMS  Voice  Webhook              |
                        +-------------------+---------------------+
                                            |
                               ExecutionCommand
                                            |
                                            v
                        +-------------------+---------------------+
                        |           LemonGateway.Runtime           |
                        |  submit_execution/1 -> ExecutionRequest  |
                        +-------------------+---------------------+
                                            |
                                            v
                        +-------------------+---------------------+
                        |         LemonGateway.Scheduler           |
                        | slot allocation + conversation-key       |
                        | routing from router-supplied requests    |
                        +-------------------+---------------------+
                                            |
                                    slot_granted
                                            |
                                            v
                        +-------------------+---------------------+
                        |       LemonGateway.ThreadWorker          |
                        |   trivial per-conversation launcher      |
                        |   (no queue semantics)                   |
                        +-------------------+---------------------+
                                            |
                                     RunSupervisor
                                     .start_run
                                            |
                                            v
                        +-------------------+---------------------+
                        |          LemonGateway.Run                |
                        |    engine lifecycle, bus events,         |
                        |    streaming deltas, steer/cancel        |
                        +-------------------+---------------------+
                                            |
                                   Engine.start_run
                                            |
                                            v
                        +-------------------+---------------------+
                        |        Engine (behaviour)                |
                        | Lemon | Claude | Codex | Opencode | Pi  |
                        +-------------------+---------------------+
                                            |
                                  events & deltas
                                            |
                                            v
                        +-------------------+---------------------+
                        |          LemonCore.Bus                   |
                        |     topic "run:<run_id>"                 |
                        |   -> LemonRouter -> LemonChannels        |
                        +-----------------------------------------+

Flow

1. Router-owned SessionCoordinator decides queue semantics (collect, followup, steer, interrupt) and hands queue-semantic-free %LemonCore.ExecutionCommand{} values to LemonGateway.Runtime.
2. Gateway-owned transports that still live in this app submit %LemonCore.RunRequest{} through LemonCore.RouterBridge, not directly into gateway internals.
3. The Scheduler routes each execution request by the router-supplied conversation_key and allocates a concurrency slot.
4. The ThreadWorker is only a per-conversation launcher/slot waiter. It does not own product queue semantics.
5. On slot grant, the worker starts a Run via RunSupervisor. The Run acquires EngineLock, resolves the engine, and calls Engine.start_run/3.
6. The Engine executes the AI request and streams lifecycle events and deltas back to the Run process.
7. The Run broadcasts all events to LemonCore.Bus on topic "run:<run_id>". Router and channels consume those events and handle semantic output plus channel rendering.
8. On completion, the Run stores chat state for future auto-resume, releases the engine lock and scheduler slot, and finalizes its lifecycle.

Supported Engines

Engine Abstraction

All engines implement the LemonGateway.Engine behaviour:

• id/0 -- unique lowercase string identifier
• start_run/3 -- starts the AI run, returns {:ok, run_ref, cancel_ctx}
• cancel/1 -- cancels an active run
• supports_steer?/0 -- whether mid-run message injection is supported
• steer/2 -- inject text into an active run (optional callback)
• format_resume/1, extract_resume/1, is_resume_line/1 -- resume token serialization

CLI-based engines (Claude, Codex, Droid, Opencode, Pi) delegate to Engines.CliAdapter, which provides shared logic for subprocess management, event stream consumption, resume token formatting, and cancellation. The lemon engine is not part of this app: it lives in coding_agent as CodingAgent.GatewayEngine and registers itself through EngineRegistry.register/1 at boot.

Engine Selection Priority

1. Resume token engine (from router-resolved auto-resume or explicit resume)
2. Inline directive (/claude, /codex, /lemon, etc. via EngineDirective)
3. Binding default_engine (topic-level, then chat-level)
4. Project default_engine
5. Global default_engine from config (default: "lemon")

Composite engine IDs like "claude:claude-3-opus" are resolved by prefix fallback to "claude".

Transports

Gateway transports implement the LemonGateway.Transport behaviour (id/0, start_link/1). They are registered in TransportRegistry and started under TransportSupervisor only when gateway ingress is explicitly enabled with config :lemon_gateway, gateway_ingress_enabled: true. Telegram, Discord, XMTP and email are owned by the lemon_channels sibling app. Voice and SMS are not registry transports; they are dedicated Twilio support services included in the same explicit ingress startup.

Webhook, SMS, and voice are gateway-owned by design, not pending migration: LemonChannels.Plugin.deliver/1 is fire-and-forget, so it cannot serve webhook's synchronous response, SMS has no reply path at all, and voice needs a live bidirectional session. Email was the one surface that genuinely was a channel, and it moved to lemon_channels in phase 2.4 — LemonChannels.Adapters.Email. See docs/platform/transport-unification.md.

Module Inventory

Core

Scheduling and Run Execution

Gateway action events preserve nested action.detail.result_meta metadata, including safe failure fields such as error_type, timeout_ms, and exit_code, so downstream router and control-plane consumers can classify tool failures without parsing rendered command output.

Engine Layer

Transport Layer

Binding and Legacy Rendering Helpers

Command System

SMS

Voice

Gateway Tools (injected into Lemon engine runs)

Health

Engine Lifecycle

Start

1. Run.init/1 acquires the EngineLock for the session's thread key (or fails fast with :lock_timeout).
2. Run.handle_continue(:start_run) resolves the engine from EngineRegistry, resolves the working directory, and calls engine.start_run(job, opts, self()).
3. The engine returns {:ok, run_ref, cancel_ctx}. For CLI engines, CliAdapter starts a runner subprocess and spawns a linked Task that consumes the runner's event stream. Lemon starts a private SessionRunner GenServer that subscribes to CodingAgent.Session events.

Streaming

• Engines send {:engine_delta, run_ref, text} messages for incremental text output.
• The Run process assigns monotonic sequence numbers, builds Event.Delta structs, and broadcasts them to LemonCore.Bus.
• First-token latency telemetry is emitted on the first delta.

Completion

• Engines send {:engine_event, run_ref, completed_event} when done.
• The Run process stores chat state for auto-resume, emits :run_completed to the bus, finalizes the run in LemonCore.Store, releases the engine lock and scheduler slot, and notifies the worker and meta.notify_pid.
• On context-length overflow errors, the ChatState is automatically cleared so the next run starts fresh.

Steering

• Only the Lemon engine supports steering (supports_steer?/0 returns true).
• Router-owned SessionCoordinator decides whether a submission should be steered, queued, or interrupted before anything reaches the gateway.
• When the active run is already live, the gateway Run only handles the low-level steer attempt by calling engine.steer(cancel_ctx, text).
• Any fallback from :steer / :steer_backlog is router behavior, not gateway queue behavior.

Cancellation

• Runtime.cancel_by_run_id/2 looks up the run in RunRegistry and casts {:cancel, reason} to the run process.
• The Run calls engine.cancel(cancel_ctx), emits a failed completion event, and terminates normally.

Queue Semantics

Queue modes such as :collect, :followup, :steer, :steer_backlog, and :interrupt are router-owned conversation semantics. The gateway no longer decides those modes for execution requests.

Gateway queue configuration only applies to legacy transport/binding compatibility paths that still emit router-facing run requests before SessionCoordinator takes over. Execution submission into the gateway is keyed by router-supplied conversation_key.

Voice Call System

Incoming Call -> Twilio -> Voice.WebhookRouter -> CallSession GenServer
                                                      |
                                               TwilioWebSocket
                                            (mulaw audio frames)
                                                      |
                                               DeepgramClient
                                            (raw audio -> text)
                                                      |
                                               LemonGateway.AI
                                            (LLM chat completion)
                                                      |
                                           ElevenLabs TTS API
                                            (text -> audio)
                                                      |
                                              Twilio <- audio

• RecordingManager starts dual-channel recording via the Twilio REST API when a call connects.
• RecordingDownloader saves recordings as WAV files organized by date (~/.lemon/recordings/<date>/).
• Audio conversion handles PCM-to-mulaw transcoding and MP3/ID3 detection for ElevenLabs responses.

SMS Inbox

1. Twilio sends SMS webhooks to Sms.WebhookServer (validates signatures via TwilioSignature).
2. Sms.Inbox stores messages with extracted verification codes (4-8 digit sequences).
3. Lemon engine runs can use injected tools (sms_wait_for_code, sms_list_messages, sms_claim_message) to interact with the inbox.
4. Messages can be "claimed" to prevent cross-session conflicts.

Binding System

Bindings map transport + chat_id + topic_id to a project, agent, engine, and queue mode:

[[gateway.bindings]]
transport = "telegram"
chat_id = 123456789
topic_id = 42
project = "myproject"
agent_id = "coder"
default_engine = "claude"
queue_mode = "steer"

BindingResolver delegates to LemonCore.BindingResolver and provides:

• resolve_binding/1 -- most specific matching binding
• resolve_engine/3 -- engine with priority cascade
• resolve_cwd/1 -- project root directory
• resolve_agent_id/1 -- agent identifier
• resolve_queue_mode/1 -- queue mode from binding

Configuration

Configuration loads from ~/.lemon/config.toml (the [gateway] section) via LemonCore.GatewayConfig.load/0 and LemonGateway.ConfigLoader.

Core Options

Startup Options

Transport Enable Flags

There is no enable_email gate. The [gateway] email block itself is still meaningful — the channel adapter reads it, so existing relay credentials, sender address and webhook token keep working. Receiving mail now depends on LemonChannels.InboundHttp being enabled and a webhook token being set; see LemonChannels.Adapters.Email.

Discord and email are not gateway transports. If a discord or email module is added to :transports, TransportRegistry ignores it and logs a warning; ownership lives in lemon_channels.

Legacy Queue Options ([gateway.queue])

TOML Example

[gateway]
max_concurrent_runs = 2
default_engine = "lemon"
auto_resume = true
require_engine_lock = true

[gateway.queue]
mode = "followup"
cap = 50
drop = "oldest"

[gateway.telegram]
bot_token = "your-token"
allowed_chat_ids = [123456789]
deny_unbound_chats = true

[gateway.projects.myproject]
root = "/path/to/project"
default_engine = "lemon"

[[gateway.bindings]]
transport = "telegram"
chat_id = 123456789
project = "myproject"
agent_id = "coder"
default_engine = "claude"
queue_mode = "steer"

[gateway.sms]
inbox_number = "+1234567890"
webhook_port = 4045

[gateway.engines.lemon]
enabled = true

[gateway.engines.claude]
enabled = true
cli_path = "/usr/local/bin/claude"

Event Protocol

Engines emit events to the Run process as {:engine_event, run_ref, event} messages where events are plain tagged maps:

Streaming text is sent as {:engine_delta, run_ref, text} with monotonic sequence numbers assigned by the Run process.

The Run re-emits all events to LemonCore.Bus as plain maps on topic "run:<run_id>". Bus event types: :run_started, :run_completed, :delta, :engine_started, :engine_completed, :engine_action.

Health Check

The health endpoint runs on port 4042 (configurable via :health_port or LEMON_GATEWAY_HEALTH_PORT). GET /health returns JSON with built-in checks for:

• Supervisor process liveness
• Scheduler state (in_flight count, waitq length, max slots)
• RunSupervisor active children
• EngineLock process liveness
• XMTP transport status (when enabled)

Custom health checks can be registered via the :health_checks application environment.

Dependencies

Umbrella Apps

External Libraries

Testing

# Run all gateway tests
mix test apps/lemon_gateway

# Run a specific test file
mix test apps/lemon_gateway/test/run_test.exs

# Run with verbose output
mix test apps/lemon_gateway --trace

Tests use async: false by default due to shared GenServer state (Config, Scheduler, EngineRegistry). The test helper sets up an isolated lock directory to avoid collisions with running development instances.