Python
"""`openworker run`: run ONE task to the end, and record it.
openworker run --prompt "..." # here, with this computer's settings
openworker run --isolated --prompt "..." --workspace /path/to/project \
--model anthropic/claude-sonnet-5 --approval-mode bypass-approvals --out ./run-record
Each run is its own process with its own engine. It reads this computer's settings (the
default model, stored keys, connectors, the sandbox and its allowed sites) and changes none
of them, beyond renewing a sign-in; `--isolated` reads nothing at all, for benchmark runs. The model id is accepted in
OpenWorker's `provider:model` form or the `provider/model` form other tools use.
Approvals and questions are separate. An approval follows `--approval-mode`: asked in the terminal
(headless/terminal.py), refused and recorded when there is none. A question is asked in the
terminal, or answered by rule with `--auto-answer` or no terminal (coworker/unattended.py).
Nothing hangs.
Writes into --out (default: sessions/<workspace path>/<session id> in the state folder):
events.jsonl every engine event, with a timestamp
messages.json the final conversation (OpenWorker's own persisted shape)
summary.json outcome, counts, tokens, cost, wall-clock, arguments
answers.json every answer the engine gave on the absent user's behalf
audit.db OpenWorker's own audit log for the session
model_calls.jsonl one line per model call: stop reason, usage, host, effort
provider_errors.log full cause chains of failed model calls (credentials redacted)
trajectory.json the ATIF trajectory (also copied to --trajectory-atif when given)
The trajectory and the exit code are the stable contract; the other files are internal
and may change. Exit code 0 when the task finished, 3 when the run stopped early with its
record written (timeout, model error, iteration cap), 1 when it crashed before producing
one, 2 for a command line that cannot be run.
With --isolated, OpenWorker's state and scratch folders are pointed under --out before
the engine is built, so the run never touches the machine's real conversations, keys or
settings. Without it the state folder is read, and the run writes only its own record.
"""
from __future__ import annotations
import argparse
import asyncio
import json
import os
import re
import sys
import time
import traceback
import uuid
from pathlib import Path
from typing import Any, Optional
# How tool calls are approved (--approval-mode). `ask` is the app's "Ask for approval";
# the engine stores it as "interactive".
APPROVAL_MODES = ["ask", "auto-approve", "bypass-approvals", "dangerously-bypass-approvals"]
RETRY_DELAYS_ENV = "OPENWORKER_RUN_RETRY_DELAYS"
def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
p = argparse.ArgumentParser(
prog="openworker run",
description="Run one task to the end, and record it.",
# No shortened flags: `--mode` would otherwise be read as `--model`.
allow_abbrev=False,
)
# With neither flag, the task is read from standard input when it is piped in.
src = p.add_mutually_exclusive_group()
src.add_argument("--prompt", help="the task text")
src.add_argument(
"--prompt-file", help="file containing the task text (UTF-8); - reads standard input"
)
p.add_argument(
"--workspace", default=".", help="folder the agent works in (default: the current folder)"
)
p.add_argument(
"--add-dir",
dest="add_dir",
action="append",
default=None,
metavar="DIR",
help="an extra folder the agent may read and write, beside the workspace "
"(repeatable), for a harness whose output contract lives outside the workspace, "
"e.g. --add-dir /output. The file tools only write inside the session's folders, in "
"every mode; the shell is not scoped, so without this a delivery would depend on "
"which tool the model happened to pick.",
)
p.add_argument(
"--model", default=None,
help="provider:model (OpenWorker) or provider/model (default: this computer's "
"setting; required with --isolated)",
)
p.add_argument(
"--coworker", default="cowork", metavar="ID",
help="the coworker that does the task, by its id (default: cowork)",
)
p.add_argument(
"--approval-mode", default="ask", choices=APPROVAL_MODES,
help="how tool calls are approved (default: ask). At a terminal an approval is "
"asked there; with no terminal it is refused and recorded.",
)
p.add_argument(
"--auto-answer", action="store_true",
help="nobody will answer the coworker's questions: it is told so and carries on. "
"Without this, a question is asked in the terminal. Implied when no terminal is "
"attached. Approvals are separate: see --approval-mode.",
)
p.add_argument(
"--allow-site", dest="allow_site", action="append", default=None, metavar="HOST[:PORT]",
help="a site this run's commands and web tools may reach, beside this computer's "
"allowed sites (repeatable). For this run only.",
)
p.add_argument(
"--allow-sites-file", default=None, metavar="FILE",
help="a file of sites to allow for this run, one HOST[:PORT] per line (# starts a comment)",
)
p.add_argument(
"--isolated", action="store_true",
help="read nothing from this computer (no settings, no stored keys, no sandbox) and "
"keep everything under --out. For benchmark and evaluation runs. Needs --out and --model.",
)
p.add_argument(
"--max-iterations", type=int, default=None, help="default: OpenWorker config (150)"
)
p.add_argument(
"--no-web-tools", action="store_true",
help="do not offer the web_search and web_fetch tools at all. For sealed evaluation "
"runs and air-gapped work: a network block only refuses the call, this keeps the "
"tools out of the model's menu, and the record says so.",
)
p.add_argument(
"--provider-order",
default=None,
help="OpenRouter only: comma-separated upstream hosts to use, in order, with no "
"fallback (e.g. 'Together')",
)
p.add_argument(
"--compaction-cap-tokens",
type=int,
default=None,
help="compact once the context reaches this many tokens (default: OpenWorker's own "
"trigger, min(0.8 x window, 250000))",
)
p.add_argument(
"--compaction-summary-max-tokens",
type=int,
default=None,
help="output ceiling for the summariser call (default: OpenWorker's own 16,000)",
)
p.add_argument(
"--tool-result-max-bytes",
type=int,
default=None,
help="bound every tool result to this many bytes (head + marker + tail; full text "
"spilled under <out>/tool-output). Default: OpenWorker's config, then 10000. 0 = off.",
)
p.add_argument(
"--max-output-tokens",
type=int,
default=None,
help="per-reply output-token cap sent as max_tokens (default: OpenWorker config, "
"else the provider's own default)",
)
p.add_argument(
"--timeout-seconds",
type=float,
default=1800.0,
help="the run's own limit; 0 disables it (use 0 when an outer runner enforces one)",
)
p.add_argument(
"--out", default=None,
help="folder for the run record (default: sessions/<workspace path>/<session id> "
"in OpenWorker's state folder)",
)
p.add_argument("--trajectory-atif", default=None, help="also write the ATIF trajectory here")
p.add_argument("--agent-version", default=None, help="label for the trajectory's agent.version")
p.add_argument(
"--reasoning-effort",
default=None,
choices=["low", "medium", "high", "xhigh", "max"],
help="reasoning-effort level sent to the provider (Anthropic output_config.effort, "
"Together/Moonshot reasoning_effort). Default: nothing sent; the provider default is recorded",
)
p.add_argument(
"--mcp",
action="store_true",
help="attach MCP servers as tools for this run (off by default). Reads this "
"computer's mcp.json unless --mcp-config points elsewhere; for an --isolated run "
"that is <out>/state/mcp.json. A server's tools reach the model as "
"mcp__<server>__<tool>; a server that fails to connect is skipped and the run "
"goes on. The headless runner attaches only the global (or --mcp-config) file — a "
"workspace .coworker/mcp.json needs trust it does not establish.",
)
p.add_argument(
"--mcp-config",
default=None,
metavar="FILE",
help="load MCP servers from this mcpServers JSON file only, with no global or "
"workspace merge (implies --mcp). For a run that brings its own server config.",
)
p.add_argument("--scripted", default=None, help=argparse.SUPPRESS) # tests: a fake model
args = p.parse_args(argv)
# The engine's name for the mode, which is also what the record states.
args.mode = "interactive" if args.approval_mode == "ask" else args.approval_mode
args.attendance = None # set when the run knows who answers: "auto" or "attended"
return args
# -- isolation ----------------------------------------------------------------------------
def isolate_environment(out: Path) -> dict[str, str]:
"""Point OpenWorker's state and scratch folders under --out BEFORE the engine is
built, exactly as the test suite does (tests/conftest.py)."""
state = out / "state"
scratch = out / "scratch"
state.mkdir(parents=True, exist_ok=True)
scratch.mkdir(parents=True, exist_ok=True)
os.environ["COWORKER_STATE_DIR"] = str(state)
os.environ["COWORKER_SCRATCH_BASE"] = str(scratch)
os.environ.pop("COWORKER_API_TOKEN", None)
return {"COWORKER_STATE_DIR": str(state), "COWORKER_SCRATCH_BASE": str(scratch)}
# -- model name ---------------------------------------------------------------------------
def normalize_model(model: str) -> str:
"""Accept `provider:model` or `provider/model`; return OpenWorker's form. Splits on
the FIRST slash only, so `together/moonshotai/Kimi-K3` becomes
`together:moonshotai/Kimi-K3`."""
from ..providers.registry import get_descriptor
if ":" in model and get_descriptor(model.split(":", 1)[0]) is not None:
return model
if "/" in model:
prefix, rest = model.split("/", 1)
if get_descriptor(prefix) is not None:
return f"{prefix}:{rest}"
return model
# -- transient provider errors ------------------------------------------------------------
# The provider clients retry a failed request a couple of times within seconds. A provider
# outage lasting minutes outlives that, and the engine then ends the run with an ERROR
# event; in an unattended run that is a lost run. So the runner waits with backoff and
# re-enters the conversation with a nudge, up to ~18 minutes in total. Permanent errors
# (bad key, unknown model, context overflow) are not retried.
#
# The first waits are short: the commonest failure is one reply cut off mid-stream, which
# the clients do not retry and which the very next request survives. Seen on OpenShell
# 0.1.2, which closes every open connection when a sandbox's settings change (10 s after
# each start, and on each policy update).
PROVIDER_RETRY_DELAYS: tuple[int, ...] = (2, 5, 10, 30, 60, 120, 240, 300, 300)
PROVIDER_RETRY_NUDGE = (
"The previous model request failed with a temporary provider error and has been "
"retried. Continue the task from where you left off."
)
# An empty reply — no text, no tool call, finish_reason "stop" — ends the engine's turn as
# "completed". Under a degraded provider that is how a lost reply looks. The runner treats
# it like a provider hiccup: wait, then re-enter the conversation with this nudge. A model
# that really is finished answers it in one line.
EMPTY_REPLY_NUDGE = (
"Your previous reply was empty: no text and no tool call. If the task is complete, "
"say so in one line; otherwise continue the task from where you left off."
)
def ended_on_empty_reply(turn_events: list[dict[str, Any]]) -> bool:
"""True when the pass's last assistant message carried neither text nor a tool call."""
last = next((e for e in reversed(turn_events) if e.get("type") == "assistant_message"), None)
if last is None:
return False
data = last.get("data") or {}
return not str(data.get("text") or "").strip() and not data.get("tool_calls")
_TRANSIENT_ERROR_TYPES = {
# The engine's own "reply carried tool-call markup the endpoint couldn't parse" stop;
# its docstring calls it drift that a retry usually clears.
"UnparsedToolCall",
"APIError",
"APIConnectionError",
"APITimeoutError",
"APIStatusError",
"InternalServerError",
"RateLimitError",
"ServiceUnavailableError",
"OverloadedError",
"ConnectionError",
"TimeoutError",
"ReadTimeout",
"ConnectTimeout",
"RemoteProtocolError",
}
_TRANSIENT_ERROR_TEXT = (
"service unavailable",
"temporarily unavailable",
"overloaded",
"rate limit",
"too many requests",
"capacity",
"try again",
"timed out",
"timeout",
"connection",
"bad gateway",
"gateway time",
"internal server error",
"empty response",
"no response",
" 429",
" 500",
" 502",
" 503",
" 504",
" 529",
)
_PERMANENT_ERROR_TEXT = (
"api key",
"authentication",
"unauthorized",
"not found",
"context length",
"maximum context",
"too long",
"insufficient",
"quota",
)
def is_transient_provider_error(payload: dict[str, Any]) -> bool:
"""True for engine ERROR payloads that describe a provider hiccup worth waiting out.
Anything the provider client raised (the SDK error types above) counts as transient
unless its text names a permanent condition; the text patterns then also catch
hiccups surfaced under other exception types ("Provider returned an empty response"
is the case that taught this: it matched no pattern and cost a long run).
"""
text = " ".join(str(payload.get(k) or "") for k in ("error", "raw")).lower()
if any(p in text for p in _PERMANENT_ERROR_TEXT):
return False
if str(payload.get("error_type") or "") in _TRANSIENT_ERROR_TYPES:
return True
return any(p in text for p in _TRANSIENT_ERROR_TEXT)
def provider_retry_delays() -> tuple[int, ...]:
"""OPENWORKER_RUN_RETRY_DELAYS="30,60,120" overrides the schedule (tests use "0")."""
raw = os.environ.get(RETRY_DELAYS_ENV)
if raw is None:
return PROVIDER_RETRY_DELAYS
raw = raw.strip()
if not raw:
return ()
return tuple(max(0, int(x)) for x in raw.split(",") if x.strip())
# -- offline provider (tests) -------------------------------------------------------------
def _scripted_effort(settings: dict[str, Any]) -> Optional[dict[str, Any]]:
"""The fake model echoes the level as a real provider's record would."""
level = settings.get("reasoning_effort")
if not level:
return None
return {"requested": level, "effective": level, "param": {"scripted": level}}
def scripted_provider(path: Path):
"""A fake model that replays turns from a JSON file: [{"text": ..., "tool_calls":
[{"name": ..., "arguments": {...}}], "usage": {...}, "finish_reason": ...}, ...].
For the offline tests only (`--scripted`)."""
from ..providers import AssistantTurn, ModelCapabilities, ProviderClient, ToolCall
from ..providers.base import TokenUsage
turns = json.loads(path.read_text(encoding="utf-8"))
class Scripted(ProviderClient):
def __init__(self) -> None:
self._turns = list(turns)
self.calls = 0
def complete(self, *, model, messages, tools=None, **settings):
self.calls += 1
if not self._turns:
return AssistantTurn(
text="(script exhausted)",
finish_reason="stop",
usage=TokenUsage(input=1, output=1),
output_limit=settings.get("max_tokens"),
effort=_scripted_effort(settings),
)
t = self._turns.pop(0)
if t.get("error"):
# A scripted provider failure: {"error": "Service unavailable",
# "error_type": "APIError"} raises an exception of that name, so the
# transient-error retry can be tested offline.
# "cause" / "cause_type" add the exception underneath, as a client library
# wraps a proxy or socket failure.
exc_cls = type(str(t.get("error_type") or "APIError"), (Exception,), {})
if t.get("cause"):
cause_cls = type(str(t.get("cause_type") or "OSError"), (Exception,), {})
raise exc_cls(str(t["error"])) from cause_cls(str(t["cause"]))
raise exc_cls(str(t["error"]))
calls = [
ToolCall(
id=tc.get("id") or f"call_{self.calls}_{i}",
name=tc["name"],
arguments=tc.get("arguments", {}),
)
for i, tc in enumerate(t.get("tool_calls", []))
]
usage = t.get("usage") or {"input": 100, "output": 20}
# An explicit "finish_reason" in the script (e.g. "length") overrides the
# derived one, so truncation handling can be tested offline.
return AssistantTurn(
text=t.get("text"),
tool_calls=calls,
finish_reason=t.get("finish_reason") or ("tool_calls" if calls else "stop"),
usage=TokenUsage(**usage),
# Echo the ceiling the engine asked for, as a real provider would.
output_limit=settings.get("max_tokens"),
effort=_scripted_effort(settings),
)
def capabilities(self, model):
return ModelCapabilities()
return Scripted()
# -- reasoning effort ---------------------------------------------------------------------
def describe_reasoning_effort(model: str) -> dict[str, Any]:
"""What OpenWorker actually sends for reasoning/thinking with this model when no
level was requested, read from its provider code. Run records state an effort per
run, so this reports the effective behaviour instead of a label.
Returns {"label": short string for metadata, "detail": {...}}."""
provider = model.split(":", 1)[0] if ":" in model else "openai"
bare = model.split(":", 1)[1] if ":" in model else model
detail: dict[str, Any] = {
"provider": provider,
"model": bare,
"source": "OpenWorker defaults, no user setting",
}
if provider in ("anthropic", "bedrock", "vertex"):
try:
from ..providers.anthropic_provider import (
DEFAULT_MAX_TOKENS,
DEFAULT_THINKING_BUDGET,
_uses_budget_thinking,
)
detail["max_tokens"] = DEFAULT_MAX_TOKENS
if _uses_budget_thinking(bare):
detail["thinking"] = {"type": "enabled", "budget_tokens": DEFAULT_THINKING_BUDGET}
label = f"extended thinking, budget {DEFAULT_THINKING_BUDGET} tokens (OpenWorker default)"
else:
detail["thinking"] = {"type": "adaptive", "display": "summarized"}
# No output_config.effort is sent; Anthropic documents that as identical
# to effort "high".
detail["effort"] = "high (API default; no output_config sent)"
label = "high (Anthropic adaptive thinking, effort not set = API default high)"
except Exception: # noqa: BLE001 - never fail a run over a metadata lookup
label = "extended thinking on (OpenWorker default; details unavailable)"
return {"label": label, "detail": detail}
if provider == "openai":
detail["reasoning_effort"] = "not sent; OpenAI server default applies (Responses API)"
return {
"label": "provider default (OpenAI Responses API, no effort parameter sent)",
"detail": detail,
}
detail["reasoning_effort"] = "not sent; provider default applies"
return {"label": "provider default (no reasoning-effort parameter sent)", "detail": detail}
# -- provider error recording -------------------------------------------------------------
_SECRET_ENV_MARKERS = ("_API_KEY", "_TOKEN", "_SECRET", "PASSWORD")
def _secret_values() -> list[str]:
"""Values of environment variables that look like credentials (for redaction)."""
values = []
for name, value in os.environ.items():
upper = name.upper()
if value and len(value) >= 8 and any(m in upper for m in _SECRET_ENV_MARKERS):
values.append(value.strip())
return sorted(set(values), key=len, reverse=True)
def redact(text: str) -> str:
"""Mask credential values and common key shapes in free text before it is written."""
import re
for value in _secret_values():
text = text.replace(value, "[REDACTED]")
# Common provider key shapes, in case a value arrived by a path other than the env.
text = re.sub(r"sk-[A-Za-z0-9_-]{16,}", "[REDACTED]", text)
text = re.sub(r"\b(AKIA|ASIA)[A-Z0-9]{16}\b", "[REDACTED]", text)
return text
def sanitize_key_env() -> list[str]:
"""Strip stray whitespace from credential variables. A key pasted with a trailing
space or newline is an illegal HTTP header value and every request fails before
leaving the machine. Returns the names that were cleaned."""
cleaned = []
for name, value in list(os.environ.items()):
upper = name.upper()
if value and any(m in upper for m in _SECRET_ENV_MARKERS):
stripped = value.strip()
if stripped != value:
os.environ[name] = stripped
cleaned.append(name)
return cleaned
def root_cause_text(exc: BaseException) -> str:
"""The exception at the bottom of a failed model call's chain, in a few words: what a
person needs to see beside "Connection error." Empty when there is nothing underneath."""
cause = exc.__cause__ or exc.__context__
last: Optional[BaseException] = None
depth = 0
while cause is not None and depth < 8:
last = cause
cause = cause.__cause__ or cause.__context__
depth += 1
if last is None:
return ""
name = type(last).__name__
detail = " ".join(str(last).split())[:200]
if name == "ProxyError":
return f"the proxy answered {detail}" if detail else "the proxy refused the connection"
return f"{name}: {detail}" if detail else name
def recording_provider(inner, log_path: Path):
"""Wrap a ProviderClient so every model call leaves one line in model_calls.jsonl
(stop reason, usage, ceiling, effort, serving host) and every exception is written to
`log_path` with its full cause chain (credentials redacted), then re-raised unchanged.
The engine reports only the top-level message; the chain underneath is what says
whether it was DNS, TLS, a proxy, a refused socket, or a malformed header."""
from ..providers import ProviderClient
class Recording(ProviderClient):
def __init__(self) -> None:
self.inner = inner
# The root cause of the last failed call, for the line the person sees.
self.last_cause = ""
def _record(self, exc: BaseException, method: str) -> None:
try:
self.last_cause = redact(root_cause_text(exc))
except Exception: # noqa: BLE001
self.last_cause = ""
try:
lines = [f"=== {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} {method} ==="]
lines.append("".join(traceback.format_exception(exc)))
cause = exc.__cause__ or exc.__context__
depth = 0
while cause is not None and depth < 8:
lines.append(
f"--- caused by ({type(cause).__module__}.{type(cause).__name__}): {cause}"
)
cause = cause.__cause__ or cause.__context__
depth += 1
log_path.parent.mkdir(parents=True, exist_ok=True)
with log_path.open("a", encoding="utf-8") as fh:
fh.write(redact("\n".join(lines)) + "\n")
except Exception: # noqa: BLE001 - diagnostics must never mask the real error
pass
def _note_turn(self, turn, method: str) -> None:
try:
usage = turn.usage.as_dict() if getattr(turn, "usage", None) else None
rec = {
"ts": time.time(),
"method": method,
"finish_reason": getattr(turn, "finish_reason", None),
"max_output_tokens": getattr(turn, "output_limit", None),
"effort": getattr(turn, "effort", None),
"served_by": getattr(turn, "served_by", None),
"n_tool_calls": len(getattr(turn, "tool_calls", None) or []),
"text_chars": len(getattr(turn, "text", None) or ""),
"reasoning_chars": len(getattr(turn, "reasoning", None) or ""),
"usage": usage,
}
calls_path = log_path.with_name("model_calls.jsonl")
with calls_path.open("a", encoding="utf-8") as fh:
fh.write(json.dumps(rec) + "\n")
except Exception: # noqa: BLE001
pass
def complete(self, *, model, messages, tools=None, **settings):
try:
turn = self.inner.complete(model=model, messages=messages, tools=tools, **settings)
except BaseException as exc:
self._record(exc, "complete")
raise
self._note_turn(turn, "complete")
return turn
def stream(self, *, model, messages, tools=None, **settings):
try:
for chunk in self.inner.stream(model=model, messages=messages, tools=tools, **settings):
if getattr(chunk, "turn", None) is not None:
self._note_turn(chunk.turn, "stream")
yield chunk
except BaseException as exc:
self._record(exc, "stream")
raise
def capabilities(self, model):
return self.inner.capabilities(model)
def __getattr__(self, name): # anything else the engine may probe on the provider
return getattr(self.inner, name)
return Recording()
# -- the answers the engine gave for the absent user --------------------------------------
class Answers:
"""Every answer the engine gave on the absent user's behalf, taken from the audit
rows the engine writes: refused cards, floors the mode cleared, auto-answered
questions, declined folder requests, pinned installs. Written as answers.json."""
def __init__(self) -> None:
self.rows: list[dict[str, Any]] = []
def sink(self, row: dict[str, Any]) -> None:
stage = str(row.get("stage") or "")
keep = (
(stage == "approval_resolved" and row.get("approval") == "auto_refused")
or (stage == "auto_allowed" and str(row.get("reason") or "").startswith("cleared by mode"))
or stage in ("question_auto_answered", "directory_auto_refused", "tool_auto_install")
)
if keep:
self.rows.append(
{
"ts": time.time(),
"stage": stage,
"tool": row.get("tool"),
"arguments": _preview(row.get("arguments")),
"reason": row.get("reason"),
}
)
def counts(self) -> dict[str, int]:
def n(stage: str) -> int:
return sum(1 for r in self.rows if r["stage"] == stage)
return {
"cards_refused": n("approval_resolved"),
"floors_cleared": n("auto_allowed"),
"questions_answered": n("question_auto_answered"),
"directory_requests_declined": n("directory_auto_refused"),
"tool_installs": n("tool_auto_install"),
}
def _preview(value: Any, limit: int = 400) -> str:
text = json.dumps(value, default=str) if not isinstance(value, str) else value
return text if len(text) <= limit else text[:limit] + "…"
# -- the run ------------------------------------------------------------------------------
class NoPrompt(Exception):
pass
def _read_prompt(args: argparse.Namespace) -> str:
if args.prompt is not None:
return args.prompt
if args.prompt_file not in (None, "-"):
return Path(args.prompt_file).read_text(encoding="utf-8")
# Piped in: `cat task.md | openworker run`. A terminal is not read: the command would
# sit waiting for typing with nothing on screen saying so.
if args.prompt_file is None and sys.stdin.isatty():
raise NoPrompt("give the task with --prompt, --prompt-file, or pipe it in on standard input")
text = sys.stdin.buffer.read().decode("utf-8", errors="replace")
if not text.strip():
raise NoPrompt("standard input was empty; give the task with --prompt or --prompt-file")
return text
def _agent_version(explicit: Optional[str]) -> str:
if explicit:
return explicit
from importlib.metadata import PackageNotFoundError, version
for dist in ("openworker", "coworker"):
try:
return f"openworker {version(dist)}"
except PackageNotFoundError:
continue
except Exception: # noqa: BLE001
break
return "openworker unknown"
def _extra_dirs(args: argparse.Namespace, workspace: Path) -> list:
"""The `--add-dir DIR` folders as writable roots: created if missing, deduplicated, and
without the workspace itself (always the first root)."""
from ..roots import RootDir
found: list = []
for raw in args.add_dir or []:
path = Path(raw).expanduser().resolve()
if path == workspace or any(path == r.path for r in found):
continue
path.mkdir(parents=True, exist_ok=True)
found.append(RootDir(path=path, writable=True))
return found
def _mcp_server_defs(
args: argparse.Namespace, workspace: Path, secrets: Any
) -> list:
"""The MCP servers to attach for this run, or [] when MCP is off. `--mcp-config`
names one explicit file (the only source); otherwise this computer's layered config.
A workspace `.coworker/mcp.json` is executable provenance that needs trust the
headless runner does not establish, so only the global (or explicit) file is read."""
if not (args.mcp or args.mcp_config):
return []
from ..mcp import load_mcp_file, load_mcp_servers
if args.mcp_config:
return load_mcp_file(args.mcp_config, secrets=secrets)
return load_mcp_servers(workspace, secrets=secrets, workspace_trusted=False)
async def _attach_mcp(engine: Any, servers: list, secrets: Any, *, on_note: Any) -> Any:
"""Connect each enabled MCP server and register its tools on the LIVE engine.
Runs on the engine's own event loop (the `asyncio.run` loop that drives the turn),
so the sync→async tool bridge in `build_callables` targets the loop the tool thread
bridges back to. The engine reads `registry.schemas()` per turn, so tools registered
here are visible from the first model call. A server that fails to connect is noted
and skipped — the run continues without its tools. Returns the MCPManager to close
when the run ends, or None when nothing attached (so there is nothing to close)."""
from ..mcp import MCPManager, build_callables
manager = MCPManager(secrets=secrets)
loop = asyncio.get_running_loop()
attached = 0
for server in servers:
if not server.enabled:
continue
try:
conn = await manager.ensure(server)
except Exception as exc: # noqa: BLE001 - a bad server must never kill the run
tail = manager.last_stderr(server.name)
msg = f"{exc}" + (f" — {tail}" if tail else "")
on_note("mcp_server_failed", {"server": server.name, "error": msg[:600]})
continue
callables = build_callables(
server,
conn.tools,
lambda tool, a, name=server.name: manager.call(name, tool, a),
loop,
)
engine.registry.register_all(callables)
attached += len(callables)
on_note(
"mcp_server_attached",
{"server": server.name, "tools": [c.__name__ for c in callables]},
)
if attached == 0:
await manager.aclose()
return None
return manager
class UsageError(Exception):
"""The command line cannot be run as given: said on standard error, exit code 2."""
def workspace_folder_name(workspace: Path) -> str:
"""The workspace's folder under sessions/: its full path with every character that is
not a letter or a digit turned into a dash (`/Users/me/src/app` gives
`-Users-me-src-app`), so one workspace's runs sit together and are found by path."""
name = re.sub(r"[^A-Za-z0-9]", "-", str(workspace))
if len(name) > 180: # a file name's limit is 255 on the common filesystems
import hashlib
name = name[:160] + "-" + hashlib.sha256(str(workspace).encode("utf-8")).hexdigest()[:12]
return name
def session_folder(workspace: Path, run_id: str) -> Path:
from ..secrets import state_dir
return state_dir() / "sessions" / workspace_folder_name(workspace) / run_id
def allowed_sites(args: argparse.Namespace) -> list[str]:
"""`--allow-site` and `--allow-sites-file` as "host:port" entries. Exact host names,
as on the network-access card; anything else stops the run before it starts."""
from ..permissions import network_request_hosts
wanted = list(args.allow_site or [])
if args.allow_sites_file:
try:
text = Path(args.allow_sites_file).expanduser().read_text(encoding="utf-8")
except OSError as exc:
raise UsageError(f"cannot read --allow-sites-file: {exc}") from exc
for line in text.splitlines():
line = line.split("#", 1)[0].strip()
if line:
wanted.append(line)
good, bad = network_request_hosts({"hosts": wanted})
if bad:
raise UsageError(
"not a site name: " + ", ".join(bad) + ". Give exact host names, with a port "
"only when it is not 443 (no wildcards, no addresses)."
)
return good
# Exit codes. 0 only when the task finished; a run that stopped early still left its record.
EXIT_FINISHED = 0
EXIT_CRASHED = 1 # no usable record
EXIT_USAGE = 2
EXIT_STOPPED = 3 # timeout, model error, iteration cap: the record is written
EXIT_INTERRUPTED = 130 # Ctrl-C, as a shell reports it; the record is written
def run(args: argparse.Namespace) -> int:
try:
return _run(args)
except UsageError as exc:
print(f"openworker run: {exc}", file=sys.stderr)
return EXIT_USAGE
def _run(args: argparse.Namespace) -> int:
if args.isolated and not args.out:
raise UsageError("--isolated needs --out: an isolated run keeps everything in that folder")
if args.isolated and not args.model:
raise UsageError("--isolated needs --model: an isolated run reads no settings from this computer")
try:
prompt = _read_prompt(args)
except NoPrompt as exc:
raise UsageError(str(exc)) from exc
sites = allowed_sites(args)
workspace = Path(args.workspace).resolve()
run_id = uuid.uuid4().hex[:12]
# Where OpenWorker's state is read from, set BEFORE the engine is built. Isolated: a
# fresh folder under --out, so nothing of this computer is read or written. Otherwise
# this computer's own state folder, read for its settings, keys, sandbox and allowed
# sites; what the run writes goes to its own record folder.
if args.isolated:
out = Path(args.out).resolve()
out.mkdir(parents=True, exist_ok=True)
isolation = isolate_environment(out)
else:
out = Path(args.out).resolve() if args.out else session_folder(workspace, run_id)
os.environ["COWORKER_SCRATCH_BASE"] = str(out / "scratch")
isolation = {"COWORKER_SCRATCH_BASE": str(out / "scratch")}
cleaned_keys = sanitize_key_env()
if cleaned_keys:
print(f"openworker run: stripped stray whitespace from {', '.join(cleaned_keys)}", file=sys.stderr)
# Build the engine only now, after the isolation variables are set.
from ..agent import build_engine
from ..agents.registry import get_agent
from ..audit import AuditStore
from ..events import EventType
from ..permissions import Mode
from ..providers import ProviderRouter
from ..roots import RootDir
from ..secrets import SecretStore, state_dir
from ..unattended import DANGEROUS_MODE_WARNING
# An unknown id would otherwise run the default coworker without saying so.
from ..personas.registry import get_registry
known = get_registry().ids()
if args.coworker not in known:
raise UsageError(f"no coworker has the id {args.coworker!r}. Known ids: {', '.join(sorted(known))}")
out.mkdir(parents=True, exist_ok=True)
# Made now, not on first use: a sandbox is given the run's folders when it starts, and
# it cannot be given one that does not exist yet.
for name in ("scratch", "tool-output"):
(out / name).mkdir(parents=True, exist_ok=True)
workspace.mkdir(parents=True, exist_ok=True)
# `--add-dir DIR`: extra writable folders. An explicit list replaces the engine's
# default single-workspace root, so the workspace goes first and stays the folder
# that relative paths resolve against.
extra_dirs = _extra_dirs(args, workspace)
roots = [RootDir(path=workspace, writable=True), *extra_dirs] if extra_dirs else None
if not args.model:
from ..config import load_config
args.model = load_config(workspace).model
model = normalize_model(args.model)
mode = Mode(args.mode)
answers = Answers()
# Who answers. Approvals and questions are separate: an approval is the person's at a
# terminal and refused without one; a question is the person's at a terminal unless
# --auto-answer says nobody will answer, and answered by rule without a terminal.
from .terminal import Terminal
terminal = Terminal.attached(cwd=workspace)
auto_answer = bool(args.auto_answer) or terminal is None
args.attendance = "auto" if auto_answer else "attended"
if terminal is None and mode is Mode.INTERACTIVE:
print(
"openworker run: no terminal is attached, so every approval is refused in mode "
"ask. For a run with nobody present use --approval-mode auto-approve or bypass-approvals.",
file=sys.stderr,
flush=True,
)
secrets = SecretStore(state_dir() / "secrets.json")
# MCP servers to attach (if any), resolved with this run's SecretStore for ${VAR}
# refs. Connected later, on the engine's own event loop (see guarded()).
mcp_servers = _mcp_server_defs(args, workspace, secrets)
if (args.mcp or args.mcp_config) and not mcp_servers:
print(
"openworker run: --mcp was given but no MCP servers were found in "
+ (args.mcp_config or "this computer's mcp.json")
+ "; the run continues with no MCP tools.",
file=sys.stderr,
flush=True,
)
if args.scripted:
provider = scripted_provider(Path(args.scripted))
else:
default_provider = model.split(":", 1)[0] if ":" in model else "openai"
provider = ProviderRouter(secrets, default_provider=default_provider)
provider = recording_provider(provider, out / "provider_errors.log")
audit = AuditStore(out / "audit.db")
def audit_sink(row: dict[str, Any]) -> None:
audit.append(row)
answers.sink(row)
engine = build_engine(
agent=get_agent(args.coworker),
workspace=workspace,
roots=roots,
model=model,
mode=mode,
provider=provider,
audit_sink=audit_sink,
max_iterations=args.max_iterations,
web_tools=not args.no_web_tools,
# The model's saved settings (model_config.py) first; the run's own flags win.
# An isolated run reads nothing from the computer.
model_settings=_merged_model_settings(args, model),
# Bounded tool results; the full texts stay with the record under tool-output/.
tool_result_max_bytes=args.tool_result_max_bytes,
tool_result_spill_dir=out / "tool-output",
session_id=run_id,
secrets=secrets,
# The reviewer only exists in auto-approve mode; elsewhere leave the config default.
auto_approve=True if mode is Mode.AUTO_APPROVE else None,
approver=terminal.approve if terminal is not None else None,
question_asker=terminal.ask if terminal is not None and not auto_answer else None,
directory_requester=terminal.directory if terminal is not None and not auto_answer else None,
tool_requester=terminal.tool if terminal is not None and not auto_answer else None,
# Connectors: whatever is connected on this computer and the coworker may use,
# as in the app. Their sign-ins are renewed under the store's lock
# (secrets.SecretStore.exclusive), so a run and the app do not collide. An
# isolated run has none: its state folder is empty.
)
# Questions: answered by rule when nobody will (coworker/unattended.py). Approvals:
# with a terminal they reach the person whatever --auto-answer says.
engine.attendance = lambda: args.attendance
if terminal is not None:
engine.cards_reach_person = lambda: True
engine.is_attended = lambda: True
def grant_folder(folder: Path, writable: bool) -> Path:
"""The person gave the coworker another folder. The engine's list of folders is
shared with the file tools, the permission checks and the sandbox, so they all
see it from the next call."""
from ..basedir import ensure_under_base
resolved = ensure_under_base(folder, "folder")
for root in engine.roots:
if root.path == resolved:
root.writable = bool(writable) or root.writable
return resolved
engine.roots.append(RootDir(path=resolved, writable=bool(writable)))
return resolved
terminal.grant_folder = grant_folder
if sites:
if engine.permissions.sandbox_sites is None:
print(
"openworker run: --allow-site has no effect here: this run's commands are "
"not held to a list of allowed sites.",
file=sys.stderr,
flush=True,
)
else:
engine.permissions.allow_network_hosts(sites, always=False)
if mode is Mode.DANGEROUSLY_BYPASS_APPROVALS:
print(f"openworker run: {DANGEROUS_MODE_WARNING}", file=sys.stderr, flush=True)
if args.compaction_cap_tokens or args.compaction_summary_max_tokens:
# Compact early so a cheap task exercises the summariser and the persisted
# compaction record. Window comes from the model matrix.
_base_cfg = engine._compaction_config()
_forced = {
"cap_tokens": int(args.compaction_cap_tokens or _base_cfg["cap_tokens"]),
"threshold_pct": float(_base_cfg["threshold_pct"]),
"context_window": _base_cfg.get("context_window"),
"summary_max_tokens": int(
args.compaction_summary_max_tokens or _base_cfg["summary_max_tokens"]
),
}
engine.compaction_settings = lambda: dict(_forced)
events: list[dict[str, Any]] = []
outcome = "unknown"
error_text: Optional[str] = None
raw_error = ""
started = time.time()
# Records are written INCREMENTALLY. An outer time limit may end the process with a
# signal, and a runner that only writes at the end leaves nothing behind. So: every
# event is appended to events.jsonl as it happens, and after every iteration a
# provisional summary, messages, and trajectory are rewritten. SIGTERM also flushes.
events_fh = (out / "events.jsonl").open("w", encoding="utf-8")
def _mcp_note(kind: str, data: dict[str, Any]) -> None:
"""Record one MCP attach/fail line to the event stream and stderr."""
rec = {"ts": time.time(), "type": kind, "data": data}
events.append(rec)
events_fh.write(json.dumps(rec, default=str) + "\n")
events_fh.flush()
if kind == "mcp_server_failed":
print(
f"openworker run: MCP server {data.get('server')!r} failed to connect: "
f"{data.get('error')}",
file=sys.stderr,
flush=True,
)
else:
print(
f"openworker run: MCP {data.get('server')}: "
f"{len(data.get('tools') or [])} tools attached",
file=sys.stderr,
flush=True,
)
def flush_provisional(status: str) -> None:
try:
events_fh.flush()
_write_records(
out=out,
engine=engine,
events=events,
answers=answers,
outcome=status,
error_text=None,
wall=time.time() - started,
model=model,
args=args,
run_id=run_id,
isolation=isolation,
trajectory_extra_path=None, # final copy to --trajectory-atif happens at the end
)
except Exception: # noqa: BLE001 - a provisional write must never break the run
pass
import signal
# A stop signal (what `timeout`, a CI job or `docker stop` sends) ends the run: the
# engine is interrupted, and a wait between retries is cut short. Without the second
# part a run waiting out a provider error ignored the signal until a hard kill.
stop: dict[str, Any] = {"asked": False, "loop": None, "event": None}
def _on_term(signum, frame): # noqa: ARG001
stop["asked"] = True
try:
engine.request_interrupt()
loop, event = stop["loop"], stop["event"]
if loop is not None and event is not None:
loop.call_soon_threadsafe(event.set)
finally:
flush_provisional("killed")
async def wait_or_stop(seconds: float) -> bool:
"""Wait before a retry. True when a stop signal arrived instead."""
if stop["asked"]:
return True
try:
await asyncio.wait_for(stop["event"].wait(), timeout=seconds)
except asyncio.TimeoutError:
return False
return True
def error_with_cause(data: dict[str, Any]) -> str:
"""`Connection error.` says nothing; the cause underneath does (a proxy's 403, a
refused socket). Shown on the retry line so nobody has to open the record."""
text = f"{data.get('error_type')}: {str(data.get('error'))[:120]}"
cause = str(getattr(provider, "last_cause", "") or "")
return f"{text} Cause: {cause}" if cause and cause not in text else text
for sig in (signal.SIGTERM, getattr(signal, "SIGHUP", None)):
if sig is not None:
try:
signal.signal(sig, _on_term)
except (ValueError, OSError):
pass
async def consume() -> None:
stop["loop"], stop["event"] = asyncio.get_running_loop(), asyncio.Event()
delays = provider_retry_delays()
retries = 0
message: Any = prompt
while True:
last_type = None
last_data: dict[str, Any] = {}
pass_start = len(events)
async for ev in engine.run(message):
rec = {"ts": time.time(), "type": ev.type.value, "data": ev.data}
events.append(rec)
events_fh.write(json.dumps(rec, default=str) + "\n")
last_type, last_data = ev.type, ev.data
if ev.type == EventType.PERMISSION_REQUIRED and terminal is not None:
terminal.card = dict(ev.data) # the approver is asked next
elif ev.type == EventType.TOOL_PROPOSED:
_progress(ev.data)
if ev.type == EventType.ITERATION_END:
flush_provisional("in_progress")
# A transient provider failure ended the turn: wait, then re-enter the same
# conversation with a nudge (the engine keeps every message so far).
if (
last_type == EventType.ERROR
and retries < len(delays)
and is_transient_provider_error(last_data)
):
delay = delays[retries]
retries += 1
rec = {
"ts": time.time(),
"type": "provider_retry",
"data": {
"attempt": retries,
"of": len(delays),
"delay_seconds": delay,
"error": last_data.get("error"),
"error_type": last_data.get("error_type"),
"cause": str(getattr(provider, "last_cause", "") or ""),
},
}
events.append(rec)
events_fh.write(json.dumps(rec, default=str) + "\n")
events_fh.flush()
print(
f"openworker run: provider error ({error_with_cause(last_data)}); "
f"retry {retries}/{len(delays)} in {delay}s",
file=sys.stderr,
flush=True,
)
flush_provisional("in_progress")
if await wait_or_stop(delay):
break
message = PROVIDER_RETRY_NUDGE
continue
# An empty reply ended the turn as "completed": same wait-and-nudge, same budget.
if (
last_type == EventType.TURN_END
and str(last_data.get("status") or "") == "completed"
and retries < len(delays)
and ended_on_empty_reply(events[pass_start:])
):
delay = delays[retries]
retries += 1
rec = {
"ts": time.time(),
"type": "provider_retry",
"data": {
"attempt": retries,
"of": len(delays),
"delay_seconds": delay,
"error": "empty reply (no text, no tool call)",
"error_type": "EmptyReply",
},
}
events.append(rec)
events_fh.write(json.dumps(rec, default=str) + "\n")
events_fh.flush()
print(
f"openworker run: empty reply; retry {retries}/{len(delays)} in {delay}s",
file=sys.stderr,
flush=True,
)
flush_provisional("in_progress")
if await wait_or_stop(delay):
break
message = EMPTY_REPLY_NUDGE
continue
break
async def guarded() -> None:
# MCP servers attach on THIS loop so their sync→async tool bridge targets the loop
# the engine runs on, and close here too (same task — the SDK's transports require
# enter and exit on one task). Attachment is outside the run's timeout: it is a
# one-time local connect, and a slow server should not eat the task's clock.
mcp_manager = (
await _attach_mcp(engine, mcp_servers, secrets, on_note=_mcp_note)
if mcp_servers
else None
)
try:
# timeout_seconds <= 0 disables the run's own limit (an outer runner may enforce
# its own; a second, shorter limit here would cut long tasks early).
if args.timeout_seconds and args.timeout_seconds > 0:
await asyncio.wait_for(consume(), timeout=args.timeout_seconds)
else:
await consume()
finally:
if mcp_manager is not None:
await mcp_manager.aclose()
try:
asyncio.run(guarded())
except asyncio.TimeoutError:
outcome = "timeout"
try:
engine.request_interrupt()
except Exception: # noqa: BLE001
pass
except KeyboardInterrupt: # Ctrl-C: stop, and still leave the record
outcome = "interrupted"
try:
engine.request_interrupt()
except Exception: # noqa: BLE001
pass
except Exception as exc: # noqa: BLE001 - recorded, then reported by exit code
outcome = "crash"
error_text = "".join(traceback.format_exception(exc))
finally:
executor = getattr(engine, "executor", None)
if executor is not None:
try:
executor.close()
except Exception: # noqa: BLE001
pass
# The run's sandbox ends with the run.
sandbox = getattr(engine, "sandbox_workspace", None)
if sandbox is not None:
try:
sandbox.close()
except Exception: # noqa: BLE001
pass
wall = time.time() - started
try:
events_fh.close()
except Exception: # noqa: BLE001
pass
if stop["asked"] and outcome in ("unknown", "timeout"):
outcome = "interrupted" # a stop signal ended it, whatever the last event was
# Outcome from the events when the loop ended on its own.
if outcome == "unknown":
outcome = "ended_without_turn_end"
for ev in reversed(events):
if ev["type"] == EventType.TURN_END.value:
outcome = str(ev["data"].get("status", "completed"))
break
if ev["type"] == EventType.ERROR.value:
outcome = "model_error"
error_text = str(ev["data"].get("error", ""))
# When the engine rewrote the message with friendly guidance, the
# provider's own wording is preserved here — surface it too, so a
# user grepping for the raw provider error still finds it.
raw_error = str(ev["data"].get("raw", "") or "")
break
if ev["type"] == EventType.INTERRUPTED.value:
outcome = "interrupted"
break
summary = _write_records(
out=out,
engine=engine,
events=events,
answers=answers,
outcome=outcome,
error_text=error_text,
wall=wall,
model=model,
args=args,
run_id=run_id,
isolation=isolation,
trajectory_extra_path=args.trajectory_atif,
)
tokens = summary["tokens"]
# Standard output is the coworker's answer and nothing else; the rest is standard error.
answer = _final_answer(engine)
if answer:
sys.stdout.write(answer if answer.endswith("\n") else answer + "\n")
sys.stdout.flush()
print(
f"openworker run: outcome={outcome} iterations={summary['iterations']} "
f"tool_calls={summary['tool_calls']} refused={summary['answers']['cards_refused']} "
f"tokens_in={tokens['input']} tokens_out={tokens['output']} "
f"cost={summary['cost_usd']} wall={wall:.0f}s out={out}",
file=sys.stderr,
flush=True,
)
if outcome == "crash":
return EXIT_CRASHED
if outcome == "interrupted":
return EXIT_INTERRUPTED
if outcome != "completed" and error_text:
# Why it stopped, in a line: the full text is in the record.
why = redact(error_text.strip().splitlines()[-1])[:600]
cause = str(getattr(provider, "last_cause", "") or "")
if outcome == "model_error" and cause and cause not in why:
why = f"{why} Cause: {cause}"
if raw_error.strip() and redact(raw_error.strip().splitlines()[-1])[:200] not in why:
# The engine's friendly rewrite replaced the provider's message; keep the
# original provider wording on stderr so it stays findable and greppable.
why = f"{why} (provider said: {redact(raw_error.strip().splitlines()[-1])[:200]})"
print(f"openworker run: {why}", file=sys.stderr, flush=True)
return EXIT_FINISHED if outcome == "completed" else EXIT_STOPPED
def _progress(data: dict[str, Any]) -> None:
"""One line per tool call on standard error, so a person watching sees the run move."""
name = str(data.get("name") or "")
args = data.get("arguments") if isinstance(data.get("arguments"), dict) else {}
detail = ""
for key in ("command", "path", "url", "query", "pattern"):
if isinstance(args.get(key), str) and args[key].strip():
detail = " ".join(args[key].split())
break
line = f" {name}" + (f": {detail}" if detail else "")
print(line if len(line) <= 160 else line[:159] + "…", file=sys.stderr, flush=True)
def _final_answer(engine: Any) -> str:
"""The text of the coworker's last reply."""
for message in reversed(getattr(engine, "messages", None) or []):
if message.get("role") != "assistant":
continue
content = message.get("content")
if isinstance(content, list):
content = "".join(
str(part.get("text", "")) for part in content if isinstance(part, dict) and part.get("type") == "text"
)
if isinstance(content, str) and content.strip():
return content.strip()
return ""
def _merged_model_settings(args: argparse.Namespace, model: str) -> Optional[dict[str, Any]]:
from .. import model_config
saved = {} if getattr(args, "isolated", False) else model_config.model_settings_for(model)
merged = {**saved, **(_model_settings(args) or {})}
return merged or None
def _model_settings(args: argparse.Namespace) -> Optional[dict[str, Any]]:
"""Explicit per-run settings that ride model_settings into every provider call:
the output ceiling and the reasoning-effort level."""
settings: dict[str, Any] = {}
if args.max_output_tokens:
settings["max_tokens"] = args.max_output_tokens
if args.reasoning_effort:
settings["reasoning_effort"] = args.reasoning_effort
if args.provider_order:
# OpenRouter's routing field rides the OpenAI SDK's `extra_body`, which
# OpenWorker's OpenAI-compatible client passes through untouched.
order = [x.strip() for x in args.provider_order.split(",") if x.strip()]
settings["extra_body"] = {"provider": {"order": order, "allow_fallbacks": False}}
return settings or None
def _effort_summary(args: argparse.Namespace, model: str, events: list[dict[str, Any]]) -> dict[str, Any]:
"""What the run record says about effort. Set: the level requested plus what the
provider reported sending on each reply. Unset: the provider default described from
OpenWorker's code."""
if not args.reasoning_effort:
described = describe_reasoning_effort(model)
return {"label": described["label"], "detail": described["detail"]}
records = [
e["data"].get("reasoning_effort")
for e in events
if e["type"] == "assistant_message" and e["data"].get("reasoning_effort")
]
effective = sorted({str(r.get("effective")) for r in records}) if records else []
detail: dict[str, Any] = {
"requested": args.reasoning_effort,
"effective": effective[0] if len(effective) == 1 else effective,
"replies_recorded": len(records),
"first_record": records[0] if records else None,
"notes": sorted({r["note"] for r in records if r.get("note")}),
}
label = args.reasoning_effort
if len(effective) == 1 and effective[0] not in (args.reasoning_effort, "None"):
label = f"{args.reasoning_effort} (sent as {effective[0]})"
elif effective == ["None"]:
label = f"{args.reasoning_effort} (requested; provider sent no effort parameter)"
return {"label": label, "detail": detail}
def _context_record(engine: Any) -> dict[str, Any]:
try:
from .. import compaction as _compaction
cfg = engine._compaction_config()
window = cfg.get("context_window")
return {
"window": window,
"window_source": "matrix" if window else "fallback",
"compaction_trigger_tokens": _compaction.trigger_tokens(
window,
threshold_pct=float(cfg["threshold_pct"]),
cap_tokens=int(cfg["cap_tokens"]),
),
}
except Exception: # noqa: BLE001 - a record field must never break the run
return {"window": None, "window_source": "unknown", "compaction_trigger_tokens": None}
def _write_records(
*,
out: Path,
engine: Any,
events: list[dict[str, Any]],
answers: Answers,
outcome: str,
error_text: Optional[str],
wall: float,
model: str,
args: argparse.Namespace,
run_id: str,
isolation: dict[str, str],
trajectory_extra_path: Optional[str],
) -> dict[str, Any]:
"""Compute the summary from the events so far and (re)write summary.json,
messages.json, answers.json, and trajectory.json. Called after every iteration with a
provisional outcome and once more at the end with the final one, so a process killed
by an outer time limit still leaves a usable record."""
from ..events import EventType
from .pricing import estimate_cost
from .trajectory import build_trajectory, write_trajectory
tool_finished = [e for e in events if e["type"] == EventType.TOOL_FINISHED.value]
assistant = [e for e in events if e["type"] == EventType.ASSISTANT_MESSAGE.value]
tokens = {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0}
model_calls_with_usage = 0
for e in assistant:
usage = e["data"].get("usage")
if usage:
model_calls_with_usage += 1
for k in tokens:
tokens[k] += int(usage.get(k, 0) or 0)
iterations = 0
for e in events:
if e["type"] == EventType.ITERATION_END.value:
iterations = max(iterations, int(e["data"].get("iteration", 0) or 0))
if e["type"] == EventType.TURN_END.value:
iterations = max(iterations, int(e["data"].get("iterations", 0) or 0))
cost = estimate_cost(model, tokens)
effort = _effort_summary(args, model, events)
summary = {
"run_id": run_id,
"outcome": outcome,
"reasoning_effort": effort["label"],
"reasoning_effort_detail": effort["detail"],
"error": error_text,
"wall_seconds": round(wall, 1),
"iterations": iterations,
"model_calls": len(assistant),
"model_calls_with_usage": model_calls_with_usage,
"tool_calls": len(tool_finished),
# Tool results the engine bounded (head + marker + tail; full text under
# <out>/tool-output). Counted from the marker the bounder writes.
"tool_results_bounded": sum(
1
for m in getattr(engine, "messages", [])
if m.get("role") == "tool" and "bytes omitted here" in str(m.get("content") or "")
),
"tool_calls_denied": sum(1 for e in tool_finished if e["data"].get("status") == "denied"),
"tool_calls_error": sum(1 for e in tool_finished if e["data"].get("status") == "error"),
# Replies cut off at the output limit with no action that the engine nudged past;
# outcome "truncated" means the cap was hit repeatedly.
"continuations": sum(1 for e in events if e["type"] == "continuation"),
# Transient provider failures the runner waited out and resumed from; outcome
# "model_error" means the schedule was exhausted (or the error was permanent).
"provider_retries": sum(1 for e in events if e["type"] == "provider_retry"),
# What the engine answered on the absent user's behalf (coworker/unattended.py).
"answers": answers.counts(),
"tokens": tokens,
"cost_usd": cost,
"args": {
"model": model,
"model_as_given": args.model,
"coworker": args.coworker,
"approval_mode": args.approval_mode,
# Questions were answered by rule (--auto-answer, or no terminal to ask on).
"auto_answer": args.attendance == "auto",
"isolated": bool(args.isolated),
"max_iterations": args.max_iterations,
# False = web_search / web_fetch were never in the tool list (--no-web-tools).
"web_tools": not args.no_web_tools,
"max_output_tokens": args.max_output_tokens,
"reasoning_effort": args.reasoning_effort,
"compaction_cap_tokens": args.compaction_cap_tokens,
"compaction_summary_max_tokens": args.compaction_summary_max_tokens,
"tool_result_max_bytes": args.tool_result_max_bytes,
"provider_order": args.provider_order,
"timeout_seconds": args.timeout_seconds,
"workspace": str(Path(args.workspace).resolve()),
"extra_dirs": [str(Path(r).expanduser().resolve()) for r in (args.add_dir or [])],
"mcp": bool(args.mcp or args.mcp_config),
"mcp_config": args.mcp_config,
"scripted": bool(args.scripted),
},
# MCP servers attached this run and the tools each exposed, from the attach events.
"mcp_servers": [
{"server": e["data"].get("server"), "tools": e["data"].get("tools")}
for e in events
if e["type"] == "mcp_server_attached"
],
"isolation": isolation,
# The window and trigger the engine actually used: an unlisted model shows
# window null and the fallback trigger.
"context": _context_record(engine),
# Distinct upstream hosts reported by a router across the run (proof of a pin).
"served_by": sorted(
{
str(e["data"]["served_by"])
for e in events
if e["type"] == "assistant_message" and e["data"].get("served_by")
}
),
# Every compaction that happened, as persisted on the notices.
"compactions": [
{
"trimmed": bool((m.get("compaction") or {}).get("trimmed")),
"boundary_index": (m.get("compaction") or {}).get("boundary_index"),
"model_used": (m.get("compaction") or {}).get("model_used"),
"summary_chars": len(str((m.get("compaction") or {}).get("summary_text") or "")),
}
for m in engine.messages
if m.get("role") == "notice" and m.get("kind") == "compacted"
],
}
(out / "messages.json").write_text(
json.dumps(engine.messages, indent=1, default=str), encoding="utf-8"
)
(out / "answers.json").write_text(
json.dumps({"counts": answers.counts(), "rows": answers.rows}, indent=1),
encoding="utf-8",
)
(out / "summary.json").write_text(json.dumps(summary, indent=1), encoding="utf-8")
trajectory = build_trajectory(
engine.messages,
agent_name="openworker",
agent_version=_agent_version(args.agent_version),
model_name=model,
session_id=run_id,
outcome=outcome,
reasoning_effort=effort["label"],
agent_extra={
"coworker": args.coworker,
"approval_mode": args.approval_mode,
# Questions were answered by rule (--auto-answer, or no terminal to ask on).
"auto_answer": args.attendance == "auto",
"web_tools": not args.no_web_tools,
"reasoning_effort": effort["label"],
"reasoning_effort_detail": effort["detail"],
},
)
write_trajectory(out / "trajectory.json", trajectory)
if trajectory_extra_path:
write_trajectory(trajectory_extra_path, trajectory)
return summary
def main(argv: Optional[list[str]] = None) -> None:
args = parse_args(argv)
try:
code = run(args)
except Exception: # noqa: BLE001 - last resort: say what happened, exit non-zero
traceback.print_exc()
code = 1
sys.exit(code)
if __name__ == "__main__":
main()