feat(ui): add live SSE debug console

- Replace snapshot polling with session SSE for live chunks
- Log run, tool, and SSE lifecycle for troubleshooting
- Load .env via glenvy for local config
- Fix OpenRouter stream setup and web_search header parsing

Author: outlndrr

.gitignore

@@ -1,6 +1,10 @@
 build
+ui/build
+.env
 *.ez
 erl_crash.dump
 *.log
 *.db
+*.db-shm
+*.db-wal
 *.sqlite*

README.md

@@ -58,6 +58,16 @@ Health check:
 curl http://localhost:4000/health
 ```
 
+Optional: create `.env` in project root. Runtime loads it at startup via `glenvy` before config parsing. Real process env still wins over `.env` values.
+
+Example:
+
+```env
+LUMMY_OPENROUTER_API_KEY=your_key_here
+LUMMY_DEFAULT_PROVIDER_ID=openrouter
+LUMMY_DEFAULT_MODEL_SELECTION=openai/gpt-4o-mini
+```
+
 ## Quickstart
 
 Copy-paste flow:
@@ -137,6 +147,33 @@ curl -X POST http://localhost:4000/api/v1/providers/openrouter/verify \
   -d '{"model":"openai/gpt-4o-mini","prompt":"Say hello in five words."}'
 ```
 
+## Simple Lustre UI
+
+UI source lives in `ui/` and is served by backend at `GET /ui`.
+
+Build client once:
+
+```sh
+cd ui
+gleam build
+cd ..
+```
+
+Then run server and open:
+
+```sh
+gleam run
+# browse http://localhost:4000/ui
+```
+
+Notes:
+- UI currently targets `openrouter` only
+- UI talks to same-origin backend routes, so no CORS setup needed
+- backend still requires `LUMMY_OPENROUTER_API_KEY`
+- UI opens live session SSE stream at `/api/v1/sessions/:id/events`
+- UI includes debug pane for HTTP actions, SSE status, and streamed events
+- backend now logs request + run/provider/tool lifecycle to Erlang logger
+
 ## Config
 
 | Variable | Default | Notes |

docs/http-api.md

@@ -10,6 +10,7 @@ Copy-paste examples live in `docs/quickstart.md`.
 - `GET /`
 - `GET /health`
 - `GET /ready`
+- `GET /ui`
 - `POST /api/v1/providers/openrouter/verify`
 
 ### Session API
@@ -63,6 +64,7 @@ Copy-paste examples live in `docs/quickstart.md`.
 ## Current limitations
 - no websocket API yet
 - no session list endpoint yet
+- simple Lustre UI exists at `GET /ui`, consumes session SSE directly, and shows a debug pane for live events
 - OpenRouter verify route exists for live configuration checks
 - OpenRouter assistant streaming now flows through persisted `run.chunk` events
 - provider/model execution for agent runs is delegated through `RunActor`

gleam.toml

@@ -26,6 +26,7 @@ simplifile = ">= 2.4.0 and < 3.0.0"
 filepath = ">= 1.1.2 and < 2.0.0"
 exception = ">= 2.1.0 and < 3.0.0"
 sqlight = ">= 1.0.3 and < 2.0.0"
+glenvy = ">= 2.0.1 and < 3.0.0"
 
 [dev_dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

@@ -12,15 +12,20 @@ packages = [
   { name = "gleam_http", version = "4.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_http", source = "hex", outer_checksum = "82EA6A717C842456188C190AFB372665EA56CE13D8559BF3B1DD9E40F619EE0C" },
   { name = "gleam_json", version = "3.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "44FDAA8847BE8FC48CA7A1C089706BD54BADCC4C45B237A992EDDF9F2CDB2836" },
   { name = "gleam_otp", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "BA6A294E295E428EC1562DC1C11EA7530DCB981E8359134BEABC8493B7B2258E" },
+  { name = "gleam_regexp", version = "1.1.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_regexp", source = "hex", outer_checksum = "9C215C6CA84A5B35BB934A9B61A9A306EC743153BE2B0425A0D032E477B062A9" },
   { name = "gleam_stdlib", version = "0.71.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "702F3BC2A14793906880B1078B19A6165F87323AEE8D0C4A34085846336FCAAE" },
+  { name = "gleam_yielder", version = "1.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_yielder", source = "hex", outer_checksum = "8E4E4ECFA7982859F430C57F549200C7749823C106759F4A19A78AEA6687717A" },
   { name = "gleeunit", version = "1.9.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "DA9553CE58B67924B3C631F96FE3370C49EB6D6DC6B384EC4862CC4AAA718F3C" },
+  { name = "glenvy", version = "2.0.1", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib", "nibble", "simplifile"], otp_app = "glenvy", source = "hex", outer_checksum = "A954C46D079ABE2D0A31CF36F1EB99371BE38E5F85BF821A8C90B77022852CC6" },
   { name = "glisten", version = "9.0.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_otp", "gleam_stdlib", "logging"], otp_app = "glisten", source = "hex", outer_checksum = "D92808C66F7D3F22F2289CD04CBA8151757AAE9CB3D86992F0C6DE32A41205E1" },
   { name = "gramps", version = "6.0.0", build_tools = ["gleam"], requirements = ["gleam_crypto", "gleam_erlang", "gleam_http", "gleam_stdlib"], otp_app = "gramps", source = "hex", outer_checksum = "8B7195978FBFD30B43DF791A8A272041B81E45D245314D7A41FC57237AA882A0" },
   { name = "houdini", version = "1.2.0", build_tools = ["gleam"], requirements = [], otp_app = "houdini", source = "hex", outer_checksum = "5DB1053F1AF828049C2B206D4403C18970ABEF5C18671CA3C2D2ED0DD64F6385" },
   { name = "hpack_erl", version = "0.3.0", build_tools = ["rebar3"], requirements = [], otp_app = "hpack", source = "hex", outer_checksum = "D6137D7079169D8C485C6962DFE261AF5B9EF60FBC557344511C1E65E3D95FB0" },
+  { name = "iv", version = "1.4.1", build_tools = ["gleam"], requirements = ["gleam_stdlib", "gleam_yielder"], otp_app = "iv", source = "hex", outer_checksum = "607B4B118FF77C5D985CFAB0D33B7A171F14AF5924314B4AB77AA725DC66D515" },
   { name = "logging", version = "1.5.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "logging", source = "hex", outer_checksum = "BC5F18CE5DD9686100229FE5409BDC3DD5C46D5A7DF2F804AD2D8F0DD6C5060E" },
   { name = "marceau", version = "1.3.0", build_tools = ["gleam"], requirements = [], otp_app = "marceau", source = "hex", outer_checksum = "2D1C27504BEF45005F5DFB18591F8610FB4BFA91744878210BDC464412EC44E9" },
   { name = "mist", version = "6.0.2", build_tools = ["gleam"], requirements = ["exception", "gleam_erlang", "gleam_http", "gleam_otp", "gleam_stdlib", "glisten", "gramps", "hpack_erl", "logging"], otp_app = "mist", source = "hex", outer_checksum = "6B03DEEA38A02F276333CB27B53B16D3D45BD741B89599085A601BAF635F2006" },
+  { name = "nibble", version = "1.1.4", build_tools = ["gleam"], requirements = ["gleam_regexp", "gleam_stdlib", "iv"], otp_app = "nibble", source = "hex", outer_checksum = "06397501730FF486AE6F99299982A33F5EA9F8945B5A25920C82C8F924CEA481" },
   { name = "platform", version = "1.0.0", build_tools = ["gleam"], requirements = [], otp_app = "platform", source = "hex", outer_checksum = "8339420A95AD89AAC0F82F4C3DB8DD401041742D6C3F46132A8739F6AEB75391" },
   { name = "simplifile", version = "2.4.0", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "7C18AFA4FED0B4CE1FA5B0B4BAC1FA1744427054EA993565F6F3F82E5453170D" },
   { name = "sqlight", version = "1.0.3", build_tools = ["gleam"], requirements = ["esqlite", "gleam_stdlib"], otp_app = "sqlight", source = "hex", outer_checksum = "CADD79663C9B61D4BAC960A47CC2D42CA8F48EAF5804DBEB79977287750F4B16" },
@@ -37,6 +42,7 @@ gleam_json = { version = ">= 3.1.0 and < 4.0.0" }
 gleam_otp = { version = ">= 1.2.0 and < 2.0.0" }
 gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
 gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
+glenvy = { version = ">= 2.0.1 and < 3.0.0" }
 mist = { version = ">= 6.0.2 and < 7.0.0" }
 simplifile = { version = ">= 2.4.0 and < 3.0.0" }
 sqlight = { version = ">= 1.0.3 and < 2.0.0" }

src/lummy_agent/app/config.gleam

@@ -4,6 +4,8 @@ import gleam/int
 import gleam/list
 import gleam/result
 import gleam/string
+import glenvy/dotenv
+import simplifile
 
 pub type ServerConfig {
   ServerConfig(host: String, port: Int, secret_key_base: String)
@@ -73,6 +75,7 @@ pub type LoadError {
   InvalidInteger(name: String, value: String)
   BlankValue(name: String)
   SecretKeyBaseTooShort(minimum: Int, actual: Int)
+  DotenvReadFailed(path: String, reason: String)
 }
 
 const default_service_name = "lummy_agent"
@@ -210,8 +213,27 @@ pub fn defaults() -> Config {
 }
 
 pub fn load() -> Result(Config, LoadError) {
-  envoy.all()
-  |> from_env
+  {
+    use env <- result.try(merge_dotenv_into_env(".env", envoy.all()))
+    from_env(env)
+  }
+}
+
+@internal
+pub fn merge_dotenv_into_env(
+  path: String,
+  env: Dict(String, String),
+) -> Result(Dict(String, String), LoadError) {
+  case dotenv.read_from(path) {
+    Ok(dotenv_env) -> Ok(dict.merge(dotenv_env, env))
+    Error(dotenv.Io(simplifile.Enoent)) -> Ok(env)
+
+    Error(dotenv.Io(error)) ->
+      Error(DotenvReadFailed(
+        path: path,
+        reason: simplifile.describe_error(error),
+      ))
+  }
 }
 
 pub fn from_env(env: Dict(String, String)) -> Result(Config, LoadError) {
@@ -560,5 +582,8 @@ pub fn render_error(error: LoadError) -> String {
       <> int.to_string(minimum)
       <> " bytes, got "
       <> int.to_string(actual)
+
+    DotenvReadFailed(path, reason) ->
+      "failed to read dotenv file " <> path <> ": " <> reason
   }
 }

src/lummy_agent/run/run_actor.gleam

@@ -1,4 +1,5 @@
 import gleam/erlang/process
+import gleam/int
 import gleam/list
 import gleam/option.{type Option, None, Some}
 import gleam/otp/actor
@@ -11,6 +12,7 @@ import lummy_agent/domain/run as domain_run
 import lummy_agent/domain/tool_call as domain_tool_call
 import lummy_agent/provider/provider
 import lummy_agent/provider/registry
+import lummy_agent/runtime/log as runtime_log
 import lummy_agent/storage/repository
 
 pub type StartArg {
@@ -590,6 +592,11 @@ fn start_model_execution(
   use _ <- result.try(ensure_run_ready_for_model_call(state.run))
   use _ <- result.try(ensure_no_active_model_execution(state))
   use selected_providers <- result.try(select_providers(state.config, state.run))
+  runtime_log.info("run_actor", "model_execute_start", [
+    #("run_id", domain_id.run_id_value(state.run.run_id)),
+    #("model", state.run.model_selection),
+    #("providers", provider_candidate_ids(selected_providers)),
+  ])
 
   let self = state.self
   let worker =
@@ -649,6 +656,10 @@ fn handle_model_worker_chunk(
 ) -> State {
   case state.active_model_execution {
     Some(execution) if execution.worker == worker -> {
+      runtime_log.info("run_actor", "model_chunk", [
+        #("run_id", domain_id.run_id_value(state.run.run_id)),
+        #("chunk", log_text(chunk)),
+      ])
       process.send(execution.chunk_subject, chunk)
       state
     }
@@ -664,6 +675,7 @@ fn handle_model_worker_done(
 ) -> State {
   case state.active_model_execution {
     Some(execution) if execution.worker == worker -> {
+      log_model_done(state.run.run_id, result)
       process.send(execution.reply_with, result)
       State(..state, active_model_execution: None)
     }
@@ -779,6 +791,11 @@ fn start_tool_call_impl(
   use _ <- result.try(ensure_tool_call_belongs_to_run(state.run, tool_call))
   use _ <- result.try(ensure_run_not_terminal(state.run))
   use tool_call <- result.try(domain_tool_call.start(tool_call, started_at))
+  runtime_log.info("run_actor", "tool_call_start", [
+    #("run_id", domain_id.run_id_value(state.run.run_id)),
+    #("tool_call_id", domain_id.tool_call_id_value(tool_call.tool_call_id)),
+    #("tool_name", tool_call.tool_name),
+  ])
   use tool_call <- result.try(repository.insert_tool_call(
     state.repositories.tool_calls,
     tool_call,
@@ -804,6 +821,10 @@ fn succeed_tool_call_impl(
     state.repositories.tool_calls,
     tool_call,
   ))
+  runtime_log.info("run_actor", "tool_call_succeed", [
+    #("run_id", domain_id.run_id_value(state.run.run_id)),
+    #("tool_call_id", domain_id.tool_call_id_value(tool_call.tool_call_id)),
+  ])
   let state =
     State(..state, tool_calls: replace_tool_call(state.tool_calls, tool_call))
   Ok(#(state, tool_call))
@@ -821,6 +842,11 @@ fn fail_tool_call_impl(
     state.repositories.tool_calls,
     tool_call,
   ))
+  runtime_log.warn("run_actor", "tool_call_fail", [
+    #("run_id", domain_id.run_id_value(state.run.run_id)),
+    #("tool_call_id", domain_id.tool_call_id_value(tool_call.tool_call_id)),
+    #("error_code", reason.code),
+  ])
   let state =
     State(..state, tool_calls: replace_tool_call(state.tool_calls, tool_call))
   Ok(#(state, tool_call))
@@ -841,6 +867,10 @@ fn complete_run(
     )
   use run <- result.try(domain_run.complete(state.run, ended_at, usage))
   use run <- result.try(repository.update_run(state.repositories.runs, run))
+  runtime_log.info("run_actor", "run_complete", [
+    #("run_id", domain_id.run_id_value(run.run_id)),
+    #("total_tokens", int.to_string(usage.total_tokens)),
+  ])
   Ok(State(..state, run: run))
 }
 
@@ -859,6 +889,10 @@ fn fail_run(
     )
   use run <- result.try(domain_run.fail(state.run, ended_at, reason))
   use run <- result.try(repository.update_run(state.repositories.runs, run))
+  runtime_log.error("run_actor", "run_fail", [
+    #("run_id", domain_id.run_id_value(run.run_id)),
+    #("error_code", reason.code),
+  ])
   Ok(State(..state, run: run))
 }
 
@@ -876,6 +910,9 @@ fn cancel_run(
     )
   use run <- result.try(domain_run.cancel(state.run, ended_at))
   use run <- result.try(repository.update_run(state.repositories.runs, run))
+  runtime_log.warn("run_actor", "run_cancel", [
+    #("run_id", domain_id.run_id_value(run.run_id)),
+  ])
   Ok(State(..state, run: run))
 }
 
@@ -907,7 +944,11 @@ fn stream_with_fallback(
 
     [candidate, ..rest] -> {
       let chunk_markers = process.new_subject()
-      let registry.CandidateProvider(_, selected_provider) = candidate
+      let registry.CandidateProvider(provider_id, selected_provider) = candidate
+      runtime_log.info("run_actor", "model_stream_attempt", [
+        #("provider_id", provider_id),
+        #("remaining_fallbacks", int.to_string(list.length(rest))),
+      ])
       let result =
         provider.stream(selected_provider, request, cancel_subject, fn(chunk) {
           process.send(chunk_markers, Nil)
@@ -924,8 +965,15 @@ fn stream_with_fallback(
             rest
           {
             True, _, _ -> Error(error)
-            _, True, [_, ..] ->
+
+            _, True, [_, ..] -> {
+              runtime_log.warn("run_actor", "model_stream_fallback", [
+                #("provider_id", provider_id),
+                #("error_code", error.code),
+              ])
               stream_with_fallback(rest, request, cancel_subject, self, worker)
+            }
+
             _, _, _ -> Error(error)
           }
       }
@@ -1064,3 +1112,46 @@ fn render_error(error: domain_error.DomainError) -> String {
   <> string.inspect(error.class)
   <> ")"
 }
+
+fn provider_candidate_ids(
+  candidates: List(registry.CandidateProvider),
+) -> String {
+  candidates
+  |> list.map(fn(candidate) {
+    let registry.CandidateProvider(provider_id, _) = candidate
+    provider_id
+  })
+  |> string.join(with: ",")
+}
+
+fn log_model_done(
+  run_id: domain_id.RunId,
+  result: Result(provider.CompletionResponse, domain_error.DomainError),
+) -> Nil {
+  case result {
+    Ok(response) ->
+      runtime_log.info("run_actor", "model_done", [
+        #("run_id", domain_id.run_id_value(run_id)),
+        #("output", response_output_name(response)),
+      ])
+
+    Error(error) ->
+      runtime_log.error("run_actor", "model_error", [
+        #("run_id", domain_id.run_id_value(run_id)),
+        #("error_code", error.code),
+      ])
+  }
+}
+
+fn response_output_name(response: provider.CompletionResponse) -> String {
+  case response.output {
+    provider.AssistantText(_) -> "assistant"
+    provider.RequestTool(tool_name, _) -> "tool:" <> tool_name
+  }
+}
+
+fn log_text(value: String) -> String {
+  value
+  |> string.replace(each: "\r", with: "\\r")
+  |> string.replace(each: "\n", with: "\\n")
+}