LemonRouter

lemon_router owns request normalization, conversation identity, queue semantics, and semantic output tracking. It sits between channel transports and lemon_gateway.

Current Flow

Channel transport or gateway-native ingress
  -> LemonRouter.Router.handle_inbound/1
  -> LemonRouter.RunOrchestrator
  -> LemonRouter.SessionCoordinator
  -> LemonRouter.RunProcess
  -> configured LemonCore.EngineRuntime.submit_execution/1
  -> gateway runtime scheduler / thread worker / run
  -> LemonCore.Bus run events
  -> LemonRouter semantic coalescers / output tracking
  -> LemonCore.DeliveryIntent
  -> LemonChannels.Dispatcher
  -> channel-specific renderer / outbox

Ownership

• Router owns:
  • RunRequest normalization
  • policy, model, and engine resolution
  • resume resolution and conversation-key selection
  • queue semantics: collect, followup, steer, steer_backlog, interrupt
  • pending-compaction prompt rewriting
  • semantic stream and tool-status coalescing
• Router does not own:
  • Telegram or Discord rendering details
  • OutboundPayload construction
  • Telegram message-id presentation state
  • gateway slot scheduling or engine lifecycle

Key Modules

SurfaceManager.finalize_answer/3 dispatches :stream_finalize first for runs that already streamed answer deltas, then finalizes StreamCoalescer state so late flushes cannot overwrite the final. For non-streamed completions it still finalizes through StreamCoalescer, with a direct :final_text fallback if the coalescer finalize call exits or times out. Completion-time artifact metadata enrichment is best-effort and must not block the final answer path. RunProcess.ArtifactTracker also supports Hermes-style final-answer media directives: a line containing MEDIA:<project-relative-path> is converted into an explicit auto_send_files entry after existing-file, cwd, and symlink escape checks pass. The directive line is removed from the final text before channel rendering, and Telegram/Discord delivery still goes through the normal attachment policy.

Important Contracts

• Inbound callers should provide structured resume data through LemonCore.RunRequest.resume when they already know it.
• Engine ID validation and normalization should use LemonCore.EngineCatalog; default cwd resolution should use LemonCore.Cwd.
• Router emits LemonCore.DeliveryIntent, not LemonChannels.OutboundPayload.
• Tool-status failure summaries preserve safe structured fields from action.detail.result_meta, including error_type, tool name, timeout, command exit code, exception class/name, status, reason, message, and validation errors.
• Cron/channel-origin summary delivery may cross router through the internal LemonRouter.ChannelsDelivery bridge, but the bridge must stay narrow. Router must not construct LemonChannels.OutboundPayload; LemonChannels remains responsible for enqueue semantics, retries, chunking, and adapter delivery.
• Runtime input is LemonCore.ExecutionCommand; gateway-private adapters may translate it to LemonGateway.ExecutionRequest.
• Telegram-specific state is owned by lemon_channels wrappers:
  • LemonChannels.Telegram.StateStore
  • LemonChannels.Telegram.ResumeIndexStore
• External apps must query busy/active session state through LemonRouter.Router or LemonCore.RouterBridge, not router-internal read-model or registry details.

Session And Queue Semantics

SessionCoordinator serializes by conversation key:

• {:resume, engine, token} when a structured resume token is available
• {:session, session_key} otherwise

Queue-mode behavior lives here:

• :collect appends
• :followup debounces/merges recent followups, except async task/delegated followups which stay separate
• :steer attempts in-run steer and falls back to followup
• :steer_backlog attempts in-run steer and falls back to collect
• active async task/delegated auto-followups are promoted to :steer so completions try to reach the live parent run before falling back to a queued followup
• :interrupt cancels the active run and inserts the new request at the front

Output Semantics

Router coalescers only track semantic state:

• accumulated text
• sequence numbers
• semantic tool/action state
• run/session metadata needed for DeliveryIntent

Channels decides:

• send vs edit
• truncation
• reply markup
• media batching
• Telegram resume indexing by platform message id

Testing

Run the app suite from the umbrella root:

mix test apps/lemon_router

Useful focused suites during refactors:

mix test apps/lemon_router/test/lemon_router/router_test.exs
mix test apps/lemon_router/test/lemon_router/run_orchestrator_test.exs
mix test apps/lemon_router/test/lemon_router/session_coordinator_test.exs
mix test apps/lemon_router/test/lemon_router/run_process_test.exs
mix test apps/lemon_router/test/lemon_router/stream_coalescer_test.exs
mix test apps/lemon_router/test/lemon_router/tool_status_coalescer_test.exs

Run architecture checks after boundary changes:

mix lemon.quality