Crate scx_forge_agent 

scx-forge-agent: an LLM-driven optimizer for sched_ext schedulers.

Hybrid loop: deterministic code owns build/validate/keep-revert/stop; the LLM is called only to propose one coherent policy experiment per round (and to fix build errors). The reward function is the built-in validation harness (validate.rs). The target scheduler is whatever [scheduler].package in the spec names (any scheds/rust/<name> crate); the agent modifies that crate in place. See tools/scx_forge_agent/README.md.

Modules

agent_cli 🔒

Subprocess backends: drive a round’s edits by shelling out to the claude, opencode, codex, or cursor-agent CLI in non-interactive mode, run with the scheduler crate directory as the cwd so the CLI’s own tools edit the files in place. The controller then builds/validates the resulting diff exactly as it does for the built-in openai backend, so keep/revert/dedup work unchanged.

api 🔒

OpenAI-compatible /chat/completions client with a tool-calling loop.

color 🔒

Minimal ANSI coloring for live terminal progress.

config 🔒

Model configuration from the spec and SCX_FORGE_* environment variables, and the backend the agent uses to drive edits.

git 🔒

In-place checkpoint/revert for the optimization loop, using the git index.

http 🔒

HTTP client for an OpenAI-compatible inference endpoint: large request bodies and long server think times.

interrupt 🔒

model_timeout 🔒

progress 🔒

TTY-only progress spinners for local blocking phases.

report 🔒

Optimization run report: per-round history table, markdown and JSON renderers.

spec 🔒

Validation spec model (parsed from the TOML the agent points the harness at).

sudo 🔒

Resolve how the harness gains root to load the scheduler, and build the privileged commands. Ported from the Python harness’s setup_sudo.

tools 🔒

Sandboxed tools exposed to the model as OpenAI function calls. Target-crate tools (read_file, list_dir, grep, optional rg, web_fetch, and gated edit_file) resolve paths relative to the scheduler crate or public URLs; comparison tools read other schedulers under scheds/rust but never write them. Host-topology tools run fixed read-only commands or read fixed sysfs CPU cache metadata paths. Absolute paths and .. are rejected, and canonicalized targets must stay inside their configured roots.

usage 🔒

Token-usage accounting summed across the whole optimization run, plus the one-line footer (prompt:24.3k tokens:515) printed at the bottom of the output. The footer shape mirrors boro’s progress UI.

validate 🔒

Native validation harness: the agent’s reward function.

Structs

ActiveModelPrinter 🔒

AttemptTags 🔒

OptimizeArgs 🔒

OptimizeOutcome 🔒

Enums

Phase 🔒

Two stages of the optimization: tune the scheduler’s existing configuration knobs first, then propose new mechanisms. The model drives the transition by emitting the completion sentinel; both phases share the [ai].rounds budget.

Constants

KNOB_MD 🔒

KNOB_PHASE_DONE_SENTINEL 🔒

Sentinel a knob-phase planner emits when no untested knob value looks promising any more, telling the controller to move on to code changes.

OPTIMIZER_MD 🔒

SKILL_MD 🔒

The resource markdown files are embedded at compile time so prompt edits stay close to the domain text instead of the Rust control flow.

Functions

agent_dim 🔒

agent_error 🔒

agent_info 🔒

agent_log 🔒

agent_success 🔒

agent_warn 🔒

append_attempt_summary 🔒

attempt_memory_for_prompt 🔒

attempt_summary_line 🔒

base_system 🔒

bpf_const_volatile_initializer_name 🔒

bpf_const_volatile_initializer_only_vars 🔒

build_keep_running_scheduler 🔒

build_with_fix_loop 🔒

cargo_build 🔒

Build the scheduler crate. Returns Err(combined output) on failure.

cargo_build_with_progress 🔒

cargo_program 🔒

classify_attempt 🔒

classify_policy_area 🔒

coding_system_prompt 🔒

configure_sudo_from_spec 🔒

contains_any 🔒

diff_file_path 🔒

direction_stopword 🔒

edit_prompt 🔒

The coder is handed exactly the planner’s plan - nothing else. Build-fix and runtime-fix rounds have no plan, so they fall back to the round context plus the failure to repair.

expand_glob_path 🔒

expand_sudo_password_file 🔒

history_table 🔒

home_dir 🔒

ineffective_round_edit_reason 🔒

ineffective_round_note 🔒

install_ctrl_c_handler 🔒

interrupted_requested 🔒

knob_edit_prompt 🔒

Knob-phase coder prompt. With a planner plan (openai backend) it just asks the coder to apply that one-line default change. Without a plan (subprocess backends, which have no separate planner) it carries the round context plus the knob inventory so the coder can pick and apply a knob itself.

knob_inventory 🔒

Assemble the scheduler-agnostic knob inventory the knob-phase model tunes from: the binary’s --help (every option, its default, and - for enums - its possible values, rendered by clap). This needs no per-scheduler hand-maintenance, works for any scheds/rust/<package> crate, and can never go stale relative to the options the scheduler actually exposes.

knob_phase_complete 🔒

True if a knob-phase planner reply signals the knob space is exhausted.

knob_planner_prompt 🔒

Knob-phase planner prompt: the round context plus an instruction to pick one option to retune (or end the phase). The available options live in the knob-phase system prompt, not here.

knob_system_prompt 🔒

System prompt for the KNOB-TUNING phase: the model picks one existing option per round and changes its default to a single untested value, or signals the phase is done. It never writes new logic here.

main 🔒

model_backend_label 🔒

Backend label for the model footer: just the backend name for the subprocess CLIs, and openai @ <base_url> for the built-in HTTP backend so the endpoint is visible.

model_display_name 🔒

normalize_attempt_summary 🔒

normalize_diff 🔒

Normalize a git diff for dedup: drop the index <hash>..<hash> lines whose blob hashes are noise, so two textually identical changes compare equal.

normalized_improvement 🔒

optimize 🔒

optimize_loop 🔒

planner_plan_rejection_reason 🔒

planner_prompt 🔒

planner_recovery_note 🔒

planner_system_prompt 🔒

prefix_at_char_boundary 🔒

print_final_report 🔒

read_attempt_memory 🔒

record_interrupted_round 🔒

record_model_timeout_round 🔒

resolve_repo_root 🔒

round_context_prompt 🔒

round_record 🔒

run_attempt_summary 🔒

run_coding_turn 🔒

scheduler_help_text 🔒

Capture the scheduler’s --help output so the planner can see which CLI options (knobs) already exist. This is the always-current, zero-maintenance source of truth for what the sweep has tuned - no hand-kept signatures. Returns None if the binary is missing or errors.

should_try_runtime_fix 🔒

spec_sudo_password_file 🔒

start_keep_running_scheduler 🔒

suffix_at_char_boundary 🔒

validation_failure_feedback 🔒