Skip to content

Commit 43fea10

Browse files
Kasper JungeRalphify
authored andcommitted
docs: fix stale SESSION_KWARGS references in codebase map
The constant was renamed from _SESSION_KWARGS to SESSION_KWARGS and moved from _agent.py to _output.py in a recent refactor, but the codebase map still pointed contributors to the old name and location. Co-authored-by: Ralphify <noreply@ralphify.co>
1 parent 976d0f5 commit 43fea10

File tree

1 file changed

+8
-3
lines changed

1 file changed

+8
-3
lines changed

docs/contributing/codebase-map.md

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ src/ralphify/ # All source code
2929
├── _frontmatter.py # Parse YAML frontmatter from RALPH.md, marker constants
3030
├── _console_emitter.py # Rich console renderer for run-loop events (ConsoleEmitter)
3131
├── _events.py # Event types, emitter protocol, and BoundEmitter convenience wrapper
32-
├── _output.py # ProcessResult base class, combine stdout+stderr, format durations
32+
├── _keypress.py # Cross-platform single-keypress listener (powers the `p` peek toggle)
33+
├── _output.py # ProcessResult base class, subprocess constants (SESSION_KWARGS, SUBPROCESS_TEXT_KWARGS), format durations
3334
└── _brand.py # Brand color constants shared across CLI and console rendering
3435
3536
tests/ # Pytest tests — one test file per module
@@ -130,6 +131,10 @@ Add it in `cli.py`. The CLI uses Typer. Update `docs/cli.md` to document the new
130131

131132
Events are defined in `_events.py:EventType`, with a corresponding TypedDict payload class for each type. Adding a new event type requires a new `EventType` member, a new TypedDict payload class, adding it to the `EventData` union, and handling it in `ConsoleEmitter` (`_console_emitter.py`).
132133

134+
### Live agent output (peek)
135+
136+
Both execution paths in `_agent.py` accept an `on_output_line(line, stream)` callback and drain the agent's stdout/stderr line-by-line — the blocking path uses two background reader threads, and the streaming path forwards each raw line from `_read_agent_stream`. The engine wires this callback to emit `EventType.AGENT_OUTPUT_LINE` events, which the `ConsoleEmitter` renders only while peek is enabled. The `p` keybinding flips that state via `ConsoleEmitter.toggle_peek()`, driven by `KeypressListener` in `_keypress.py`. The listener only activates on a real TTY; in CI or when stdin is piped it silently no-ops.
137+
133138
### Credit trailer
134139

135140
When `credit` is `true` (the default), `engine.py:_assemble_prompt()` appends `_CREDIT_INSTRUCTION` to the prompt — a short instruction telling the agent to include a `Co-authored-by: Ralphify` trailer in git commits. Users can opt out with `credit: false` in frontmatter.
@@ -140,14 +145,14 @@ When `credit` is `true` (the default), `engine.py:_assemble_prompt()` appends `_
140145

141146
### If you change shutdown or signal handling...
142147

143-
Agent subprocesses run in their own process group (`start_new_session=True` on POSIX, configured via `_SESSION_KWARGS` in `_agent.py`). This lets `_kill_process_group()` send signals to the agent and all its children at once.
148+
Agent subprocesses run in their own process group (`start_new_session=True` on POSIX, configured via `SESSION_KWARGS` in `_output.py`). This lets `_kill_process_group()` send signals to the agent and all its children at once.
144149

145150
The two-stage Ctrl+C flow:
146151

147152
1. **First Ctrl+C** — the engine's SIGINT handler sets `RunState.stop_requested`, which lets the current iteration finish gracefully.
148153
2. **Second Ctrl+C**`KeyboardInterrupt` propagates normally and the agent process is killed.
149154

150-
Timeout and cancellation both use a two-step kill: SIGTERM first, then SIGKILL after `_SIGTERM_GRACE_PERIOD` seconds (3s). If you add a new subprocess wrapper, use `_kill_process_group()` and `_SESSION_KWARGS` to get consistent cleanup behavior.
155+
Timeout and cancellation both use a two-step kill: SIGTERM first, then SIGKILL after `_SIGTERM_GRACE_PERIOD` seconds (3s). If you add a new subprocess wrapper, use `_kill_process_group()` and `SESSION_KWARGS` to get consistent cleanup behavior.
151156

152157
### Command parsing
153158

0 commit comments

Comments
 (0)