Strix (STRIX) — Low-Level Design

docs / design / LLD

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:

  1. Registers/attaches an AgentRuntime (SDK session + interrupt_on_message flag) with the AgentCoordinator.
  2. Checks global budget/reserve flags up front — raises BudgetExceededError or SubagentBudgetReservedError immediately if already tripped, before spending a turn.
  3. Calls _run_until_lifecycle(), which loops _run_cycle() — each cycle is one Runner.run_streamed(agent, input=..., run_config=..., context=..., session=..., hooks=...) call from the OpenAI Agents SDK, streaming events out to event_sink (the CLI/TUI's live-render hook).
  4. A turn only ends the loop if it calls a lifecycle tool — finish_scan, agent_finish, respond_to_user (interactive), or wait_for_agents (parking). This is enforced by _finish_tool_use_behavior, the SDK's tool_use_behavior hook set in agents/factory.py; only these four tool calls set is_final_output=True.
  5. 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) or max_turns (autonomous) before _exhausted_recovery() either parks the agent or raises MaxTurnsExceeded and marks it crashed.
  6. For root/interactive agents, after the first cycle settles, an outer while True loop blocks on coordinator.wait_for_message(agent_id, timeout=...) (the agent's wake asyncio.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.