refactor: refactor via Claude Code with Opus 4.7

Author: outlndrr

.gitignore

@@ -7,4 +7,5 @@ erl_crash.dump
 *.db
 *.db-shm
 *.db-wal
-*.sqlite*
+*.sqlite*
+.claude

CLAUDE.md

@@ -0,0 +1,105 @@
+# lummy_agent
+
+Local-first LLM agent runtime on Gleam/BEAM. See `PLAN.md` for the long-form
+roadmap and `docs/refactors/` for architectural decisions.
+
+## Running
+
+```sh
+gleam run          # start server on http://localhost:4000
+gleam format
+gleam check
+gleam test
+```
+
+On Windows, the C compiler shim for sqlight/mist needs Zig. From bash:
+
+```sh
+bash scripts/with-zig-env.sh gleam test
+```
+
+From `cmd.exe` / PowerShell, use `rebar3.cmd` in the project root.
+
+## House conventions
+
+### Tests
+- Use the `assert` keyword (Gleam 1.11+). **Never** use `should.equal` from
+  gleeunit in new code.
+- Test files live in `test/`, named `lummy_agent_<area>_test.gleam`.
+
+### Actors
+Follow the existing template in `session/session_actor.gleam` and
+`run/run_actor.gleam`:
+
+- `StartArg` record carries construction-time dependencies.
+- `Message` variant carries a `reply_with: process.Subject(Result(..))` on
+  every call; fire-and-forget messages skip it.
+- `State` record is internal.
+- `pub type Handle = process.Subject(Message)` is the external surface.
+- Start with `actor.new_with_initialiser |> actor.on_message |> actor.start`.
+  Do **not** use the older `actor.start(state, loop)` form.
+- Supervise with `static_supervisor.new(OneForOne) |> supervisor.add(...) |> supervisor.start`.
+
+### Transaction-style builders
+When accumulating into a list across many `|>` steps (see `SessionTransaction`
+in `session/session_actor.gleam`), cons onto the head and reverse once at the
+consumer — **never** `list.append(list, [item])` inside a builder chain.
+That's O(n²) over the chain.
+
+### Providers
+New OpenAI-shaped providers go through `provider/openai_style.gleam` as an
+`Adapter` (see `provider/openrouter.gleam` and `provider/openai_compatible.gleam`).
+Only drop to a bespoke provider module when the wire format genuinely differs.
+
+### Domain errors
+Every fallible boundary returns `Result(T, domain_error.DomainError)`. Don't
+reach for `panic` / `let assert` for expected error cases — that's what the
+error taxonomy in `domain/error.gleam` is for.
+
+`let assert` is acceptable only when the failure truly cannot happen (e.g.
+constructing an id from a constant literal whose validator only rejects blanks).
+Add a one-line comment explaining why.
+
+### Debug printing
+Use the `echo` keyword. `io.debug` is deprecated — do not reintroduce it.
+
+### Externals
+Keep `@external` wrappers at the edges (`src/*_ffi.erl`, FFI files in
+`src/lummy_agent/`). Core logic stays in pure Gleam. Any new external needs a
+typed facade and error normalization.
+
+## Map of the repo
+
+```
+src/lummy_agent/
+├── app/          composition root: config loader + root supervisor
+├── domain/       pure types + state machines + validators
+├── storage/      sqlite persistence + codec + migrations
+├── session/      session actor + supervisor + event types
+├── run/          run actor + supervisor
+├── agent/        basic agent loop, planner, prompt builder, memory
+├── provider/     provider contract + openai_style backbone + adapters
+├── tools/        tool registry + runtime + policy
+├── transport/    mist/wisp http server, SSE, JSON encoders
+├── runtime/      clock, event bus, log FFI
+└── (empty dirs)  observability/, policy/, skills/, auth/, crypto/,
+                  rag/, scheduler/, files/ — reserved per PLAN.md
+```
+
+## Known rough edges
+
+- `storage/sqlite.gleam` opens a fresh sqlite connection on every repository
+  call. Planned refactor: hold a pooled/long-lived connection per session
+  actor. Biggest perf lever.
+- `session_actor.gleam` persists a row per streamed chunk. Planned: batch or
+  debounce chunk persistence while keeping live SSE fan-out per-chunk.
+- `session_actor.gleam` (1.7k lines), `tools/runtime.gleam` (1.7k),
+  `transport/http_server.gleam` (1.3k) are candidates for splitting.
+
+## Docs
+
+- `PLAN.md` — product/architecture plan, stage-by-stage.
+- `docs/quickstart.md` — copy-paste API flow.
+- `docs/http-api.md`, `docs/event-stream.md`, `docs/event-log.md` — transport surfaces.
+- `docs/persistence.md`, `docs/session-runtime.md`, `docs/domain-core.md` — internals.
+- `CHANGELOG.md` — per-stage public contract changes.

src/lummy_agent/app/config.gleam

@@ -78,136 +78,66 @@ pub type LoadError {
   DotenvReadFailed(path: String, reason: String)
 }
 
-const default_service_name = "lummy_agent"
-
-const default_environment = "dev"
-
-const default_host = "localhost"
-
-const default_port = 4000
-
-const default_database_path = "lummy_agent.db"
-
 const minimum_secret_key_base_bytes = 64
 
-const default_secret_key_base = "lummy-agent-dev-secret-key-base-00000000000000000000000000000000"
-
-const default_openrouter_api_key = ""
-
-const default_openrouter_base_url = "https://openrouter.ai/api/v1"
-
-const default_openrouter_site_url = "http://localhost"
-
-const default_openrouter_app_name = "lummy_agent"
-
-const default_openrouter_timeout_ms = 30_000
-
-const default_openai_compatible_api_key = ""
-
-const default_openai_compatible_base_url = "https://api.openai.com/v1"
-
-const default_openai_compatible_timeout_ms = 30_000
-
-const default_provider_id = "basic-local"
-
-const default_provider_fallback_ids = []
-
-const default_model_selection = "basic-local"
-
-const default_agent_system_prompt = "You are lummy_agent, a local-first assistant. Be concise, accurate, and use tools when they help answer the user."
-
-const default_agent_context_message_limit = 12
-
-const default_agent_context_summary_chars = 600
-
-const default_agent_context_summary_mode = "model"
-
-const default_agent_context_summary_input_chars = 2400
-
-const default_agent_max_steps = 4
-
-const default_agent_max_total_tokens = 16_000
-
-const default_agent_max_cost_micros = 5_000_000
-
-const default_agent_max_duration_ms = 60_000
-
-const default_agent_tool_timeout_ms = 5000
-
-const default_agent_tool_max_retries = 1
-
-const default_agent_tool_file_root = "."
-
-const default_agent_tool_shell_working_directory = "."
-
-const default_agent_tool_notes_path = ".lummy_agent_notes.md"
-
-const default_agent_allowed_tools = [
-  "calculator",
-  "web_fetch",
-  "web_search",
-  "file_read",
-  "file_write",
-  "shell_command",
-  "notes_memory",
-]
-
-const default_agent_allowed_tool_capabilities = [
-  "math",
-  "filesystem_read",
-  "network",
-  "external_api",
-  "memory",
-]
-
-const default_agent_max_tool_risk = "low"
-
-const default_agent_external_provider_max_tool_risk = "low"
-
 pub fn defaults() -> Config {
   Config(
-    service_name: default_service_name,
-    environment: default_environment,
+    service_name: "lummy_agent",
+    environment: "dev",
     server: ServerConfig(
-      host: default_host,
-      port: default_port,
-      secret_key_base: default_secret_key_base,
+      host: "localhost",
+      port: 4000,
+      secret_key_base: "lummy-agent-dev-secret-key-base-00000000000000000000000000000000",
     ),
-    storage: StorageConfig(database_path: default_database_path),
+    storage: StorageConfig(database_path: "lummy_agent.db"),
     providers: ProviderConfig(
-      default_provider_id: default_provider_id,
-      fallback_ids: default_provider_fallback_ids,
-      default_model_selection: default_model_selection,
-      openrouter_api_key: default_openrouter_api_key,
-      openrouter_base_url: default_openrouter_base_url,
-      openrouter_site_url: default_openrouter_site_url,
-      openrouter_app_name: default_openrouter_app_name,
-      openrouter_timeout_ms: default_openrouter_timeout_ms,
-      openai_compatible_api_key: default_openai_compatible_api_key,
-      openai_compatible_base_url: default_openai_compatible_base_url,
-      openai_compatible_timeout_ms: default_openai_compatible_timeout_ms,
+      default_provider_id: "basic-local",
+      fallback_ids: [],
+      default_model_selection: "basic-local",
+      openrouter_api_key: "",
+      openrouter_base_url: "https://openrouter.ai/api/v1",
+      openrouter_site_url: "http://localhost",
+      openrouter_app_name: "lummy_agent",
+      openrouter_timeout_ms: 30_000,
+      openai_compatible_api_key: "",
+      openai_compatible_base_url: "https://api.openai.com/v1",
+      openai_compatible_timeout_ms: 30_000,
     ),
     agent: AgentConfig(
-      system_prompt: default_agent_system_prompt,
-      context_message_limit: default_agent_context_message_limit,
-      context_summary_chars: default_agent_context_summary_chars,
-      context_summary_mode: default_agent_context_summary_mode,
-      context_summary_input_chars: default_agent_context_summary_input_chars,
-      max_steps: default_agent_max_steps,
-      max_total_tokens: default_agent_max_total_tokens,
-      max_cost_micros: default_agent_max_cost_micros,
-      max_duration_ms: default_agent_max_duration_ms,
+      system_prompt: "You are lummy_agent, a local-first assistant. Be concise, accurate, and use tools when they help answer the user.",
+      context_message_limit: 12,
+      context_summary_chars: 600,
+      context_summary_mode: "model",
+      context_summary_input_chars: 2400,
+      max_steps: 4,
+      max_total_tokens: 16_000,
+      max_cost_micros: 5_000_000,
+      max_duration_ms: 60_000,
     ),
     tools: ToolsConfig(
-      timeout_ms: default_agent_tool_timeout_ms,
-      max_retries: default_agent_tool_max_retries,
-      file_root: default_agent_tool_file_root,
-      shell_working_directory: default_agent_tool_shell_working_directory,
-      notes_path: default_agent_tool_notes_path,
-      allowed_tools: default_agent_allowed_tools,
-      allowed_tool_capabilities: default_agent_allowed_tool_capabilities,
-      max_tool_risk: default_agent_max_tool_risk,
-      external_provider_max_tool_risk: default_agent_external_provider_max_tool_risk,
+      timeout_ms: 5000,
+      max_retries: 1,
+      file_root: ".",
+      shell_working_directory: ".",
+      notes_path: ".lummy_agent_notes.md",
+      allowed_tools: [
+        "calculator",
+        "web_fetch",
+        "web_search",
+        "file_read",
+        "file_write",
+        "shell_command",
+        "notes_memory",
+      ],
+      allowed_tool_capabilities: [
+        "math",
+        "filesystem_read",
+        "network",
+        "external_api",
+        "memory",
+      ],
+      max_tool_risk: "low",
+      external_provider_max_tool_risk: "low",
     ),
   )
 }
@@ -465,19 +395,12 @@ fn csv_list_from_env(
 fn parse_csv_list(value: String) -> List(String) {
   value
   |> string.split(on: ",")
-  |> non_blank_csv_values([])
-}
-
-fn non_blank_csv_values(values: List(String), acc: List(String)) -> List(String) {
-  case values {
-    [] -> list.reverse(acc)
-
-    [value, ..rest] ->
-      case string.trim(value) {
-        "" -> non_blank_csv_values(rest, acc)
-        trimmed -> non_blank_csv_values(rest, [trimmed, ..acc])
-      }
-  }
+  |> list.filter_map(fn(raw) {
+    case string.trim(raw) {
+      "" -> Error(Nil)
+      trimmed -> Ok(trimmed)
+    }
+  })
 }
 
 fn valid_tool_risk(value: String) -> Bool {

src/lummy_agent/run/run_actor.gleam

@@ -566,16 +566,13 @@ fn collect_model_execution(
     |> process.select_map(chunk_subject, ModelChunk)
     |> process.select_map(reply_subject, ModelDone)
 
+  // `chunks` accumulates reversed for O(1) prepend, flipped back on Done.
   case process.selector_receive_forever(selector) {
     ModelChunk(chunk) ->
-      collect_model_execution(
-        list.append(chunks, [chunk]),
-        chunk_subject,
-        reply_subject,
-      )
+      collect_model_execution([chunk, ..chunks], chunk_subject, reply_subject)
 
     ModelDone(Ok(response)) ->
-      Ok(ModelExecution(chunks: chunks, response: response))
+      Ok(ModelExecution(chunks: list.reverse(chunks), response: response))
     ModelDone(Error(error)) -> Error(error)
   }
 }