Strix — Low-Level Design (LLD)
Technical audience: implementers, code reviewers. Cross-cutting internals not
covered at the HLD's component level. Every function/class named here was verified
against the actual source (strix/ at commit 8ca0c4a9).
Agent turn loop, in detail
core/execution.py:run_agent_loop() is called once per agent (root or child) and:
- Registers/attaches an
AgentRuntime(SDK session +interrupt_on_messageflag) with theAgentCoordinator. - Checks global budget/reserve flags up front — raises
BudgetExceededErrororSubagentBudgetReservedErrorimmediately if already tripped, before spending a turn. - Calls
_run_until_lifecycle(), which loops_run_cycle()— each cycle is oneRunner.run_streamed(agent, input=..., run_config=..., context=..., session=..., hooks=...)call from the OpenAI Agents SDK, streaming events out toevent_sink(the CLI/TUI's live-render hook). - A turn only ends the loop if it calls a lifecycle tool —
finish_scan,agent_finish,respond_to_user(interactive), orwait_for_agents(parking). This is enforced by_finish_tool_use_behavior, the SDK'stool_use_behaviorhook set inagents/factory.py; only these four tool calls setis_final_output=True. - A turn that ends on plain text with no lifecycle call is not accepted:
coordinator.record_recovery()fires and a "you must call a tool" nudge is re-injected (_append_tool_required_message), up to_INTERACTIVE_TOOL_RECOVERY_LIMIT=3(interactive) ormax_turns(autonomous) before_exhausted_recovery()either parks the agent or raisesMaxTurnsExceededand marks itcrashed. - For root/interactive agents, after the first cycle settles, an outer
while Trueloop blocks oncoordinator.wait_for_message(agent_id, timeout=...)(the agent'swakeasyncio.Event) — a bounded auto-resume timeout only applies when the agent is parked specifically waiting on other agents (capped at_MAX_IDLE_AUTO_RESUMES=3), otherwise it waits indefinitely for a mailbox message or a user reply.
Spawning and merging children
create_agent (a tool in tools/agents_graph/tools.py) calls
context["spawn_child_agent"] — a closure runner.py builds around
core.execution.spawn_child_agent(). That function generates a child_id, invokes
the captured child_agent_builder factory (from agents.factory.make_child_factory())
to construct a non-root SandboxAgent (identical tool list minus finish_scan, plus
agent_finish), registers it with the coordinator (parent_id set), opens a
dedicated SQLite session (open_agent_session), and launches run_agent_loop() as a
detached asyncio.Task — the parent's turn returns immediately; it does not block
on the child. A parent typically fans out several create_agent calls before calling
the blocking wait_for_agents tool.
Merging back is asynchronous and message-based, not a return value. When a child
finishes, agent_finish() renders a structured completion report
(_render_completion_report: status, task, summary, findings, recommendations) and
calls coordinator.send() to append it to the parent's mailbox, then sets its own
status to completed. notify_parent_on_terminal() is a backstop: any terminal
status (completed/crashed/failed/stopped) that hasn't already sent a report gets a
synthesized notice sent instead, guarded by a one-shot claim_parent_notice latch —
so a parent can never be left waiting on a report a crashed child never sent.
Resume semantics
AgentCoordinator._maybe_snapshot() periodically writes the entire coordinator state
(status, parent/child tree, metadata, queued mailbox contents) atomically to
agents.json (temp-file-then-replace). strix --resume <run> re-enters
run_strix_scan() with is_resume=True: it reads agents.json, requires the SDK
session database (agents.db) to exist, calls coordinator.restore(snap), recomputes
budget-stop flags against the current max_budget_usd, finds the root agent (the one
with parent=None), and calls respawn_subagents() — which re-creates a runner task
for every non-root agent in the snapshot, either continuing (running) or immediately
parking (start_parked=True, waiting on its restored mailbox) for agents that were
mid-wait when the process died. A --resume with a new --instruction is injected as
a fresh user-role message into the root's SDK session rather than passed as
initial_input (which is [] on resume — the SDK replays history from agents.db).
Tool result size control
Every tool call's result is wrapped by _with_bounded_result (agents/factory.py),
which routes through tools/output_store.py:bound_and_store() /bound_text().
Output is capped by both line count and byte count (ContextSettings); anything over
the cap is truncated with a head/tail preview, and — if a SpillWriter is configured
(configure_spill_writer, wired in runner.py to write into the sandbox's
/workspace/.strix-spill/ directory) — the full, untruncated text is written to
disk so nothing is silently lost, only kept out of the model's context window.
Argument coercion
_with_coerced_arguments (agents/factory.py) wraps every FunctionTool to repair
a common model mistake: handing a JSON-shaped argument as a string instead of a
parsed object. This is applied uniformly rather than per-tool, so no individual tool
implementation needs its own defensive parsing.
Deduplication judgment
report/dedupe.py:check_duplicate(candidate, existing) is an LLM call, not a
hash or embedding comparison. It builds a dedicated (optionally distinct, via
DedupeSettings) model call with a system prompt instructing the model to judge "same
root cause on the same asset," not textual similarity, and parses a structured
is_duplicate / duplicate_id / confidence / reason response. A separate fast
path, _check_dependency_duplicate, exists for dependency/CVE-style findings, where
identity (package + version + CVE id) is checked directly without an LLM call — the
one place duplicate detection is deterministic.
Provider-specific model behavior
config/models.py centralizes several provider quirks so the rest of the codebase
doesn't special-case them: uses_chat_completions_tool_schema() decides whether a
model must be downgraded from the SDK's native Responses-API custom-tool schema to
plain chat-completions function tools (this is threaded all the way into
agents/factory.py's tool assembly); is_claude_model / is_bedrock_route /
model_supports_reasoning gate whether reasoning-effort parameters and
required-tool-choice forcing apply. Three custom Model wrapper classes exist for
edge cases: _CodexResponsesModel (OpenAI Codex/ChatGPT-subscription auth flow,
strix auth login chatgpt), _NonStreamingModel (fallback for providers that reject
streaming), and _TurnGuardModel (a defensive per-turn wrapper, working alongside
config/tool_call_limits.py).
What was not independently verified
strix/report/sarif.py (1,051 lines) and the Go TUI internals
(interface/tui/internal/{app,render,protocol}) were reviewed at the level of
directory/file structure and top-level docstrings, not verified line-by-line against
every SARIF field mapping or every TUI rendering path. Treat exact SARIF schema
details and TUI keybindings as needing a source check before being asserted as fact
in a downstream document.
Related: STRIX — Architecture (HLD), HLD.md, data-flow.md.