AGENTS.md

1# src/cli/run/ — Non-Interactive Session Launcher
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
737 files. Powers the `oh-my-opencode run <message>` command. Connects to OpenCode server, creates/resumes sessions, streams events, and polls for completion.
8 
9## EXECUTION FLOW
10 
11```
12runner.ts
13  1. opencode-binary-resolver.ts → Find OpenCode binary
14  2. server-connection.ts → Connect to OpenCode server (start if needed)
15  3. agent-resolver.ts → Flag → env → config → Sisyphus
16  4. session-resolver.ts → Create new or resume existing session
17  5. events.ts → Stream SSE events from session
18  6. event-handlers.ts → Process each event type
19  7. poll-for-completion.ts → Wait for todos + background tasks done
20  8. on-complete-hook.ts → Execute user-defined completion hook
21```
22 
23## KEY FILES
24 
25| File | Purpose |
26|------|---------|
27| `runner.ts` | Main orchestration — connects, resolves, runs, completes |
28| `server-connection.ts` | Start OpenCode server process, create SDK client |
29| `agent-resolver.ts` | Resolve agent: `--agent` flag → `OPENCODE_AGENT` env → config → Sisyphus |
30| `session-resolver.ts` | Create new session or resume via `--attach` / `--session-id` |
31| `events.ts` | SSE event stream subscription |
32| `event-handlers.ts` | Route events to handlers (message, tool, error, idle) |
33| `event-stream-processor.ts` | Process event stream with filtering and buffering |
34| `poll-for-completion.ts` | Poll session until todos complete + no background tasks |
35| `completion.ts` | Determine if session is truly done |
36| `continuation-state.ts` | Persist state for `run` continuation across invocations |
37| `output-renderer.ts` | Format session output for terminal |
38| `json-output.ts` | JSON output mode (`--json` flag) |
39| `types.ts` | `RunOptions`, `RunResult`, `RunContext`, event payload types |
40 
41## AGENT RESOLUTION PRIORITY
42 
43```
441. --agent CLI flag
452. OPENCODE_AGENT environment variable
463. default_run_agent config
474. "sisyphus" (default)
48```
49 
50## COMPLETION DETECTION
51 
52Poll-based with two conditions:
531. All todos marked completed (no pending/in_progress)
542. No running background tasks
55 
56`on-complete-hook.ts` executes optional user command on completion (e.g., `--on-complete "notify-send done"`).
57