Skip to content

feat(agent): run long commands in the background and hold the turn for them - #1372

Open
LivXue wants to merge 3 commits into
feat/unbounded_tool_iterationsfrom
feat/exec_deadline_and_background_hold
Open

LivXue wants to merge 3 commits into
feat/unbounded_tool_iterationsfrom
feat/exec_deadline_and_background_hold

Conversation

@LivXue

@LivXue LivXue commented Nov 20, 2026

Copy link
Copy Markdown
Member

Summary

Stacked on #1370, which gives a turn a wall clock; this PR makes commands fit inside that clock, and stops a turn - and the ACP prompt - from reading as finished while a background command it started is still running.

  • Commands fit the turn. The code flow's exec default drops from 600 s to 120 s and the ceiling from 1200 s to 600 s. With a turn clock set, the effective limit is the smaller of the request, the ceiling and "time left minus a 20 s wrap-up reserve", with a note in the result when it was cut. The reserve exists because the loop reads its deadline between iterations, never mid-call: the last call and the wrap-up have to fit after the command returns.
  • A command that still hits its limit is adopted, not killed. The executor hands the live process to the background lane, keeps reading both pipes into a log, and returns the output produced so far plus the task id and log path. Adoption is skipped when the turn's clock has run out; then the process is killed as before. The background registry gained adopt(), a per-task session_key, running(session_key=...) and a tail() that reads the recorded log path, so an adopted command is listed, capped and reaped like one started with run_in_background.
  • The ACP prompt stays open while that command runs. The code flow's turn record carries raven.holdTurn with background: true when the session still has a running command; the ACP layer already knows how to hold a prompt with heartbeats. The held prompt now starts its own closing turn once the command is gone (nothing else would), reaps what is left at the turn's deadline, and reaps on cancel so a cancelled prompt leaves no orphan.
  • raven agent -m waits for the same work before exiting, instead of returning a task id for output that is still being written.

Type

  • Feature
  • Fix
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

  • uv run pytest tests/test_acp_methods.py tests/test_cli_agent_commands.py tests/test_agents_code_flow_exec.py tests/test_agents_code_flow_plugin.py tests/test_shell_background.py tests/test_agent_loop_iteration_hooks.py -q -> 332 passed

  • uv run pytest tests/test_agent_loop_dead_end.py tests/test_agent_loop_dead_end_retry.py tests/test_config_live.py tests/test_config_loader.py -q -> 359 passed, 1 skipped (the pre-existing POSIX-permission case under root)

  • New tests were written first and failed against the previous code: a 600 s request is cut to the turn's remaining time and says so; a timed-out command is adopted (its log keeps growing after the call returns, the result names the task); no time left means killed, not adopted; an adopted task is listed under its session only; a held prompt runs its closing turn when the command ends; a cancelled hold reaps what it waited on; a one-shot run waits for its background commands.

  • uv run ruff check and uv run ruff format --check pass on every touched file.

  • Relevant tests pass locally

  • Relevant lint / type checks pass locally

  • User-facing docs or screenshots are updated when needed

Risk

  • Behaviour change: a command that times out no longer dies by default. On a host whose event loop ends with the turn (a one-shot run.py that exits), the adopted process can outlive the reading: the adoption is skipped when the turn's clock has run out, and raven agent -m waits, but a caller that abandons the loop still loses the remaining output.

  • Behaviour change for ACP clients: a session/prompt whose turn started a long command answers later than before, by design. A client with a timeout shorter than the command being adopted will now time out where it used to see end_turn immediately; that prompt previously misreported the work as finished.

  • The poll for "background work gone" is two seconds, the same order as the hold heartbeat; at the turn deadline the rest are killed and the closing turn runs anyway, so a prompt cannot be held forever.

  • Rollback: revert the commit. No persisted state or schema migration is involved.

  • Security impact considered

  • Backward compatibility considered

  • Rollback path is clear for risky changes

Related Issues

N/A

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: tag explicit background launches with their session so held turns can observe them.

I reviewed the full target diff, relevant callers and history, backward compatibility, whether tests were weakened, the AGENTS.md/CLAUDE.md/CONTEXT terminology and architecture constraints, and the held-turn/process-lifecycle paths. The changed-area suite passes after syncing the workspace packages: uv run pytest tests/test_acp_methods.py tests/test_agent_loop_iteration_hooks.py tests/test_agents_code_flow_exec.py tests/test_agents_code_launcher.py tests/test_cli_agent_commands.py tests/test_shell_background.py -x -> 416 passed. The first attempt did not reach project code because the local environment lacked raven_everos; uv sync --all-packages corrected that environment issue.

One ordinary-use blocker remains inline.

*,
cwd: str | None = None,
env: dict[str, str] | None = None,
session_key: str | None = None,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: explicit run_in_background commands are invisible to the new held-turn wait.

ExecTool.execute() still calls background_exec.start(command, cwd=cwd, env=bg_env) without this argument. The record therefore stores session_key: null, while both CodeParticipant.end_turn() and _wait_for_background_work() call running(session_key=<current session>), which excludes that task. I reproduced this directly: the task appeared in running() but running(session_key='cli:review') returned []. Thus the model's documented path for work longer than the ceiling can still end the ACP prompt or one-shot CLI run while its command is running, which is the behavior this change is intended to prevent. Please propagate the current turn session on this launch path and cover it with the hold/wait tests.

…or them

A command that outlives its limit was killed, and a command started in the
background left the turn (and the ACP prompt) reading as finished. Both cut the
same way in practice: the work was still running and the caller was told it was
over.

Exec now fits inside the turn: the default drops to 120 s, the ceiling to 600 s,
and with a turn clock set the limit is cut to the time the turn has left minus a
wrap-up reserve, with the result saying so. A command that still hits its limit
is adopted rather than killed: the adopter keeps reading the pipes into a log,
the task records the session that started it, and the result names the task and
its log.

The ACP layer keeps the prompt open while a session's adopted command runs: the
code flow files raven.holdTurn in its turn record, and the held prompt starts the
closing turn once the command is gone, reaping the rest at the turn's deadline
and on cancel. raven agent -m waits for the same work before it exits.
@LivXue
LivXue force-pushed the feat/exec_deadline_and_background_hold branch from 345b42a to 0cc6bda Compare November 20, 2026 08:05

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: propagate the current session into explicit background launches before this merges.

I reviewed the new commits and the full target diff, including repository rules and canonical terms, callers and history, backward compatibility, test changes, and the ACP/CLI held-turn architecture. The new deadline, failed-closing-turn, empty-wait, manifest, and timing-test changes introduce no additional findings, but they do not change the open blocker: ExecTool.execute() still launches run_in_background work without session_key, so both session-filtered waits remain unable to see it. The existing inline thread remains current and open.

Verification: uv run pytest tests/test_acp_methods.py tests/test_agent_loop_iteration_hooks.py tests/test_agents_code_flow_exec.py tests/test_agents_code_launcher.py tests/test_agents_code_tools_plugin.py tests/test_cli_agent_commands.py tests/test_shell_background.py -x -> 537 passed.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants