ADR-0024: !<langgraph> command type — thin Kotlin launcher for a Python runtime
Context and Problem Statement
Human-in-the-loop workflows that park mid-graph and resume later (ADR-0023's completion continuations) are a natural fit for LangGraph, whose ecosystem is Python. Homer's executors are Kotlin. We need a command type that lets an agent run a LangGraph graph and resume it through Homer's existing dispatch/continuation machinery, without reimplementing graph execution or durable checkpointing in Kotlin.
Decision Drivers
- Graph execution, checkpointing, and side effects belong in the Python LangGraph runtime, not in Kotlin.
- Resume must flow through the continuation machinery already built in ADR-0023, which re-fires a target agent run carrying the watched process's result.
- The durable checkpoint location is a server-level concern (one store per Homer instance), not something each command should redefine.
- Keep the contract surface (model ↔ schema ↔ AGENT.md) minimal.
Considered Options
- A thin Kotlin launcher that shells out to
python -m homer_langgraphand lets Python own the graph and checkpointer. - A full Kotlin LangGraph reimplementation / JVM port.
- A long-lived Python sidecar process Homer talks to over RPC.
Decision Outcome
Chosen option: thin Kotlin launcher, because it keeps the division of labor clean — Kotlin launches and captures output; Python owns graph execution, side effects, and checkpointing — and reuses the existing command-executor and continuation paths without new infrastructure.
Command.LangGraph runs python -m homer_langgraph run --module <module>, passes the workspace env through (so resume params arriving in env reach the runtime), and injects the durable state directory as HOMER_LG_STATE_DIR, resolved from server config (server.langGraph.stateDir, else derived beside the database path), not from a per-command field. (Amended 2026-10-09 by ADR-0046: the configured directory is now a root, and each run gets <root>/<owner-segment>.)
Two conventions are enforced/established:
dispatch.enabled: trueis required. An agent with a!<langgraph>command resumes through the dispatch/continuation machinery, so it must be dispatchable. This is checked at load time inAgentsService.parseAgentDir; an agent that omits it is rejected and skipped.- Resume re-runs the whole agent from the top. When a parked thread resumes, Homer re-fires the agent run (carrying the thread id in
HMR_LG_THREAD), not just the langgraph step. Earlier commands must be self-contained or guarded withwhen:onHMR_LG_THREADso they don't repeat side effects on resume.
Consequences
- Good: no graph engine or checkpointer in Kotlin; Python owns the hard parts.
- Good: reuses the ADR-0023 continuation path for resume; no new resume protocol.
- Good: one durable state dir per server, consistent with the SQLite store layout. (Amended by ADR-0046: one directory per owner under that root.)
- Bad: introduces a Python runtime dependency on the execution host (shipped in a later commit) — Kotlin alone cannot run a langgraph agent.
- Bad: re-running the whole agent on resume puts the idempotency burden on the author (mitigated by the
HMR_LG_THREADguard convention).
More Information
- ADR-0023 — completion continuations, the resume mechanism this command type relies on.
- ADR-0020 — the durable-store layout the langgraph state dir derives beside.
- Reference docs:
app/AGENT.md(Command.LangGraph) andapp/SERVER.md(server.langGraph.stateDir).