Strix (STRIX) — core

docs / modules / core

← all docs

Strix (STRIX) — core

flowchart LR IN["IN: scan_config,\ntarget local_sources"] --> ACT["ACT: build coordinator,\nsandbox, root agent,\nrun the turn loop"] ACT --> VAL["VAL: lifecycle-tool\nstop condition\n(finish_scan/agent_finish)"] VAL --> OUT["OUT: final RunResult\n+ live agent-graph state"]

What this is

strix/core is the multi-agent orchestration engine — the part of Strix that turns "here's a target" into a running tree of AI agents, keeps them coordinated, and knows when a scan is actually done. If strix/agents builds one agent and strix/tools gives it things to call, core is what decides how many agents exist at once, who's talking to whom, and what happens when one of them finishes, crashes, or runs out of budget.

What flows through it

flowchart TD Runner["runner.py\nrun_strix_scan()"] --> Coord["agents.py\nAgentCoordinator"] Runner --> Exec["execution.py\nrun_agent_loop()"] Exec -- "create_agent tool call" --> Exec2["execution.py\nspawn_child_agent()"] Exec2 --> Coord Coord -- "mailbox message" --> Exec Exec -- "budget/turn checks" --> Hooks["hooks.py\nReportUsageHooks"]

Technical details

flowchart LR IN["IN: scan_config,\ntarget local_sources"] --> ACT["ACT: build coordinator,\nsandbox, root agent,\nrun the turn loop"] ACT --> VAL["VAL: lifecycle-tool\nstop condition\n(finish_scan/agent_finish)"] VAL --> OUT["OUT: final RunResult\n+ live agent-graph state"]

Package: strix/core/ Depends on: strix.agents (build_strix_agent, make_child_factory), strix.config (settings, model routing), strix.runtime (sandbox session), strix.report (global report state), strix.tools.output_store (spill writer). Depended on by: strix.interface (both cli.py and the TUI runtime call run_strix_scan), strix.tools.agents_graph (calls back into spawn_child_agent via an injected context closure).

Files at a glance

File Role
runner.py run_strix_scan() — the single top-level entry point every mode (headless CLI, interactive TUI) funnels into.
agents.py AgentCoordinator — sole owner of agent-graph state: statuses, parent/child tree, mailboxes, resume snapshots.
execution.py run_agent_loop() (per-agent turn driver), spawn_child_agent()/respawn_subagents() (child lifecycle).
hooks.py ReportUsageHooks, BudgetExceededError — budget and turn-limit enforcement, wired into every Runner cycle.
inputs.py build_root_task(), build_scope_context(), child_initial_input(), make_model_settings() — assembles the initial prompt/context each agent starts with.
sessions.py open_agent_session() — opens the per-agent SQLite session backing the SDK's conversation state.
paths.py run_dir_for(), runtime_state_dir() — resolves strix_runs/<run>/ and its internal state directory.

Files & functions, explained

runner.py - run_strix_scan(*, scan_config, scan_id, image, local_sources, coordinator, interactive, max_turns, max_budget_usd, model, ...) — brings up the sandbox, builds and registers the root agent, runs its loop to completion, and tears down the sandbox in a finally block regardless of outcome (clean finish, budget stop, crash, or KeyboardInterrupt). - _merge_root_prompt_context() / _compose_root_instructions_override() — merge platform-injected scope metadata into the root agent's prompt without letting caller-supplied overrides weaken the system-verified authorization scope.

agents.py - AgentCoordinator.register/send/consume_pending/wait_for_message — the mailbox primitives. - AgentCoordinator.restore/_maybe_snapshot — resume support: atomic JSON snapshot of the entire graph, including undelivered mailbox messages. - AgentCoordinator.trigger_budget_stop/pause_for_budget/resume_from_budget_pause — budget-exhaustion handling that can wake every parked agent at once.

execution.py - run_agent_loop() — turn-by-turn driver described in full in design/LLD.md. - spawn_child_agent() — builds and registers a child, launches its loop as a detached asyncio.Task (children run in parallel with siblings and the parent). - respawn_subagents() — the resume-from-snapshot path; re-creates runner tasks for every non-root agent, parking any that were mid-wait when the process died.

hooks.py - ReportUsageHooks — an SDK RunHooks implementation tracking LLM cost/turns per call and raising BudgetExceededError once max_budget_usd is exceeded. - recomputed_budget_flags() — used on resume to re-derive budget-stop state against a (possibly changed) max_budget_usd.

Related: STRIX — Architecture (HLD), ../design/LLD.md, agents.md, tools.md.