Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

fix(agent-core): settle a stopped job with its output and its recorded reason (#2443)

Call White7b96290721ff
diff --git a/core/agent_core/tools/bash.py b/core/agent_core/tools/bash.py
index fb2daa9f2..1dd636667 100644
--- a/core/agent_core/tools/bash.py
+++ b/core/agent_core/tools/bash.py
@@ -13,6 +13,7 @@ from __future__ import annotations
import asyncio
import logging
import os
+import re
import time
from typing import Any, Mapping, Optional
@@ -38,7 +39,9 @@ from core.agent_core.tools.base import (
)
from core.agent_core.tools.jobs import (
STOP_ABORTED,
+ STOP_KILLED,
STOP_TIMEOUT,
+ STOP_WRAPPER_ERROR,
JobHandOverUnavailable,
JobStartError,
LocalJobHost,
@@ -110,7 +113,7 @@ async def final_result(output: JobOutput, status: JobStatus, *, note: Optional[s
async def stopped_result(output: JobOutput, status_line: str) -> ToolResult:
- """The result of a job that was killed (timeout, abort): the output so far, then why it stopped."""
+ """The result of a job that was stopped: the output so far, then why it stopped (``_stopped_line``)."""
await output.finish_off_loop()
text, truncation = output.render("")
return error_result(_append_status(text, status_line), details=output.details(truncation))
@@ -124,13 +127,31 @@ def _timed_out_line(timeout_s: float) -> str:
ABORTED_LINE = "Stopped by the user; the command was terminated."
+KILLED_LINE = "Command was killed before it finished"
+WRAPPER_ERROR_LINE = "Command ended because the job wrapper running it failed"
+# A reason another owner records (``vibe stop``, a Watch) is named as recorded, if it reads as a name: the
+# job's directory is one its command can write to.
+_RECORDED_REASON = re.compile(r"^[a-z][a-z0-9_]{0,39}$")
+
+
def _stopped_line(reason: Optional[str], timeout_s: Optional[float]) -> Optional[str]:
- """The status line for a job someone stopped, from the reason recorded when it was stopped."""
- if reason == STOP_TIMEOUT and timeout_s is not None:
- return _timed_out_line(timeout_s)
+ """The status line for a job someone stopped, from the reason recorded when it was stopped.
+
+ Every recorded reason has one (``recovery.md`` T2); ``None`` means no stop was recorded.
+ """
+ if not reason:
+ return None
+ if reason == STOP_TIMEOUT:
+ return _timed_out_line(timeout_s) if timeout_s is not None else "Command timed out"
if reason == STOP_ABORTED:
return ABORTED_LINE
- return None
+ if reason == STOP_KILLED:
+ return KILLED_LINE
+ if reason == STOP_WRAPPER_ERROR:
+ return WRAPPER_ERROR_LINE
+ if _RECORDED_REASON.match(reason):
+ return f"Command was stopped before it finished ({reason})"
+ return "Command was stopped before it finished"
async def handover_result(output: JobOutput, watch_id: str) -> ToolResult:
@@ -157,9 +178,10 @@ async def recovered_result(
"""The result of a ``bash`` call whose run ended before it committed one (``recovery.md`` T2).
The one renderer for a crash, a restart, and a Stop: a job handed to ``watch_id``
- gets the hand-over result, a finished job its final output, and a job stopped at
- its deadline or by an abort that result. ``None`` means the job is gone for
- another reason or never ran: the caller commits the synthetic interrupted result.
+ gets the hand-over result, a finished job its final output, and a job stopped
+ with a recorded reason its output so far and why it stopped. ``None`` means the
+ job is gone with no recorded stop, or never ran: the caller commits the
+ synthetic interrupted result.
"""
output = JobOutput(jobs, job_id)
if watch_id is not None:
diff --git a/core/agent_core/tools/jobs.py b/core/agent_core/tools/jobs.py
index fc619dc42..cd0f15343 100644
--- a/core/agent_core/tools/jobs.py
+++ b/core/agent_core/tools/jobs.py
@@ -86,6 +86,10 @@ FINISHED_JOB_RETENTION_S = 7 * 24 * 3600
STOP_TIMEOUT = "timeout"
STOP_ABORTED = "aborted"
+#: A stop by anyone else, the wrapper's catchable signals included; ``kill``'s default.
+STOP_KILLED = "killed"
+#: The wrapper itself failed (a full disk, a bug) and stopped the command it could no longer follow.
+STOP_WRAPPER_ERROR = "wrapper_error"
_WRAPPER = os.path.join(os.path.dirname(os.path.abspath(__file__)), "job_wrapper.py")
#: How long past the deadline the host leaves a live wrapper to decide (its poll interval, its
@@ -484,7 +488,7 @@ class LocalJobHost:
return b"", since
return data, start + len(data)
- async def kill(self, job_id: str, *, reason: str = "killed") -> None:
+ async def kill(self, job_id: str, *, reason: str = STOP_KILLED) -> None:
"""Terminate the job's process tree, background children included, if it is provably the job's.
``reason`` is recorded first (``stop_reason``), so whoever reports the
diff --git a/docs/plans/agent-core-contracts/recovery.md b/docs/plans/agent-core-contracts/recovery.md
index 4d7c1fc62..6819eb141 100644
--- a/docs/plans/agent-core-contracts/recovery.md
+++ b/docs/plans/agent-core-contracts/recovery.md
@@ -24,7 +24,7 @@ at-least-once, and that is stated where it applies.
| ID | Invariant | Proof |
| --- | --- | --- |
| T1 | `project()` reads only committed rows; the same rows always produce the same request. | projection before and after job state changes |
-| T2 | At resume, before the first projection, and when a run ends without completing (a Stop), every tool call without a committed `tool_result` gets exactly one, chosen from the state of the job its call instance started (exited: the output; running: handover; stopped with a recorded reason: that result; never ran: the interrupted result). A call without job state (`write`, `edit`) gets `[tool call interrupted; it may or may not have completed; re-read the file before continuing]`. Retries settle nothing twice, and neither do concurrent writers: the store's `append_tool_result` returns the result already committed for the call instance instead of writing a second. | crash between settlement steps, then resume twice; a Stop while several calls of one group (C-3 §2) run |
+| T2 | At resume, before the first projection, and when a run ends without completing (a Stop), every tool call without a committed `tool_result` gets exactly one, chosen from the state of the job its call instance started (exited: the output; running: handover; stopped with a recorded reason: the output so far and that reason, `tools.md` §5; never ran: the interrupted result). A call without job state (`write`, `edit`) gets `[tool call interrupted; it may or may not have completed; re-read the file before continuing]`. Retries settle nothing twice, and neither do concurrent writers: the store's `append_tool_result` returns the result already committed for the call instance instead of writing a second. | crash between settlement steps, then resume twice; a Stop while several calls of one group (C-3 §2) run |
| T3 | Inputs accepted by `steer` or `follow_up` are never dropped: they enter the context, including after a crash. They belong to the Turn that accepted them and are never re-queued as a new P3 Turn. A run that ended by design runs again for them within its Turn; after a stop, an error, or a crash they are admitted into the context (at the end of the run, or at the Session's resume) and share the Turn's outcome. | a terminating tool while a steer is queued; a crash before consumption |
| T4 | An unsettled Turn found at startup is settled as interrupted after T2; the agent never continues it on its own (a hook `end`, an abort, or a crash all leave the same safe state). The user's next message starts a new Turn with the full context. When T2 handed the Turn's running commands to Watches, its notice names them and offers no Retry, because a resend would run them twice. | crash after an `end` hook and after a mid-turn commit |
diff --git a/docs/plans/agent-core-contracts/tools.md b/docs/plans/agent-core-contracts/tools.md
index 320dbf92b..7876e3c04 100644
--- a/docs/plans/agent-core-contracts/tools.md
+++ b/docs/plans/agent-core-contracts/tools.md
@@ -171,6 +171,17 @@ continue in the background as an Avibe Watch; you get a follow-up message when t
- `timeout` kills the process tree: `Command timed out after {n} seconds`. Abort kills it: `Stopped by the user; the
command was terminated.` (Avibe change to Pi's `Command aborted`: an abort is the user's Stop, and the model should
know who ended the command). The adapter commits that result when the run ends (recovery's renderer, T2).
+- Every stop reason a job records ends its result the same way, as an error result: the output so far under the tail
+ rules above, then one line naming the reason. In the foreground and in recovery (T2) alike:
+ - `timeout`: `Command timed out after {n} seconds`;
+ - `aborted`: `Stopped by the user; the command was terminated.`;
+ - `killed` (anyone else's stop, a run ending with its command still running, or a signal that reached the
+ wrapper): `Command was killed before it finished`;
+ - `wrapper_error`: `Command ended because the job wrapper running it failed`;
+ - a reason another owner recorded through the job host, such as `vibe_stop`:
+ `Command was stopped before it finished ({reason})`, naming the reason only when it reads as a name.
+
+ A job that never ran, or ended with neither an exit nor a recorded stop, settles as interrupted (T2).
- Handover (Avibe), when `watch: true` or the foreground window passes: the result is not an error and reads
`Command is still running and is now Watch {watch_id}. You will get a follow-up message when it finishes.` followed
by the output so far (tail rules above), `{label}: {path}`, and `Check: vibe watch show {watch_id}`,
diff --git a/tests/agent_core/tools/test_bash.py b/tests/agent_core/tools/test_bash.py
index 279de7403..090ca3908 100644
--- a/tests/agent_core/tools/test_bash.py
+++ b/tests/agent_core/tools/test_bash.py
@@ -176,7 +176,7 @@ async def test_only_the_recorded_reason_makes_a_gone_job_a_timeout(tmp_path, mak
assert host.stop_reason(job_id) == "wrapper_error"
assert result.is_error
- assert result_text(result).endswith("Command terminated without an exit code")
+ assert result_text(result).endswith("Command ended because the job wrapper running it failed")
@pytest.mark.parametrize("failure", ["cwd_missing", "cwd_not_accessible", "jobs_dir_not_writable", "shell_missing"])
@@ -205,8 +205,8 @@ async def test_a_command_that_cannot_start_has_a_defined_result(tmp_path, make_c
"cwd_missing": f"Working directory does not exist: {cwd}\nCannot execute bash commands.",
"cwd_not_accessible": f"Working directory is not accessible: {cwd}\nCannot execute bash commands.",
"jobs_dir_not_writable": "Could not start the command: permission denied.",
- # The wrapper cannot spawn the shell: it records wrapper_error and the job ends without an exit code.
- "shell_missing": "(no output)\n\nCommand terminated without an exit code",
+ # The wrapper cannot spawn the shell: it records wrapper_error, and the result says so.
+ "shell_missing": "Command ended because the job wrapper running it failed",
}[failure]
assert (result.is_error, result_text(result)) == (True, expected)
assert not (tmp_path / "ran").exists()
@@ -548,7 +548,57 @@ async def test_settlement_reports_each_job_state(tmp_path, make_ctx):
assert again.details["watch_id"] == running.details["watch_id"] == "wch_1"
assert await settle_bash_call(recovery, instance("unknown")) is None
await recovery.kill(running.details["job_id"])
- assert await settle_bash_call(recovery, instance("running")) is None
+ killed = await settle_bash_call(recovery, instance("running"))
+ assert result_text(killed).endswith("Command was killed before it finished")
+
+
+ ("reason", "line"),
+ [
+ (jobs_module.STOP_TIMEOUT, "Command timed out after 60 seconds"),
+ (jobs_module.STOP_ABORTED, "Stopped by the user; the command was terminated."),
+ ("killed", "Command was killed before it finished"),
+ ("wrapper_error", "Command ended because the job wrapper running it failed"),
+ # Recorded by another owner through the job host (``vibe stop`` ends every job).
+ ("vibe_stop", "Command was stopped before it finished (vibe_stop)"),
+ ],
+)
+async def test_recovery_settles_a_stopped_job_with_its_output_and_its_recorded_reason(tmp_path, reason, line):
+ """T2: a job stopped with a recorded reason settles as its output so far and why it stopped, not as interrupted."""
+ host = _host(tmp_path)
+ job_id = await host.start(
+ "echo so far; sleep 30", cwd=str(tmp_path), env={"PATH": os.environ["PATH"]}, timeout_s=60, call=instance()
+ )
+ output = host.output_path(job_id)
+ await hang_guard.until(
+ lambda: os.path.exists(output) and open(output).read() == "so far\n", "the command's first output"
+ )
+ await host.kill(job_id, reason=reason)
+
+ settled = await settle_bash_call(LocalJobHost(str(tmp_path / "jobs")), instance())
+
+ assert settled is not None
+ assert (result_text(settled), settled.is_error) == (f"so far\n\n\n{line}", True)
+
+
+async def test_a_recovered_stop_keeps_the_output_governance_of_any_result(tmp_path):
+ """The tail, its truncation notice and the output log, exactly as a foreground result shows them."""
+ host = _host(tmp_path)
+ job_id = await host.start(
+ "seq 1 3000; sleep 30", cwd=str(tmp_path), env={"PATH": os.environ["PATH"]}, timeout_s=None, call=instance()
+ )
+ output = host.output_path(job_id)
+ await hang_guard.until(
+ lambda: os.path.exists(output) and open(output).read().endswith("\n3000\n"), "the command's output"
+ )
+ await host.kill(job_id)
+
+ settled = await settle_bash_call(LocalJobHost(str(tmp_path / "jobs")), instance())
+
+ assert settled.details["output_path"] == output
+ assert result_text(settled).endswith(
+ f"2999\n3000\n\n[Showing lines 1001-3000 of 3000. {LABEL}: {output}]\n\nCommand was killed before it finished"
+ )
async def test_a_timeout_holds_across_handover_and_a_restart(tmp_path, make_ctx):