Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
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.pynew file mode 100644index 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.pynew file mode 100644index 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 Nonediff --git a/core/agent_core/tools/coding.py b/core/agent_core/tools/coding.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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_changeddiff --git a/core/agent_core/tools/job_wrapper.py b/core/agent_core/tools/job_wrapper.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 outdiff --git a/core/agent_core/tools/paths.py b/core/agent_core/tools/paths.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/tests/agent_core/tools/conftest.py b/tests/agent_core/tools/conftest.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 == expecteddiff --git a/tests/agent_core/tools/test_read.py b/tests/agent_core/tools/test_read.pynew file mode 100644index 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.pynew file mode 100644index 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