Agent & Tools

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 DEEPBUILDER_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
core/tools/bash/output.py
core/tools/bash/signals.py
core/tools/bash/progress_signals.py
core/tools/bash/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.
Compaction: 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.