Python
Bound tool results, steer edits, keep compacted turns readable (OPE-186)
Devika Verma65ba394393af
diff --git a/coworker/agent.py b/coworker/agent.pyindex 29fde87a..7e904188 100644--- a/coworker/agent.py+++ b/coworker/agent.py@@ -188,6 +188,14 @@ def _skill_dirs(workspace: Optional[Path]) -> list[Path]:return dirs+def _is_within(path: Path, root: Path) -> bool:+ try:+ Path(path).resolve().relative_to(Path(root).resolve())+ return True+ except (ValueError, OSError):+ return False++def build_engine(*,agent: Agent,@@ -199,6 +207,11 @@ def build_engine(allowed_commands: Optional[list[str]] = None,max_iterations: Optional[int] = None,model_settings: Optional[dict[str, Any]] = None,+ # OPE-186: explicit tool-result byte cap (None = config, then the 10,000 default;+ # 0 = off) and where bounded results' full text is spilled (None = the session's+ # scratch root if there is one, else a per-process temp directory).+ tool_result_max_bytes: Optional[int] = None,+ tool_result_spill_dir: Optional[str | Path] = None,memory_store: Optional[MemoryStore] = None,# Twentieth pass: the project key memory loads/saves under. Defaults to the# workspace path; the manager passes the resolved key (binding > git > path)@@ -262,6 +275,30 @@ def build_engine(else:root_list = []+ # OPE-186: bounded tool results keep their full text in a spill file the model can+ # read, and the compaction transcript is written there too. Prefer the session's+ # scratch root (already one of the agent's folders). Otherwise the folder joins the+ # session's directories read-only, BEFORE the tools are built, so read_file can open+ # it (2026-09-14: the first trial spilled under the run's log folder and read_file+ # answered "path escapes the session's directories"). The workspace itself is never+ # written to, so a repository or task tree stays clean.+ if tool_result_spill_dir is not None:+ spill_dir: Optional[Path] = Path(tool_result_spill_dir).expanduser().resolve()+ else:+ scratch = next((r.path for r in root_list if r.label == "scratch"), None)+ if scratch is not None:+ spill_dir = Path(scratch) / "tool-output"+ else:+ import os+ import tempfile++ spill_dir = (+ Path(tempfile.gettempdir()) / "openworker" / f"tool-output-{os.getpid()}"+ ).resolve()+ # Registered, not created: the folder appears on disk only when something is spilled.+ if root_list and not any(_is_within(spill_dir, r.path) for r in root_list):+ root_list.append(RootDir(path=spill_dir, writable=False, label="tool-output"))+workspace_trusted = bool(ws and WorkspaceTrustStore().is_trusted(ws))config = load_config(ws, workspace_trusted=workspace_trusted)# OPE-177: the configured per-reply output ceiling rides `model_settings`, which@@ -534,6 +571,12 @@ def build_engine()return "\n\n".join(parts)+ cap = (+ tool_result_max_bytes+ if tool_result_max_bytes is not None+ else config.tool_result_max_bytes+ )+engine = TurnEngine(provider=provider,registry=registry,@@ -541,6 +584,8 @@ def build_engine(model=model,instructions=instructions,approver=approver,+ tool_result_max_bytes=cap,+ tool_result_spill_dir=spill_dir,# Stop kills the in-flight foreground shell command, not just the loop.interrupt_hooks=[executor.interrupt_now] if executor is not None else None,max_iterations=(@@ -557,6 +602,11 @@ def build_engine(team_approver=team_approver,items_approver=items_approver,)+ # OPE-186 change 3: a configured compaction cap makes the summariser fire earlier+ # than the built-in 250,000-token cap. The window still comes from the model matrix.+ if config.compaction_cap_tokens:+ _cap_tokens = int(config.compaction_cap_tokens)+ engine.compaction_settings = lambda: {"cap_tokens": _cap_tokens}engine.executor = executor # type: ignore[attr-defined]engine.todo = todo # type: ignore[attr-defined]engine.agent_name = agent.name # type: ignore[attr-defined]diff --git a/coworker/agents/cowork.py b/coworker/agents/cowork.pyindex d72ddc6f..2669390e 100644--- a/coworker/agents/cowork.py+++ b/coworker/agents/cowork.py@@ -25,7 +25,10 @@ COWORK_INSTRUCTIONS = ("no todo list means the user sees nothing happening. Keep exactly one item in_progress and ""update statuses as you finish each step. NEVER inline a multi-line script in a shell ""command (no heredocs): write it to a file with write_file, then run that file — the "- "script stays reviewable and the approval prompt stays short. Be outcome-oriented — "+ "script stays reviewable and the approval prompt stays short. To change an existing "+ "file, read it and edit it in place with replace_in_file or apply_patch rather than "+ "rewriting the whole file; reserve write_file for new files or full rewrites. "+ "Be outcome-oriented — ""clarify the goal, do the ""work in small reversible steps, and finish with the actual artifact plus a short summary ""of what you produced and where. When your deliverable is a file, end the reply with a "diff --git a/coworker/catalog.py b/coworker/catalog.pyindex cdf4fae3..c910f37b 100644--- a/coworker/catalog.py+++ b/coworker/catalog.py@@ -51,6 +51,51 @@ class Capability:# -- capability builders --------------------------------------------------------# These reproduce, exactly, what the Code and Cowork agent factories assembled by hand.+# OPE-186 change 2: aisuite's file tools describe themselves in one generic line each+# ("Write a UTF-8 text file under the configured root."), so nothing tells the model when+# to rewrite a file and when to edit it. In one long multi-task session Kimi K3 chose+# write_file 1,812 times against 609 targeted edits, and every whole-file body it wrote+# rode along in the conversation on every later turn. Building the guidance into the+# tool description is the usual remedy; these descriptions do that.+EDIT_TOOL_GUIDANCE: dict[str, str] = {+ "write_file": (+ "Create a NEW file, or replace an existing file's ENTIRE content when most of it "+ "changes. For a small or medium change to an existing file do not rewrite it: read "+ "it, then use replace_in_file (exact text swap) or apply_patch (multi-line edit). "+ "The whole `content` you pass stays in the conversation on every later turn, so "+ "whole-file rewrites of large files are expensive."+ ),+ "replace_in_file": (+ "Edit an existing file in place: replace `old` (an exact, unique text fragment, "+ "whitespace included) with `new`. Prefer this over write_file for changing part of "+ "a file; read the file first so `old` matches exactly. Set expected_replacements "+ "when the fragment appears more than once."+ ),+ "apply_patch": (+ "Apply a Codex-style patch (*** Begin Patch / *** Update File: path / @@ hunks of "+ "' ' context, '-' removed and '+' added lines / *** End Patch) for targeted "+ "multi-line edits to one or more existing files, or to add or delete files. Prefer "+ "this over write_file for edits that touch several places."+ ),+ "apply_unified_diff": (+ "Apply a standard unified diff (the format of `diff -u` or `git diff`) to existing "+ "files. Use it when you already have the change as a diff."+ ),+}+++def _describe_edit_tools(tools: list) -> list:+ """Give the file tools descriptions that say WHEN to use each (the registry builds the+ schema the model sees from the docstring)."""+ for t in tools:+ text = EDIT_TOOL_GUIDANCE.get(getattr(t, "__name__", ""))+ if text:+ try:+ t.__doc__ = text+ except (AttributeError, TypeError):+ pass+ return tools+def _code_files(context: AgentContext) -> list:"""Repo-oriented files: line-numbered/windowed `read_file`. Our `grep` and windowed@@ -63,11 +108,13 @@ def _code_files(context: AgentContext) -> list:file_kwargs = ({"roots": context.roots} if context.roots else {"root": ws, "allow_write": True})- files = [- t- for t in ai.toolkits.files(**file_kwargs)- if getattr(t, "__name__", "") not in replaced- ]+ files = _describe_edit_tools(+ [+ t+ for t in ai.toolkits.files(**file_kwargs)+ if getattr(t, "__name__", "") not in replaced+ ]+ )return [*files, *file_tools(ws, roots=context.roots)]@@ -82,11 +129,13 @@ def _files(context: AgentContext) -> list:{"roots": context.roots} if context.roots else {"root": ws, "allow_write": True})replaced = {"search_files", "read_file", "read_file_lines"}- files = [- t- for t in ai.toolkits.files(**file_kwargs)- if getattr(t, "__name__", "") not in replaced- ]+ files = _describe_edit_tools(+ [+ t+ for t in ai.toolkits.files(**file_kwargs)+ if getattr(t, "__name__", "") not in replaced+ ]+ )return [*files, *file_tools(ws, roots=context.roots)]diff --git a/coworker/compaction.py b/coworker/compaction.pyindex 678682a5..1958dc7c 100644--- a/coworker/compaction.py+++ b/coworker/compaction.py@@ -98,6 +98,10 @@ class CompactionState:created_at: float = 0.0model_used: str = ""trimmed: bool = False # True when this state came from the no-summary trim fallback+ # OPE-186 change 3: where the verbatim transcript of the compacted turns was written+ # (empty when the engine had nowhere to write it). Named in the compacted block so the+ # model can read back anything the summary dropped.+ transcript_path: str = ""def as_dict(self) -> dict[str, Any]:return {@@ -109,6 +113,7 @@ class CompactionState:"created_at": self.created_at,"model_used": self.model_used,"trimmed": self.trimmed,+ "transcript_path": self.transcript_path,}@classmethod@@ -124,6 +129,7 @@ class CompactionState:created_at=float(raw.get("created_at", 0.0)),model_used=str(raw.get("model_used", "")),trimmed=bool(raw.get("trimmed", False)),+ transcript_path=str(raw.get("transcript_path", "") or ""),)@@ -517,10 +523,54 @@ def compacted_block(state: CompactionState) -> str:"their intent is covered by the summary above)"]parts += [f"- {u}" for u in state.user_messages]+ if state.transcript_path:+ parts += [+ "",+ "The verbatim transcript of the compacted turns (every message, tool call and "+ f"tool result, without your private reasoning) is saved at {state.transcript_path}. "+ "If a detail you need is missing from the summary, read that file (read_file, "+ "or run_shell with grep / sed -n) instead of guessing.",+ ]parts += ["", CONTINUATION_CONTRACT, "</compacted-history>"]return "\n".join(parts)+def render_transcript(messages: list[dict[str, Any]], upto: int) -> str:+ """The canonical messages before index `upto`, rendered as readable Markdown for the+ transcript file: role, the assistant's visible text and tool calls (name + arguments),+ every tool result in full, notices. Private reasoning sidecars are left out: they are+ the model's own thinking, not session facts, and they are the bulkiest part."""+ lines = [+ "# Compacted transcript",+ "",+ f"Messages 0 to {max(0, upto - 1)} of this session, verbatim, written when they were "+ "summarised into the compacted history block.",+ "",+ ]+ for i, m in enumerate(messages[:upto]):+ role = str(m.get("role") or "")+ if role == "system":+ continue+ if role == "notice":+ lines += [f"## [{i}] notice: {m.get('kind', '')}", "", str(m.get("content") or ""), ""]+ continue+ lines.append(f"## [{i}] {role}")+ content = m.get("content")+ if isinstance(content, str) and content:+ lines += ["", content]+ elif content:+ lines += ["", json.dumps(content, default=str, ensure_ascii=False)]+ for tc in m.get("tool_calls") or []:+ fn = tc.get("function") if isinstance(tc, dict) else None+ name = (fn or {}).get("name") if fn else (tc.get("name") if isinstance(tc, dict) else "")+ args = (fn or {}).get("arguments") if fn else (tc.get("arguments") if isinstance(tc, dict) else "")+ if not isinstance(args, str):+ args = json.dumps(args, default=str, ensure_ascii=False)+ lines += ["", f"tool call: {name}", "```", str(args), "```"]+ lines.append("")+ return "\n".join(lines)++def apply_to_outbound(messages: list[dict[str, Any]], state: Optional[CompactionState]) -> list[dict[str, Any]]:diff --git a/coworker/config.py b/coworker/config.pyindex f98f2c76..262ad159 100644--- a/coworker/config.py+++ b/coworker/config.py@@ -51,6 +51,16 @@ class Config:# session — changing it mid-conversation restarts the prompt cache. Environment# override: COWORKER_REASONING_EFFORT.reasoning_effort: Optional[str] = None+ # OPE-186: bound every tool result before it enters the conversation. A result whose+ # serialised form exceeds this many bytes is stored as head + marker + tail, with the+ # full text in a spill file the model can read. Unset = 10,000;+ # 0 = off. Environment override: COWORKER_TOOL_RESULT_MAX_BYTES.+ tool_result_max_bytes: Optional[int] = None+ # OPE-186 change 3: cap on the auto-compaction trigger, in tokens. The engine compacts+ # at min(80% of the model's window, this cap); the built-in cap is 250,000, which on a+ # 1M-window model fired once in 445 long sessions. Lower it (e.g. 60000) to+ # summarise long sessions earlier. Environment override: COWORKER_COMPACTION_CAP_TOKENS.+ compaction_cap_tokens: Optional[int] = Noneallowed_commands: list[str] = field(default_factory=lambda: list(DEFAULT_ALLOWED_COMMANDS))@@ -100,6 +110,8 @@ _FIELDS = {"max_iterations","max_output_tokens","reasoning_effort",+ "tool_result_max_bytes",+ "compaction_cap_tokens","allowed_commands","auto_allow","allowed_domains",@@ -152,6 +164,19 @@ def workspace_allowed_commands(workspace: str | Path) -> list[str]:MAX_OUTPUT_TOKENS_ENV = "COWORKER_MAX_OUTPUT_TOKENS"REASONING_EFFORT_ENV = "COWORKER_REASONING_EFFORT"+TOOL_RESULT_MAX_BYTES_ENV = "COWORKER_TOOL_RESULT_MAX_BYTES"+COMPACTION_CAP_TOKENS_ENV = "COWORKER_COMPACTION_CAP_TOKENS"+++def _nonnegative_int(value: Any, source: str) -> Optional[int]:+ """`tool_result_max_bytes`: an integer >= 0 (0 turns bounding off); bools rejected."""+ if value is None:+ return None+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:+ raise ValueError(+ f"tool_result_max_bytes must be an integer >= 0, got {value!r} ({source})"+ )+ return valuedef _effort_level(value: Any, source: str) -> Optional[str]:@@ -217,4 +242,31 @@ def load_config(raw_effort = os.environ.get(REASONING_EFFORT_ENV)if raw_effort is not None and raw_effort.strip():cfg.reasoning_effort = _effort_level(raw_effort, REASONING_EFFORT_ENV)+ cfg.tool_result_max_bytes = _nonnegative_int(cfg.tool_result_max_bytes, "config.toml")+ raw_cap = (os.environ.get(TOOL_RESULT_MAX_BYTES_ENV) or "").strip()+ if raw_cap:+ try:+ parsed_cap: Any = int(raw_cap)+ except ValueError:+ parsed_cap = raw_cap+ cfg.tool_result_max_bytes = _nonnegative_int(parsed_cap, TOOL_RESULT_MAX_BYTES_ENV)+ if cfg.compaction_cap_tokens is not None and (+ isinstance(cfg.compaction_cap_tokens, bool)+ or not isinstance(cfg.compaction_cap_tokens, int)+ or cfg.compaction_cap_tokens <= 0+ ):+ raise ValueError(+ f"compaction_cap_tokens must be a positive integer, got {cfg.compaction_cap_tokens!r} (config.toml)"+ )+ raw_comp = (os.environ.get(COMPACTION_CAP_TOKENS_ENV) or "").strip()+ if raw_comp:+ try:+ parsed_comp = int(raw_comp)+ except ValueError:+ parsed_comp = 0+ if parsed_comp <= 0:+ raise ValueError(+ f"compaction_cap_tokens must be a positive integer, got {raw_comp!r} ({COMPACTION_CAP_TOKENS_ENV})"+ )+ cfg.compaction_cap_tokens = parsed_compreturn cfgdiff --git a/coworker/engine.py b/coworker/engine.pyindex 47492d12..f282c1b2 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -19,12 +19,14 @@ import jsonimport timefrom dataclasses import dataclass, replacefrom enum import Enum+from pathlib import Pathfrom typing import Any, AsyncIterator, Awaitable, Callable, Optionalfrom . import compaction as _compactionfrom . import provenancefrom . import session_factsfrom . import toolchain as _toolchain+from . import toolresultfrom .events import Event, EventType# §8.4 retry guard: the reviewer pauses for the rest of the turn after this many denials@@ -143,6 +145,11 @@ class TurnEngine:# Called (thread-safe, best-effort) when the user stops the turn — e.g. the# executor's kill for a running shell command.interrupt_hooks: Optional[list[Callable[[], None]]] = None,+ # OPE-186 change 1: bound every tool result before it enters the conversation+ # (head + marker + tail; full text in a spill file). None = the module default+ # (10,000 bytes), 0 = off. See coworker/toolresult.py.+ tool_result_max_bytes: Optional[int] = None,+ tool_result_spill_dir: Optional[Path] = None,) -> None:self.provider = providerself.registry = registry@@ -251,6 +258,14 @@ class TurnEngine:# the card and in the reviewer's request. Runtime-only, like `_ask_replies`: a# restart costs context (more cards), never correctness.self._agent_files = provenance.SessionFiles(permissions.workspace_root)+ self._tool_result_max_bytes = (+ toolresult.DEFAULT_TOOL_RESULT_MAX_BYTES+ if tool_result_max_bytes is None+ else int(tool_result_max_bytes)+ )+ self._tool_result_spill_dir = (+ Path(tool_result_spill_dir) if tool_result_spill_dir is not None else None+ )# Completed tool calls so far, so a fact can say how many steps back the write was.self._step = 0self._last_context_tokens: Optional[int] = None@@ -817,6 +832,25 @@ class TurnEngine:except Exception:continueif state is not None:+ # OPE-186 change 3: keep the compacted turns readable. The verbatim transcript+ # up to the boundary goes to a file next to the spilled tool results, and the+ # compacted block tells the model where it is, so a detail the summary dropped+ # costs one read instead of being lost.+ if self._tool_result_spill_dir is not None:+ try:+ self._tool_result_spill_dir.mkdir(parents=True, exist_ok=True)+ path = (+ self._tool_result_spill_dir+ / f"compacted-transcript-upto-{state.boundary_index:04d}.md"+ )+ path.write_text(+ _compaction.render_transcript(self.messages, state.boundary_index),+ encoding="utf-8",+ errors="replace",+ )+ state.transcript_path = str(path)+ except OSError:+ passself.compaction_state = stateself._last_context_tokens = None # stale once the outbound view shrankreturn "Context compacted — earlier turns were summarized"@@ -1604,6 +1638,15 @@ class TurnEngine:**({"approval_note": origin["note"]} if origin.get("note") else {}),**({"approval_grant": origin["grant"]} if origin.get("grant") else {}),}+ # OPE-186 change 1: what the model sees (and re-reads on every later turn) is+ # bounded here, once, for every tool. Provenance above recorded the full result.+ result = toolresult.bound_tool_result(+ result,+ max_bytes=self._tool_result_max_bytes,+ spill_dir=self._tool_result_spill_dir,+ step=self._step,+ tool_name=tool_call.name,+ )message = _tool_result_message(tool_call, result)if display:message["_display"] = displaydiff --git a/coworker/toolresult.py b/coworker/toolresult.pynew file mode 100644index 00000000..69b06e8d--- /dev/null+++ b/coworker/toolresult.py@@ -0,0 +1,120 @@+"""Bound every tool result before it enters the conversation (OPE-186, change 1).++A tool result is re-sent to the model on every later turn, so one oversized result taxes+the whole rest of the session. The shell tool used to keep the LAST 20,000 characters of+its output and drop the beginning; every other tool was unbounded (a `read_file` of a+486,000-character file was seen in one long session).++Rule, applied in one place for all tools (`TurnEngine._record_result`): if the result, as+it would be serialised into the tool message, exceeds `max_bytes`, the full text is written+to a spill file and the oversized field is replaced by its head, a marker naming the file+and the omitted byte count, and its tail. Head-plus-tail at 10,000 bytes is a common shape;+another is to keep the full output on disk and hand the model only the path.+Head AND tail because a build log needs both its first error and its final verdict.++The marker carries no timestamp, so a bounded result is byte-identical on every later+request and never disturbs the provider's prompt cache. Structured results stay valid+JSON: only the largest string field(s) are bounded, everything else is untouched.+"""++from __future__ import annotations++import json+import re+from pathlib import Path+from typing import Any, Optional++DEFAULT_TOOL_RESULT_MAX_BYTES = 10_000+# Bytes set aside for the marker line and JSON escaping when sizing head + tail.+_MARKER_RESERVE = 400+# Never shrink a field below this many bytes of head + tail, whatever the budget says.+_MIN_KEEP = 1_000+_SAFE_NAME = re.compile(r"[^A-Za-z0-9_.-]+")+++def serialize_result(result: Any) -> str:+ """Exactly what `_tool_result_message` puts in the message content."""+ return result if isinstance(result, str) else json.dumps(result, default=str)+++def _nbytes(text: str) -> int:+ return len(text.encode("utf-8"))+++def head_tail(text: str, keep_bytes: int, *, spill_path: Optional[Path], total_bytes: int) -> str:+ """First half of `keep_bytes`, a marker, last half. Cuts are byte-based and decoded+ with errors ignored so a multi-byte character split at the boundary is dropped, never+ corrupted."""+ keep = max(int(keep_bytes), _MIN_KEEP)+ raw = text.encode("utf-8")+ half = keep // 2+ head = raw[:half].decode("utf-8", errors="ignore")+ tail = raw[-half:].decode("utf-8", errors="ignore") if half else ""+ omitted = max(0, len(raw) - _nbytes(head) - _nbytes(tail))+ where = (+ f"full text saved to {spill_path} (read it with read_file, or "+ f"run_shell: sed -n '1,200p' \"{spill_path}\")"+ if spill_path is not None+ else "full text not saved"+ )+ marker = f"\n[... {omitted} bytes omitted here; this result was {total_bytes} bytes; {where} ...]\n"+ return head + marker + tail+++def bound_tool_result(+ result: Any,+ *,+ max_bytes: Optional[int],+ spill_dir: Optional[Path],+ step: int,+ tool_name: str,+) -> Any:+ """Return `result` unchanged when it fits, else a bounded copy. `max_bytes` None or+ <= 0 disables bounding. Spill files are written only when `spill_dir` is given."""+ if not max_bytes or max_bytes <= 0:+ return result+ text = serialize_result(result)+ if _nbytes(text) <= max_bytes:+ return result++ safe_tool = _SAFE_NAME.sub("_", tool_name or "tool")[:40] or "tool"++ def spill(name: str, payload: str) -> Optional[Path]:+ if spill_dir is None:+ return None+ try:+ spill_dir.mkdir(parents=True, exist_ok=True)+ path = spill_dir / name+ path.write_text(payload, encoding="utf-8", errors="replace")+ return path+ except OSError:+ return None++ if isinstance(result, dict):+ out: dict[str, Any] = dict(result)+ # Bound the largest string field, re-measure, repeat for the next largest if the+ # whole message is still over budget (a result can carry two big fields).+ for _ in range(4):+ key = max(+ (k for k, v in out.items() if isinstance(v, str)),+ key=lambda k: _nbytes(out[k]),+ default=None,+ )+ if key is None or _nbytes(out[key]) < _MIN_KEEP:+ break+ others = _nbytes(serialize_result({k: v for k, v in out.items() if k != key}))+ budget = max_bytes - others - _MARKER_RESERVE+ original = out[key]+ path = spill(f"{step:04d}-{safe_tool}-{_SAFE_NAME.sub('_', key)[:30]}.txt", original)+ bounded = head_tail(original, budget, spill_path=path, total_bytes=_nbytes(original))+ # JSON escaping (newlines, quotes) grows the serialised size; tighten once.+ over = _nbytes(serialize_result({**out, key: bounded})) - max_bytes+ if over > 0:+ bounded = head_tail(original, budget - over, spill_path=path, total_bytes=_nbytes(original))+ out[key] = bounded+ if _nbytes(serialize_result(out)) <= max_bytes:+ break+ return out++ path = spill(f"{step:04d}-{safe_tool}.txt", text)+ return head_tail(text, max_bytes - _MARKER_RESERVE, spill_path=path, total_bytes=_nbytes(text))diff --git a/coworker/tools/shell.py b/coworker/tools/shell.pyindex 0404511d..0f1554f7 100644--- a/coworker/tools/shell.py+++ b/coworker/tools/shell.py@@ -142,7 +142,11 @@ class LocalExecutor(Executor):env: Optional[dict[str, str]] = None,shell_path: Optional[str] = None,default_timeout: float = _DEFAULT_TIMEOUT,- max_output_chars: int = 20_000,+ # Memory safety net only (OPE-186): what the MODEL sees is bounded by the engine's+ # tool-result cap (head + marker + tail, full text in a spill file), which needs+ # the whole output to spill. This tail-keep cap now only stops a runaway command+ # from filling memory; it used to be 20,000 and silently dropped the beginning.+ max_output_chars: int = 2_000_000,) -> None:self.cwd = str(Path(cwd).expanduser().resolve())self.default_timeout = default_timeoutdiff --git a/tests/test_compaction_transcript.py b/tests/test_compaction_transcript.pynew file mode 100644index 00000000..89ac3e32--- /dev/null+++ b/tests/test_compaction_transcript.py@@ -0,0 +1,127 @@+"""OPE-186 change 3: the summariser can fire earlier (configurable cap), and the compacted+turns stay readable: the verbatim transcript is written to a file the model is told about+in the compacted block. Scripted provider, tiny forced window, no network."""++from __future__ import annotations++import asyncio+import os++from coworker import compaction as C+from coworker.config import COMPACTION_CAP_TOKENS_ENV, load_config+from coworker.engine import TurnEngine+from coworker.events import EventType+from coworker.permissions import PermissionEngine+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient+from coworker.tools import ToolRegistry++SUMMARY = "## Primary request and intent\nkeep building the report"+++class CompactingProvider(ProviderClient):+ def __init__(self, turns):+ self._turns = list(turns)++ def complete(self, *, model, messages, tools=None, **settings):+ if messages and "compacting an AI coworker" in str(messages[0].get("content", "")):+ return AssistantTurn(text=SUMMARY, finish_reason="stop")+ return self._turns.pop(0)++ def capabilities(self, model):+ return ModelCapabilities()+++def _history(turns=8, bulk=1500):+ msgs = [{"role": "system", "content": "be helpful"}]+ for i in range(turns):+ msgs.append({"role": "user", "content": f"request {i}", "ts": 1.0})+ msgs.append(+ {+ "role": "assistant",+ "content": f"answer {i} " + "x" * bulk,+ "ts": 1.0,+ "reasoning": "private thinking " + "r" * 200,+ "tool_calls": [{"id": f"c{i}", "function": {"name": "run_shell", "arguments": '{"command": "ls -la"}'}}],+ }+ )+ msgs.append({"role": "tool", "tool_call_id": f"c{i}", "content": f"listing {i}: file_{i}.txt", "ts": 1.0})+ return msgs+++def _collect(engine):+ async def go():+ return [e async for e in engine.run("continue")]++ return asyncio.run(go())+++def test_compaction_writes_transcript_and_tells_the_model(tmp_path):+ spill = tmp_path / "spill"+ engine = TurnEngine(+ provider=CompactingProvider([AssistantTurn(text="done", finish_reason="stop")]),+ registry=ToolRegistry(),+ permissions=PermissionEngine(workspace_root=tmp_path),+ model="gpt-5.5",+ messages=_history(),+ tool_result_spill_dir=spill,+ )+ engine.compaction_settings = lambda: {"cap_tokens": 400, "threshold_pct": 0.8, "context_window": 100_000}+ events = _collect(engine)+ assert any(e.type == EventType.COMPACTED for e in events)+ state = engine.compaction_state+ assert state is not None and state.transcript_path+ files = list(spill.glob("compacted-transcript-upto-*.md"))+ assert len(files) == 1 and str(files[0]) == state.transcript_path+ text = files[0].read_text(encoding="utf-8")+ # Verbatim content of the compacted turns: text, tool calls with arguments, results.+ assert "request 0" in text and "answer 0" in text+ assert "tool call: run_shell" in text and '"command": "ls -la"' in text+ assert "listing 0: file_0.txt" in text+ # Private reasoning is not written out.+ assert "private thinking" not in text+ # The compacted block the model receives names the file.+ out = engine._outbound_messages()+ assert state.transcript_path in out[1]["content"]+ assert "read that file" in out[1]["content"]+ # The record round-trips with the path.+ assert C.CompactionState.from_dict(state.as_dict()).transcript_path == state.transcript_path+++def test_no_spill_dir_means_no_transcript_and_no_mention(tmp_path):+ engine = TurnEngine(+ provider=CompactingProvider([AssistantTurn(text="done", finish_reason="stop")]),+ registry=ToolRegistry(),+ permissions=PermissionEngine(workspace_root=tmp_path),+ model="gpt-5.5",+ messages=_history(),+ )+ engine.compaction_settings = lambda: {"cap_tokens": 400, "threshold_pct": 0.8, "context_window": 100_000}+ _collect(engine)+ state = engine.compaction_state+ assert state is not None and state.transcript_path == ""+ assert "saved at" not in engine._outbound_messages()[1]["content"]+++def test_compaction_cap_config_and_env(tmp_path, monkeypatch):+ (tmp_path / ".coworker").mkdir()+ (tmp_path / ".coworker" / "config.toml").write_text("compaction_cap_tokens = 60000\n", encoding="utf-8")+ monkeypatch.delenv(COMPACTION_CAP_TOKENS_ENV, raising=False)+ cfg = load_config(tmp_path, global_path=tmp_path / "no-global.toml")+ assert cfg.compaction_cap_tokens == 60000 # a workspace config.toml may set it+ monkeypatch.setenv(COMPACTION_CAP_TOKENS_ENV, "80000")+ cfg = load_config(tmp_path, global_path=tmp_path / "no-global.toml")+ assert cfg.compaction_cap_tokens == 80000+ monkeypatch.setenv(COMPACTION_CAP_TOKENS_ENV, "0")+ try:+ load_config(tmp_path, global_path=tmp_path / "no-global.toml")+ except ValueError as exc:+ assert "compaction_cap_tokens" in str(exc)+ else:+ raise AssertionError("a zero cap must be rejected")+++def test_render_transcript_is_readable_and_skips_system():+ text = C.render_transcript(_history(turns=2), upto=7)+ assert text.startswith("# Compacted transcript")+ assert "be helpful" not in text # system prompt is not part of the compacted span+ assert "## [1] user" in text and "## [2] assistant" in text and "## [3] tool" in textdiff --git a/tests/test_edit_tool_guidance.py b/tests/test_edit_tool_guidance.pynew file mode 100644index 00000000..ba7366a8--- /dev/null+++ b/tests/test_edit_tool_guidance.py@@ -0,0 +1,42 @@+"""OPE-186 change 2: the file tools tell the model WHEN to use each (rewrite vs edit in+place), and the Cowork prompt says the same. The schema the model sees is built from the+tool's docstring by the registry, so that is what is checked here."""++from __future__ import annotations++from coworker.agents import AgentContext+from coworker.agents.cowork import COWORK_INSTRUCTIONS+from coworker.catalog import EDIT_TOOL_GUIDANCE, expand+from coworker.tools import ToolRegistry+++def _descriptions(capability: str, tmp_path) -> dict[str, str]:+ context = AgentContext(workspace=str(tmp_path), executor=None, todo=None, roots=None)+ registry = ToolRegistry()+ registry.register_all(expand([capability], context))+ return {+ name: registry.get(name).schema["function"]["description"] # type: ignore[union-attr]+ for name in registry.names()+ }+++def test_files_capability_describes_when_to_rewrite_and_when_to_edit(tmp_path):+ d = _descriptions("files", tmp_path)+ assert "NEW file" in d["write_file"] and "replace_in_file" in d["write_file"]+ assert "in place" in d["replace_in_file"] and "Prefer this over write_file" in d["replace_in_file"]+ assert "*** Begin Patch" in d["apply_patch"]+ assert "unified diff" in d["apply_unified_diff"]+ # The generic aisuite one-liner is gone from every edit tool.+ for name in EDIT_TOOL_GUIDANCE:+ assert d[name] != "Write a UTF-8 text file under the configured root."+++def test_code_files_capability_gets_the_same_guidance(tmp_path):+ d = _descriptions("code_files", tmp_path)+ for name, text in EDIT_TOOL_GUIDANCE.items():+ assert d[name] == text+++def test_cowork_prompt_steers_edits_to_in_place_tools():+ assert "edit it in place with replace_in_file or apply_patch" in COWORK_INSTRUCTIONS+ assert "reserve write_file for new files or full rewrites" in COWORK_INSTRUCTIONSdiff --git a/tests/test_tool_result_cap.py b/tests/test_tool_result_cap.pynew file mode 100644index 00000000..aa93e9f7--- /dev/null+++ b/tests/test_tool_result_cap.py@@ -0,0 +1,173 @@+"""OPE-186 change 1: every tool result is bounded before it enters the conversation.++Unit tests for `coworker.toolresult` and an engine round trip with a scripted provider+(no network). The contract: a result that fits is untouched byte-for-byte; an oversized+result keeps its head and tail, names a spill file holding the full text, stays valid+JSON when it was a dict, and is deterministic (no timestamps) so later requests carry an+identical prefix for the provider's prompt cache.+"""++from __future__ import annotations++import asyncio+import json+from pathlib import Path++import aisuite as ai++from coworker import toolresult+from coworker.engine import TurnEngine+from coworker.events import EventType+from coworker.permissions import PermissionEngine+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient, ToolCall+from coworker.tools import ToolRegistry+++def _bounded(result, *, max_bytes=10_000, spill: Path | None, step=7, tool="run_shell"):+ return toolresult.bound_tool_result(+ result, max_bytes=max_bytes, spill_dir=spill, step=step, tool_name=tool+ )+++def _size(x) -> int:+ return len(toolresult.serialize_result(x).encode("utf-8"))+++def test_small_result_is_returned_unchanged(tmp_path):+ result = {"command": "ls", "exit_code": 0, "output": "a\nb\n", "truncated": False}+ out = _bounded(result, spill=tmp_path)+ assert out is result # same object, not a copy+ assert not list(tmp_path.iterdir()) # nothing spilled+++def test_large_shell_output_keeps_head_and_tail_and_spills_full_text(tmp_path):+ lines = "\n".join(f"line{i:05d}" for i in range(4000)) # ~44 KB+ result = {"command": "make", "cwd": "/app", "exit_code": 1, "output": lines, "truncated": False}+ out = _bounded(result, spill=tmp_path)+ assert out is not result and out["exit_code"] == 1 and out["command"] == "make"+ assert _size(out) <= 10_000+ assert out["output"].startswith("line00000") # the head survives+ assert out["output"].rstrip().endswith("line03999") # and the tail+ assert "bytes omitted here" in out["output"] and "run_shell: sed -n" in out["output"]+ spilled = list(tmp_path.iterdir())+ assert len(spilled) == 1 and spilled[0].name == "0007-run_shell-output.txt"+ assert spilled[0].read_text(encoding="utf-8") == lines # complete, untouched+ assert str(spilled[0]) in out["output"] # the marker names the file+ # Still a well-formed message: the model gets JSON it can parse.+ json.loads(toolresult.serialize_result(out))+++def test_read_file_content_is_bounded_the_same_way(tmp_path):+ content = "\n".join(f"{i:>6}\t{'x' * 80}" for i in range(3000))+ result = {"path": "big.py", "start_line": 1, "end_line": 3000, "total_lines": 3000, "content": content}+ out = _bounded(result, spill=tmp_path, tool="read_file")+ assert _size(out) <= 10_000 and out["path"] == "big.py" and out["total_lines"] == 3000+ assert "bytes omitted here" in out["content"]+ assert (tmp_path / "0007-read_file-content.txt").read_text(encoding="utf-8") == content+++def test_plain_string_result_is_bounded(tmp_path):+ text = "y" * 50_000+ out = _bounded(text, spill=tmp_path, tool="web_fetch")+ assert isinstance(out, str) and len(out.encode()) <= 10_000+ assert out.startswith("yyyy") and out.endswith("yyyy") and "bytes omitted" in out+ assert (tmp_path / "0007-web_fetch.txt").read_text(encoding="utf-8") == text+++def test_multibyte_text_is_cut_safely(tmp_path):+ text = "é☃𝄞" * 20_000 # 1-, 3- and 4-byte characters+ out = _bounded(text, spill=tmp_path)+ out.encode("utf-8") # no lone surrogates / broken sequences+ assert len(out.encode()) <= 10_000+++def test_deterministic_and_cache_stable(tmp_path):+ result = {"output": "z" * 30_000, "exit_code": 0}+ a = _bounded(result, spill=tmp_path)+ b = _bounded(result, spill=tmp_path)+ assert a == b # identical text both times: no timestamps, no counters+++def test_disabled_with_zero_or_none(tmp_path):+ result = {"output": "z" * 30_000}+ assert _bounded(result, max_bytes=0, spill=tmp_path) is result+ assert _bounded(result, max_bytes=None, spill=tmp_path) is result+++def test_two_big_fields_are_both_bounded(tmp_path):+ result = {"stdout": "a" * 20_000, "stderr": "b" * 20_000, "exit_code": 2}+ out = _bounded(result, spill=tmp_path)+ assert _size(out) <= 10_000+ assert "bytes omitted" in out["stdout"] and "bytes omitted" in out["stderr"]+ assert sorted(p.name for p in tmp_path.iterdir()) == ["0007-run_shell-stderr.txt", "0007-run_shell-stdout.txt"]+++def test_without_spill_dir_marker_says_so(tmp_path):+ out = _bounded({"output": "q" * 30_000}, spill=None)+ assert "full text not saved" in out["output"]+++# -- engine round trip --------------------------------------------------------------------+++class _Scripted(ProviderClient):+ def __init__(self, turns):+ self._turns = list(turns)++ def complete(self, *, model, messages, tools=None, **settings):+ return self._turns.pop(0)++ def capabilities(self, model):+ return ModelCapabilities()+++def _run(engine, prompt):+ async def go():+ return [ev async for ev in engine.run(prompt)]++ return asyncio.run(go())+++def test_engine_bounds_tool_results_and_keeps_the_rest_of_the_message(tmp_path):+ low = ai.ToolMetadata(category="search", risk_level="low", requires_approval=False)++ def big_out():+ """Return a very large result."""+ return {"output": "\n".join(f"row{i}" for i in range(6000)), "exit_code": 0}++ registry = ToolRegistry()+ registry.register(big_out, metadata=low)+ permissions = PermissionEngine(workspace_root=tmp_path)+ spill = tmp_path / "spill"+ engine = TurnEngine(+ provider=_Scripted([+ AssistantTurn(tool_calls=[ToolCall(id="c1", name="big_out", arguments={})], finish_reason="tool_calls"),+ AssistantTurn(text="done", finish_reason="stop"),+ ]),+ registry=registry,+ permissions=permissions,+ model="gpt-5.5",+ approver=None,+ tool_result_max_bytes=10_000,+ tool_result_spill_dir=spill,+ )+ events = _run(engine, "go")+ assert [e for e in events if e.type == EventType.TOOL_FINISHED][0].data["status"] == "ok"+ tool_msgs = [m for m in engine.messages if m.get("role") == "tool"]+ assert len(tool_msgs) == 1+ content = tool_msgs[0]["content"]+ assert len(content.encode()) <= 10_000+ parsed = json.loads(content)+ assert parsed["exit_code"] == 0 and parsed["output"].startswith("row0")+ assert "bytes omitted here" in parsed["output"]+ files = list(spill.iterdir())+ assert len(files) == 1 and files[0].read_text(encoding="utf-8").endswith("row5999")+++def test_engine_default_cap_is_ten_thousand_and_zero_disables(tmp_path):+ registry = ToolRegistry()+ permissions = PermissionEngine(workspace_root=tmp_path)+ e1 = TurnEngine(provider=_Scripted([]), registry=registry, permissions=permissions, model="m")+ assert e1._tool_result_max_bytes == toolresult.DEFAULT_TOOL_RESULT_MAX_BYTES == 10_000+ e2 = TurnEngine(provider=_Scripted([]), registry=registry, permissions=permissions, model="m", tool_result_max_bytes=0)+ assert e2._tool_result_max_bytes == 0