jsonl-subprocess-runner

JSONL Subprocess Runner Framework

All Untether engine runners (Claude, Codex, OpenCode, Pi) extend JsonlSubprocessRunner, which manages subprocess lifecycle, JSONL parsing, session locking, and error handling.

Key files

File	Purpose
src/untether/runner.py	JsonlSubprocessRunner base class, Runner protocol, SessionLockMixin, ResumeTokenMixin
src/untether/model.py	StartedEvent, ActionEvent, CompletedEvent, ResumeToken, Action, ActionKind
src/untether/events.py	EventFactory — consistent event creation per engine
src/untether/backends.py	EngineBackend dataclass, EngineConfig
src/untether/progress.py	ProgressTracker — aggregates actions for UI rendering
src/untether/runner_bridge.py	ProgressEdits, handle_message — connects runners to transport
src/untether/runners/	Engine-specific runner implementations

Class hierarchy

Runner (Protocol)
  BaseRunner (SessionLockMixin)
    JsonlSubprocessRunner
      CodexRunner
      OpenCodeRunner
      PiRunner
      ClaudeRunner (overrides run_impl for PTY support)

Template methods to override

When creating a new runner, override these methods on JsonlSubprocessRunner:

class MyRunner(JsonlSubprocessRunner):
    engine: EngineId = "myengine"

    def command(self) -> str:
        """CLI binary name (e.g. 'codex', 'opencode', 'pi')."""

    def build_args(self, prompt, resume, *, state) -> list[str]:
        """Build CLI arguments. Called once per run."""

    def translate(self, data, *, state, resume, found_session) -> list[UntetherEvent]:
        """Translate a decoded JSON dict to Untether events. Core logic."""

    def new_state(self, prompt, resume) -> Any:
        """Create per-run state (e.g. EventFactory, accumulators)."""

    # Optional overrides:
    def stdin_payload(self, prompt, resume, *, state) -> bytes | None:
        """Data to send on stdin. Default: prompt.encode()."""

    def env(self, *, state) -> dict[str, str] | None:
        """Extra environment variables for the subprocess."""

    def decode_jsonl(self, *, line: bytes) -> Any | None:
        """Custom JSON decoder. Default: json.loads."""