1. ScienceAgent composition
core/agent/agent.py is the composition point for a shared agent used by REPL sessions, data preparation, and LNR workers. Behavior is divided by responsibility rather than duplicated across solver modes.
| Area | Current responsibility |
|---|---|
runtime/run_loop.py | LLM/tool rounds, auto-continue policy, text-only retry, and completion. |
runtime/llm_stream.py | Streaming, retry, repetition detection, and usage tracing. |
runtime/recovery.py | Tool, edit, and runtime-error recovery. |
runtime/lnr_hooks.py | Stage, resource observer, memory, and ESTRA integration points. |
tool_exec/ | Single, sequential, parallel bash, and parallel read-only tool scheduling. |
run_control/embedded_fullrun.py | Optional embedded full-run handling and unified final-candidate evaluation. |
memory/ | Tool-memory compression, reasoning replay, and resource-feedback folding. |
io/ | Human-readable interaction logs and logging policy. |
2. Tool collection
core/tools/tool_collection.py builds the tool surface. The default agent can receive bash, read, grep, glob, and ls, with optional write, edit, skill, and resource_wait.
| Tool | Role | Controls |
|---|---|---|
bash | Run code, training, evaluation, and file-changing commands. | Sandbox and path guards, timeout, output shaping, command classification, process tracking, resource observation. |
read/grep/glob/ls | Inspect workspace and permitted read-only roots. | PathGuard, result caps, overlap protection, and parallel read-only scheduling. |
write/edit | Legacy structured file changes when the tool preset enables them. | Snapshots, syntax-oriented feedback, size limits, and edit diagnostics. |
skill | List and read Markdown skills from a loaded registry. | Mode/category filtering, visibility limit, aliases, and priority. |
resource_wait | Wait on a resource-runtime token until an unlock condition changes. | Only available when the observer supplies a valid wait state. |
3. Bash as an observed execution surface
core/tools/bash_tool.py is more than a shell wrapper. It classifies commands, normalizes selected package-install invocations, registers long jobs with the resource observer, streams compact interaction logs, parses SCIENCEFLOW_HB heartbeats and metric history, detects artifact updates, enforces visible GPU boundaries, and returns bounded feedback.
Supporting code is split into core/tools/bash/guards.py, output.py, signals.py, progress_signals.py, and spawn_feedback.py. Resource value judgments do not belong in the tool facade; they are made by the task-local resource runtime.
4. Context hygiene
- Sliding-window projection prioritizes task and recent execution context.
- Tool output is capped, deduplicated, summarized, or stored as an artifact reference.
- Repeated resource feedback is folded by capability state rather than appended as a live summary stream.
- File snapshots can remain latest-only in the model-visible memory.
- LNR may trigger context-hygiene compaction after stage count, code churn, repeated large files, low cache efficiency, or large tool output.
5. Workspace protection
Path guards constrain file tools to the workspace and explicitly allowed read-only roots. The REPL and LNR profiles can maintain a lightweight workspace Git baseline for source and Markdown files, while generated data, snapshots, submissions, and runtime logs are excluded from source checkpointing.