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.

feat(agent-core): coding tools and the pipe job host

cyh1b47a5af7c1d
diff --git a/core/agent_core/tools/args.py b/core/agent_core/tools/args.py
new file mode 100644
index 000000000..6b5dedae7
--- /dev/null
+++ b/core/agent_core/tools/args.py
@@ -0,0 +1,55 @@
+"""Argument checks and result helpers shared by the coding tools."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Mapping, Optional
+
+from core.agent_core.messages import TextBlock
+from core.agent_core.tools.base import ToolResult
+
+
+class ToolInputError(ValueError):
+ """Arguments the tool cannot act on; the message becomes the error result."""
+
+
+def text_result(text: str, *, is_error: bool = False, details: Optional[Mapping[str, Any]] = None) -> ToolResult:
+ return ToolResult(content=(TextBlock(text=text),), is_error=is_error, details=dict(details or {}))
+
+
+def error_result(text: str, *, details: Optional[Mapping[str, Any]] = None) -> ToolResult:
+ return text_result(text, is_error=True, details=details)
+
+
+def str_arg(arguments: Mapping[str, Any], name: str) -> str:
+ value = arguments.get(name)
+ if not isinstance(value, str):
+ raise ToolInputError(f"{name} must be a string")
+ return value
+
+
+def optional_number_arg(arguments: Mapping[str, Any], name: str) -> Optional[float]:
+ value = arguments.get(name)
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+ raise ToolInputError(f"{name} must be a number")
+ return float(value)
+
+
+def optional_bool_arg(arguments: Mapping[str, Any], name: str) -> bool:
+ value = arguments.get(name)
+ if value is None:
+ return False
+ if not isinstance(value, bool):
+ raise ToolInputError(f"{name} must be a boolean")
+ return value
+
+
+def format_number(value: float) -> str:
+ """``5`` for 5.0 and ``0.5`` for 0.5, as JavaScript prints numbers in Pi's messages."""
+ return str(int(value)) if float(value).is_integer() else repr(float(value))
+
+
+def os_error_text(error: OSError) -> str:
+ return str(error) or type(error).__name__
diff --git a/core/agent_core/tools/bash.py b/core/agent_core/tools/bash.py
new file mode 100644
index 000000000..fbae71b94
--- /dev/null
+++ b/core/agent_core/tools/bash.py
@@ -0,0 +1,243 @@
+"""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 time
+from typing import Any, Mapping, Optional
+
+from core.agent_core.cancel import CancelToken
+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, JobHost, JobStatus, ToolContext, ToolResult, ToolSpec
+from core.agent_core.tools.jobs import STOP_TIMEOUT, JobStartError, LocalJobHost
+from core.agent_core.tools.output import JobOutput
+
+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
+# A job found gone this close to its timeout was killed for it, by this tool or by the job host.
+_DEADLINE_SLACK_S = 1.0
+
+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) -> str:
+ return (
+ "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to "
+ f"last {MAX_LINES} lines or {MAX_BYTES // 1024}KB (whichever is hit first). If truncated, full output is saved "
+ "to a temp file. 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."
+ )
+
+
+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
+
+
+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."""
+ output.finish()
+ 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)
+
+
+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."""
+ output.finish()
+ 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"
+
+
+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."""
+ output.poll()
+ 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(f"Full output: {output.path}")
+ 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 settle_bash_call(jobs: LocalJobHost, session_id: str, tool_call_id: str) -> Optional[ToolResult]:
+ """The durable result for a ``bash`` call left open by a crash (``recovery.md``).
+
+ A finished job gets its final output, a job killed at its deadline gets the
+ timeout result, and a running one is handed to Watch. ``None`` means the job
+ is gone, never ran, or does not exist: the caller commits the synthetic
+ interrupted result.
+ """
+ job_id = jobs.find_job(session_id, tool_call_id)
+ if job_id is None:
+ return None
+ await jobs.enforce_deadline(job_id)
+ status = jobs.status(job_id)
+ if status.state == "running":
+ return handover_result(JobOutput(jobs, job_id), await jobs.hand_over(job_id))
+ if status.state == "exited":
+ return final_result(JobOutput(jobs, job_id), status)
+ timeout_s = jobs.meta(job_id).get("timeout_s")
+ if jobs.stop_reason(job_id) == STOP_TIMEOUT and timeout_s is not None:
+ return stopped_result(JobOutput(jobs, job_id), _timed_out_line(timeout_s))
+ return None
+
+
+class BashTool:
+ """``jobs`` is the loop's tracking wrapper around the adapter's host; ``bash`` never makes its own."""
+
+ def __init__(self, jobs: JobHost, *, foreground_window_s: float = DEFAULT_FOREGROUND_WINDOW_S) -> None:
+ self._jobs = jobs
+ self._window_s = foreground_window_s
+ self._spec = ToolSpec(name="bash", description=bash_description(foreground_window_s), 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")
+ 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 bash commands.")
+ if ctx.cancel.cancelled:
+ return error_result("Command aborted")
+
+ # Measured from before the start, so this deadline passes no later than the job's recorded one and
+ # the foreground reports the timeout itself.
+ started = time.monotonic()
+ try:
+ job_id = await self._jobs.start(
+ command,
+ cwd=ctx.cwd,
+ env=ctx.env,
+ timeout_s=timeout,
+ session_id=ctx.session_id,
+ tool_call_id=ctx.tool_call_id,
+ )
+ 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: {exc}")
+
+ output = JobOutput(self._jobs, job_id)
+ handover_error: Optional[Exception] = None
+ last_progress = ""
+ while True:
+ elapsed = time.monotonic() - started
+ if handover_error is None and (watch or elapsed >= self._window_s):
+ try:
+ return handover_result(output, await self._jobs.hand_over(job_id))
+ except Exception as exc: # no Watch here: the command stays in the foreground
+ logger.info("Job %s stays in the foreground: %s", job_id, exc)
+ handover_error = exc
+
+ slice_s = _PROGRESS_INTERVAL_S
+ if timeout is not None:
+ slice_s = min(slice_s, max(0.0, timeout - elapsed))
+ if handover_error is None:
+ slice_s = min(slice_s, max(0.0, self._window_s - elapsed))
+ status = await self._wait_or_cancel(job_id, slice_s, ctx.cancel)
+
+ if status is not None and status.state == "gone" and timeout is not None:
+ # Whoever holds the job enforces its deadline; the host may have killed it first.
+ if time.monotonic() - started >= timeout - _DEADLINE_SLACK_S:
+ return stopped_result(output, _timed_out_line(timeout))
+ 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 final_result(output, status, note=note)
+ if ctx.cancel.cancelled:
+ await self._jobs.kill(job_id)
+ return stopped_result(output, "Command aborted")
+ if timeout is not None and time.monotonic() - started >= timeout:
+ await self._jobs.kill(job_id)
+ return stopped_result(output, _timed_out_line(timeout))
+ if ctx.on_progress is not None and output.poll():
+ tail = output.snapshot().content
+ if tail != last_progress:
+ last_progress = tail
+ ctx.on_progress(tail)
+
+ 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
diff --git a/core/agent_core/tools/coding.py b/core/agent_core/tools/coding.py
new file mode 100644
index 000000000..fd8dc28c9
--- /dev/null
+++ b/core/agent_core/tools/coding.py
@@ -0,0 +1,30 @@
+"""The coding tool set: Pi's ``read``, ``write``, ``edit``, and ``bash`` with the Avibe additions (C-7)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from core.agent_core.tools.base import JobHost, Tool
+from core.agent_core.tools.bash import DEFAULT_FOREGROUND_WINDOW_S, BashTool
+from core.agent_core.tools.edit import EditTool
+from core.agent_core.tools.read import ImageSink, ReadTool
+from core.agent_core.tools.write import WriteTool
+
+
+def create_coding_tools(
+ jobs: JobHost,
+ *,
+ image_sink: Optional[ImageSink] = None,
+ foreground_window_s: float = DEFAULT_FOREGROUND_WINDOW_S,
+) -> tuple[Tool, ...]:
+ """One tool set for every model; each tool's ``spec`` is what the model sees.
+
+ ``jobs`` is the loop's ``Agent.jobs`` wrapper, so an abort can kill a
+ foreground command; ``image_sink`` stores images ``read`` attaches.
+ """
+ return (
+ ReadTool(image_sink=image_sink),
+ WriteTool(),
+ EditTool(),
+ BashTool(jobs, foreground_window_s=foreground_window_s),
+ )
diff --git a/core/agent_core/tools/edit.py b/core/agent_core/tools/edit.py
new file mode 100644
index 000000000..4c3a26e7f
--- /dev/null
+++ b/core/agent_core/tools/edit.py
@@ -0,0 +1,174 @@
+"""The ``edit`` tool (C-7 section 4).
+
+Ported from Pi ``packages/coding-agent/src/core/tools/edit.ts`` (MIT, Copyright
+(c) 2025 Mario Zechner); the description and model-facing strings are Pi's.
+``replaceAll`` is an Avibe addition, so its schema text and the "unless
+replaceAll is true" clause are Avibe's.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+import json
+import os
+from typing import Any, Mapping
+
+from core.agent_core.tools.args import ToolInputError, error_result, os_error_text, str_arg, text_result
+from core.agent_core.tools.base import ToolContext, ToolResult, ToolSpec
+from core.agent_core.tools.edit_diff import (
+ Edit,
+ EditError,
+ apply_edits_to_normalized_content,
+ detect_line_ending,
+ generate_diff_string,
+ generate_unified_patch,
+ normalize_to_lf,
+ restore_line_endings,
+ split_bom,
+)
+from core.agent_core.tools.paths import file_mutation_lock, resolve_to_cwd
+from core.agent_core.tools.write import write_text
+
+EDIT_DESCRIPTION = (
+ "Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping "
+ "region of the original file. If two changes affect the same block or nearby lines, merge them into one edit "
+ "instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes."
+)
+
+EDIT_SCHEMA: Mapping[str, Any] = {
+ "type": "object",
+ "required": ["path", "edits"],
+ "properties": {
+ "path": {"type": "string", "description": "Path to the file to edit (relative or absolute)"},
+ "edits": {
+ "type": "array",
+ "description": (
+ "One or more targeted replacements. Each edit is matched against the original file, not "
+ "incrementally. Do not include overlapping or nested edits. If two changes touch the same block or "
+ "nearby lines, merge them into one edit instead."
+ ),
+ "items": {
+ "type": "object",
+ "required": ["oldText", "newText"],
+ "properties": {
+ "oldText": {
+ "type": "string",
+ "description": (
+ "Exact text for one targeted replacement. It must be unique in the original file unless "
+ "replaceAll is true, and must not overlap with any other edits[].oldText in the same call."
+ ),
+ },
+ "newText": {"type": "string", "description": "Replacement text for this targeted edit."},
+ "replaceAll": {
+ "type": "boolean",
+ "description": (
+ "Replace every occurrence of oldText instead of requiring exactly one. Defaults to false."
+ ),
+ },
+ },
+ },
+ },
+ },
+}
+
+
+def _is_single_edit(value: Any) -> bool:
+ return isinstance(value, dict) and isinstance(value.get("oldText"), str) and isinstance(value.get("newText"), str)
+
+
+def prepare_edit_arguments(arguments: Mapping[str, Any]) -> dict[str, Any]:
+ """Pi's repairs: ``edits`` sent as a JSON string or a single object, and the legacy top-level pair."""
+ args = dict(arguments)
+ edits = args.get("edits")
+ if isinstance(edits, str):
+ try:
+ parsed = json.loads(edits)
+ except ValueError:
+ parsed = None
+ if isinstance(parsed, list):
+ args["edits"] = parsed
+ elif _is_single_edit(parsed):
+ args["edits"] = [parsed]
+ elif _is_single_edit(edits):
+ args["edits"] = [edits]
+ if isinstance(args.get("oldText"), str) and isinstance(args.get("newText"), str):
+ listed = list(args["edits"]) if isinstance(args.get("edits"), list) else []
+ listed.append({"oldText": args.pop("oldText"), "newText": args.pop("newText")})
+ args["edits"] = listed
+ return args
+
+
+def _edits_arg(arguments: Mapping[str, Any]) -> list[Edit]:
+ edits = arguments.get("edits")
+ if not isinstance(edits, list) or not edits:
+ raise ToolInputError("Edit tool input is invalid. edits must contain at least one replacement.")
+ parsed: list[Edit] = []
+ for index, item in enumerate(edits):
+ if not isinstance(item, dict):
+ raise ToolInputError(f"edits[{index}] must be an object")
+ old_text, new_text = item.get("oldText"), item.get("newText")
+ if not isinstance(old_text, str) or not isinstance(new_text, str):
+ raise ToolInputError(f"edits[{index}] needs string oldText and newText")
+ replace_all = item.get("replaceAll", False)
+ if replace_all is None:
+ replace_all = False
+ if not isinstance(replace_all, bool):
+ raise ToolInputError(f"edits[{index}].replaceAll must be a boolean")
+ parsed.append(Edit(old_text, new_text, replace_all))
+ return parsed
+
+
+def _plan_edits(absolute: str, edits: list[Edit], path: str) -> tuple[str, str, str, str]:
+ """Read the file and compute the edited content: ``(bom, line_ending, before, after)``, LF-normalized."""
+ with open(absolute, "rb") as handle:
+ raw = handle.read().decode("utf-8", "replace")
+ # The model never includes an invisible BOM in oldText.
+ bom, content = split_bom(raw)
+ ending = detect_line_ending(content)
+ base = normalize_to_lf(content)
+ return bom, ending, base, apply_edits_to_normalized_content(base, edits, path)
+
+
+class EditTool:
+ def __init__(self) -> None:
+ self._spec = ToolSpec(name="edit", description=EDIT_DESCRIPTION, input_schema=EDIT_SCHEMA)
+
+ @property
+ def spec(self) -> ToolSpec:
+ return self._spec
+
+ async def execute(self, arguments: Mapping[str, Any], ctx: ToolContext) -> ToolResult:
+ try:
+ arguments = prepare_edit_arguments(arguments)
+ path = str_arg(arguments, "path")
+ edits = _edits_arg(arguments)
+ except ToolInputError as exc:
+ return error_result(str(exc))
+ absolute = resolve_to_cwd(path, ctx.cwd)
+
+ async with file_mutation_lock(absolute):
+ if ctx.cancel.cancelled:
+ return error_result("Operation aborted")
+ if not os.access(absolute, os.R_OK | os.W_OK):
+ code = errno.errorcode.get(errno.ENOENT if not os.path.exists(absolute) else errno.EACCES, "EACCES")
+ return error_result(f"Could not edit file: {path}. Error code: {code}.")
+ try:
+ bom, ending, base, new_content = await asyncio.to_thread(_plan_edits, absolute, edits, path)
+ if ctx.cancel.cancelled:
+ return error_result("Operation aborted")
+ await asyncio.to_thread(write_text, absolute, bom + restore_line_endings(new_content, ending))
+ except EditError as exc:
+ return error_result(str(exc))
+ except OSError as exc:
+ return error_result(os_error_text(exc))
+
+ diff, first_changed_line = generate_diff_string(base, new_content)
+ return text_result(
+ f"Successfully replaced {len(edits)} block(s) in {path}.",
+ details={
+ "diff": diff,
+ "patch": generate_unified_patch(path, base, new_content),
+ "first_changed_line": first_changed_line,
+ },
+ )
diff --git a/core/agent_core/tools/edit_diff.py b/core/agent_core/tools/edit_diff.py
new file mode 100644
index 000000000..3596ec0a5
--- /dev/null
+++ b/core/agent_core/tools/edit_diff.py
@@ -0,0 +1,334 @@
+"""Matching and diff helpers for ``edit`` (C-7 section 4).
+
+Ported from Pi ``packages/coding-agent/src/core/tools/edit-diff.ts`` (MIT,
+Copyright (c) 2025 Mario Zechner): exact match first, then Pi's deterministic
+normalized match with no similarity threshold, every edit matched against the
+original, overlapping edits rejected. Avibe adds ``replaceAll`` (from Claude
+Code and OpenCode): every occurrence in the tier that matched, each one a span
+for the overlap check.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+import unicodedata
+from dataclasses import dataclass
+from typing import Optional
+
+BOM = "\ufeff"
+
+# JavaScript's String.prototype.trimEnd set, which Pi uses (Python's isspace differs).
+_TRAILING_SPACE = re.compile("[ \t\v\f\r\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+$")
+_SMART_SINGLE = re.compile("[\u2018\u2019\u201a\u201b]")
+_SMART_DOUBLE = re.compile("[\u201c\u201d\u201e\u201f]")
+_DASHES = re.compile("[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]")
+_SPECIAL_SPACES = re.compile("[\u00a0\u2002-\u200a\u202f\u205f\u3000]")
+_LINES_WITH_ENDINGS = re.compile(r"[^\n]*\n|[^\n]+")
+
+
+class EditError(ValueError):
+ """An edit that cannot be applied; the message is the model-facing error."""
+
+
+@dataclass(frozen=True)
+class Edit:
+ old_text: str
+ new_text: str
+ replace_all: bool = False
+
+
+@dataclass(frozen=True)
+class _Replacement:
+ edit_index: int
+ index: int
+ length: int
+ new_text: str
+
+
+def split_bom(content: str) -> tuple[str, str]:
+ return (BOM, content[1:]) if content.startswith(BOM) else ("", content)
+
+
+def detect_line_ending(content: str) -> str:
+ crlf = content.find("\r\n")
+ lf = content.find("\n")
+ if lf == -1 or crlf == -1:
+ return "\n"
+ return "\r\n" if crlf < lf else "\n"
+
+
+def normalize_to_lf(text: str) -> str:
+ return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def restore_line_endings(text: str, ending: str) -> str:
+ return text.replace("\n", "\r\n") if ending == "\r\n" else text
+
+
+def normalize_for_fuzzy_match(text: str) -> str:
+ """NFKC, no trailing whitespace per line, ASCII quotes and dashes, plain spaces."""
+ text = unicodedata.normalize("NFKC", text)
+ text = "\n".join(_TRAILING_SPACE.sub("", line) for line in text.split("\n"))
+ text = _SMART_SINGLE.sub("'", text)
+ text = _SMART_DOUBLE.sub('"', text)
+ text = _DASHES.sub("-", text)
+ return _SPECIAL_SPACES.sub(" ", text)
+
+
+def _find_all(content: str, needle: str) -> list[int]:
+ found: list[int] = []
+ if not needle:
+ return found
+ index = content.find(needle)
+ while index != -1:
+ found.append(index)
+ index = content.find(needle, index + len(needle))
+ return found
+
+
+def _find(content: str, old_text: str) -> Optional[tuple[int, int, bool]]:
+ """``(index, length, used_fuzzy)`` of the first match, exact before normalized."""
+ exact = content.find(old_text)
+ if exact != -1:
+ return exact, len(old_text), False
+ fuzzy_old = normalize_for_fuzzy_match(old_text)
+ fuzzy = normalize_for_fuzzy_match(content).find(fuzzy_old)
+ if fuzzy == -1:
+ return None
+ return fuzzy, len(fuzzy_old), True
+
+
+def _find_every(content: str, old_text: str) -> list[tuple[int, int]]:
+ """All occurrences in the first tier that has one. ``content`` is already normalized when needed."""
+ exact = _find_all(content, old_text)
+ if exact:
+ return [(index, len(old_text)) for index in exact]
+ fuzzy_old = normalize_for_fuzzy_match(old_text)
+ return [(index, len(fuzzy_old)) for index in _find_all(normalize_for_fuzzy_match(content), fuzzy_old)]
+
+
+def _count_occurrences(content: str, old_text: str) -> int:
+ fuzzy_old = normalize_for_fuzzy_match(old_text)
+ if not fuzzy_old:
+ # Whitespace-only text normalizes to nothing; count it as written.
+ return content.count(old_text)
+ return normalize_for_fuzzy_match(content).count(fuzzy_old)
+
+
+def _not_found(path: str, index: int, total: int) -> EditError:
+ if total == 1:
+ return EditError(
+ f"Could not find the exact text in {path}. The old text must match exactly including all whitespace "
+ "and newlines."
+ )
+ return EditError(
+ f"Could not find edits[{index}] in {path}. The oldText must match exactly including all whitespace and "
+ "newlines."
+ )
+
+
+def _duplicate(path: str, index: int, total: int, occurrences: int) -> EditError:
+ if total == 1:
+ return EditError(
+ f"Found {occurrences} occurrences of the text in {path}. The text must be unique. Please provide more "
+ "context to make it unique."
+ )
+ return EditError(
+ f"Found {occurrences} occurrences of edits[{index}] in {path}. Each oldText must be unique. Please provide "
+ "more context to make it unique."
+ )
+
+
+def _empty(path: str, index: int, total: int) -> EditError:
+ if total == 1:
+ return EditError(f"oldText must not be empty in {path}.")
+ return EditError(f"edits[{index}].oldText must not be empty in {path}.")
+
+
+def _no_change(path: str, total: int) -> EditError:
+ if total == 1:
+ return EditError(
+ f"No changes made to {path}. The replacement produced identical content. This might indicate an issue "
+ "with special characters or the text not existing as expected."
+ )
+ return EditError(f"No changes made to {path}. The replacements produced identical content.")
+
+
+def _apply(content: str, replacements: list[_Replacement], offset: int = 0) -> str:
+ result = content
+ for replacement in reversed(replacements):
+ start = replacement.index - offset
+ result = result[:start] + replacement.new_text + result[start + replacement.length :]
+ return result
+
+
+def _line_spans(content: str) -> list[tuple[int, int]]:
+ spans = []
+ offset = 0
+ for line in _LINES_WITH_ENDINGS.findall(content):
+ spans.append((offset, offset + len(line)))
+ offset += len(line)
+ return spans
+
+
+def _line_range(lines: list[tuple[int, int]], replacement: _Replacement) -> tuple[int, int]:
+ start, end = replacement.index, replacement.index + replacement.length
+ start_line = next((i for i, (lo, hi) in enumerate(lines) if lo <= start < hi), -1)
+ if start_line == -1:
+ raise EditError("Replacement range is outside the base content.")
+ end_line = start_line
+ while end_line < len(lines) and lines[end_line][1] < end:
+ end_line += 1
+ if end_line >= len(lines):
+ raise EditError("Replacement range is outside the base content.")
+ return start_line, end_line + 1
+
+
+def _apply_preserving_unchanged_lines(original: str, base: str, replacements: list[_Replacement]) -> str:
+ """Apply replacements found in the normalized ``base`` to ``original``.
+
+ Lines a replacement touches are rewritten from the normalized base; every
+ other line keeps its original bytes.
+ """
+ original_lines = _LINES_WITH_ENDINGS.findall(original)
+ base_lines = _line_spans(base)
+ if len(original_lines) != len(base_lines):
+ raise EditError("Cannot preserve unchanged lines because the base content has a different line count.")
+ groups: list[list] = [] # [start_line, end_line, replacements]
+ for replacement in sorted(replacements, key=lambda r: r.index):
+ start_line, end_line = _line_range(base_lines, replacement)
+ if groups and start_line < groups[-1][1]:
+ groups[-1][1] = max(groups[-1][1], end_line)
+ groups[-1][2].append(replacement)
+ continue
+ groups.append([start_line, end_line, [replacement]])
+ out: list[str] = []
+ line = 0
+ for start_line, end_line, members in groups:
+ out.append("".join(original_lines[line:start_line]))
+ lo, hi = base_lines[start_line][0], base_lines[end_line - 1][1]
+ out.append(_apply(base[lo:hi], members, lo))
+ line = end_line
+ out.append("".join(original_lines[line:]))
+ return "".join(out)
+
+
+def apply_edits_to_normalized_content(content: str, edits: list[Edit], path: str) -> str:
+ """Apply every edit to LF-normalized ``content`` and return the new content.
+
+ If any edit needs the normalized match, all edits are matched in normalized
+ space and only the touched lines are taken from it.
+ """
+ edits = [Edit(normalize_to_lf(e.old_text), normalize_to_lf(e.new_text), e.replace_all) for e in edits]
+ total = len(edits)
+ for index, edit in enumerate(edits):
+ if not edit.old_text:
+ raise _empty(path, index, total)
+
+ used_fuzzy = any(m is not None and m[2] for m in (_find(content, e.old_text) for e in edits))
+ base = normalize_for_fuzzy_match(content) if used_fuzzy else content
+
+ replacements: list[_Replacement] = []
+ for index, edit in enumerate(edits):
+ if edit.replace_all:
+ spans = _find_every(base, edit.old_text)
+ if not spans:
+ raise _not_found(path, index, total)
+ replacements.extend(_Replacement(index, at, length, edit.new_text) for at, length in spans)
+ continue
+ match = _find(base, edit.old_text)
+ if match is None:
+ raise _not_found(path, index, total)
+ occurrences = _count_occurrences(base, edit.old_text)
+ if occurrences > 1:
+ raise _duplicate(path, index, total, occurrences)
+ replacements.append(_Replacement(index, match[0], match[1], edit.new_text))
+
+ replacements.sort(key=lambda r: r.index)
+ for previous, current in zip(replacements, replacements[1:]):
+ if previous.index + previous.length > current.index:
+ raise EditError(
+ f"edits[{previous.edit_index}] and edits[{current.edit_index}] overlap in {path}. Merge them into "
+ "one edit or target disjoint regions."
+ )
+
+ new_content = (
+ _apply_preserving_unchanged_lines(content, base, replacements) if used_fuzzy else _apply(base, replacements)
+ )
+ if new_content == content:
+ raise _no_change(path, total)
+ return new_content
+
+
+def generate_unified_patch(path: str, old: str, new: str, context: int = 4) -> str:
+ lines = difflib.unified_diff(
+ old.splitlines(keepends=True), new.splitlines(keepends=True), fromfile=path, tofile=path, n=context
+ )
+ return "".join(lines)
+
+
+def generate_diff_string(old: str, new: str, context: int = 4) -> tuple[str, Optional[int]]:
+ """Pi's display diff: numbered ``+``/``-``/context lines and the first changed line of the new file."""
+ old_lines, new_lines = old.split("\n"), new.split("\n")
+ width = len(str(max(len(old_lines), len(new_lines))))
+ parts: list[tuple[str, list[str]]] = []
+ a, b = old.splitlines(), new.splitlines()
+ for tag, i1, i2, j1, j2 in difflib.SequenceMatcher(None, a, b, autojunk=False).get_opcodes():
+ if tag == "equal":
+ parts.append((" ", a[i1:i2]))
+ continue
+ if i2 > i1:
+ parts.append(("-", a[i1:i2]))
+ if j2 > j1:
+ parts.append(("+", b[j1:j2]))
+
+ out: list[str] = []
+ old_no = new_no = 1
+ last_was_change = False
+ first_changed: Optional[int] = None
+ blank = " " * width
+ for position, (kind, raw) in enumerate(parts):
+ if kind != " ":
+ if first_changed is None:
+ first_changed = new_no
+ for line in raw:
+ if kind == "+":
+ out.append(f"+{str(new_no).rjust(width)} {line}")
+ new_no += 1
+ else:
+ out.append(f"-{str(old_no).rjust(width)} {line}")
+ old_no += 1
+ last_was_change = True
+ continue
+
+ trailing = position < len(parts) - 1 and parts[position + 1][0] != " "
+ if last_was_change and trailing and len(raw) > context * 2:
+ shown_head, skipped, shown_tail = raw[:context], len(raw) - 2 * context, raw[-context:]
+ elif last_was_change and trailing:
+ shown_head, skipped, shown_tail = raw, 0, []
+ elif last_was_change:
+ shown_head, skipped, shown_tail = raw[:context], max(0, len(raw) - context), []
+ elif trailing:
+ skipped = max(0, len(raw) - context)
+ shown_head, shown_tail = [], raw[skipped:]
+ else:
+ shown_head, skipped, shown_tail = [], len(raw), []
+ old_no += skipped
+ new_no += skipped
+ last_was_change = False
+ continue
+ for line in shown_head:
+ out.append(f" {str(old_no).rjust(width)} {line}")
+ old_no += 1
+ new_no += 1
+ if skipped:
+ out.append(f" {blank} ...")
+ old_no += skipped
+ new_no += skipped
+ for line in shown_tail:
+ out.append(f" {str(old_no).rjust(width)} {line}")
+ old_no += 1
+ new_no += 1
+ last_was_change = False
+ return "\n".join(out), first_changed
diff --git a/core/agent_core/tools/job_wrapper.py b/core/agent_core/tools/job_wrapper.py
new file mode 100644
index 000000000..30053994d
--- /dev/null
+++ b/core/agent_core/tools/job_wrapper.py
@@ -0,0 +1,150 @@
+"""The process that runs one job's command (``LocalJobHost``'s ``pipe`` backend).
+
+Run as ``python -I -S job_wrapper.py avibe-job <job_dir> <shell> <command>
+<decision_timeout_s> <head_cap> <tail_cap>`` in a new session, so its pid is
+the job's process group. Standard library only: ``-S`` skips site-packages.
+
+1. Write ``pid`` (temporary file, rename).
+2. Wait for ``decision``, at most ``decision_timeout_s``; on timeout, decide
+ ``abandon`` itself through the same exclusive ``link(2)`` the host uses.
+3. Only on ``go``: run ``<shell> -c <command>`` with stdin closed and stdout and
+ stderr into one pipe.
+4. Keep the output bounded on disk: the first ``head_cap`` bytes are appended
+ to ``output.log`` as they arrive; after that, the last ``tail_cap`` bytes are
+ kept in ``tail.log`` (a ``<offset>\\n`` header, then the bytes from that
+ offset of the whole stream), replaced atomically a few times a second.
+5. When the shell exits, read what it wrote, then write ``exit`` (temporary
+ file, rename). Keep reading until every holder of the pipe closes it, so
+ background children are not killed by ``SIGPIPE``.
+"""
+
+from __future__ import annotations
+
+import os
+import select
+import subprocess
+import sys
+import time
+
+_SNAPSHOT_INTERVAL_S = 0.25
+_DRAIN_LIMIT_S = 0.5
+
+
+def _write_atomic(path: str, data: bytes) -> None:
+ tmp = f"{path}.{os.getpid()}.tmp"
+ with open(tmp, "wb") as handle:
+ handle.write(data)
+ os.replace(tmp, path)
+
+
+def _wait_for_decision(job_dir: str, timeout_s: float) -> str:
+ decision = os.path.join(job_dir, "decision")
+ deadline = time.monotonic() + timeout_s
+ delay = 0.001
+ while not os.path.exists(decision):
+ if time.monotonic() >= deadline:
+ tmp = f"{decision}.abandon.{os.getpid()}.tmp"
+ with open(tmp, "w") as handle:
+ handle.write("abandon\n")
+ try:
+ os.link(tmp, decision)
+ except FileExistsError:
+ pass
+ finally:
+ os.unlink(tmp)
+ break
+ time.sleep(delay)
+ delay = min(delay * 2, 0.05)
+ with open(decision) as handle:
+ return handle.read().strip()
+
+
+class _BoundedLog:
+ def __init__(self, job_dir: str, head_cap: int, tail_cap: int) -> None:
+ self._fd = os.open(os.path.join(job_dir, "output.log"), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+ self._tail_path = os.path.join(job_dir, "tail.log")
+ self._head_cap = head_cap
+ self._tail_cap = tail_cap
+ self._total = 0
+ self._tail = bytearray()
+ self._dirty = False
+ self._last_snapshot = 0.0
+
+ def write(self, data: bytes) -> None:
+ if self._total < self._head_cap:
+ head = data[: self._head_cap - self._total]
+ view = memoryview(head)
+ while view:
+ view = view[os.write(self._fd, view) :]
+ self._total += len(head)
+ data = data[len(head) :]
+ if data:
+ self._tail += data
+ self._total += len(data)
+ if len(self._tail) > 2 * self._tail_cap:
+ del self._tail[: len(self._tail) - self._tail_cap]
+ self._dirty = True
+
+ def snapshot(self, *, force: bool = False) -> None:
+ now = time.monotonic()
+ if not self._dirty or (not force and now - self._last_snapshot < _SNAPSHOT_INTERVAL_S):
+ return
+ kept = bytes(self._tail[-self._tail_cap :])
+ _write_atomic(self._tail_path, b"%d\n" % (self._total - len(kept)) + kept)
+ self._dirty = False
+ self._last_snapshot = now
+
+
+def _run(job_dir: str, shell: str, command: str, log: _BoundedLog) -> None:
+ proc = subprocess.Popen(
+ [shell, "-c", command], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+ )
+ fd = proc.stdout.fileno()
+ exit_written = False
+ eof = False
+
+ def write_exit() -> None:
+ code = proc.returncode
+ _write_atomic(os.path.join(job_dir, "exit"), b"%d\n" % (code if code >= 0 else 128 - code))
+
+ while not eof:
+ ready, _, _ = select.select([fd], [], [], 0.05)
+ if ready:
+ chunk = os.read(fd, 65536)
+ if chunk:
+ log.write(chunk)
+ else:
+ eof = True
+ if not exit_written and proc.poll() is not None:
+ # Everything the shell wrote is in the pipe by now; take it before reporting the exit.
+ deadline = time.monotonic() + _DRAIN_LIMIT_S
+ while not eof and time.monotonic() < deadline and select.select([fd], [], [], 0)[0]:
+ chunk = os.read(fd, 65536)
+ if chunk:
+ log.write(chunk)
+ else:
+ eof = True
+ log.snapshot(force=True)
+ write_exit()
+ exit_written = True
+ log.snapshot()
+ log.snapshot(force=True)
+ if not exit_written:
+ proc.wait()
+ write_exit()
+
+
+def main(argv: list[str]) -> int:
+ if len(argv) != 8 or argv[1] != "avibe-job":
+ return 64
+ job_dir, shell, command = argv[2], argv[3], argv[4]
+ decision_timeout_s, head_cap, tail_cap = float(argv[5]), int(argv[6]), int(argv[7])
+ _write_atomic(os.path.join(job_dir, "pid"), b"%d\n" % os.getpid())
+ if _wait_for_decision(job_dir, decision_timeout_s) != "go":
+ return 0
+ _run(job_dir, shell, command, _BoundedLog(job_dir, head_cap, tail_cap))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))
diff --git a/core/agent_core/tools/jobs.py b/core/agent_core/tools/jobs.py
new file mode 100644
index 000000000..2313affd7
--- /dev/null
+++ b/core/agent_core/tools/jobs.py
@@ -0,0 +1,538 @@
+"""``LocalJobHost``: the ``pipe`` backend of ``JobHost`` (C-7 section 7, ``recovery.md`` J1-J6).
+
+Every command runs under ``job_wrapper.py`` in its own session: stdin closed,
+stdout and stderr through a pipe into a bounded log the wrapper keeps. Nothing
+in the host holds a pipe to the job, so any ``LocalJobHost`` over the same
+directory, in this process or after a restart, can read, wait on, or kill it.
+
+Job directory: ``meta.json``, ``pid``, ``decision``, ``output.log`` (the head),
+``tail.log`` (the rolling tail, once the head is full), ``exit``, ``stopped``
+(why the host killed it), ``wrapper.log`` (the wrapper's own diagnostics).
+
+J1, launch handshake: the host writes ``meta.json`` and spawns the wrapper; the
+wrapper writes ``pid`` and waits for ``decision``; the host records the process
+identity in ``meta.json`` (J2), then decides ``go``; the wrapper runs the
+command only on ``go``, and decides ``abandon`` itself if no decision comes in
+time. A decision is created exclusively, through ``link(2)`` of a written
+temporary file, so exactly one side decides and nobody reads it half-written.
+Recovery decides ``abandon`` for a job that has none; a missing or late
+``pid`` proves nothing.
+
+J2, identity: the wrapper's argv names the job directory, a random path no
+recycled pid carries, and argv is readable on every POSIX platform. The
+inherited ``AVIBE_PROCESS_IDENTITY`` marker is set and fingerprinted as well,
+but macOS hides the environment of its own binaries (``/bin/bash``,
+``/bin/sleep``), so the marker only verifies a group whose wrapper has exited.
+
+J3: ``meta.json.deadline_at`` is absolute; ``wait`` and ``enforce_deadline``
+kill the tree once it passes, whoever holds the job.
+
+POSIX only in v1.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import secrets
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+from typing import Any, Awaitable, Callable, Mapping, Optional
+
+import psutil
+
+from core.agent_core.tools.base import JobStatus
+from core.process_isolation import (
+ DEFAULT_PROCESS_TERMINATE_TIMEOUT_SECONDS,
+ KILL_SIGNAL,
+ PROCESS_IDENTITY_ENV,
+ PersistedProcessIdentity,
+ capture_spawned_process_identity,
+ new_process_identity_marker,
+ process_group_identity_status,
+ process_identity_from_payload,
+ serialize_process_identity,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Adopt-or-create the once Watch (target kind ``job``) for the job's ``meta.json``; returns the Watch id.
+#: Keyed by ``job_id``, so calling it again after a crash returns the same Watch (J6).
+HandOver = Callable[[Mapping[str, Any]], Awaitable[str]]
+#: Whether the tool call that owns a job has a durable ``tool_result`` and its Watch, if any, has settled (J5).
+Settled = Callable[[Mapping[str, Any]], bool]
+
+#: How long the wrapper waits for the host's decision before abandoning the command.
+DECISION_TIMEOUT_S = 30.0
+#: The host gives up on the wrapper's ``pid`` well before the wrapper gives up on a decision.
+PID_TIMEOUT_S = 10.0
+#: Output kept on disk per job (J4): this much from the start and this much from the end.
+OUTPUT_HEAD_BYTES = 1024 * 1024
+OUTPUT_TAIL_BYTES = 2 * 1024 * 1024
+OUTPUT_CHUNK_BYTES = 1024 * 1024
+FINISHED_JOB_RETENTION_S = 7 * 24 * 3600
+
+STOP_TIMEOUT = "timeout"
+
+_WRAPPER = os.path.join(os.path.dirname(os.path.abspath(__file__)), "job_wrapper.py")
+_JOB_ID = re.compile(r"^job_[a-z0-9]+$")
+_GO = "go"
+_ABANDON = "abandon"
+
+
+class JobStartError(RuntimeError):
+ """The command was not started; nothing ran."""
+
+
+class JobHandOverUnavailable(RuntimeError):
+ """This host has no Watch to hand a job to."""
+
+
+def default_shell() -> str:
+ """Pi's choice: ``/bin/bash``, then ``bash`` on PATH, then ``sh``."""
+ if os.path.exists("/bin/bash"):
+ return "/bin/bash"
+ return shutil.which("bash") or "sh"
+
+
+def _iso(moment: datetime) -> str:
+ return moment.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _ceil_ms(moment: datetime) -> datetime:
+ """Round up to the millisecond ``_iso`` keeps, so a recorded deadline is never early."""
+ rest = moment.microsecond % 1000
+ return moment + timedelta(microseconds=1000 - rest) if rest else moment
+
+
+def _parse_iso(value: str) -> datetime:
+ return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _write_atomic(path: str, data: str) -> None:
+ tmp = f"{path}.{secrets.token_hex(4)}.tmp"
+ with open(tmp, "w", encoding="utf-8") as handle:
+ handle.write(data)
+ os.replace(tmp, path)
+
+
+def _read_text(path: str) -> Optional[str]:
+ try:
+ with open(path, encoding="utf-8") as handle:
+ return handle.read().strip()
+ except FileNotFoundError:
+ return None
+
+
+class LocalJobHost:
+ """Job handles under ``jobs_dir`` (``<state>/agent_core/jobs``).
+
+ ``hand_over`` delegates to ``on_hand_over``, which the adapter backs with
+ Watch; without it, ``hand_over`` raises ``JobHandOverUnavailable``.
+ """
+
+ def __init__(
+ self,
+ jobs_dir: str,
+ *,
+ on_hand_over: Optional[HandOver] = None,
+ shell: Optional[str] = None,
+ ) -> None:
+ self._jobs_dir = os.path.abspath(jobs_dir)
+ self._on_hand_over = on_hand_over
+ self._shell = shell or default_shell()
+ # Wrappers this host spawned. Each has a reaper thread, so a finished wrapper never lingers
+ # as a zombie (which would keep its process group alive), and an unreaped pid cannot be recycled.
+ self._children: dict[str, subprocess.Popen] = {}
+
+ # --- paths and metadata ---------------------------------------------
+
+ def job_dir(self, job_id: str) -> str:
+ if not _JOB_ID.match(job_id):
+ raise KeyError(job_id)
+ return os.path.join(self._jobs_dir, job_id)
+
+ def _path(self, job_id: str, name: str) -> str:
+ return os.path.join(self.job_dir(job_id), name)
+
+ def output_path(self, job_id: str) -> str:
+ return self._path(job_id, "output.log")
+
+ def meta(self, job_id: str) -> dict[str, Any]:
+ try:
+ with open(self._path(job_id, "meta.json"), encoding="utf-8") as handle:
+ return json.load(handle)
+ except FileNotFoundError:
+ raise KeyError(job_id) from None
+
+ def _write_meta(self, job_id: str, meta: Mapping[str, Any]) -> None:
+ _write_atomic(self._path(job_id, "meta.json"), json.dumps(meta, indent=2))
+
+ def find_job(self, session_id: str, tool_call_id: str) -> Optional[str]:
+ """The job started for a tool call, for settling it at resume."""
+ for name in self._job_ids():
+ try:
+ meta = self.meta(name)
+ except (KeyError, ValueError, OSError):
+ continue
+ if meta.get("session_id") == session_id and meta.get("tool_call_id") == tool_call_id:
+ return name
+ return None
+
+ def _job_ids(self) -> list[str]:
+ try:
+ return sorted(name for name in os.listdir(self._jobs_dir) if _JOB_ID.match(name))
+ except FileNotFoundError:
+ return []
+
+ # --- decision (J1) ----------------------------------------------------
+
+ def _create_decision(self, job_id: str, value: str) -> str:
+ """Try to decide; return the decision that holds, ours or the wrapper's."""
+ decision = self._path(job_id, "decision")
+ tmp = f"{decision}.{value}.{secrets.token_hex(4)}.tmp"
+ with open(tmp, "w", encoding="utf-8") as handle:
+ handle.write(f"{value}\n")
+ try:
+ os.link(tmp, decision)
+ except FileExistsError:
+ pass
+ finally:
+ os.unlink(tmp)
+ return _read_text(decision) or _ABANDON
+
+ def _decision(self, job_id: str) -> str:
+ """The job's decision; a job without one is abandoned now, as recovery requires."""
+ current = _read_text(self._path(job_id, "decision"))
+ if current is not None:
+ return current
+ self.meta(job_id) # an unknown job raises KeyError
+ return self._create_decision(job_id, _ABANDON)
+
+ def started(self, job_id: str) -> bool:
+ """Whether the command may have run. ``False`` is final: it never ran and never will."""
+ return self._decision(job_id) == _GO
+
+ # --- JobHost ------------------------------------------------------------
+
+ async def start(
+ self,
+ command: str,
+ *,
+ cwd: str,
+ env: Mapping[str, str],
+ timeout_s: Optional[float],
+ session_id: str,
+ tool_call_id: str,
+ ) -> str:
+ """Start ``command`` with ``env`` as its whole environment; return once it may run.
+
+ Raises ``JobStartError`` when the command did not start.
+ """
+ if os.name != "posix":
+ raise JobStartError("Command jobs are not supported on Windows yet.")
+ if not sys.executable:
+ raise JobStartError("No Python interpreter is available to run the command.")
+ job_id = f"job_{secrets.token_hex(8)}"
+ job_dir = self.job_dir(job_id)
+ os.makedirs(self._jobs_dir, exist_ok=True)
+ os.mkdir(job_dir, 0o700)
+ created = datetime.now(timezone.utc)
+ meta: dict[str, Any] = {
+ "version": 1,
+ "job_id": job_id,
+ "session_id": session_id,
+ "tool_call_id": tool_call_id,
+ "backend": "pipe",
+ "command": command,
+ "cwd": cwd,
+ "timeout_s": timeout_s,
+ "created_at": _iso(created),
+ "state_dir": job_dir,
+ "process": None,
+ "terminal": None,
+ "watch_id": None,
+ "deadline_at": _iso(_ceil_ms(created + timedelta(seconds=timeout_s))) if timeout_s is not None else None,
+ }
+ self._write_meta(job_id, meta)
+
+ marker = new_process_identity_marker()
+ child_env = dict(env)
+ child_env[PROCESS_IDENTITY_ENV] = marker
+ argv = [
+ sys.executable,
+ "-I",
+ "-S",
+ _WRAPPER,
+ "avibe-job",
+ job_dir,
+ self._shell,
+ command,
+ repr(DECISION_TIMEOUT_S),
+ str(OUTPUT_HEAD_BYTES),
+ str(OUTPUT_TAIL_BYTES),
+ ]
+ open(self.output_path(job_id), "ab").close()
+ diagnostics = os.open(self._path(job_id, "wrapper.log"), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+ try:
+ proc = subprocess.Popen(
+ argv,
+ cwd=cwd,
+ env=child_env,
+ stdin=subprocess.DEVNULL,
+ stdout=diagnostics,
+ stderr=diagnostics,
+ start_new_session=True,
+ )
+ except OSError as exc:
+ self._create_decision(job_id, _ABANDON)
+ raise JobStartError(f"Could not start the command: {exc}") from exc
+ finally:
+ os.close(diagnostics)
+ self._children[job_id] = proc
+ threading.Thread(target=proc.wait, name=f"avibe-{job_id}-reaper", daemon=True).start()
+
+ identity = await self._await_pid(job_id, proc, marker)
+ if identity is not None:
+ meta["process"] = {**serialize_process_identity(identity), "pgid": identity.pid}
+ self._write_meta(job_id, meta)
+ decision = self._create_decision(job_id, _GO if identity is not None else _ABANDON)
+ if decision != _GO:
+ raise JobStartError("The command did not start.")
+ return job_id
+
+ async def _await_pid(self, job_id: str, proc: subprocess.Popen, marker: str) -> Optional[PersistedProcessIdentity]:
+ deadline = time.monotonic() + PID_TIMEOUT_S
+ pid_path = self._path(job_id, "pid")
+ while time.monotonic() < deadline:
+ text = _read_text(pid_path)
+ if text:
+ try:
+ pgid = os.getpgid(proc.pid)
+ except ProcessLookupError:
+ return None
+ if text != str(proc.pid) or pgid != proc.pid:
+ logger.error("Job %s wrapper reported pid %s, expected %s", job_id, text, proc.pid)
+ return None
+ return capture_spawned_process_identity(proc.pid, marker)
+ if proc.poll() is not None:
+ return None
+ await asyncio.sleep(0.002)
+ return None
+
+ def status(self, job_id: str) -> JobStatus:
+ exit_code = self._exit_code(job_id)
+ if exit_code is not None:
+ self._reap(job_id)
+ return JobStatus("exited", exit_code)
+ if self._decision(job_id) != _GO:
+ return JobStatus("gone")
+ if self._alive(job_id):
+ return JobStatus("running")
+ # The wrapper writes `exit` before it exits, so look once more.
+ exit_code = self._exit_code(job_id)
+ self._reap(job_id)
+ return JobStatus("exited", exit_code) if exit_code is not None else JobStatus("gone")
+
+ async def wait(self, job_id: str, *, deadline_s: Optional[float]) -> JobStatus:
+ """Wait until exit, or at most ``deadline_s`` seconds from now; enforce the job's own deadline meanwhile."""
+ end = None if deadline_s is None else time.monotonic() + max(0.0, deadline_s)
+ delay = 0.005
+ while True:
+ if await self.enforce_deadline(job_id):
+ return self.status(job_id)
+ current = self.status(job_id)
+ if current.state != "running":
+ return current
+ if end is not None:
+ remaining = end - time.monotonic()
+ if remaining <= 0:
+ return current
+ delay = min(delay, remaining)
+ await asyncio.sleep(delay)
+ delay = min(delay * 2, 0.1)
+
+ def output(self, job_id: str, since: int = 0) -> tuple[bytes, int]:
+ """At most ``OUTPUT_CHUNK_BYTES`` of raw output after offset ``since``; call again until empty.
+
+ Offsets count the command's whole output. Past the kept head, a reader
+ that falls behind the kept tail jumps forward: the new offset then
+ exceeds ``since + len(data)`` by the bytes dropped from disk (J4).
+ """
+ head_path = self.output_path(job_id)
+ try:
+ head_size = os.path.getsize(head_path)
+ except FileNotFoundError:
+ self.meta(job_id)
+ return b"", since
+ if since < head_size:
+ with open(head_path, "rb") as handle:
+ handle.seek(since)
+ data = handle.read(min(OUTPUT_CHUNK_BYTES, head_size - since))
+ return data, since + len(data)
+ try:
+ with open(self._path(job_id, "tail.log"), "rb") as handle:
+ tail_start = int(handle.readline())
+ start = max(since, tail_start)
+ handle.seek(start - tail_start, os.SEEK_CUR)
+ data = handle.read(OUTPUT_CHUNK_BYTES)
+ except (FileNotFoundError, ValueError):
+ return b"", since
+ return data, start + len(data)
+
+ async def kill(self, job_id: str, *, reason: str = "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
+ job later can say why it ended.
+ """
+ if self._decision(job_id) != _GO:
+ return
+ identity = self._identity(job_id)
+ if identity is None:
+ logger.warning("Job %s has no recorded process identity; not signaling", job_id)
+ return
+ if not (self._alive(job_id) or self._group_carries_marker(identity)):
+ if _group_exists(identity.pid):
+ logger.warning("Job %s process group %s cannot be verified; not signaling", job_id, identity.pid)
+ return
+ if _read_text(self._path(job_id, "stopped")) is None:
+ _write_atomic(self._path(job_id, "stopped"), f"{reason}\n")
+ if not await asyncio.to_thread(_terminate_group, identity.pid):
+ logger.warning("Job %s process group %s survived termination", job_id, identity.pid)
+ self._reap(job_id)
+
+ async def hand_over(self, job_id: str) -> str:
+ """Give the job to its Watch: adopt-or-create through ``on_hand_over``, then record the id (J6)."""
+ meta = self.meta(job_id)
+ if meta.get("watch_id"):
+ return meta["watch_id"]
+ if self._on_hand_over is None:
+ raise JobHandOverUnavailable("No Watch is available to take over the command.")
+ watch_id = await self._on_hand_over(meta)
+ meta = self.meta(job_id)
+ meta["watch_id"] = watch_id
+ self._write_meta(job_id, meta)
+ return watch_id
+
+ # --- deadline (J3) and reporting --------------------------------------
+
+ async def enforce_deadline(self, job_id: str) -> bool:
+ """Kill the job if its ``deadline_at`` has passed while it runs; ``True`` if it was killed."""
+ deadline_at = self.meta(job_id).get("deadline_at")
+ if not deadline_at or datetime.now(timezone.utc) < _parse_iso(deadline_at):
+ return False
+ if self.status(job_id).state != "running":
+ return False
+ await self.kill(job_id, reason=STOP_TIMEOUT)
+ return True
+
+ def stop_reason(self, job_id: str) -> Optional[str]:
+ """Why the host killed the job (``"timeout"``, or the caller's reason), if it did."""
+ return _read_text(self._path(job_id, "stopped"))
+
+ # --- maintenance (J5) -------------------------------------------------
+
+ def prune(self, settled: Settled, *, older_than_s: float = FINISHED_JOB_RETENTION_S) -> list[str]:
+ """Remove jobs that are finished, settled (``settled(meta)``), and untouched for ``older_than_s``."""
+ removed: list[str] = []
+ cutoff = time.time() - older_than_s
+ for name in self._job_ids():
+ try:
+ job_dir = self.job_dir(name)
+ if max(entry.stat().st_mtime for entry in os.scandir(job_dir)) > cutoff:
+ continue
+ if self.status(name).state == "running" or not settled(self.meta(name)):
+ continue
+ except (KeyError, ValueError, OSError):
+ continue
+ shutil.rmtree(job_dir, ignore_errors=True)
+ removed.append(name)
+ return removed
+
+ # --- internals --------------------------------------------------------
+
+ def _exit_code(self, job_id: str) -> Optional[int]:
+ text = _read_text(self._path(job_id, "exit"))
+ if text is None:
+ return None
+ try:
+ return int(text)
+ except ValueError:
+ return None
+
+ def _identity(self, job_id: str) -> Optional[PersistedProcessIdentity]:
+ process = self.meta(job_id).get("process")
+ if not isinstance(process, dict) or process.get("pgid") != process.get("pid"):
+ return None
+ return process_identity_from_payload(
+ {key: process.get(key) for key in ("pid", "create_time", "worker_fingerprint")}, process.get("pid")
+ )
+
+ def _alive(self, job_id: str) -> bool:
+ """Whether the job's wrapper still runs: our unreaped child, or the process whose argv names this job."""
+ child = self._children.get(job_id)
+ if child is not None:
+ return child.returncode is None
+ identity = self._identity(job_id)
+ if identity is None:
+ return False
+ try:
+ argv = psutil.Process(identity.pid).cmdline()
+ except (psutil.Error, OSError):
+ # Gone, a zombie, or unreadable: none of them proves the job still runs.
+ return False
+ job_dir = self.job_dir(job_id)
+ return any(argv[i : i + 2] == ["avibe-job", job_dir] for i in range(len(argv) - 1))
+
+ def _group_carries_marker(self, identity: PersistedProcessIdentity) -> bool:
+ return process_group_identity_status(identity.pid, identity, logger, "agent job") == "match"
+
+ def _reap(self, job_id: str) -> None:
+ child = self._children.get(job_id)
+ if child is not None and child.returncode is not None:
+ del self._children[job_id]
+
+
+def _group_exists(pgid: int) -> bool:
+ try:
+ os.killpg(pgid, 0)
+ except ProcessLookupError:
+ return False
+ except PermissionError:
+ return True
+ return True
+
+
+def _terminate_group(pgid: int, timeout_s: float = DEFAULT_PROCESS_TERMINATE_TIMEOUT_SECONDS) -> bool:
+ """SIGTERM the verified group, then SIGKILL what is left; ``True`` once the group is gone.
+
+ The group was verified just before. A process group id is not reused while
+ the group exists, so signaling it until it is gone reaches only its members.
+ """
+ if pgid <= 1 or pgid == os.getpgrp():
+ logger.error("Refusing to signal process group %s", pgid)
+ return False
+ for sig in (signal.SIGTERM, KILL_SIGNAL):
+ try:
+ os.killpg(pgid, sig)
+ except ProcessLookupError:
+ return True
+ except PermissionError:
+ return False
+ deadline = time.monotonic() + timeout_s
+ while _group_exists(pgid):
+ if time.monotonic() >= deadline:
+ break
+ time.sleep(0.02)
+ else:
+ return True
+ return not _group_exists(pgid)
diff --git a/core/agent_core/tools/normalize.py b/core/agent_core/tools/normalize.py
new file mode 100644
index 000000000..79e8c0c96
--- /dev/null
+++ b/core/agent_core/tools/normalize.py
@@ -0,0 +1,117 @@
+"""The output normalizer for command output (C-7 section 6).
+
+Every command output the model sees passes through here before the caps:
+decode UTF-8 with replacement, strip ANSI escape sequences, and collapse
+carriage-return redraws to the final line state. ``pipe`` output rarely needs
+more than the decode; the future ``pty`` backend needs all of it.
+
+A redrawn line keeps its last non-empty segment: ``"10%\\r55%\\r100%\\n"``
+becomes ``"100%\\n"``, and ``"done\\r"`` at the end stays ``"done"``. ``"\\r\\n"``
+is a line break, never a redraw.
+"""
+
+from __future__ import annotations
+
+import codecs
+import re
+
+_ANSI_RE = re.compile(
+ r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)" # OSC ... BEL or ST
+ r"|\x1b[P^_][^\x1b]*\x1b\\" # DCS, PM, APC ... ST
+ r"|\x1b\[[0-?]*[ -/]*[@-~]" # CSI
+ r"|\x1b[ -/]*[0-~]" # other escape sequences
+ r"|\x9b[0-?]*[ -/]*[@-~]" # 8-bit CSI
+)
+# An escape sequence that may still be incomplete at the end of a chunk.
+_HOLD_BACK_CHARS = 64
+# An open line (no newline yet) is committed once its current segment grows past this.
+_MAX_OPEN_CHARS = 64 * 1024
+
+
+def strip_ansi(text: str) -> str:
+ return _ANSI_RE.sub("", text).replace("\x1b", "")
+
+
+def _collapse(segments: list[str]) -> str:
+ """The last segment that still shows something once escape sequences are gone."""
+ for segment in reversed(segments):
+ visible = strip_ansi(segment)
+ if visible:
+ return visible
+ return ""
+
+
+class OutputNormalizer:
+ """Incremental normalizer: feed raw bytes, receive normalized text.
+
+ ``feed`` returns only text that is final (complete lines, or an over-long
+ open line); ``peek`` shows the open line as it would read now.
+ """
+
+ def __init__(self) -> None:
+ self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+ self._carry_cr = False
+ self._prev = "" # last non-empty finished segment of the open line
+ self._cur = "" # segment after the last carriage return of the open line
+
+ def feed(self, data: bytes) -> str:
+ return self._consume(self._decoder.decode(data))
+
+ def flush(self) -> str:
+ out = self._consume(self._decoder.decode(b"", final=True))
+ if self._carry_cr:
+ self._carry_cr = False
+ self._open_segments("\r")
+ tail = _collapse([self._prev, self._cur])
+ self._prev = self._cur = ""
+ return out + tail
+
+ def peek(self) -> str:
+ return _collapse([self._prev, self._cur])
+
+ def _consume(self, text: str) -> str:
+ if self._carry_cr:
+ text = "\r" + text
+ self._carry_cr = False
+ if not text:
+ return ""
+ if text.endswith("\r"):
+ # Possibly the first half of "\r\n"; decide with the next chunk.
+ self._carry_cr = True
+ text = text[:-1]
+ out: list[str] = []
+ lines = text.split("\n")
+ for line in lines[:-1]:
+ if line.endswith("\r"):
+ line = line[:-1]
+ self._open_segments(line)
+ out.append(_collapse([self._prev, self._cur]) + "\n")
+ self._prev = self._cur = ""
+ self._open_segments(lines[-1])
+ if len(self._cur) > _MAX_OPEN_CHARS:
+ out.append(self._commit_open())
+ return "".join(out)
+
+ def _open_segments(self, text: str) -> None:
+ segments = (self._cur + text).split("\r")
+ if len(segments) > 1:
+ for segment in reversed(segments[:-1]):
+ if strip_ansi(segment):
+ self._prev = segment
+ break
+ self._cur = segments[-1]
+
+ def _commit_open(self) -> str:
+ # Bound memory on a line that never ends; keep a possibly incomplete escape.
+ cut = len(self._cur)
+ escape = self._cur.rfind("\x1b", max(0, cut - _HOLD_BACK_CHARS))
+ if escape != -1 and not _ANSI_RE.match(self._cur, escape):
+ cut = escape
+ committed, self._cur = self._cur[:cut], self._cur[cut:]
+ self._prev = ""
+ return strip_ansi(committed)
+
+
+def normalize_output(data: bytes) -> str:
+ normalizer = OutputNormalizer()
+ return normalizer.feed(data) + normalizer.flush()
diff --git a/core/agent_core/tools/output.py b/core/agent_core/tools/output.py
new file mode 100644
index 000000000..1a5b4892d
--- /dev/null
+++ b/core/agent_core/tools/output.py
@@ -0,0 +1,171 @@
+"""Bounded tail of a job's output, with Pi's ``bash`` truncation notices (C-7 section 5).
+
+``OutputAccumulator`` is ported from Pi
+``packages/coding-agent/src/core/tools/output-accumulator.ts`` and the notices
+from ``bash.ts`` (MIT, Copyright (c) 2025 Mario Zechner). Pi spills to a temp
+file once output passes the caps; a job's ``output.log`` already is the full
+output, so only the rolling tail and the counters remain.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Optional
+
+from core.agent_core.tools.base import MAX_BYTES, MAX_LINES, JobHost
+from core.agent_core.tools.normalize import OutputNormalizer
+from core.agent_core.tools.truncate import TruncationResult, format_size, truncate_tail, utf8_len
+
+
+class OutputAccumulator:
+ """Counts every line and byte of normalized output and keeps a tail of at most ``4 * max_bytes``."""
+
+ def __init__(self, *, max_lines: int = MAX_LINES, max_bytes: int = MAX_BYTES) -> None:
+ self._max_lines = max_lines
+ self._max_bytes = max_bytes
+ self._max_rolling = max(max_bytes * 2, 1)
+ self._tail = ""
+ self._tail_bytes = 0
+ self._tail_starts_at_line_boundary = True
+ self._total_bytes = 0
+ self._completed_lines = 0
+ self._current_line_bytes = 0
+ self._has_open_line = False
+
+ def append(self, text: str) -> None:
+ if not text:
+ return
+ size = utf8_len(text)
+ self._total_bytes += size
+ self._tail += text
+ self._tail_bytes += size
+ if self._tail_bytes > self._max_rolling * 2:
+ self._trim()
+ newlines = text.count("\n")
+ if newlines == 0:
+ self._current_line_bytes += size
+ self._has_open_line = True
+ else:
+ self._completed_lines += newlines
+ rest = text[text.rindex("\n") + 1 :]
+ self._current_line_bytes = utf8_len(rest)
+ self._has_open_line = bool(rest)
+
+ def snapshot(self, open_line: str = "") -> TruncationResult:
+ """The tail as the model would see it, with ``open_line`` (not yet final) appended."""
+ extra = utf8_len(open_line)
+ total_bytes = self._total_bytes + extra
+ total_lines = self._completed_lines + (1 if self._has_open_line or open_line else 0)
+ tail = truncate_tail(self._snapshot_text() + open_line, max_lines=self._max_lines, max_bytes=self._max_bytes)
+ truncated = total_lines > self._max_lines or total_bytes > self._max_bytes
+ truncated_by = None
+ if truncated:
+ truncated_by = tail.truncated_by or ("bytes" if total_bytes > self._max_bytes else "lines")
+ return replace(
+ tail, truncated=truncated, truncated_by=truncated_by, total_lines=total_lines, total_bytes=total_bytes
+ )
+
+ def last_line_bytes(self, open_line: str = "") -> int:
+ return (self._current_line_bytes if self._has_open_line else 0) + utf8_len(open_line)
+
+ def _trim(self) -> None:
+ data = self._tail.encode("utf-8", "surrogatepass")
+ if len(data) <= self._max_rolling:
+ self._tail_bytes = len(data)
+ return
+ start = len(data) - self._max_rolling
+ while start < len(data) and (data[start] & 0xC0) == 0x80:
+ start += 1
+ if start:
+ self._tail_starts_at_line_boundary = data[start - 1] == 0x0A
+ self._tail = data[start:].decode("utf-8", "replace")
+ self._tail_bytes = utf8_len(self._tail)
+
+ def _snapshot_text(self) -> str:
+ if self._tail_starts_at_line_boundary:
+ return self._tail
+ newline = self._tail.find("\n")
+ return self._tail if newline == -1 else self._tail[newline + 1 :]
+
+
+class JobOutput:
+ """Follows a job's raw output through the normalizer into an accumulator."""
+
+ def __init__(self, jobs: JobHost, job_id: str) -> None:
+ self._jobs = jobs
+ self._job_id = job_id
+ self._offset = 0
+ self._normalizer = OutputNormalizer()
+ self._accumulator = OutputAccumulator()
+ self._finished = False
+ self._omitted = 0
+
+ @property
+ def path(self) -> str:
+ return self._jobs.output_path(self._job_id)
+
+ def poll(self) -> bool:
+ """Read everything written so far; ``True`` if there was anything new."""
+ changed = False
+ while True:
+ data, offset = self._jobs.output(self._job_id, self._offset)
+ skipped = offset - len(data) - self._offset
+ self._offset = offset
+ if skipped > 0:
+ # The host dropped this part of a long output from disk.
+ self._omitted += skipped
+ self._accumulator.append(self._normalizer.feed(f"\n[... {skipped} bytes omitted ...]\n".encode()))
+ if not data:
+ return changed or skipped > 0
+ changed = True
+ self._accumulator.append(self._normalizer.feed(data))
+
+ def finish(self) -> None:
+ """Read the rest and end the stream; call once the job is no longer running."""
+ if self._finished:
+ return
+ self.poll()
+ self._accumulator.append(self._normalizer.flush())
+ self._finished = True
+
+ def snapshot(self) -> TruncationResult:
+ return self._accumulator.snapshot("" if self._finished else self._normalizer.peek())
+
+ def render(self, empty_text: str) -> tuple[str, Optional[TruncationResult]]:
+ """Pi's ``formatOutput``: the tail (or ``empty_text``) and, when truncated, the notice naming the full output."""
+ truncation = self.snapshot()
+ text = truncation.content or empty_text
+ if not truncation.truncated:
+ return text, None
+ path = self.path
+ start = truncation.total_lines - truncation.output_lines + 1
+ end = truncation.total_lines
+ if truncation.last_line_partial:
+ open_line = "" if self._finished else self._normalizer.peek()
+ line_size = format_size(self._accumulator.last_line_bytes(open_line))
+ notice = (
+ f"[Showing last {format_size(truncation.output_bytes)} of line {end} (line is {line_size}). "
+ f"Full output: {path}]"
+ )
+ elif truncation.truncated_by == "lines":
+ notice = f"[Showing lines {start}-{end} of {truncation.total_lines}. Full output: {path}]"
+ else:
+ notice = (
+ f"[Showing lines {start}-{end} of {truncation.total_lines} ({format_size(MAX_BYTES)} limit). "
+ f"Full output: {path}]"
+ )
+ if self._omitted:
+ # Only LocalJobHost drops output, and it keeps the end in tail.log next to output.log.
+ notice += (
+ f"\n[{format_size(self._omitted)} from the middle of the output was not kept on disk: "
+ "output.log holds the start, tail.log beside it the end.]"
+ )
+ return f"{text}\n\n{notice}", truncation
+
+ def details(self, truncation: Optional[TruncationResult]) -> dict[str, Any]:
+ out: dict[str, Any] = {"job_id": self._job_id, "full_output_path": self.path}
+ if self._omitted:
+ out["omitted_bytes"] = self._omitted
+ if truncation is not None:
+ out["truncation"] = truncation.to_details()
+ return out
diff --git a/core/agent_core/tools/paths.py b/core/agent_core/tools/paths.py
new file mode 100644
index 000000000..e61a67d7a
--- /dev/null
+++ b/core/agent_core/tools/paths.py
@@ -0,0 +1,86 @@
+"""Path resolution and per-file mutation serialization for the file tools.
+
+Ported from Pi ``packages/coding-agent/src/core/tools/path-utils.ts``,
+``file-mutation-queue.ts``, and ``src/utils/paths.ts`` (MIT, Copyright (c) 2025
+Mario Zechner).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import unicodedata
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+from urllib.parse import unquote, urlparse
+
+_UNICODE_SPACES = re.compile("[\u00a0\u2000-\u200a\u202f\u205f\u3000]")
+_NARROW_NO_BREAK_SPACE = "\u202f"
+_AM_PM = re.compile(r" (AM|PM)\.", re.IGNORECASE)
+
+
+def expand_path(path: str) -> str:
+ """Normalize a model-supplied path: Unicode spaces, a leading ``@``, ``~``, ``file://``."""
+ value = _UNICODE_SPACES.sub(" ", path)
+ if value.startswith("@"):
+ value = value[1:]
+ if value == "~" or value.startswith("~/"):
+ value = os.path.expanduser(value)
+ if value.startswith("file://"):
+ value = unquote(urlparse(value).path)
+ return value
+
+
+def resolve_to_cwd(path: str, cwd: str) -> str:
+ expanded = expand_path(path)
+ if os.path.isabs(expanded):
+ return os.path.normpath(expanded)
+ return os.path.normpath(os.path.join(cwd, expanded))
+
+
+def resolve_read_path(path: str, cwd: str) -> str:
+ """Like ``resolve_to_cwd``, also trying the spellings macOS uses in screenshot names."""
+ resolved = resolve_to_cwd(path, cwd)
+ if os.path.exists(resolved):
+ return resolved
+ am_pm = _AM_PM.sub(lambda m: f"{_NARROW_NO_BREAK_SPACE}{m.group(1)}.", resolved)
+ nfd = unicodedata.normalize("NFD", resolved)
+ curly = resolved.replace("'", "\u2019")
+ nfd_curly = nfd.replace("'", "\u2019")
+ for candidate in (am_pm, nfd, curly, nfd_curly):
+ if candidate != resolved and os.path.exists(candidate):
+ return candidate
+ return resolved
+
+
+class _PathLock:
+ __slots__ = ("lock", "users")
+
+ def __init__(self) -> None:
+ self.lock = asyncio.Lock()
+ self.users = 0
+
+
+_locks: dict[str, _PathLock] = {}
+
+
+@asynccontextmanager
+async def file_mutation_lock(path: str) -> AsyncIterator[None]:
+ """Serialize ``write`` and ``edit`` on one file, keyed by its canonical path.
+
+ Different files proceed in parallel. The key follows symlinks, so two names
+ for one file share a lock.
+ """
+ key = os.path.realpath(path)
+ entry = _locks.get(key)
+ if entry is None:
+ entry = _locks[key] = _PathLock()
+ entry.users += 1
+ try:
+ async with entry.lock:
+ yield
+ finally:
+ entry.users -= 1
+ if entry.users == 0:
+ del _locks[key]
diff --git a/core/agent_core/tools/read.py b/core/agent_core/tools/read.py
new file mode 100644
index 000000000..f471c9840
--- /dev/null
+++ b/core/agent_core/tools/read.py
@@ -0,0 +1,288 @@
+"""The ``read`` tool (C-7 section 2).
+
+Ported from Pi ``packages/coding-agent/src/core/tools/read.ts`` and
+``src/utils/mime.ts`` (MIT, Copyright (c) 2025 Mario Zechner); the description
+and every model-facing string are Pi's unless marked as Avibe's.
+
+Unlike Pi, the file is streamed: only the lines that can reach the model are
+kept in memory, so reading a multi-gigabyte log cannot exhaust the process the
+loop shares with the rest of Avibe. The result is the same as Pi's.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import struct
+from typing import Any, Awaitable, Callable, Mapping, Optional, Union
+
+from core.agent_core.messages import IMAGE_MIME_TYPES, ImageBlock, TextBlock
+from core.agent_core.tools.args import (
+ ToolInputError,
+ error_result,
+ format_number,
+ optional_number_arg,
+ os_error_text,
+ str_arg,
+ text_result,
+)
+from core.agent_core.tools.base import MAX_BYTES, MAX_LINES, ToolContext, ToolResult, ToolSpec
+from core.agent_core.tools.paths import resolve_read_path
+from core.agent_core.tools.truncate import format_size, truncate_head
+
+#: Stores an image for the transcript and returns its media token: ``(data, mime_type, name)``.
+ImageSink = Callable[[bytes, str, str], Union[str, Awaitable[str]]]
+
+# Pi keeps images under 4.5MB of base64 payload, below Anthropic's 5MB limit. Avibe v1 does not
+# resize, so the cap applies to the file as it is.
+MAX_INLINE_IMAGE_BYTES = int(4.5 * 1024 * 1024) * 3 // 4
+_IMAGE_SNIFF_BYTES = 4100
+_READ_CHUNK_BYTES = 1024 * 1024
+
+READ_DESCRIPTION = (
+ "Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as "
+ f"attachments. For text files, output is truncated to {MAX_LINES} lines or {MAX_BYTES // 1024}KB (whichever is "
+ "hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete."
+)
+
+READ_SCHEMA: Mapping[str, Any] = {
+ "type": "object",
+ "required": ["path"],
+ "properties": {
+ "path": {"type": "string", "description": "Path to the file to read (relative or absolute)"},
+ "offset": {"type": "number", "description": "Line number to start reading from (1-indexed)"},
+ "limit": {"type": "number", "description": "Maximum number of lines to read"},
+ },
+}
+
+
+class ReadTool:
+ def __init__(self, *, image_sink: Optional[ImageSink] = None) -> None:
+ self._image_sink = image_sink
+ self._spec = ToolSpec(name="read", description=READ_DESCRIPTION, input_schema=READ_SCHEMA)
+
+ @property
+ def spec(self) -> ToolSpec:
+ return self._spec
+
+ async def execute(self, arguments: Mapping[str, Any], ctx: ToolContext) -> ToolResult:
+ if ctx.cancel.cancelled:
+ return error_result("Operation aborted")
+ try:
+ path = str_arg(arguments, "path")
+ offset = optional_number_arg(arguments, "offset")
+ limit = optional_number_arg(arguments, "limit")
+ if limit is not None and limit < 1:
+ raise ToolInputError("limit must be at least 1")
+ except ToolInputError as exc:
+ return error_result(str(exc))
+
+ absolute = resolve_read_path(path, ctx.cwd)
+ try:
+ mime_type = await asyncio.to_thread(_sniff_image, absolute)
+ if mime_type is not None:
+ return await self._read_image(absolute, mime_type)
+ # Off the event loop, which every Session and surface shares.
+ return await asyncio.to_thread(_read_text, absolute, path, offset, limit)
+ except OSError as exc:
+ return error_result(os_error_text(exc))
+ except ToolInputError as exc:
+ return error_result(str(exc))
+
+ async def _read_image(self, absolute: str, mime_type: str) -> ToolResult:
+ header = f"Read image file [{mime_type}]"
+ details = {"path": absolute, "mime_type": mime_type}
+ if mime_type not in IMAGE_MIME_TYPES:
+ # Pi converts other formats to PNG; without an image library Avibe cannot.
+ return text_result(
+ f"{header}\n[Image omitted: could not be converted to a supported inline image format.]",
+ details=details,
+ )
+ size = os.path.getsize(absolute)
+ if size > MAX_INLINE_IMAGE_BYTES:
+ # Avibe: no resizing in v1.
+ return text_result(
+ f"{header}\n[Image omitted: the file is {format_size(size)}, over the "
+ f"{format_size(MAX_INLINE_IMAGE_BYTES)} inline image limit. Images are not resized.]",
+ details={**details, "bytes": size},
+ )
+ if self._image_sink is None:
+ return text_result(f"{header}\n[Image omitted: image attachments are not available.]", details=details)
+ data = await asyncio.to_thread(_read_bytes, absolute)
+ name = os.path.basename(absolute)
+ token = self._image_sink(data, mime_type, name)
+ if inspect.isawaitable(token):
+ token = await token
+ return ToolResult(
+ content=(TextBlock(text=header), ImageBlock(mime_type=mime_type, media_token=token, name=name)),
+ details={**details, "bytes": len(data)},
+ )
+
+
+def _sniff_image(path: str) -> Optional[str]:
+ with open(path, "rb") as handle:
+ return detect_supported_image_mime_type(handle.read(_IMAGE_SNIFF_BYTES))
+
+
+def _read_bytes(path: str) -> bytes:
+ with open(path, "rb") as handle:
+ return handle.read()
+
+
+def _read_text(absolute: str, path: str, offset: Optional[float], limit: Optional[float]) -> ToolResult:
+ start_line = max(0, int(offset) - 1) if offset else 0
+ stop_line = start_line + int(limit) if limit is not None else None
+ collected, total_lines, first_line_bytes = _scan_lines(absolute, start_line, stop_line)
+ if start_line >= total_lines:
+ raise ToolInputError(f"Offset {format_number(offset or 0)} is beyond end of file ({total_lines} lines total)")
+
+ truncation = truncate_head("\n".join(collected))
+ start_display = start_line + 1
+ details: dict[str, Any] = {"path": absolute}
+ if truncation.first_line_exceeds_limit:
+ text = (
+ f"[Line {start_display} is {format_size(first_line_bytes)}, exceeds {format_size(MAX_BYTES)} limit. "
+ f"Use bash: sed -n '{start_display}p' {path} | head -c {MAX_BYTES}]"
+ )
+ details["truncation"] = truncation.to_details()
+ elif truncation.truncated:
+ end_display = start_display + truncation.output_lines - 1
+ next_offset = end_display + 1
+ if truncation.truncated_by == "lines":
+ notice = (
+ f"[Showing lines {start_display}-{end_display} of {total_lines}. Use offset={next_offset} to continue.]"
+ )
+ else:
+ notice = (
+ f"[Showing lines {start_display}-{end_display} of {total_lines} ({format_size(MAX_BYTES)} limit). "
+ f"Use offset={next_offset} to continue.]"
+ )
+ text = f"{truncation.content}\n\n{notice}"
+ details["truncation"] = truncation.to_details()
+ elif stop_line is not None and stop_line < total_lines:
+ text = f"{truncation.content}\n\n[{total_lines - stop_line} more lines in file. Use offset={stop_line + 1} to continue.]"
+ else:
+ text = truncation.content
+ return text_result(text, details=details)
+
+
+def _scan_lines(path: str, start: int, stop: Optional[int]) -> tuple[list[str], int, int]:
+ """Lines ``[start, stop)`` as Pi's ``text.split("\\n")`` gives them, the file's line count, and the
+ raw size of line ``start``.
+
+ Collection stops once the kept lines pass either cap, so the kept prefix exceeds a cap exactly when
+ the whole selection does: decoding with replacement never makes text shorter than its bytes, and
+ ``\\n`` never occurs inside a UTF-8 sequence, so lines decode independently.
+ """
+ lines: list[bytearray] = []
+ kept = 0 # raw bytes of "\\n".join(lines)
+ opened = -1 # file line index of lines[-1]
+ index = 0 # file line index of the bytes being read
+ first_line_bytes = 0
+ collecting = stop is None or start < stop
+
+ def collect(segment: bytes) -> None:
+ nonlocal kept, opened, collecting
+ if opened != index:
+ if lines:
+ kept += 1
+ lines.append(bytearray())
+ opened = index
+ room = MAX_BYTES + 1 - kept
+ if room > 0:
+ lines[-1] += segment[:room]
+ kept += min(len(segment), room)
+ # One line beyond the cap: a final empty piece does not count as a line.
+ if kept > MAX_BYTES or len(lines) > MAX_LINES + 1:
+ collecting = False
+
+ def count_rest(chunk: bytes, pos: int) -> None:
+ nonlocal index, first_line_bytes
+ if index == start:
+ newline = chunk.find(b"\n", pos)
+ first_line_bytes += (len(chunk) if newline == -1 else newline) - pos
+ index += chunk.count(b"\n", pos)
+
+ with open(path, "rb") as handle:
+ while chunk := handle.read(_READ_CHUNK_BYTES):
+ pos = 0
+ while collecting:
+ newline = chunk.find(b"\n", pos)
+ end = len(chunk) if newline == -1 else newline
+ if stop is not None and index >= stop:
+ collecting = False
+ continue
+ if index == start:
+ first_line_bytes += end - pos
+ if index >= start:
+ collect(chunk[pos:end])
+ if newline == -1:
+ pos = len(chunk)
+ break
+ index += 1
+ pos = newline + 1
+ else:
+ count_rest(chunk, pos)
+ if collecting and opened != index and index >= start:
+ # An empty file: its one line is empty.
+ lines.append(bytearray())
+ return [bytes(line).decode("utf-8", "replace") for line in lines], index + 1, first_line_bytes
+
+
+def detect_supported_image_mime_type(data: bytes) -> Optional[str]:
+ """Pi's content sniffing: JPEG, static PNG, GIF, WebP, and BMP."""
+ if data.startswith(b"\xff\xd8\xff"):
+ return None if len(data) > 3 and data[3] == 0xF7 else "image/jpeg"
+ if data.startswith(b"\x89PNG\r\n\x1a\n"):
+ return "image/png" if _is_png(data) and not _is_animated_png(data) else None
+ if data.startswith((b"GIF87a", b"GIF89a")):
+ return "image/gif"
+ if data.startswith(b"RIFF") and data[8:12] == b"WEBP":
+ return "image/webp"
+ if data.startswith(b"BM") and _is_bmp(data):
+ return "image/bmp"
+ return None
+
+
+def _is_png(data: bytes) -> bool:
+ return len(data) >= 16 and struct.unpack(">I", data[8:12])[0] == 13 and data[12:16] == b"IHDR"
+
+
+def _is_animated_png(data: bytes) -> bool:
+ offset = 8
+ while offset + 8 <= len(data):
+ length = struct.unpack(">I", data[offset : offset + 4])[0]
+ kind = data[offset + 4 : offset + 8]
+ if kind == b"acTL":
+ return True
+ if kind == b"IDAT":
+ return False
+ following = offset + 8 + length + 4
+ if following <= offset or following > len(data):
+ return False
+ offset = following
+ return False
+
+
+def _is_bmp(data: bytes) -> bool:
+ if len(data) < 26:
+ return False
+ (declared_size,) = struct.unpack("<I", data[2:6])
+ (pixel_offset,) = struct.unpack("<I", data[10:14])
+ (dib_size,) = struct.unpack("<I", data[14:18])
+ if declared_size != 0 and declared_size < 26:
+ return False
+ if pixel_offset < 14 + dib_size:
+ return False
+ if declared_size != 0 and pixel_offset >= declared_size:
+ return False
+ if dib_size == 12:
+ planes, bits = struct.unpack("<HH", data[22:26])
+ elif 40 <= dib_size <= 124:
+ if len(data) < 30:
+ return False
+ planes, bits = struct.unpack("<HH", data[26:30])
+ else:
+ return False
+ return planes == 1 and bits in (1, 4, 8, 16, 24, 32)
diff --git a/core/agent_core/tools/truncate.py b/core/agent_core/tools/truncate.py
new file mode 100644
index 000000000..6a405eb75
--- /dev/null
+++ b/core/agent_core/tools/truncate.py
@@ -0,0 +1,186 @@
+"""Output caps for tool results (C-7 section 1).
+
+Two independent limits, whichever is hit first: ``MAX_LINES`` lines and
+``MAX_BYTES`` UTF-8 bytes. ``read`` keeps the head, ``bash`` keeps the tail.
+
+Ported from Pi ``packages/coding-agent/src/core/tools/truncate.ts`` (MIT,
+Copyright (c) 2025 Mario Zechner).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Literal, Optional
+
+from core.agent_core.tools.base import MAX_BYTES, MAX_LINES
+
+TruncatedBy = Literal["lines", "bytes"]
+
+
+@dataclass(frozen=True)
+class TruncationResult:
+ content: str
+ truncated: bool
+ truncated_by: Optional[TruncatedBy]
+ total_lines: int
+ total_bytes: int
+ output_lines: int
+ output_bytes: int
+ # Tail truncation only: the kept text starts inside the last line.
+ last_line_partial: bool
+ # Head truncation only: the first line alone is over the byte limit.
+ first_line_exceeds_limit: bool
+ max_lines: int
+ max_bytes: int
+
+ def to_details(self) -> dict[str, Any]:
+ """The display form for ``ToolResult.details``, without the content itself."""
+ out = asdict(self)
+ del out["content"]
+ return out
+
+
+def utf8_len(value: str) -> int:
+ return len(value.encode("utf-8", "surrogatepass"))
+
+
+def format_size(size: int) -> str:
+ if size < 1024:
+ return f"{size}B"
+ if size < 1024 * 1024:
+ return f"{size / 1024:.1f}KB"
+ return f"{size / (1024 * 1024):.1f}MB"
+
+
+def split_lines_for_counting(content: str) -> list[str]:
+ """Lines of ``content``; a trailing newline does not start another line."""
+ if not content:
+ return []
+ lines = content.split("\n")
+ if content.endswith("\n"):
+ lines.pop()
+ return lines
+
+
+def _untruncated(content: str, total_lines: int, total_bytes: int, max_lines: int, max_bytes: int) -> TruncationResult:
+ return TruncationResult(
+ content=content,
+ truncated=False,
+ truncated_by=None,
+ total_lines=total_lines,
+ total_bytes=total_bytes,
+ output_lines=total_lines,
+ output_bytes=total_bytes,
+ last_line_partial=False,
+ first_line_exceeds_limit=False,
+ max_lines=max_lines,
+ max_bytes=max_bytes,
+ )
+
+
+def truncate_head(content: str, *, max_lines: int = MAX_LINES, max_bytes: int = MAX_BYTES) -> TruncationResult:
+ """Keep the first lines that fit. Never returns a partial line."""
+ total_bytes = utf8_len(content)
+ lines = split_lines_for_counting(content)
+ total_lines = len(lines)
+ if total_lines <= max_lines and total_bytes <= max_bytes:
+ return _untruncated(content, total_lines, total_bytes, max_lines, max_bytes)
+
+ if utf8_len(lines[0]) > max_bytes:
+ return TruncationResult(
+ content="",
+ truncated=True,
+ truncated_by="bytes",
+ total_lines=total_lines,
+ total_bytes=total_bytes,
+ output_lines=0,
+ output_bytes=0,
+ last_line_partial=False,
+ first_line_exceeds_limit=True,
+ max_lines=max_lines,
+ max_bytes=max_bytes,
+ )
+
+ kept: list[str] = []
+ kept_bytes = 0
+ truncated_by: TruncatedBy = "lines"
+ for index, line in enumerate(lines[:max_lines]):
+ line_bytes = utf8_len(line) + (1 if index > 0 else 0)
+ if kept_bytes + line_bytes > max_bytes:
+ truncated_by = "bytes"
+ break
+ kept.append(line)
+ kept_bytes += line_bytes
+ if len(kept) >= max_lines and kept_bytes <= max_bytes:
+ truncated_by = "lines"
+
+ output = "\n".join(kept)
+ return TruncationResult(
+ content=output,
+ truncated=True,
+ truncated_by=truncated_by,
+ total_lines=total_lines,
+ total_bytes=total_bytes,
+ output_lines=len(kept),
+ output_bytes=utf8_len(output),
+ last_line_partial=False,
+ first_line_exceeds_limit=False,
+ max_lines=max_lines,
+ max_bytes=max_bytes,
+ )
+
+
+def truncate_tail(content: str, *, max_lines: int = MAX_LINES, max_bytes: int = MAX_BYTES) -> TruncationResult:
+ """Keep the last lines that fit; only a single over-long last line is cut mid-line."""
+ total_bytes = utf8_len(content)
+ lines = split_lines_for_counting(content)
+ total_lines = len(lines)
+ if total_lines <= max_lines and total_bytes <= max_bytes:
+ return _untruncated(content, total_lines, total_bytes, max_lines, max_bytes)
+
+ kept: list[str] = []
+ kept_bytes = 0
+ truncated_by: TruncatedBy = "lines"
+ last_line_partial = False
+ for line in reversed(lines):
+ if len(kept) >= max_lines:
+ break
+ line_bytes = utf8_len(line) + (1 if kept else 0)
+ if kept_bytes + line_bytes > max_bytes:
+ truncated_by = "bytes"
+ if not kept:
+ partial = truncate_string_to_bytes_from_end(line, max_bytes)
+ kept.insert(0, partial)
+ kept_bytes = utf8_len(partial)
+ last_line_partial = True
+ break
+ kept.insert(0, line)
+ kept_bytes += line_bytes
+ if len(kept) >= max_lines and kept_bytes <= max_bytes:
+ truncated_by = "lines"
+
+ output = "\n".join(kept)
+ return TruncationResult(
+ content=output,
+ truncated=True,
+ truncated_by=truncated_by,
+ total_lines=total_lines,
+ total_bytes=total_bytes,
+ output_lines=len(kept),
+ output_bytes=utf8_len(output),
+ last_line_partial=last_line_partial,
+ first_line_exceeds_limit=False,
+ max_lines=max_lines,
+ max_bytes=max_bytes,
+ )
+
+
+def truncate_string_to_bytes_from_end(value: str, max_bytes: int) -> str:
+ """The longest suffix of ``value`` within ``max_bytes``, cut at a character boundary."""
+ data = value.encode("utf-8", "surrogatepass")
+ if len(data) <= max_bytes:
+ return value
+ start = len(data) - max_bytes
+ while start < len(data) and (data[start] & 0xC0) == 0x80:
+ start += 1
+ return data[start:].decode("utf-8", "replace")
diff --git a/core/agent_core/tools/write.py b/core/agent_core/tools/write.py
new file mode 100644
index 000000000..0602e53d4
--- /dev/null
+++ b/core/agent_core/tools/write.py
@@ -0,0 +1,65 @@
+"""The ``write`` tool (C-7 section 3).
+
+Ported from Pi ``packages/coding-agent/src/core/tools/write.ts`` (MIT, Copyright
+(c) 2025 Mario Zechner); the description and result text are Pi's.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Mapping
+
+from core.agent_core.tools.args import ToolInputError, error_result, os_error_text, str_arg, text_result
+from core.agent_core.tools.base import ToolContext, ToolResult, ToolSpec
+from core.agent_core.tools.paths import file_mutation_lock, resolve_to_cwd
+
+WRITE_DESCRIPTION = (
+ "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates "
+ "parent directories."
+)
+
+WRITE_SCHEMA: Mapping[str, Any] = {
+ "type": "object",
+ "required": ["path", "content"],
+ "properties": {
+ "path": {"type": "string", "description": "Path to the file to write (relative or absolute)"},
+ "content": {"type": "string", "description": "Content to write to the file"},
+ },
+}
+
+
+class WriteTool:
+ def __init__(self) -> None:
+ self._spec = ToolSpec(name="write", description=WRITE_DESCRIPTION, input_schema=WRITE_SCHEMA)
+
+ @property
+ def spec(self) -> ToolSpec:
+ return self._spec
+
+ async def execute(self, arguments: Mapping[str, Any], ctx: ToolContext) -> ToolResult:
+ try:
+ path = str_arg(arguments, "path")
+ content = str_arg(arguments, "content")
+ except ToolInputError as exc:
+ return error_result(str(exc))
+ absolute = resolve_to_cwd(path, ctx.cwd)
+ async with file_mutation_lock(absolute):
+ # Checked before each step, never in the middle of one, so the lock is held until
+ # the filesystem operation in progress has finished.
+ if ctx.cancel.cancelled:
+ return error_result("Operation aborted")
+ try:
+ await asyncio.to_thread(os.makedirs, os.path.dirname(absolute), exist_ok=True)
+ if ctx.cancel.cancelled:
+ return error_result("Operation aborted")
+ await asyncio.to_thread(write_text, absolute, content)
+ except OSError as exc:
+ return error_result(os_error_text(exc))
+ return text_result(f"Successfully wrote to {path}")
+
+
+def write_text(path: str, content: str) -> None:
+ """UTF-8 without newline translation; a lone surrogate (possible from JSON) is replaced."""
+ with open(path, "w", encoding="utf-8", errors="replace", newline="") as handle:
+ handle.write(content)
diff --git a/tests/agent_core/tools/__init__.py b/tests/agent_core/tools/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/agent_core/tools/conftest.py b/tests/agent_core/tools/conftest.py
new file mode 100644
index 000000000..ebde6f36a
--- /dev/null
+++ b/tests/agent_core/tools/conftest.py
@@ -0,0 +1,36 @@
+"""Hermetic context for the coding tools: temp directories, a minimal environment, no live service."""
+
+from __future__ import annotations
+
+import os
+from typing import Callable, Optional
+
+import pytest
+
+from core.agent_core.cancel import CancelToken
+from core.agent_core.tools.base import ToolContext
+
+
+def make_ctx(tmp_path) -> Callable[..., ToolContext]:
+ def make(
+ *,
+ cwd: Optional[str] = None,
+ tool_call_id: str = "toolu_1",
+ cancel: Optional[CancelToken] = None,
+ on_progress: Optional[Callable[[str], None]] = None,
+ ) -> ToolContext:
+ return ToolContext(
+ session_id="ses_test",
+ tool_call_id=tool_call_id,
+ cwd=cwd or str(tmp_path),
+ env={"PATH": os.environ.get("PATH", "/usr/bin:/bin")},
+ cancel=cancel or CancelToken(),
+ on_progress=on_progress,
+ )
+
+ return make
+
+
+def result_text(result) -> str:
+ return "".join(block.text for block in result.content if getattr(block, "text", None) is not None)
diff --git a/tests/agent_core/tools/test_bash.py b/tests/agent_core/tools/test_bash.py
new file mode 100644
index 000000000..a8620b1f8
--- /dev/null
+++ b/tests/agent_core/tools/test_bash.py
@@ -0,0 +1,172 @@
+"""C-7 ``bash``: Pi's results over a job handle, foreground-to-Watch handover, and settlement (J3)."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+
+import psutil
+
+from core.agent_core.cancel import CancelToken
+from core.agent_core.tools.bash import BashTool, settle_bash_call
+from core.agent_core.tools.jobs import LocalJobHost
+from tests.agent_core.tools.conftest import result_text
+
+
+class Watches:
+ """Adopt-or-create keyed by job id, as the adapter's Watch target is."""
+
+ def __init__(self) -> None:
+ self.by_job: dict[str, str] = {}
+
+ async def __call__(self, meta) -> str:
+ return self.by_job.setdefault(meta["job_id"], f"wch_{len(self.by_job) + 1}")
+
+
+def _host(tmp_path, watches=None):
+ return LocalJobHost(str(tmp_path / "jobs"), on_hand_over=watches)
+
+
+def _process_gone(pid: int, timeout_s: float = 3.0) -> bool:
+ deadline = time.monotonic() + timeout_s
+ while time.monotonic() < deadline:
+ try:
+ if psutil.Process(pid).status() == psutil.STATUS_ZOMBIE:
+ return True
+ except psutil.NoSuchProcess:
+ return True
+ time.sleep(0.02)
+ return False
+
+
+async def test_long_output_keeps_the_tail_and_names_the_full_output(tmp_path, make_ctx):
+ result = await BashTool(_host(tmp_path)).execute({"command": "seq 1 2500"}, make_ctx())
+
+ path = result.details["full_output_path"]
+ assert not result.is_error
+ assert result_text(result).endswith(f"2499\n2500\n\n[Showing lines 501-2500 of 2500. Full output: {path}]")
+ assert open(path).read() == "".join(f"{i}\n" for i in range(1, 2501))
+
+
+async def test_a_non_zero_exit_is_an_error_result(tmp_path, make_ctx):
+ result = await BashTool(_host(tmp_path)).execute({"command": "echo oops >&2; exit 3"}, make_ctx())
+
+ assert result.is_error
+ assert result_text(result) == "oops\n\n\nCommand exited with code 3"
+
+
+async def test_stdin_is_closed(tmp_path, make_ctx):
+ started = time.monotonic()
+ result = await BashTool(_host(tmp_path)).execute({"command": 'read x; echo "rc=$?"'}, make_ctx())
+
+ assert result_text(result) == "rc=1\n"
+ assert time.monotonic() - started < 5
+
+
+async def test_timeout_kills_the_tree_including_background_children(tmp_path, make_ctx):
+ command = f"sleep 30 & echo $! > {tmp_path / 'bg.pid'}; echo started; sleep 30"
+
+ result = await BashTool(_host(tmp_path)).execute({"command": command, "timeout": 0.5}, make_ctx())
+
+ assert result.is_error
+ assert result_text(result) == "started\n\n\nCommand timed out after 0.5 seconds"
+ assert _process_gone(int((tmp_path / "bg.pid").read_text()))
+
+
+async def test_abort_kills_the_command(tmp_path, make_ctx):
+ cancel = CancelToken()
+ seen = []
+
+ def progress(tail):
+ seen.append(tail)
+ cancel.cancel()
+
+ ctx = make_ctx(cancel=cancel, on_progress=progress)
+ result = await BashTool(_host(tmp_path)).execute(
+ {"command": f"echo $$ > {tmp_path / 'sh.pid'}; echo started; sleep 30"}, ctx
+ )
+
+ assert seen == ["started\n"]
+ assert result.is_error
+ assert result_text(result) == "started\n\n\nCommand aborted"
+ assert _process_gone(int((tmp_path / "sh.pid").read_text()))
+
+
+async def test_the_foreground_window_hands_over_and_the_command_runs_once(tmp_path, make_ctx):
+ watches = Watches()
+ host = _host(tmp_path, watches)
+ command = f"echo run >> {tmp_path / 'counter'}; echo working; sleep 1; echo finished"
+
+ result = await BashTool(host, foreground_window_s=0.3).execute({"command": command}, make_ctx())
+
+ job_id = result.details["job_id"]
+ path = host.output_path(job_id)
+ assert not result.is_error
+ assert result_text(result) == (
+ "Command is still running and is now Watch wch_1. You will get a follow-up message when it finishes.\n\n"
+ f"working\n\nFull output: {path}\nCheck: vibe watch show wch_1\nStop: vibe watch remove wch_1"
+ )
+ assert (await host.wait(job_id, deadline_s=5)).exit_code == 0
+ assert open(path).read() == "working\nfinished\n"
+ assert (tmp_path / "counter").read_text() == "run\n"
+ assert watches.by_job == {job_id: "wch_1"}
+
+
+async def test_watch_true_returns_at_once(tmp_path, make_ctx):
+ host = _host(tmp_path, Watches())
+ started = time.monotonic()
+
+ result = await BashTool(host).execute({"command": "sleep 2; echo late", "watch": True}, make_ctx())
+
+ assert time.monotonic() - started < 1.5
+ assert result_text(result).startswith("Command is still running and is now Watch wch_1.")
+ assert host.status(result.details["job_id"]).state == "running"
+ await host.kill(result.details["job_id"])
+
+
+async def test_without_a_watch_the_command_stays_in_the_foreground(tmp_path, make_ctx):
+ result = await BashTool(_host(tmp_path)).execute({"command": "echo hi", "watch": True}, make_ctx())
+
+ assert not result.is_error
+ assert result_text(result) == (
+ "hi\n\n\n[Watch unavailable (No Watch is available to take over the command.); "
+ "the command ran in the foreground.]"
+ )
+
+
+async def test_settlement_reports_each_job_state(tmp_path, make_ctx):
+ watches = Watches()
+ host = _host(tmp_path, watches)
+ tool = BashTool(host, foreground_window_s=0.2)
+ foreground = await tool.execute({"command": "echo out; exit 4"}, make_ctx(tool_call_id="exited"))
+ await tool.execute({"command": "echo still; sleep 30"}, make_ctx(tool_call_id="running"))
+
+ recovery = LocalJobHost(str(tmp_path / "jobs"), on_hand_over=watches)
+
+ exited = await settle_bash_call(recovery, "ses_test", "exited")
+ assert (result_text(exited), exited.is_error) == (result_text(foreground), True)
+ running = await settle_bash_call(recovery, "ses_test", "running")
+ assert result_text(running).startswith("Command is still running and is now Watch wch_1.")
+ assert result_text(await settle_bash_call(recovery, "ses_test", "running")) == result_text(running)
+ assert await settle_bash_call(recovery, "ses_test", "unknown") is None
+ await recovery.kill(running.details["job_id"])
+ assert await settle_bash_call(recovery, "ses_test", "running") is None
+
+
+async def test_a_timeout_holds_across_handover_and_a_restart(tmp_path, make_ctx):
+ """J3: the deadline is the job's, so the next owner enforces it."""
+ result = await BashTool(_host(tmp_path, Watches())).execute(
+ {"command": "echo begun; sleep 30", "timeout": 0.5, "watch": True}, make_ctx()
+ )
+ job_id = result.details["job_id"]
+ assert result_text(result).startswith("Command is still running")
+
+ restarted = LocalJobHost(str(tmp_path / "jobs"))
+ status = await asyncio.wait_for(restarted.wait(job_id, deadline_s=None), timeout=5)
+
+ assert status.state == "gone"
+ assert restarted.stop_reason(job_id) == "timeout"
+ settled = await settle_bash_call(restarted, "ses_test", "toolu_1")
+ assert result_text(settled) == "begun\n\n\nCommand timed out after 0.5 seconds"
+ assert not os.path.exists(os.path.join(restarted.job_dir(job_id), "exit"))
diff --git a/tests/agent_core/tools/test_jobs.py b/tests/agent_core/tools/test_jobs.py
new file mode 100644
index 000000000..f68651bb6
--- /dev/null
+++ b/tests/agent_core/tools/test_jobs.py
@@ -0,0 +1,237 @@
+"""``LocalJobHost`` recovery invariants (``recovery.md`` J1, J2, J4, J5, J6).
+
+A "crash" raises out of ``start`` at one step and abandons that host object;
+recovery is a new ``LocalJobHost`` over the same directory, as after a restart.
+The wrapper runs in its own session, so it outlives the crash as it would in
+production.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+import time
+
+import psutil
+import pytest
+
+import core.agent_core.tools.jobs as jobs_module
+from core.agent_core.tools.jobs import JobStartError, LocalJobHost
+
+
+class Crash(Exception):
+ pass
+
+
+def _env():
+ return {"PATH": os.environ.get("PATH", "/usr/bin:/bin")}
+
+
+async def _start(host, cwd, command, *, tool_call_id="toolu_1", timeout_s=None):
+ return await host.start(
+ command, cwd=str(cwd), env=_env(), timeout_s=timeout_s, session_id="ses_test", tool_call_id=tool_call_id
+ )
+
+
+def _wait_until(predicate, timeout_s=5.0):
+ deadline = time.monotonic() + timeout_s
+ while time.monotonic() < deadline:
+ if predicate():
+ return True
+ time.sleep(0.01)
+ return False
+
+
+def _wrapper_gone(job_dir):
+ """True once the job's wrapper has exited (or never wrote its pid and never will)."""
+ try:
+ pid = int(open(os.path.join(job_dir, "pid")).read())
+ except (FileNotFoundError, ValueError):
+ return False
+ try:
+ return psutil.Process(pid).status() == psutil.STATUS_ZOMBIE
+ except psutil.NoSuchProcess:
+ return True
+
+
+def _counter(tmp_path):
+ path = tmp_path / "counter"
+ return len(path.read_text().splitlines()) if path.exists() else 0
+
+
+def _crash_on_meta_write(monkeypatch, number):
+ """Crash right after the ``number``-th ``meta.json`` write of a start."""
+ original = LocalJobHost._write_meta
+ calls = []
+
+ def write(self, job_id, meta):
+ original(self, job_id, meta)
+ calls.append(job_id)
+ if len(calls) == number:
+ raise Crash
+
+ monkeypatch.setattr(LocalJobHost, "_write_meta", write)
+
+
+async def _crash_before_pid(self, *args):
+ raise Crash
+
+
+ "crash_point",
+ ["after_meta_before_spawn", "after_spawn_before_pid", "after_identity_before_go", "after_go"],
+)
+async def test_a_crash_at_any_launch_step_runs_the_command_at_most_once(tmp_path, monkeypatch, crash_point):
+ jobs_dir = tmp_path / "jobs"
+ host = LocalJobHost(str(jobs_dir))
+ if crash_point == "after_meta_before_spawn":
+ _crash_on_meta_write(monkeypatch, 1)
+ elif crash_point == "after_spawn_before_pid":
+ monkeypatch.setattr(LocalJobHost, "_await_pid", _crash_before_pid)
+ elif crash_point == "after_identity_before_go":
+ _crash_on_meta_write(monkeypatch, 2)
+
+ try:
+ await _start(host, tmp_path, f"echo ran >> {tmp_path / 'counter'}")
+ except Crash:
+ pass
+ monkeypatch.undo()
+
+ recovery = LocalJobHost(str(jobs_dir))
+ job_id = recovery.find_job("ses_test", "toolu_1")
+ assert job_id is not None
+ may_have_started = recovery.started(job_id)
+ if crash_point != "after_meta_before_spawn":
+ assert _wait_until(lambda: _wrapper_gone(recovery.job_dir(job_id)))
+
+ assert may_have_started is (crash_point == "after_go")
+ assert _counter(tmp_path) == (1 if may_have_started else 0)
+ assert recovery.status(job_id).state == ("exited" if may_have_started else "gone")
+
+
+async def test_a_wrapper_left_without_a_decision_abandons_and_a_late_host_cannot_start_it(tmp_path, monkeypatch):
+ monkeypatch.setattr(jobs_module, "DECISION_TIMEOUT_S", 0.05)
+ original = LocalJobHost._await_pid
+
+ async def slow_host(self, *args):
+ identity = await original(self, *args)
+ await asyncio.sleep(0.5) # the wrapper's own deadline passes meanwhile
+ return identity
+
+ monkeypatch.setattr(LocalJobHost, "_await_pid", slow_host)
+ host = LocalJobHost(str(tmp_path / "jobs"))
+
+ with pytest.raises(JobStartError):
+ await _start(host, tmp_path, f"echo ran >> {tmp_path / 'counter'}")
+
+ job_id = host.find_job("ses_test", "toolu_1")
+ assert _wait_until(lambda: _wrapper_gone(host.job_dir(job_id)))
+ assert not host.started(job_id)
+ assert _counter(tmp_path) == 0
+
+
+async def test_recovery_reads_exited_running_and_gone(tmp_path):
+ jobs_dir = str(tmp_path / "jobs")
+ host = LocalJobHost(jobs_dir)
+ exited = await _start(host, tmp_path, "echo done; exit 7", tool_call_id="exited")
+ running = await _start(host, tmp_path, "sleep 30", tool_call_id="running")
+ gone = await _start(host, tmp_path, "sleep 30", tool_call_id="gone")
+ assert (await host.wait(exited, deadline_s=5)).exit_code == 7
+ # The wrapper dies without writing `exit` (as on SIGKILL); its command child is cleaned up too.
+ gone_pid = host.meta(gone)["process"]["pid"]
+ os.killpg(gone_pid, 9)
+ assert _wait_until(lambda: _wrapper_gone(host.job_dir(gone)))
+
+ recovery = LocalJobHost(jobs_dir)
+
+ assert recovery.status(exited) == jobs_module.JobStatus("exited", 7)
+ assert recovery.output(exited) == (b"done\n", 5)
+ assert recovery.status(running).state == "running"
+ assert recovery.status(gone).state == "gone"
+ await recovery.kill(running)
+ assert recovery.status(running).state == "gone"
+
+
+async def test_a_recycled_pid_is_neither_reported_nor_killed(tmp_path):
+ """J2: the recorded pid now belongs to another session leader."""
+ jobs_dir = str(tmp_path / "jobs")
+ host = LocalJobHost(jobs_dir)
+ job_id = await _start(host, tmp_path, "sleep 30")
+ await host.kill(job_id)
+ stranger = subprocess.Popen(["sleep", "30"], start_new_session=True)
+ try:
+ meta = host.meta(job_id)
+ meta["process"].update(pid=stranger.pid, pgid=stranger.pid)
+ host._write_meta(job_id, meta)
+
+ recovery = LocalJobHost(jobs_dir)
+ assert recovery.status(job_id).state == "gone"
+ await recovery.kill(job_id)
+
+ time.sleep(0.1)
+ assert stranger.poll() is None
+ finally:
+ stranger.kill()
+ stranger.wait()
+
+
+async def test_output_on_disk_keeps_the_head_and_tail_of_a_long_command(tmp_path, monkeypatch):
+ """J4: the reader is told how much was dropped."""
+ monkeypatch.setattr(jobs_module, "OUTPUT_HEAD_BYTES", 1000)
+ monkeypatch.setattr(jobs_module, "OUTPUT_TAIL_BYTES", 2000)
+ host = LocalJobHost(str(tmp_path / "jobs"))
+ job_id = await _start(host, tmp_path, "seq 1 100000")
+ assert (await host.wait(job_id, deadline_s=10)).exit_code == 0
+
+ job_dir = host.job_dir(job_id)
+ assert os.path.getsize(os.path.join(job_dir, "output.log")) == 1000
+ assert os.path.getsize(os.path.join(job_dir, "tail.log")) <= 2000 + 16
+
+ chunks, offset, skipped = [], 0, 0
+ while True:
+ data, new_offset = host.output(job_id, offset)
+ skipped += new_offset - len(data) - offset
+ offset = new_offset
+ if not data:
+ break
+ chunks.append(data)
+ total = len(b"".join(f"{i}\n".encode() for i in range(1, 100001)))
+ assert offset == total
+ assert skipped == total - 3000
+ assert b"".join(chunks).endswith(b"99999\n100000\n")
+
+
+async def test_job_files_stay_until_the_call_is_settled(tmp_path):
+ """J5."""
+ host = LocalJobHost(str(tmp_path / "jobs"))
+ finished = await _start(host, tmp_path, "true", tool_call_id="finished")
+ running = await _start(host, tmp_path, "sleep 30", tool_call_id="running")
+ await host.wait(finished, deadline_s=5)
+
+ assert host.prune(lambda meta: False, older_than_s=0) == []
+ assert host.prune(lambda meta: True, older_than_s=0) == [finished]
+ assert os.path.isdir(host.job_dir(running))
+ await host.kill(running)
+
+
+async def test_hand_over_gives_a_job_at_most_one_watch(tmp_path, monkeypatch):
+ """J6, job side: the Watch is adopt-or-create by job id, and a recorded Watch is reused."""
+ watches: dict[str, str] = {}
+
+ async def adopt_or_create(meta):
+ return watches.setdefault(meta["job_id"], f"wch_{len(watches) + 1}")
+
+ host = LocalJobHost(str(tmp_path / "jobs"), on_hand_over=adopt_or_create)
+ job_id = await _start(host, tmp_path, "sleep 30")
+ _crash_on_meta_write(monkeypatch, 1) # the Watch exists, recording it crashes
+ with pytest.raises(Crash):
+ await host.hand_over(job_id)
+ monkeypatch.undo()
+
+ recovery = LocalJobHost(str(tmp_path / "jobs"), on_hand_over=adopt_or_create)
+ assert await recovery.hand_over(job_id) == "wch_1"
+ assert await recovery.hand_over(job_id) == "wch_1"
+ assert watches == {job_id: "wch_1"}
+ assert recovery.meta(job_id)["watch_id"] == "wch_1"
+ await recovery.kill(job_id)
diff --git a/tests/agent_core/tools/test_normalize.py b/tests/agent_core/tools/test_normalize.py
new file mode 100644
index 000000000..fb129e762
--- /dev/null
+++ b/tests/agent_core/tools/test_normalize.py
@@ -0,0 +1,29 @@
+"""C-7 section 6: the output normalizer, fed in arbitrary chunks as a job's log is read."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.agent_core.tools.normalize import OutputNormalizer
+
+
+ ("chunks", "expected"),
+ [
+ ([b"\x1b[31mred\x1b[0m plain\n"], "red plain\n"),
+ ([b"\x1b]0;window title\x07text\n"], "text\n"),
+ ([b"10%\r55%\r100%\n"], "100%\n"),
+ ([b"progress 100%\r\x1b[K\n"], "progress 100%\n"),
+ ([b"done\r"], "done"),
+ ([b"a\r\n", b"b\r", b"\nc"], "a\nb\nc"),
+ ([b"\x1b[3", b"2mgreen\n"], "green\n"),
+ ([b"\xe4\xb8", b"\xad\xe6\x96\x87\n"], "中文\n"),
+ ([b"bad \xff byte\n"], "bad \ufffd byte\n"),
+ ],
+)
+def test_chunks_normalize_to_the_final_screen_text(chunks, expected):
+ normalizer = OutputNormalizer()
+
+ out = "".join(normalizer.feed(chunk) for chunk in chunks) + normalizer.flush()
+
+ assert out == expected
diff --git a/tests/agent_core/tools/test_read.py b/tests/agent_core/tools/test_read.py
new file mode 100644
index 000000000..009dc977f
--- /dev/null
+++ b/tests/agent_core/tools/test_read.py
@@ -0,0 +1,161 @@
+"""C-7 ``read``: Pi's head truncation and continuation text, streamed; images through the sink."""
+
+from __future__ import annotations
+
+import random
+import struct
+import zlib
+
+import pytest
+
+import core.agent_core.tools.read as read_module
+from core.agent_core.messages import ImageBlock, TextBlock
+from core.agent_core.tools.read import ReadTool
+from core.agent_core.tools.truncate import truncate_head
+from tests.agent_core.tools.conftest import result_text
+
+
+async def _read(make_ctx, **arguments):
+ return await ReadTool().execute(arguments, make_ctx())
+
+
+async def test_head_is_cut_at_the_line_limit_with_the_next_offset(tmp_path, make_ctx):
+ (tmp_path / "log.txt").write_text("".join(f"line {i}\n" for i in range(1, 2501)))
+
+ result = await _read(make_ctx, path="log.txt")
+
+ text = result_text(result)
+ assert not result.is_error
+ assert text.startswith("line 1\nline 2\n")
+ assert text.endswith("line 2000\n\n[Showing lines 1-2000 of 2501. Use offset=2001 to continue.]")
+
+
+async def test_head_is_cut_at_the_byte_limit(tmp_path, make_ctx):
+ # 1,000-byte lines: the first takes 1,000 bytes and each further one 1,001, so 51 fit in 51,200.
+ (tmp_path / "wide.txt").write_text("".join(f"{i:04d}" + "x" * 996 + "\n" for i in range(100)))
+
+ text = result_text(await _read(make_ctx, path="wide.txt"))
+
+ assert text.endswith("\n\n[Showing lines 1-51 of 101 (50.0KB limit). Use offset=52 to continue.]")
+ assert text.split("\n\n[")[0].splitlines()[-1].startswith("0050")
+
+
+async def test_offset_and_limit_name_the_remaining_lines(tmp_path, make_ctx):
+ (tmp_path / "ten.txt").write_text("\n".join(f"l{i}" for i in range(1, 11)))
+
+ text = result_text(await _read(make_ctx, path="ten.txt", offset=3, limit=4))
+
+ assert text == "l3\nl4\nl5\nl6\n\n[4 more lines in file. Use offset=7 to continue.]"
+
+
+async def test_offset_beyond_the_end_is_an_error(tmp_path, make_ctx):
+ (tmp_path / "two.txt").write_text("a\nb")
+
+ result = await _read(make_ctx, path="two.txt", offset=5)
+
+ assert result.is_error
+ assert result_text(result) == "Offset 5 is beyond end of file (2 lines total)"
+
+
+async def test_an_over_long_first_line_points_at_bash(tmp_path, make_ctx):
+ (tmp_path / "big.txt").write_text("short\n" + "x" * 61_440 + "\nafter\n")
+
+ text = result_text(await _read(make_ctx, path="big.txt", offset=2))
+
+ assert text == "[Line 2 is 60.0KB, exceeds 50.0KB limit. Use bash: sed -n '2p' big.txt | head -c 51200]"
+
+
+def _whole_file_read(data: bytes, start: int, stop):
+ """Pi's algorithm on the whole file, as the oracle for the streamed reader."""
+ lines = data.decode("utf-8", "replace").split("\n")
+ return truncate_head("\n".join(lines[start:stop]), max_lines=5, max_bytes=20), len(lines)
+
+
+async def test_streaming_matches_reading_the_whole_file(tmp_path, monkeypatch):
+ # Tiny caps and chunks put every cap and chunk boundary inside a few bytes.
+ monkeypatch.setattr(read_module, "MAX_LINES", 5)
+ monkeypatch.setattr(read_module, "MAX_BYTES", 20)
+ pieces = [b"", b"a", b"abc", b"x" * 30, "é".encode(), b"\xff", b"\n", b"\n\n", b"\r\n"]
+ rng = random.Random(7)
+ path = tmp_path / "f"
+ for _ in range(300):
+ monkeypatch.setattr(read_module, "_READ_CHUNK_BYTES", rng.choice([1, 2, 3, 7, 64]))
+ data = b"".join(rng.choice(pieces) for _ in range(rng.randint(0, 12)))
+ path.write_bytes(data)
+ start = rng.randint(0, 6)
+ stop = None if rng.random() < 0.5 else start + rng.randint(1, 6)
+
+ lines, total, first_line_bytes = read_module._scan_lines(str(path), start, stop)
+ expected, expected_total = _whole_file_read(data, start, stop)
+
+ assert total == expected_total, data
+ if start >= total:
+ continue
+ got = truncate_head("\n".join(lines), max_lines=5, max_bytes=20)
+ assert (got.content, got.truncated, got.truncated_by, got.first_line_exceeds_limit) == (
+ expected.content,
+ expected.truncated,
+ expected.truncated_by,
+ expected.first_line_exceeds_limit,
+ ), (data, start, stop)
+ if got.first_line_exceeds_limit:
+ assert first_line_bytes == len(data.split(b"\n")[start])
+
+
+def _png() -> bytes:
+ def chunk(kind: bytes, body: bytes) -> bytes:
+ return struct.pack(">I", len(body)) + kind + body + struct.pack(">I", zlib.crc32(kind + body))
+
+ ihdr = struct.pack(">IIBBBBB", 1, 1, 8, 2, 0, 0, 0)
+ return (
+ b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr) + chunk(b"IDAT", zlib.compress(b"\0\xff\0\0")) + chunk(b"IEND", b"")
+ )
+
+
+async def test_an_image_is_stored_through_the_sink_and_attached(tmp_path, make_ctx):
+ (tmp_path / "pic.png").write_bytes(_png())
+ stored = []
+
+ async def sink(data, mime_type, name):
+ stored.append((data, mime_type, name))
+ return "media_1"
+
+ result = await ReadTool(image_sink=sink).execute({"path": "pic.png"}, make_ctx())
+
+ assert stored == [(_png(), "image/png", "pic.png")]
+ assert result.content == (
+ TextBlock(text="Read image file [image/png]"),
+ ImageBlock(mime_type="image/png", media_token="media_1", name="pic.png"),
+ )
+
+
+ ("name", "data", "cap", "expected"),
+ [
+ (
+ "pic.bmp",
+ struct.pack("<2sIHHIIiiHH", b"BM", 58, 0, 0, 54, 40, 1, 1, 1, 24) + bytes(28),
+ None,
+ "Read image file [image/bmp]\n[Image omitted: could not be converted to a supported inline image format.]",
+ ),
+ (
+ "pic.png",
+ _png(),
+ 16,
+ "Read image file [image/png]\n[Image omitted: the file is {size}B, over the 16B inline image limit. "
+ "Images are not resized.]",
+ ),
+ ],
+)
+async def test_images_that_cannot_be_sent_as_they_are_are_omitted(
+ tmp_path, make_ctx, monkeypatch, name, data, cap, expected
+):
+ (tmp_path / name).write_bytes(data)
+ if cap is not None:
+ monkeypatch.setattr(read_module, "MAX_INLINE_IMAGE_BYTES", cap)
+ stored = []
+
+ result = await ReadTool(image_sink=lambda *args: stored.append(args) or "never").execute({"path": name}, make_ctx())
+
+ assert stored == []
+ assert result.content == (TextBlock(text=expected.format(size=len(data))),)
diff --git a/tests/agent_core/tools/test_write_edit.py b/tests/agent_core/tools/test_write_edit.py
new file mode 100644
index 000000000..cdf37d2b9
--- /dev/null
+++ b/tests/agent_core/tools/test_write_edit.py
@@ -0,0 +1,115 @@
+"""C-7 ``write`` and ``edit``: Pi's matching tiers and errors, ``replaceAll``, and all-or-nothing writes."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.agent_core.tools.edit import EditTool
+from core.agent_core.tools.write import WriteTool
+from tests.agent_core.tools.conftest import result_text
+
+
+async def test_write_creates_parent_directories_and_keeps_bytes(tmp_path, make_ctx):
+ result = await WriteTool().execute({"path": "a/b/notes.txt", "content": "第一行\r\nsecond\n"}, make_ctx())
+
+ assert not result.is_error
+ assert result_text(result) == "Successfully wrote to a/b/notes.txt"
+ assert (tmp_path / "a/b/notes.txt").read_bytes() == "第一行\r\nsecond\n".encode()
+
+
+async def _edit(make_ctx, path, *edits, **extra):
+ return await EditTool().execute({"path": path, "edits": list(edits), **extra}, make_ctx())
+
+
+async def test_disjoint_edits_apply_against_the_original(tmp_path, make_ctx):
+ (tmp_path / "f.py").write_text("a = 1\nb = 2\nc = 3\n")
+
+ result = await _edit(
+ make_ctx, "f.py", {"oldText": "a = 1", "newText": "a = 10"}, {"oldText": "c = 3", "newText": "c = 30"}
+ )
+
+ assert result_text(result) == "Successfully replaced 2 block(s) in f.py."
+ assert (tmp_path / "f.py").read_text() == "a = 10\nb = 2\nc = 30\n"
+ assert "+1 a = 10" in result.details["diff"]
+
+
+async def test_normalized_match_rewrites_only_the_touched_lines(tmp_path, make_ctx):
+ original = "title = “Hello” \nkeep = ‘as is’ \nlast = 1\n"
+ (tmp_path / "f.txt").write_text(original)
+
+ # ASCII quotes and no trailing spaces: only Pi's normalized tier finds it.
+ result = await _edit(make_ctx, "f.txt", {"oldText": 'title = "Hello"', "newText": 'title = "Hi"'})
+
+ assert not result.is_error, result_text(result)
+ assert (tmp_path / "f.txt").read_text() == 'title = "Hi"\nkeep = ‘as is’ \nlast = 1\n'
+
+
+async def test_replace_all_replaces_every_occurrence(tmp_path, make_ctx):
+ (tmp_path / "f.txt").write_text("foo(1)\nbar\nfoo(2)\nfoo(3)\n")
+
+ result = await _edit(
+ make_ctx,
+ "f.txt",
+ {"oldText": "foo(", "newText": "baz(", "replaceAll": True},
+ {"oldText": "bar", "newText": "qux"},
+ )
+
+ assert result_text(result) == "Successfully replaced 2 block(s) in f.txt."
+ assert (tmp_path / "f.txt").read_text() == "baz(1)\nqux\nbaz(2)\nbaz(3)\n"
+
+
+async def test_bom_and_crlf_are_preserved(tmp_path, make_ctx):
+ (tmp_path / "win.txt").write_bytes("\ufeffone\r\ntwo\r\nthree\r\n".encode())
+
+ result = await _edit(make_ctx, "win.txt", {"oldText": "two\nthree", "newText": "2\n3"})
+
+ assert not result.is_error, result_text(result)
+ assert (tmp_path / "win.txt").read_bytes() == "\ufeffone\r\n2\r\n3\r\n".encode()
+
+
+ ("edits", "message"),
+ [
+ (
+ [{"oldText": "missing", "newText": "x"}],
+ "Could not find the exact text in f.txt. The old text must match exactly including all whitespace and "
+ "newlines.",
+ ),
+ (
+ [{"oldText": "alpha", "newText": "A"}, {"oldText": "missing", "newText": "x"}],
+ "Could not find edits[1] in f.txt. The oldText must match exactly including all whitespace and newlines.",
+ ),
+ (
+ [{"oldText": "dup", "newText": "x"}],
+ "Found 2 occurrences of the text in f.txt. The text must be unique. Please provide more context to make "
+ "it unique.",
+ ),
+ (
+ [{"oldText": "alpha", "newText": "A"}, {"oldText": "dup", "newText": "x"}],
+ "Found 2 occurrences of edits[1] in f.txt. Each oldText must be unique. Please provide more context to "
+ "make it unique.",
+ ),
+ (
+ [{"oldText": "alpha beta", "newText": "x"}, {"oldText": "beta", "newText": "y"}],
+ "edits[0] and edits[1] overlap in f.txt. Merge them into one edit or target disjoint regions.",
+ ),
+ (
+ # An occurrence matched by replaceAll counts as a span for the overlap check.
+ [{"oldText": "dup", "newText": "x", "replaceAll": True}, {"oldText": "dup two", "newText": "y"}],
+ "edits[0] and edits[1] overlap in f.txt. Merge them into one edit or target disjoint regions.",
+ ),
+ (
+ [{"oldText": "alpha", "newText": "A"}, {"oldText": "", "newText": "x"}],
+ "edits[1].oldText must not be empty in f.txt.",
+ ),
+ ],
+)
+async def test_a_failing_edit_writes_nothing(tmp_path, make_ctx, edits, message):
+ original = "alpha beta\ndup one\ndup two\n"
+ (tmp_path / "f.txt").write_text(original)
+
+ result = await _edit(make_ctx, "f.txt", *edits)
+
+ assert result.is_error
+ assert result_text(result) == message
+ assert (tmp_path / "f.txt").read_text() == original