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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""The ``bash`` tool (C-7 section 5).
Ported from Pi ``packages/coding-agent/src/core/tools/bash.ts`` (MIT, Copyright
(c) 2025 Mario Zechner): the description, parameters, tail truncation, and
status lines are Pi's. Avibe additions: every command is a job handle from its
first moment, so a command still running after the foreground window, or
started with ``watch: true``, is handed to a Watch instead of being killed, and
it runs exactly once either way.
"""
from __future__ import annotations
import asyncio
import logging
import os
import re
import time
from datetime import datetime, timezone
from typing import Any, Mapping, Optional
from core.agent_core.cancel import CancelToken
from core.agent_core.messages import ToolCallBlock
from core.agent_core.tools.args import (
ToolInputError,
error_result,
format_number,
optional_bool_arg,
optional_number_arg,
str_arg,
text_result,
)
from core.agent_core.tools.base import (
MAX_BYTES,
MAX_LINES,
CallInstance,
JobHost,
JobStatus,
ToolContext,
ToolResult,
ToolSpec,
)
from core.agent_core.tools.jobs import (
STOP_ABORTED,
STOP_KILLED,
STOP_TIMEOUT,
STOP_WRAPPER_ERROR,
JobHandOverUnavailable,
JobStartError,
LocalJobHost,
)
from core.agent_core.tools.paths import os_reason
from core.agent_core.tools.output import FINISH_BYTES, JobOutput
from core.agent_core.tools.shell import Shell, default_shell
logger = logging.getLogger(__name__)
DEFAULT_FOREGROUND_WINDOW_S = 120.0
_MAX_TIMEOUT_S = 2_147_483.647
_PROGRESS_INTERVAL_S = 0.1 # Pi's BASH_UPDATE_THROTTLE_MS
_WATCH_GRACE_S = 0.5
BASH_SCHEMA: Mapping[str, Any] = {
"type": "object",
"required": ["command"],
"properties": {
"command": {"type": "string", "description": "Shell command to execute"},
"timeout": {"type": "number", "description": "Timeout in seconds (optional, no default timeout)"},
"watch": {
"type": "boolean",
"description": "Start the command as a background Watch and return immediately. Defaults to false.",
},
},
}
def bash_description(foreground_window_s: float = DEFAULT_FOREGROUND_WINDOW_S, shell: Optional[Shell] = None) -> str:
"""Pi's description; for PowerShell, its first sentence names PowerShell (C-7 tools.md section 5)."""
shell = shell or default_shell()
opening = (
"Execute a PowerShell command in the current working directory. Returns its output and errors."
if shell.powershell
else "Execute a bash command in the current working directory. Returns stdout and stderr."
)
description = (
f"{opening} Output is truncated to "
f"last {MAX_LINES} lines or {MAX_BYTES // 1024}KB (whichever is hit first). If truncated, the output log is saved "
"to a file; very large logs keep their beginning and end. Optionally provide a timeout in seconds. "
f"Commands still running after {format_number(foreground_window_s)} seconds, or started with watch=true, "
"continue in the background as an Avibe Watch; you get a follow-up message when they finish."
)
if shell.windows_powershell:
description += (
" This is Windows PowerShell 5.1: it has no && or ||, so separate commands with ; and test $? or "
"$LASTEXITCODE."
)
return description
def _append_status(text: str, status: str) -> str:
return f"{text}\n\n{status}" if text else status
def _timeout_arg(arguments: Mapping[str, Any]) -> Optional[float]:
try:
timeout = optional_number_arg(arguments, "timeout")
except ToolInputError:
raise ToolInputError("Invalid timeout: must be a finite number of seconds") from None
if timeout is None:
return None
if timeout <= 0:
raise ToolInputError("Invalid timeout: must be a finite number of seconds")
if timeout > _MAX_TIMEOUT_S:
raise ToolInputError(f"Invalid timeout: maximum is {format_number(_MAX_TIMEOUT_S)} seconds")
return timeout
async def final_result(output: JobOutput, status: JobStatus, *, note: Optional[str] = None) -> ToolResult:
"""The result of a job that is no longer running, as Pi formats a finished command."""
await output.finish_off_loop()
text, truncation = output.render("(no output)")
if note:
text = f"{text}\n\n{note}"
details = {**output.details(truncation), "exit_code": status.exit_code}
if status.state == "exited" and status.exit_code == 0:
return text_result(text, details=details)
if status.state == "exited":
return error_result(_append_status(text, f"Command exited with code {status.exit_code}"), details=details)
return error_result(_append_status(text, "Command terminated without an exit code"), details=details)
async def stopped_result(output: JobOutput, status_line: str) -> ToolResult:
"""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))
def _timed_out_line(timeout_s: float) -> str:
return f"Command timed out after {format_number(timeout_s)} seconds"
#: Avibe change to Pi's ``Command aborted``: an abort is the user's Stop, and the model should know who ended it.
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.
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
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:
"""Avibe: the command keeps running as a Watch; the model sees the output so far and how to manage it."""
# A one-shot render reads the whole retained log (head, omitted middle, tail), not one poll's worth.
await output.poll_off_loop(FINISH_BYTES)
text, truncation = output.render("(no output yet)")
text = text.rstrip("\n")
lines = [
f"Command is still running and is now Watch {watch_id}. You will get a follow-up message when it finishes.",
"",
text,
"",
]
if truncation is None:
lines.append(output.where())
lines += [f"Check: vibe watch show {watch_id}", f"Stop: vibe watch remove {watch_id}"]
return text_result("\n".join(lines), details={**output.details(truncation), "watch_id": watch_id})
async def recovered_result(
jobs: LocalJobHost, job_id: str, status: JobStatus, watch_id: Optional[str]
) -> Optional[ToolResult]:
"""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
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:
return await handover_result(output, watch_id)
if status.state == "exited":
return await final_result(output, status)
if status.state != "gone":
return None
line = _stopped_line(jobs.stop_reason(job_id), jobs.meta(job_id).get("timeout_s"))
return await stopped_result(output, line) if line else None
async def settle_in_foreground(
jobs: LocalJobHost,
call: ToolCallBlock,
job_id: str,
*,
stop: asyncio.Event,
foreground_window_s: float = DEFAULT_FOREGROUND_WINDOW_S,
) -> tuple[JobStatus, Optional[str]]:
"""Settle a job that survived a restart as its live call would (``recovery.md`` T2).
The call's foreground window counts from the job's launch (``meta.created_at``),
so downtime spends it: a window that already passed hands over at once. A job
still running then goes to a Watch, retried once as ``BashTool`` does; when no
Watch can take it, it stays in the foreground until it ends. A Stop ends the
wait and the command, as it ends a live foreground command. Returns the job's
status and its Watch, if it went to one.
"""
window_s = foreground_window_s
if (call.arguments or {}).get("watch") is True:
window_s = min(window_s, _WATCH_GRACE_S)
try:
launched = datetime.fromisoformat(str(jobs.meta(job_id).get("created_at") or "").replace("Z", "+00:00"))
# A wall clock that stepped back never stretches the window past its length.
remaining: Optional[float] = min(window_s, window_s - (datetime.now(timezone.utc) - launched).total_seconds())
except ValueError:
remaining = 0.0
status = await _wait_or_stop(jobs, job_id, max(0.0, remaining or 0.0), stop)
if status.state != "running":
return status, None
error: Optional[Exception] = None
for _ in range(2):
if stop.is_set():
# As the live call checks its Stop before each handover: the Stop ends the command.
return await _wait_or_stop(jobs, job_id, 0, stop), None
try:
return status, await jobs.hand_over(job_id)
except JobHandOverUnavailable as exc:
error = exc
break
except Exception as exc:
error = exc
logger.info("Job %s stays in the foreground: %s", job_id, error)
return await _wait_or_stop(jobs, job_id, None, stop), None
async def _wait_or_stop(jobs: LocalJobHost, job_id: str, seconds: Optional[float], stop: asyncio.Event) -> JobStatus:
"""The job's status after it ends, ``seconds`` pass (``None``: no limit), or ``stop``, which kills it."""
if not stop.is_set() and (seconds is None or seconds > 0):
waiting = asyncio.ensure_future(jobs.wait(job_id, deadline_s=seconds))
stopped = asyncio.ensure_future(stop.wait())
try:
await asyncio.wait({waiting, stopped}, return_when=asyncio.FIRST_COMPLETED)
finally:
for task in (waiting, stopped):
if not task.done():
task.cancel()
await asyncio.gather(waiting, stopped, return_exceptions=True)
if stop.is_set() and jobs.status(job_id).state == "running":
await jobs.kill(job_id, reason=STOP_ABORTED)
return jobs.status(job_id)
async def settle_bash_call(jobs: LocalJobHost, call: CallInstance) -> Optional[ToolResult]:
"""The durable result for a ``bash`` call left open by a crash; a running job is handed to Watch first."""
job_id = jobs.find_job(call)
if job_id is None:
return None
await jobs.enforce_deadline(job_id)
status = jobs.status(job_id)
watch_id = await jobs.hand_over(job_id) if status.state == "running" else None
return await recovered_result(jobs, job_id, status, watch_id)
class BashTool:
"""``jobs`` is the loop's tracking wrapper around the adapter's host; ``bash`` never makes its own."""
concurrent = True
def __init__(
self,
jobs: JobHost,
*,
foreground_window_s: float = DEFAULT_FOREGROUND_WINDOW_S,
shell: Optional[Shell] = None,
) -> None:
"""``shell`` is what ``jobs`` runs commands in (``LocalJobHost.shell``); it names the tool."""
shell = shell or default_shell()
self._jobs = jobs
self._window_s = foreground_window_s
self._spec = ToolSpec(
name="powershell" if shell.powershell else "bash",
description=bash_description(foreground_window_s, shell),
input_schema=BASH_SCHEMA,
)
@property
def spec(self) -> ToolSpec:
return self._spec
async def execute(self, arguments: Mapping[str, Any], ctx: ToolContext) -> ToolResult:
try:
command = str_arg(arguments, "command")
if "\x00" in command:
raise ToolInputError("Invalid command: contains a NUL byte")
timeout = _timeout_arg(arguments)
watch = optional_bool_arg(arguments, "watch")
except ToolInputError as exc:
return error_result(str(exc))
if not os.path.isdir(ctx.cwd):
return error_result(f"Working directory does not exist: {ctx.cwd}\nCannot execute {self._spec.name} commands.")
if not os.access(ctx.cwd, os.X_OK):
return error_result(
f"Working directory is not accessible: {ctx.cwd}\nCannot execute {self._spec.name} commands."
)
if ctx.cancel.cancelled:
return error_result("Command aborted")
if ctx.call is None:
# A job is keyed by its call instance; a checkpoint turn's call has none (its policy denies bash first).
return error_result("Commands cannot run in this turn.")
# The job host enforces the timeout (its wrapper decides timeout versus exit); bash only reports
# the recorded reason.
try:
job_id = await self._jobs.start(
command,
cwd=ctx.cwd,
env=ctx.env,
timeout_s=timeout,
call=ctx.call,
)
except JobStartError as exc:
return error_result(str(exc))
except OSError as exc:
logger.warning("Could not start a bash job", exc_info=True)
return error_result(f"Could not start the command: {os_reason(exc)}.")
# The handover clock starts once the command may run, so the launch never counts against it.
started = time.monotonic()
output = JobOutput(self._jobs, job_id)
# watch=true still lets a command that ends at once report its own result instead of becoming a Watch.
handover_at = min(self._window_s, _WATCH_GRACE_S) if watch else self._window_s
handover_error: Optional[Exception] = None
last_progress = ""
while True:
elapsed = time.monotonic() - started
hand_over = handover_error is None and elapsed >= handover_at
# A handover is decided only after a fresh status: a command that already ended keeps its own result.
slice_s = 0.0 if hand_over else _PROGRESS_INTERVAL_S
if handover_error is None:
slice_s = min(slice_s, max(0.0, handover_at - elapsed))
status = await self._wait_or_cancel(job_id, slice_s, ctx.cancel)
if status is not None and status.state == "gone":
# Whoever stopped the job recorded why; the job host or its wrapper may have stopped it first.
line = _stopped_line(self._jobs.stop_reason(job_id), timeout)
if line:
return await stopped_result(output, line)
if status is not None and status.state != "running":
note = None
if watch and handover_error is not None:
note = f"[Watch unavailable ({handover_error}); the command ran in the foreground.]"
return await final_result(output, status, note=note)
if ctx.cancel.cancelled:
await self._jobs.kill(job_id, reason=STOP_ABORTED)
return await stopped_result(output, ABORTED_LINE)
if hand_over:
watch_id, handover_error = await self._hand_over(job_id)
if watch_id is not None:
return await handover_result(output, watch_id)
continue
# Off the event loop: following a flood of output costs CPU every Session would otherwise wait on.
if ctx.on_progress is not None and await output.poll_off_loop():
tail = output.snapshot().content
if tail != last_progress:
last_progress = tail
ctx.on_progress(tail)
async def _hand_over(self, job_id: str) -> tuple[Optional[str], Optional[Exception]]:
"""``(watch_id, None)``, or ``(None, error)`` when no Watch owns the job and it stays in the foreground.
``hand_over`` raising means no Watch owns the job, and adopt-or-create is idempotent, so one
failed attempt is tried once more; ``JobHandOverUnavailable`` means there is no Watch to try.
"""
error: Optional[Exception] = None
for _ in range(2):
try:
return await self._jobs.hand_over(job_id), None
except JobHandOverUnavailable as exc:
error = exc
break
except Exception as exc:
error = exc
logger.info("Job %s stays in the foreground: %s", job_id, error)
return None, error
async def _wait_or_cancel(self, job_id: str, seconds: float, cancel: CancelToken) -> Optional[JobStatus]:
"""The job's status after at most ``seconds``, or ``None`` as soon as ``cancel`` fires."""
if cancel.cancelled:
return None
waiting = asyncio.ensure_future(self._jobs.wait(job_id, deadline_s=seconds))
cancelled = asyncio.ensure_future(cancel.wait())
try:
await asyncio.wait({waiting, cancelled}, return_when=asyncio.FIRST_COMPLETED)
finally:
for task in (waiting, cancelled):
if not task.done():
task.cancel()
await asyncio.gather(waiting, cancelled, return_exceptions=True)
return waiting.result() if waiting.done() and not waiting.cancelled() else None