Feat/engine

[francescov1]

Note

High Risk
High risk due to adding a large new execution runtime (LLM calls, tool streaming/compaction, sandboxed code execution) and new release/CI pipelines that can affect publishing and developer workflows.

Overview
Adds a new engine/ uv package implementing the HALO agent runtime, including async streaming entrypoints (stream_engine_async/run_engine_async), shared output bus sequencing across root/subagents, context compaction that preserves valid tool-call turns, and an OpenAI Agents SDK runner with retriable-error classification and a circuit breaker.

Introduces a sandboxed run_code tool (bubblewrap on Linux / sandbox-exec on macOS) with capped output and timeouts, plus supporting config/models and trace indexing/store wiring.

Adds repo tooling and delivery: git hook shims in .githooks/ that delegate to engine/scripts/git-hooks, an engine/Taskfile.yml for setup/checks, new GitHub Actions workflows for engine lint/unit/integration/e2e and a multi-stage release workflow (version bump, build, PyPI publish), and a separate cli/ package (halo-cli) exposing a halo-engine Typer command for streaming runs.

^{Reviewed by Cursor Bugbot for commit 1ad22ea. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale field name in plan's integration test code

Medium Severity

Task 11.4's integration test snippet uses tool_call_compaction_keep_last_messages=1, but EngineConfig defines the field as tool_call_compaction_keep_last_turns (with extra="forbid"). When an engineer or agentic worker follows the plan to create test_engine_compaction.py, the test will immediately fail with a Pydantic ValidationError on construction rather than testing compaction behavior.

 

^{Reviewed by Cursor Bugbot for commit f8bde0f. Configure here.}

[cursor]

Dead compaction_model field on AgentContext

Low Severity

AgentContext.__init__ accepts and stores compaction_model as a required field, but no method on AgentContext ever reads self.compaction_model. Compaction actually happens through the compactor callable injected into compact_old_items, which is produced by build_openai_compactor_factory(engine_config) — AgentContext has no role in resolving the model. Every call site (including subagent_tool_factory) must pass the field for no effect, and the TODO comment in openai_agent_runner.py acknowledges the current two-path design.

Additional Locations (1)

• engine/engine/tools/subagent_tool_factory.py#L208-L209

 

^{Reviewed by Cursor Bugbot for commit f8bde0f. Configure here.}

[cursor]

Hardcoded sandbox mount paths duplicated across modules

Medium Severity

The in-sandbox mount paths /mnt/trace/traces.jsonl, /mnt/trace/traces.jsonl.engine-index.jsonl, /venv, /venv/bin/python, and /workspace/bootstrap.py are hardcoded as string literals in both platform_commands.py and sandbox_runner.py. They must stay perfectly synchronized — if one is changed without the other, the sandbox silently breaks because the bootstrap script tries to load files at paths the bind mount no longer provides. Extracting them into shared constants would eliminate this drift risk.

Additional Locations (1)

• engine/engine/sandbox/sandbox_runner.py#L44-L66

 

^{Reviewed by Cursor Bugbot for commit 58a6ec6. Configure here.}

[cursor]

Pre-commit hook silently no-ops when engine hook missing

Low Severity

Both hooks silently skip when $ENGINE_HOOK is not executable or doesn't exist. A developer who hasn't run task setup-git-hooks, or whose checkout has the file but without the executable bit, will get zero feedback that pre-commit/pre-push validation is being bypassed entirely. The PR discussion explicitly flagged "dont like fallbacks like this lets use one way of setting paths" — this silent fallback is the kind of behavior that change was meant to remove.

Additional Locations (1)

• .githooks/pre-push#L17-L22

 

^{Reviewed by Cursor Bugbot for commit 4be7579. Configure here.}

[cursor]

Compactor lazy client reads unset model_provider

Low Severity

The factory closure mutates a shared openai_client via nonlocal, lazily constructing one AsyncOpenAI per factory but reusing it across executions. Two issues: (1) under concurrent subagent compaction the lazy if openai_client is None check is racy, possibly creating multiple clients; (2) the inline TODO already calls out this design — building one client per run and injecting it removes the branch entirely. As written, this is overly complex relative to the simpler single-client construction the TODO describes.

 

^{Reviewed by Cursor Bugbot for commit 4be7579. Configure here.}

[cursor]

Sandbox stdout/stderr drained twice loses output

Medium Severity

In _read_capped, after the first loop fills buf exactly to cap, the second while True loop continues to read and discard the remaining stream. However, if the first loop exits because len(buf) == cap while the next chunk would have fit (the boundary case), or if the process emits less than cap total bytes, the second loop still runs an extra await stream.read(65536) after EOF — harmless but wasteful. More importantly, when output exceeds cap, bytes between cap and the next chunk boundary are silently discarded with no truncation marker, so users see partial output with no indication that it was capped.

 

^{Reviewed by Cursor Bugbot for commit 83cea0a. Configure here.}

[cursor]

Pre-push hook silently swallows refs when engine hook missing

Low Severity

The wrapper unconditionally consumes stdin via cat > "$REFS_FILE" before checking whether the engine hook exists. If the engine hook is absent or non-executable, the captured refs file is discarded on cleanup and the push proceeds with no validation. That's the intended fallback, but it also means any failure to install the engine hook (typo in path, lost executable bit) becomes a silent no-op rather than an obvious error — defeating the purpose of having a pre-push hook at all. Consider logging a warning when the engine hook is not found.

 

^{Reviewed by Cursor Bugbot for commit 83cea0a. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 14 total unresolved issues (including 13 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1ad22ea. Configure here.}

[cursor]

_run_streamed hardcodes root agent's max turns

Low Severity

The _run_streamed closure ignores its agent kwarg and always passes engine_config.root_agent.maximum_turns to Runner.run_streamed. The runner is only bound to the root execution today, so this works, but if OpenAiAgentRunner is ever reused for a non-root agent (or subagent is configured with a different maximum_turns), the wrong cap will be silently applied. Reading max_turns from the agent that was passed in would remove this latent coupling.

 

^{Reviewed by Cursor Bugbot for commit 1ad22ea. Configure here.}