Skip to content
Python

Add `openworker run`: one task, no human, a record left behind (OPE-196)

Devika Verma78acad675851
diff --git a/coworker/cli.py b/coworker/cli.py
index a0d06bb0..66ae7718 100644
--- a/coworker/cli.py
+++ b/coworker/cli.py
@@ -1,9 +1,10 @@
"""CLI entry point.
Public surface: `openworker join <link>` and `openworker up` (the two everyday commands),
-`openworker machine <command>` (status, keys, logs, service, leave), `openworker version`,
-and help. The terminal UI (`openworker tui`, or a skill name as before) is unlisted until
-it has been tested as a product surface.
+`openworker run` (one task, no human, a record left behind), `openworker machine
+<command>` (status, keys, logs, service, leave), `openworker version`, and help. The
+terminal UI (`openworker tui`, or a skill name as before) is unlisted until it has been
+tested as a product surface.
"""
from __future__ import annotations
@@ -31,6 +32,7 @@ commands:
(the link comes from the app: Settings > Machines > Add a machine;
give the controller's address instead to approve a code there)
up serve again with the stored identity
+ run <task> run one task with no human and exit (writes a record and a trajectory)
machine manage this machine
status show enrollment and the sealing-key fingerprint (--json)
keys manage provider keys stored on this machine
@@ -77,6 +79,11 @@ def main(argv: Optional[list[str]] = None) -> None:
from .remote.joiner import cli as remote_cli
raise SystemExit(remote_cli(args, prog="openworker", only=TOP_COMMANDS))
+ if args[0] == "run":
+ from .headless.runner import main as run_main
+
+ run_main(args[1:]) # exits with the run's code
+ return
if args[0] == "machine":
from .remote.joiner import cli as remote_cli
diff --git a/coworker/headless/__init__.py b/coworker/headless/__init__.py
new file mode 100644
index 00000000..a9584886
--- /dev/null
+++ b/coworker/headless/__init__.py
@@ -0,0 +1,9 @@
+"""Headless one-shot runs: `openworker run` (coworker/headless/runner.py).
+
+Give it a task, a folder and a model; it builds the same engine the desktop app uses,
+runs the task to the end with nobody present, and leaves a record behind: every event,
+the final conversation, a summary with tokens and cost, the audit log, and a trajectory
+in the ATIF interchange format (coworker/headless/trajectory.py). Questions, folder
+requests, pinned installs and approval cards are answered by the engine's attendance
+rules (coworker/unattended.py), never by a person and never by a policy file.
+"""
diff --git a/coworker/headless/prices.yaml b/coworker/headless/prices.yaml
new file mode 100644
index 00000000..299c75a0
--- /dev/null
+++ b/coworker/headless/prices.yaml
@@ -0,0 +1,94 @@
+# Token prices in USD per MILLION tokens, keyed by the OpenWorker model id (provider:model).
+#
+# Fields: input, output, cache_read, cache_write. cache_write is the 5-minute cache write
+# price; OpenWorker's usage does not distinguish 5-minute from 1-hour cache writes, so
+# the cheaper rate is assumed. A model with no entry gets cost = null in summary.json and
+# in the trajectory; token counts are always recorded.
+#
+# This table is a cross-check for a run's own record. Re-check every row against the
+# vendor's page before relying on it, and update the date in its source line.
+models:
+ "anthropic:claude-sonnet-5":
+ input: 2.00
+ output: 10.00
+ cache_read: 0.20
+ cache_write: 2.50
+ source: "https://claude.com/pricing (checked 2026-09-06)"
+ "anthropic:claude-opus-5":
+ input: 5.00
+ output: 25.00
+ cache_read: 0.50
+ cache_write: 6.25
+ source: "https://claude.com/pricing (checked 2026-09-06)"
+ "anthropic:claude-fable-5":
+ input: 10.00
+ output: 50.00
+ cache_read: 1.00
+ cache_write: 12.50
+ source: "https://claude.com/pricing (checked 2026-09-06), listed under legacy models; cache read is 1.00 vs 0.25 for Fable 5.1"
+ "anthropic:claude-fable-5-1":
+ input: 10.00
+ output: 50.00
+ cache_read: 0.25
+ cache_write: 12.50
+ source: "https://claude.com/pricing (checked 2026-09-06)"
+ "anthropic:claude-haiku-4-5":
+ input: 1.00
+ output: 5.00
+ cache_read: 0.10
+ cache_write: 1.25
+ source: "https://claude.com/pricing (checked 2026-09-06)"
+ "anthropic:claude-sonnet-4-6":
+ input: 3.00
+ output: 15.00
+ cache_read: 0.30
+ cache_write: 3.75
+ source: "https://claude.com/pricing (checked 2026-09-06), listed as legacy"
+ "anthropic:claude-opus-4-6":
+ input: 5.00
+ output: 25.00
+ cache_read: 0.50
+ cache_write: 6.25
+ source: "https://claude.com/pricing (checked 2026-09-16), listed as legacy"
+ "anthropic:claude-opus-4-5":
+ input: 5.00
+ output: 25.00
+ cache_read: 0.50
+ cache_write: 6.25
+ source: "https://claude.com/pricing (checked 2026-09-16), listed as legacy"
+ "anthropic:claude-sonnet-4-5":
+ input: 3.00
+ output: 15.00
+ cache_read: 0.30
+ cache_write: 3.75
+ source: "https://claude.com/pricing (checked 2026-09-16), listed as legacy"
+ # Together serverless prices copied from https://www.together.ai/pricing on 2026-09-06.
+ # Together lists a cached-input price but no separate cache-write price; cache_write is
+ # set to the plain input price.
+ "together:zai-org/GLM-5.1":
+ input: 1.40
+ output: 4.40
+ cache_read: 0.26
+ cache_write: 1.40
+ source: "Together /v1/models pricing field for zai-org/GLM-5.1 (read 2026-09-06); not on the public price page"
+ "together:zai-org/GLM-5.2":
+ input: 1.40
+ output: 4.40
+ cache_read: 0.26
+ cache_write: 1.40
+ source: "https://www.together.ai/pricing (checked 2026-09-06)"
+ "together:moonshotai/Kimi-K3":
+ input: 3.00
+ output: 15.00
+ cache_read: 0.30
+ cache_write: 3.00
+ source: "https://www.together.ai/pricing (checked 2026-09-06)"
+ # Kimi K3 via OpenRouter, pinned to the Together host (`--provider-order Together`).
+ # OpenRouter's own default row for this model is the cheapest host's price, which is
+ # not what a Together-pinned run pays; these are the Together endpoint's rates.
+ "openrouter:moonshotai/kimi-k3":
+ input: 3.00
+ output: 15.00
+ cache_read: 0.30
+ cache_write: 3.00
+ source: "https://openrouter.ai/api/v1/models/moonshotai/kimi-k3/endpoints (read 2026-09-09), Together endpoint"
diff --git a/coworker/headless/pricing.py b/coworker/headless/pricing.py
new file mode 100644
index 00000000..e99115ee
--- /dev/null
+++ b/coworker/headless/pricing.py
@@ -0,0 +1,56 @@
+"""Token prices, used to estimate the cost of a headless run. An unknown model gets no
+cost, never a guess; token counts are always recorded regardless.
+
+The table (prices.yaml beside this file) is a cross-check, not the source of truth: a
+run's cost is recomputed by whoever consumes the trajectory. Re-check the rows against
+the vendors' pages before relying on them and update the dates in the file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+_PRICES_PATH = Path(__file__).with_name("prices.yaml")
+_NUMERIC = ("input", "output", "cache_read", "cache_write")
+
+
+def load_prices() -> dict[str, dict[str, float]]:
+ """{model id: {input, output, cache_read, cache_write}} in USD per million tokens."""
+ try:
+ data = yaml.safe_load(_PRICES_PATH.read_text(encoding="utf-8")) or {}
+ except FileNotFoundError:
+ return {}
+ models = data.get("models") or {}
+ return {
+ str(k): {f: float((spec or {})[f]) for f in _NUMERIC if f in (spec or {})}
+ for k, spec in models.items()
+ }
+
+
+def estimate_cost(
+ model: str, usage: dict[str, Any], prices: Optional[dict] = None
+) -> Optional[float]:
+ """USD for one usage record {input, output, cache_read, cache_write} (token counts).
+ Returns None when the model has no row."""
+ prices = load_prices() if prices is None else prices
+ spec = prices.get(model)
+ if not spec:
+ return None
+ per_million = 1_000_000.0
+ cost = 0.0
+ cost += float(usage.get("input", 0) or 0) * spec.get("input", 0.0) / per_million
+ cost += float(usage.get("output", 0) or 0) * spec.get("output", 0.0) / per_million
+ cost += (
+ float(usage.get("cache_read", 0) or 0)
+ * spec.get("cache_read", spec.get("input", 0.0))
+ / per_million
+ )
+ cost += (
+ float(usage.get("cache_write", 0) or 0)
+ * spec.get("cache_write", spec.get("input", 0.0))
+ / per_million
+ )
+ return round(cost, 6)
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.py
new file mode 100644
index 00000000..f9b27228
--- /dev/null
+++ b/coworker/headless/runner.py
@@ -0,0 +1,1081 @@
+"""`openworker run`: run ONE task with no human present, and record it.
+
+ openworker run --prompt "..." --workspace /path/to/project --model anthropic/claude-sonnet-5 \
+ --mode bypass-approvals --out ./run-record --trajectory-atif ./run-record/trajectory.json
+
+The model id is accepted in OpenWorker's `provider:model` form or the `provider/model`
+form other tools use. Nothing waits for a person: attendance is `auto`
+(coworker/unattended.py), so the engine answers questions with the least-destructive
+default, declines folder requests with guidance, installs pinned catalog tools itself,
+and refuses any approval card only a person could clear unless the mode grants it.
+
+Writes into --out:
+ 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 whenever a trajectory was written (completed, iteration cap,
+timeout, model error); 1 only when the run crashed before producing one.
+
+OpenWorker's state and scratch folders are pointed under --out before the engine is
+built, so a run never touches the machine's real conversations, keys or settings.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+import time
+import traceback
+import uuid
+from pathlib import Path
+from typing import Any, Optional
+
+MODES = [
+ "bypass-approvals",
+ "dangerously-bypass-approvals",
+ "auto-approve",
+ "interactive",
+ "custom",
+ "auto", # legacy spelling of bypass-approvals
+]
+ATTENDANCE = ["auto"] # `inbox` needs the server's Inbox; `attended` needs a screen
+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 with no human present, and record it.",
+ )
+ src = p.add_mutually_exclusive_group(required=True)
+ src.add_argument("--prompt", "--prompt-text", dest="prompt_text", help="the task text")
+ src.add_argument("--prompt-file", help="file containing the task text (UTF-8)")
+ p.add_argument("--workspace", required=True, help="folder the agent works in")
+ p.add_argument(
+ "--model", required=True, help="provider:model (OpenWorker) or provider/model"
+ )
+ p.add_argument("--persona", default="cowork", help="OpenWorker persona id (default: cowork)")
+ p.add_argument("--mode", default="bypass-approvals", choices=MODES)
+ p.add_argument(
+ "--attendance",
+ default="auto",
+ choices=ATTENDANCE,
+ help="who answers when the agent asks; `auto` = the engine, by fixed rule (default)",
+ )
+ p.add_argument(
+ "--max-iterations", type=int, default=None, help="default: OpenWorker config (150)"
+ )
+ 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", required=True, help="folder for the run record")
+ 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("--scripted", default=None, help=argparse.SUPPRESS) # tests: a fake model
+ return p.parse_args(argv)
+
+
+# -- 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 ~17 minutes in total. Permanent errors
+# (bad key, unknown model, context overflow) are not retried.
+PROVIDER_RETRY_DELAYS: tuple[int, ...] = (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.
+ exc_cls = type(str(t.get("error_type") or "APIError"), (Exception,), {})
+ 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 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
+
+ def _record(self, exc: BaseException, method: str) -> None:
+ 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 ------------------------------------------------------------------------------
+
+
+def _read_prompt(args: argparse.Namespace) -> str:
+ if args.prompt_text is not None:
+ return args.prompt_text
+ return Path(args.prompt_file).read_text(encoding="utf-8")
+
+
+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 run(args: argparse.Namespace) -> int:
+ out = Path(args.out).resolve()
+ out.mkdir(parents=True, exist_ok=True)
+ isolation = isolate_environment(out)
+ cleaned_keys = sanitize_key_env()
+ if cleaned_keys:
+ print(f"openworker run: stripped stray whitespace from {', '.join(cleaned_keys)}")
+
+ # 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 ..secrets import SecretStore, state_dir
+ from ..unattended import DANGEROUS_MODE_WARNING
+
+ workspace = Path(args.workspace).resolve()
+ workspace.mkdir(parents=True, exist_ok=True)
+ model = normalize_model(args.model)
+ mode = Mode(args.mode)
+ run_id = uuid.uuid4().hex[:12]
+ prompt = _read_prompt(args)
+ answers = Answers()
+
+ secrets = SecretStore(state_dir() / "secrets.json")
+ 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.persona),
+ workspace=workspace,
+ model=model,
+ mode=mode,
+ provider=provider,
+ audit_sink=audit_sink,
+ max_iterations=args.max_iterations,
+ # An explicit ceiling rides model_settings into every provider call.
+ model_settings=_model_settings(args),
+ # 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,
+ )
+ # Nobody is present: the engine answers by rule (coworker/unattended.py).
+ engine.attendance = lambda: args.attendance
+ 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
+ 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 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
+
+ def _on_term(signum, frame): # noqa: ARG001
+ try:
+ engine.request_interrupt()
+ finally:
+ flush_provisional("killed")
+
+ 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:
+ 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.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"),
+ },
+ }
+ events.append(rec)
+ events_fh.write(json.dumps(rec, default=str) + "\n")
+ events_fh.flush()
+ print(
+ f"openworker run: provider error ({last_data.get('error_type')}: "
+ f"{str(last_data.get('error'))[:120]}); retry {retries}/{len(delays)} "
+ f"in {delay}s",
+ file=sys.stderr,
+ flush=True,
+ )
+ flush_provisional("in_progress")
+ await asyncio.sleep(delay)
+ 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")
+ await asyncio.sleep(delay)
+ message = EMPTY_REPLY_NUDGE
+ continue
+ break
+
+ async def guarded() -> None:
+ # 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()
+
+ try:
+ asyncio.run(guarded())
+ except asyncio.TimeoutError:
+ outcome = "timeout"
+ 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
+ wall = time.time() - started
+ try:
+ events_fh.close()
+ except Exception: # noqa: BLE001
+ pass
+
+ # 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", ""))
+ 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"]
+ 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}"
+ )
+ return 1 if outcome == "crash" else 0
+
+
+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,
+ "persona": args.persona,
+ "mode": args.mode,
+ "attendance": args.attendance,
+ "max_iterations": args.max_iterations,
+ "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()),
+ "scripted": bool(args.scripted),
+ },
+ "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={
+ "persona": args.persona,
+ "mode": args.mode,
+ "attendance": args.attendance,
+ "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()
diff --git a/coworker/headless/trajectory.py b/coworker/headless/trajectory.py
new file mode 100644
index 00000000..cc8a6876
--- /dev/null
+++ b/coworker/headless/trajectory.py
@@ -0,0 +1,217 @@
+"""Build an ATIF (Agent Trajectory Interchange Format) trajectory from an OpenWorker
+conversation, so a headless run's record can be read by tools that consume that format.
+
+Written against ATIF-v1.7:
+
+- steps are numbered from 1, sequentially;
+- `source` is "user", "agent", or "system"; model_name / tool_calls / metrics only on
+ agent steps;
+- an observation result's `source_call_id` must name a tool call in the SAME step;
+- an agent step with llm_call_count == 0 may not carry metrics.
+
+OpenWorker persists one message per model round-trip (role "assistant", with
+`tool_calls` in OpenAI form and a `usage` sidecar) followed by one "tool" message per
+tool call, so the mapping is: assistant message -> agent step, following tool messages ->
+that step's observation.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from .pricing import estimate_cost
+
+SCHEMA_VERSION = "ATIF-v1.7"
+
+
+def _iso(ts: Any) -> Optional[str]:
+ try:
+ return datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
+ except (TypeError, ValueError, OverflowError, OSError):
+ return None
+
+
+def _text(content: Any) -> str:
+ if content is None:
+ return ""
+ if isinstance(content, str):
+ return content
+ try:
+ from ..attachments import content_to_text
+
+ return content_to_text(content)
+ except Exception: # noqa: BLE001 - never fail the trajectory over a content part
+ return json.dumps(content, default=str)
+
+
+def _parse_args(raw: Any) -> dict[str, Any]:
+ if isinstance(raw, dict):
+ return raw
+ try:
+ parsed = json.loads(raw or "{}")
+ except (TypeError, ValueError):
+ return {"_raw": str(raw)}
+ return parsed if isinstance(parsed, dict) else {"_value": parsed}
+
+
+def build_trajectory(
+ messages: list[dict[str, Any]],
+ *,
+ agent_name: str,
+ agent_version: str,
+ model_name: str,
+ session_id: str,
+ outcome: str,
+ prices: Optional[dict] = None,
+ agent_extra: Optional[dict[str, Any]] = None,
+ reasoning_effort: Optional[str] = None,
+) -> dict[str, Any]:
+ steps: list[dict[str, Any]] = []
+ pending: Optional[dict[str, Any]] = None # the last agent step, for observations
+ totals = {"prompt": 0, "completion": 0, "cached": 0}
+ cost_total = 0.0
+ cost_known = False
+
+ for msg in messages:
+ role = msg.get("role")
+ ts = _iso(msg.get("ts"))
+
+ if role == "user":
+ pending = None
+ steps.append({"source": "user", "message": _text(msg.get("content")), "timestamp": ts})
+ continue
+
+ if role == "assistant":
+ step: dict[str, Any] = {
+ "source": "agent",
+ "message": _text(msg.get("content")),
+ "timestamp": ts,
+ "llm_call_count": 1,
+ }
+ usage = msg.get("usage") or {}
+ step["model_name"] = str(usage.get("model") or model_name)
+ if reasoning_effort:
+ step["reasoning_effort"] = reasoning_effort # ATIF: agent steps only
+ if msg.get("reasoning"):
+ step["reasoning_content"] = str(msg["reasoning"])
+ calls = msg.get("tool_calls") or []
+ if calls:
+ step["tool_calls"] = [
+ {
+ "tool_call_id": str(tc.get("id")),
+ "function_name": str((tc.get("function") or {}).get("name", "")),
+ "arguments": _parse_args((tc.get("function") or {}).get("arguments")),
+ }
+ for tc in calls
+ ]
+ if usage:
+ prompt = (
+ int(usage.get("input", 0) or 0)
+ + int(usage.get("cache_read", 0) or 0)
+ + int(usage.get("cache_write", 0) or 0)
+ )
+ completion = int(usage.get("output", 0) or 0)
+ cached = int(usage.get("cache_read", 0) or 0)
+ metrics: dict[str, Any] = {
+ "prompt_tokens": prompt,
+ "completion_tokens": completion,
+ "cached_tokens": cached,
+ }
+ # The four raw counts and the serving host travel too, so a consumer can
+ # price the call itself (cache reads and writes are billed differently,
+ # and a router's upstream host decides which rate applies).
+ extra = {
+ k: int(usage.get(k, 0) or 0)
+ for k in ("input", "output", "cache_read", "cache_write")
+ }
+ if msg.get("served_by"):
+ extra["served_by"] = str(msg["served_by"])
+ metrics["extra"] = extra
+ cost = estimate_cost(step["model_name"], usage, prices)
+ if cost is not None:
+ metrics["cost_usd"] = cost
+ cost_total += cost
+ cost_known = True
+ step["metrics"] = metrics
+ totals["prompt"] += prompt
+ totals["completion"] += completion
+ totals["cached"] += cached
+ steps.append(step)
+ pending = step
+ continue
+
+ if role == "tool":
+ result = {"content": _text(msg.get("content"))}
+ call_id = msg.get("tool_call_id")
+ if pending is not None and any(
+ tc["tool_call_id"] == call_id for tc in pending.get("tool_calls") or []
+ ):
+ result["source_call_id"] = str(call_id)
+ pending.setdefault("observation", {"results": []})["results"].append(result)
+ else:
+ # Orphan tool output (should not happen); keep it as a system step.
+ steps.append({"source": "system", "message": result["content"], "timestamp": ts})
+ continue
+
+ # Notices, system prompts, and anything else become system steps. Engine notices
+ # carry their wording in `text` (not `content`); a compacted notice also carries
+ # the compaction record, so the trajectory shows what the model's memory was
+ # replaced with, not just that it was.
+ text = (
+ _text(msg.get("content"))
+ or str(msg.get("text") or "")
+ or str(msg.get("kind") or role or "")
+ )
+ compaction = msg.get("compaction") if role == "notice" else None
+ if isinstance(compaction, dict):
+ summary = str(compaction.get("summary_text") or "")
+ working = str(compaction.get("working_state") or "")
+ parts = [text]
+ if compaction.get("trimmed"):
+ # The trim path stores a placeholder sentence as its summary; say what
+ # happened instead of quoting it as if it were a summary.
+ parts.append("[compaction: oldest turns trimmed; no summary was produced]")
+ elif summary:
+ parts.append("[compaction summary]\n" + summary)
+ if working:
+ parts.append("[working state]\n" + working)
+ text = "\n\n".join(x for x in parts if x)
+ if text:
+ steps.append({"source": "system", "message": text, "timestamp": ts})
+
+ for i, step in enumerate(steps, start=1):
+ step["step_id"] = i
+ if step.get("timestamp") is None:
+ step.pop("timestamp", None)
+
+ final_metrics: dict[str, Any] = {
+ "total_prompt_tokens": totals["prompt"],
+ "total_completion_tokens": totals["completion"],
+ "total_cached_tokens": totals["cached"],
+ "total_steps": len(steps),
+ "extra": {"outcome": outcome},
+ }
+ if cost_known:
+ final_metrics["total_cost_usd"] = round(cost_total, 6)
+
+ return {
+ "schema_version": SCHEMA_VERSION,
+ "session_id": session_id,
+ "agent": {
+ "name": agent_name,
+ "version": agent_version,
+ "model_name": model_name,
+ **({"extra": agent_extra} if agent_extra else {}),
+ },
+ "steps": steps,
+ "final_metrics": final_metrics,
+ }
+
+
+def write_trajectory(path: str | Path, trajectory: dict[str, Any]) -> None:
+ p = Path(path)
+ p.parent.mkdir(parents=True, exist_ok=True)
+ p.write_text(json.dumps(trajectory, indent=1, default=str), encoding="utf-8")
diff --git a/docs/headless.md b/docs/headless.md
new file mode 100644
index 00000000..f0c02b19
--- /dev/null
+++ b/docs/headless.md
@@ -0,0 +1,108 @@
+# Running OpenWorker with nobody at the keyboard
+
+OpenWorker has two headless modes. They answer different questions.
+
+| Command | What it does | Who drives it |
+|---|---|---|
+| `openworker up` (after `openworker join`) | Keeps this computer serving as a machine the desktop app controls, forever | The desktop app: tasks and chat arrive over its channel |
+| `openworker run` | Runs one task to the end and exits, leaving a record behind | A script, a CI job, an evaluation harness |
+
+This page is about `openworker run` and the two switches that decide what happens when
+the agent would normally stop and ask.
+
+## Two switches: approving and answering
+
+**Approving** is a yes/no on a tool call the agent has already decided to make. It is
+answered by a person, by the reviewer model, or by the permission *mode*.
+
+**Answering** is the agent asking for something it does not have: a question, a folder,
+a tool install. The answer is content, not permission. It is answered by a person, parked
+in the Inbox, or supplied by the engine. That is the *attendance* setting.
+
+### Mode (approving)
+
+| Mode | Routine tool calls | The safety checks (run a downloaded file, write outside the workspace, edit git hooks / CI / settings files, grant authority that outlives the session) |
+|---|---|---|
+| `interactive` | asks | asks |
+| `auto-approve` | the reviewer decides; anything it is unsure about asks | asks |
+| `bypass-approvals` | runs | asks |
+| `dangerously-bypass-approvals` | runs | runs, each one recorded as "cleared by mode" |
+
+`bypass-approvals` is for someone who wants no reviewer and few prompts but keeps the
+basic checks. `dangerously-bypass-approvals` grants every approval and switches the
+checks off. Use it only on a disposable machine or container. It is never offered in the
+desktop app; the server accepts it only when started with `--allow-dangerous-mode`, and
+`openworker run` prints a warning line when it is on.
+
+### Attendance (answering)
+
+| Attendance | Questions, folder requests, pinned tool installs | An approval card only a person could clear |
+|---|---|---|
+| `attended` | appear on screen | appears on screen |
+| `inbox` | parked in the Inbox until someone returns | parked in the Inbox |
+| `auto` | answered by the engine, by fixed rule, and recorded | refused, unless the mode clears it |
+
+In `auto`:
+
+- a question gets: *"No one is available. Choose the least destructive option that still
+ satisfies the task as written."*
+- a folder request is declined with guidance: work inside the workspace (or, in the
+ dangerous mode, use the shell for paths outside it), and stop and say what is missing if
+ the task cannot continue without the user;
+- a pinned catalog tool (any tool in `coworker/toolchain.py`'s catalog) is installed by the
+ verified installer, same version and checksum as the desktop card would use;
+- an approval card that would have needed a person is refused, never parked. Nothing hangs.
+
+`openworker run` always uses `auto`. The desktop app offers it as the third position of the
+Unattended toggle ("Answer for me while I'm away"); there it can only combine with modes
+that keep the checks, so the worst case is a refused card.
+
+## `openworker run`
+
+```
+openworker run --prompt "Fix the failing test in tests/test_parser.py" \
+ --workspace ~/src/project --model anthropic/claude-sonnet-5 \
+ --mode bypass-approvals --out ./run-record
+```
+
+Options:
+
+| Flag | Meaning |
+|---|---|
+| `--prompt TEXT` / `--prompt-file PATH` | the task |
+| `--workspace DIR` | the folder the agent works in |
+| `--model ID` | `provider:model` or `provider/model` (first slash splits) |
+| `--mode` | see above; default `bypass-approvals` |
+| `--attendance` | `auto` (the only value here) |
+| `--persona` | `cowork` (default) or `code` |
+| `--reasoning-effort` | `low` … `max`, sent to the provider; unset = provider default, recorded |
+| `--max-output-tokens`, `--max-iterations`, `--timeout-seconds` | ceilings; `--timeout-seconds 0` when an outer runner enforces its own |
+| `--tool-result-max-bytes` | bound each tool result (default 10,000; 0 = off); full text spilled under `out/tool-output/` |
+| `--provider-order` | OpenRouter only: pin the upstream host, no fallback |
+| `--out DIR`, `--trajectory-atif PATH` | where the record goes |
+
+The model key comes from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`TOGETHER_API_KEY`, `OPENROUTER_API_KEY`, …). OpenWorker's state and scratch folders are
+pointed under `--out` before the engine starts, so a run never touches the machine's own
+conversations, keys or settings.
+
+### The record
+
+| File | Contents |
+|---|---|
+| `trajectory.json` | the run in ATIF-v1.7, with per-call token counts, the serving host, and an estimated cost from `coworker/headless/prices.yaml` (a cross-check; a consumer should price the counts itself) |
+| `summary.json` | outcome, iterations, tool calls, tokens, cost, the arguments, the context window and compaction trigger used, the hosts that served the run |
+| `answers.json` | every answer the engine gave on the absent user's behalf: refused cards, cleared checks, answered questions, declined folder requests, installs |
+| `events.jsonl` | every engine event, in order, written as it happens |
+| `messages.json` | the final conversation in OpenWorker's own shape |
+| `model_calls.jsonl` | one line per model call: stop reason, usage, ceiling, effort, host |
+| `provider_errors.log` | full cause chains of failed model calls, credentials redacted |
+| `audit.db` | OpenWorker's audit log for the session |
+
+The trajectory and the exit code are the stable contract. Exit code 0 means a trajectory
+was written (completed, iteration cap, timeout, model error); 1 means the run crashed
+before producing one.
+
+A transient provider failure or an empty reply does not end the run: the runner waits
+(30 s, 60 s, 120 s, 240 s, 300 s, 300 s) and re-enters the conversation with a nudge.
+Permanent errors (bad key, unknown model, context overflow) are not retried.
diff --git a/pyproject.toml b/pyproject.toml
index 87c77c21..c43def9d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -75,6 +75,7 @@ coworker = [
"personas/builtin/*.md",
"personas/builtin/*/manifest.md",
"personas/builtin/*/skills/*/SKILL.md",
+ "headless/*.yaml",
]
[tool.pytest.ini_options]
diff --git a/tests/test_cli_surface.py b/tests/test_cli_surface.py
index c37e006d..9fed230f 100644
--- a/tests/test_cli_surface.py
+++ b/tests/test_cli_surface.py
@@ -12,7 +12,7 @@ def test_no_arguments_prints_help_that_lists_every_public_command(capsys):
ow_cli.main([])
out = capsys.readouterr().out
assert "usage: openworker <command>" in out
- for verb in ("join <link>", "up", "machine", "status", "keys", "logs", "service", "leave", "version"):
+ for verb in ("join <link>", "up", "run <task>", "machine", "status", "keys", "logs", "service", "leave", "version"):
assert verb in out
# Unlisted until tested as a product surface.
for hidden in ("tui", "sessions", "inbox", "doctor"):
diff --git a/tests/test_headless_run.py b/tests/test_headless_run.py
new file mode 100644
index 00000000..afa0b7e6
--- /dev/null
+++ b/tests/test_headless_run.py
@@ -0,0 +1,320 @@
+"""`openworker run` end to end with a scripted fake model: no network, no keys.
+
+Each test runs the command in a subprocess because the runner points OpenWorker's state
+and scratch folders under --out BEFORE the engine is built, which cannot be undone inside
+one process.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+SCRIPT = [
+ {"text": "I will create the file.", "tool_calls": [{"name": "write_file", "arguments": {"path": "hello.txt", "content": "hello"}}]},
+ {"text": "Now reading it back.", "tool_calls": [{"name": "read_file", "arguments": {"path": "hello.txt"}}]},
+ {"text": "The file says: hello. Done.", "usage": {"input": 300, "output": 40, "cache_read": 100}},
+]
+
+TASK = "Create hello.txt containing the word hello, then read it back."
+
+
+def _env(extra: dict | None = None) -> dict:
+ env = dict(os.environ)
+ env["PYTHONPATH"] = str(ROOT) + os.pathsep + env.get("PYTHONPATH", "")
+ env.pop("ANTHROPIC_API_KEY", None)
+ env.pop("OPENAI_API_KEY", None)
+ env.pop("COWORKER_STATE_DIR", None)
+ env.pop("COWORKER_SCRATCH_BASE", None)
+ env.update(extra or {})
+ return env
+
+
+def _run(
+ tmp_path: Path,
+ mode: str,
+ script: list[dict] | None = None,
+ *,
+ model: str = "anthropic/claude-sonnet-5",
+ prompt: str = TASK,
+ extra: list[str] | None = None,
+ env: dict | None = None,
+) -> tuple[subprocess.CompletedProcess, Path, Path]:
+ ws = tmp_path / "ws"
+ ws.mkdir(exist_ok=True)
+ out = tmp_path / "out"
+ path = tmp_path / "script.json"
+ path.write_text(json.dumps(script if script is not None else SCRIPT), encoding="utf-8")
+ cmd = [
+ sys.executable, "-m", "coworker.cli", "run",
+ "--prompt", prompt,
+ "--workspace", str(ws), "--model", model,
+ "--mode", mode, "--out", str(out),
+ "--trajectory-atif", str(tmp_path / "logs" / "trajectory.json"),
+ "--scripted", str(path), "--timeout-seconds", "120",
+ *(extra or []),
+ ]
+ proc = subprocess.run(cmd, env=_env(env), capture_output=True, text=True, timeout=300)
+ return proc, ws, out
+
+
+def _summary(out: Path) -> dict:
+ return json.loads((out / "summary.json").read_text(encoding="utf-8"))
+
+
+def _messages(out: Path) -> list[dict]:
+ return json.loads((out / "messages.json").read_text(encoding="utf-8"))
+
+
+def _events(out: Path) -> list[dict]:
+ return [
+ json.loads(line)
+ for line in (out / "events.jsonl").read_text(encoding="utf-8").splitlines()
+ if line.strip()
+ ]
+
+
+def _calls(out: Path) -> list[dict]:
+ return [
+ json.loads(line)
+ for line in (out / "model_calls.jsonl").read_text(encoding="utf-8").splitlines()
+ if line.strip()
+ ]
+
+
+# -- the record ----------------------------------------------------------------------------
+
+
+def test_bypass_writes_the_file_and_leaves_a_full_record(tmp_path: Path) -> None:
+ proc, ws, out = _run(tmp_path, "bypass-approvals")
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert (ws / "hello.txt").read_text(encoding="utf-8") == "hello"
+
+ summary = _summary(out)
+ assert summary["outcome"] == "completed"
+ assert summary["args"]["model"] == "anthropic:claude-sonnet-5" # provider/model converted
+ assert summary["args"]["attendance"] == "auto"
+ assert summary["tool_calls"] == 2 and summary["tool_calls_denied"] == 0
+ assert summary["answers"] == {
+ "cards_refused": 0,
+ "floors_cleared": 0,
+ "questions_answered": 0,
+ "directory_requests_declined": 0,
+ "tool_installs": 0,
+ }
+ assert summary["tokens"]["input"] > 0 and summary["tokens"]["output"] > 0
+ assert summary["cost_usd"] is not None and summary["cost_usd"] > 0 # Sonnet 5 is priced
+ for name in ("events.jsonl", "messages.json", "answers.json", "audit.db", "trajectory.json", "model_calls.jsonl"):
+ assert (out / name).exists(), name
+ # The run never touched the machine's own state: both folders live under --out.
+ assert Path(summary["isolation"]["COWORKER_STATE_DIR"]).is_relative_to(out)
+
+ traj = json.loads((tmp_path / "logs" / "trajectory.json").read_text(encoding="utf-8"))
+ assert traj["schema_version"] == "ATIF-v1.7"
+ assert traj["agent"]["name"] == "openworker" and traj["agent"]["version"].startswith("openworker")
+ assert traj["agent"]["extra"]["attendance"] == "auto"
+ assert [s["step_id"] for s in traj["steps"]] == list(range(1, len(traj["steps"]) + 1))
+ agent_steps = [s for s in traj["steps"] if s["source"] == "agent"]
+ assert agent_steps[0]["tool_calls"][0]["function_name"] == "write_file"
+ obs = agent_steps[0]["observation"]["results"]
+ assert obs[0]["source_call_id"] == agent_steps[0]["tool_calls"][0]["tool_call_id"]
+ assert traj["final_metrics"]["total_completion_tokens"] > 0
+ assert traj["final_metrics"]["total_cost_usd"] > 0
+ for s in traj["steps"]:
+ if s["source"] != "agent":
+ assert "tool_calls" not in s and "metrics" not in s and "model_name" not in s
+
+
+def test_interactive_refuses_the_card_nobody_can_answer_and_records_it(tmp_path: Path) -> None:
+ # Also an unpriced model (cost must be null, never guessed) in the two-slash form,
+ # which must split on the first slash only.
+ proc, ws, out = _run(tmp_path, "interactive", model="together/deepseek-ai/DeepSeek-V4-Pro")
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert not (ws / "hello.txt").exists()
+ summary = _summary(out)
+ assert summary["args"]["model"] == "together:deepseek-ai/DeepSeek-V4-Pro"
+ assert summary["tool_calls_denied"] >= 1
+ assert summary["answers"]["cards_refused"] >= 1
+ assert summary["cost_usd"] is None
+ answers = json.loads((out / "answers.json").read_text(encoding="utf-8"))
+ assert answers["rows"][0]["tool"] == "write_file" and answers["rows"][0]["stage"] == "approval_resolved"
+ traj = json.loads((out / "trajectory.json").read_text(encoding="utf-8"))
+ assert "total_cost_usd" not in traj["final_metrics"]
+
+
+def test_dangerous_mode_warns_and_clears_the_downloaded_file_floor(tmp_path: Path) -> None:
+ script = [
+ {"text": "fetching", "tool_calls": [{"name": "run_shell", "arguments": {"command": "echo 'echo hi' > setup.sh"}}]},
+ {"text": "running", "tool_calls": [{"name": "run_shell", "arguments": {"command": "sh setup.sh"}}]},
+ {"text": "Done."},
+ ]
+ proc, _ws, out = _run(tmp_path, "dangerously-bypass-approvals", script)
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert "Dangerously bypass approvals is on" in proc.stderr
+ messages = _messages(out)
+ assert any(m.get("role") == "notice" and m.get("kind") == "dangerous_mode" for m in messages)
+ assert _summary(out)["args"]["mode"] == "dangerously-bypass-approvals"
+
+
+def test_a_question_is_answered_by_the_engine_and_counted(tmp_path: Path) -> None:
+ script = [
+ {"text": "asking", "tool_calls": [{"name": "ask_user", "arguments": {"question": "Rewrite history?"}}]},
+ {"text": "ok", "tool_calls": [{"name": "write_file", "arguments": {"path": "hello.txt", "content": "hello"}}]},
+ {"text": "Done."},
+ ]
+ proc, ws, out = _run(tmp_path, "bypass-approvals", script)
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert (ws / "hello.txt").exists()
+ summary = _summary(out)
+ assert summary["answers"]["questions_answered"] == 1
+ tool_msgs = [m for m in _messages(out) if m["role"] == "tool"]
+ assert "least destructive" in tool_msgs[0]["content"]
+
+
+def test_finish_reason_is_persisted_on_messages_events_and_the_call_log(tmp_path: Path) -> None:
+ proc, _ws, out = _run(tmp_path, "bypass-approvals")
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assistant = [m for m in _messages(out) if m.get("role") == "assistant"]
+ assert [m.get("finish_reason") for m in assistant] == ["tool_calls", "tool_calls", "stop"]
+ replies = [e for e in _events(out) if e.get("type") == "assistant_message"]
+ assert [e["data"].get("finish_reason") for e in replies] == ["tool_calls", "tool_calls", "stop"]
+ assert [c["finish_reason"] for c in _calls(out)] == [m["finish_reason"] for m in assistant]
+
+
+def test_a_cut_off_reply_is_continued_and_repeated_cut_offs_end_as_truncated(tmp_path: Path) -> None:
+ cut = {"text": None, "finish_reason": "length"}
+ write = {"text": "ok", "tool_calls": [{"name": "write_file", "arguments": {"path": "hello.txt", "content": "hello"}}]}
+ proc, ws, out = _run(tmp_path, "bypass-approvals", [cut, write, {"text": "Done."}], prompt="Do something hard.")
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ summary = _summary(out)
+ assert summary["outcome"] == "completed" and summary["continuations"] == 1
+ assert (ws / "hello.txt").read_text(encoding="utf-8") == "hello"
+
+ second = tmp_path / "again"
+ second.mkdir()
+ proc, _ws, out = _run(second, "bypass-approvals", [cut, cut, cut], prompt="Do something hard.")
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ summary = _summary(out)
+ assert summary["outcome"] == "truncated" and summary["continuations"] == 2
+ assert _messages(out)[-1]["kind"] == "truncated"
+
+
+def test_max_output_tokens_and_reasoning_effort_reach_every_call_and_the_record(tmp_path: Path) -> None:
+ proc, _ws, out = _run(
+ tmp_path, "bypass-approvals", extra=["--max-output-tokens", "64000", "--reasoning-effort", "xhigh"]
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ summary = _summary(out)
+ assert summary["args"]["max_output_tokens"] == 64000
+ assert summary["reasoning_effort"] == "xhigh"
+ assert summary["reasoning_effort_detail"]["replies_recorded"] == 3
+ calls = _calls(out)
+ assert [c["max_output_tokens"] for c in calls] == [64000, 64000, 64000]
+ assert [c["effort"]["effective"] for c in calls] == ["xhigh", "xhigh", "xhigh"]
+
+
+def test_without_the_flags_the_provider_defaults_are_described(tmp_path: Path) -> None:
+ proc, _ws, out = _run(tmp_path, "bypass-approvals") # claude-sonnet-5
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ summary = _summary(out)
+ assert summary["args"]["max_output_tokens"] is None
+ assert summary["reasoning_effort"].startswith("high (Anthropic adaptive thinking")
+ assert summary["context"] == {
+ "window": 1_000_000,
+ "window_source": "matrix",
+ "compaction_trigger_tokens": 250_000,
+ }
+
+
+# -- transient provider errors ------------------------------------------------------------
+
+
+def test_transient_provider_error_is_waited_out_and_the_run_completes(tmp_path: Path) -> None:
+ fail = {"error": "Service unavailable", "error_type": "APIError"}
+ write = {"text": "ok", "tool_calls": [{"name": "write_file", "arguments": {"path": "hello.txt", "content": "hello"}}]}
+ proc, ws, out = _run(
+ tmp_path, "bypass-approvals", [fail, write, {"text": "Done."}],
+ prompt="Do something hard.", env={"OPENWORKER_RUN_RETRY_DELAYS": "0,0"},
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ summary = _summary(out)
+ assert summary["outcome"] == "completed" and summary["provider_retries"] == 1
+ assert (ws / "hello.txt").read_text(encoding="utf-8") == "hello"
+ kinds = [e["type"] for e in _events(out)]
+ assert kinds.index("error") < kinds.index("provider_retry") < kinds.index("turn_end")
+ users = [m["content"] for m in _messages(out) if m["role"] == "user"]
+ assert users[0] == "Do something hard." and "temporary provider error" in users[1]
+
+
+def test_empty_reply_is_nudged_and_a_permanent_error_is_not_retried(tmp_path: Path) -> None:
+ empty = {"text": None}
+ write = {"text": "ok", "tool_calls": [{"name": "write_file", "arguments": {"path": "hello.txt", "content": "hello"}}]}
+ proc, ws, out = _run(
+ tmp_path, "bypass-approvals", [empty, write, {"text": "Done."}],
+ prompt="Do something hard.", env={"OPENWORKER_RUN_RETRY_DELAYS": "0,0"},
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert _summary(out)["provider_retries"] == 1 and (ws / "hello.txt").exists()
+ retry = next(e for e in _events(out) if e["type"] == "provider_retry")
+ assert retry["data"]["error_type"] == "EmptyReply"
+
+ second = tmp_path / "permanent"
+ second.mkdir()
+ fail = {"error": "Invalid API key provided", "error_type": "AuthenticationError"}
+ proc, _ws, out = _run(
+ second, "bypass-approvals", [fail, {"text": "never reached"}],
+ prompt="Do something hard.", env={"OPENWORKER_RUN_RETRY_DELAYS": "0,0"},
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr # a model error is a recorded outcome
+ summary = _summary(out)
+ assert summary["outcome"] == "model_error" and summary["provider_retries"] == 0
+
+
+# -- persona and tool results -------------------------------------------------------------
+
+
+def test_code_persona_runs_headless_and_is_recorded(tmp_path: Path) -> None:
+ proc, ws, out = _run(tmp_path, "bypass-approvals", extra=["--persona", "code"])
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ summary = _summary(out)
+ assert summary["outcome"] == "completed" and summary["args"]["persona"] == "code"
+ assert (ws / "hello.txt").read_text(encoding="utf-8") == "hello"
+ system = next(m for m in _messages(out) if m["role"] == "system")["content"]
+ assert "coding agent" in system
+
+
+def test_large_tool_result_is_bounded_and_spilled(tmp_path: Path) -> None:
+ ws = tmp_path / "ws"
+ ws.mkdir()
+ big = "\n".join(f"{i:04d} " + "x" * 55 for i in range(1500)) # ~90 KB, inside read_file's window
+ (ws / "big.txt").write_text(big, encoding="utf-8")
+ script = [
+ {"text": "reading", "tool_calls": [{"name": "read_file", "arguments": {"path": "big.txt", "max_lines": 5000}}]},
+ {"text": "Done."},
+ ]
+ proc, _ws, out = _run(tmp_path, "bypass-approvals", script, prompt="Read big.txt.")
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ tool = [m for m in _messages(out) if m["role"] == "tool"]
+ content = tool[0]["content"]
+ assert len(content.encode("utf-8")) <= 10_000 and "bytes omitted here" in content
+ spilled = list((out / "tool-output").iterdir())
+ assert len(spilled) == 1 and "1499 xxxxx" in spilled[0].read_text(encoding="utf-8")
+ assert _summary(out)["tool_results_bounded"] == 1
+
+
+def test_run_help_and_the_top_level_help_mention_the_command() -> None:
+ proc = subprocess.run(
+ [sys.executable, "-m", "coworker.cli", "run", "--help"],
+ env=_env(), capture_output=True, text=True, timeout=120,
+ )
+ assert proc.returncode == 0 and "usage: openworker run" in proc.stdout
+ assert "--attendance" in proc.stdout and "--scripted" not in proc.stdout # test-only flag stays hidden
+ top = subprocess.run(
+ [sys.executable, "-m", "coworker.cli"], env=_env(), capture_output=True, text=True, timeout=120
+ )
+ assert "run <task>" in top.stdout
diff --git a/tests/test_headless_trajectory.py b/tests/test_headless_trajectory.py
new file mode 100644
index 00000000..e4e5d9bd
--- /dev/null
+++ b/tests/test_headless_trajectory.py
@@ -0,0 +1,103 @@
+"""The trajectory writer renders engine notices by their text, a compacted notice's
+summary lands in the trajectory, and every agent step carries the raw token counts so a
+consumer can price the call itself. Direct unit tests, no subprocess."""
+
+from __future__ import annotations
+
+from coworker.headless.trajectory import build_trajectory
+
+
+def _traj(messages, model="anthropic:claude-sonnet-5"):
+ return build_trajectory(
+ messages,
+ agent_name="openworker",
+ agent_version="test",
+ model_name=model,
+ session_id="s",
+ outcome="completed",
+ )
+
+
+def test_compacted_notice_step_includes_the_summary():
+ messages = [
+ {"role": "user", "content": "do the thing", "ts": 1.0},
+ {"role": "assistant", "content": "working", "finish_reason": "tool_calls", "ts": 2.0},
+ {
+ "role": "notice",
+ "kind": "compacted",
+ "text": "Context compacted — earlier turns were summarized",
+ "compaction": {
+ "boundary_index": 7,
+ "summary_text": "## Summary\nWrote interp.py; tests 1-40 pass.",
+ "working_state": "next: fix tail calls",
+ "user_messages": ["do the thing"],
+ "user_messages_dropped": 0,
+ "created_at": 3.0,
+ "model_used": "claude-sonnet-5",
+ "trimmed": False,
+ },
+ "ts": 3.0,
+ },
+ {"role": "assistant", "content": "done", "finish_reason": "stop", "ts": 4.0},
+ ]
+ steps = _traj(messages)["steps"]
+ system = [s for s in steps if s["source"] == "system"]
+ assert len(system) == 1
+ msg = system[0]["message"]
+ assert msg.startswith("Context compacted")
+ assert "[compaction summary]" in msg and "tests 1-40 pass" in msg
+ assert "[working state]" in msg and "fix tail calls" in msg
+ assert "trimmed" not in msg
+
+
+def test_trimmed_notice_and_plain_notices_render_their_text():
+ messages = [
+ {"role": "user", "content": "go", "ts": 1.0},
+ {"role": "notice", "kind": "compacted", "text": "Context trimmed — oldest turns dropped",
+ "compaction": {"boundary_index": 3, "summary_text": "", "working_state": "", "trimmed": True}, "ts": 2.0},
+ {"role": "notice", "kind": "truncated", "text": "cut off 3 times", "ts": 3.0},
+ {"role": "notice", "kind": "interrupted", "ts": 4.0},
+ ]
+ system = [s["message"] for s in _traj(messages)["steps"] if s["source"] == "system"]
+ assert system[0].startswith("Context trimmed") and "no summary was produced" in system[0]
+ assert system[1] == "cut off 3 times"
+ assert system[2] == "interrupted" # kind is the fallback when a notice has no text
+
+
+def test_agent_steps_carry_raw_counts_host_and_a_priced_total():
+ messages = [
+ {"role": "user", "content": "go", "ts": 1.0},
+ {
+ "role": "assistant",
+ "content": "done",
+ "finish_reason": "stop",
+ "ts": 2.0,
+ "usage": {"input": 1000, "output": 100, "cache_read": 500, "cache_write": 200},
+ "served_by": "Together",
+ },
+ ]
+ traj = _traj(messages)
+ step = [s for s in traj["steps"] if s["source"] == "agent"][0]
+ assert step["metrics"]["prompt_tokens"] == 1700 and step["metrics"]["cached_tokens"] == 500
+ assert step["metrics"]["extra"] == {
+ "input": 1000,
+ "output": 100,
+ "cache_read": 500,
+ "cache_write": 200,
+ "served_by": "Together",
+ }
+ # Sonnet 5: 1000*2 + 100*10 + 500*0.2 + 200*2.5 per million.
+ assert step["metrics"]["cost_usd"] == round((2000 + 1000 + 100 + 500) / 1e6, 6)
+ assert traj["final_metrics"]["total_cost_usd"] == step["metrics"]["cost_usd"]
+
+
+def test_an_unpriced_model_gets_counts_but_no_cost():
+ messages = [
+ {"role": "user", "content": "go", "ts": 1.0},
+ {"role": "assistant", "content": "done", "finish_reason": "stop", "ts": 2.0,
+ "usage": {"input": 10, "output": 5}},
+ ]
+ traj = _traj(messages, model="together:some/unpriced-model")
+ step = [s for s in traj["steps"] if s["source"] == "agent"][0]
+ assert "cost_usd" not in step["metrics"] and step["metrics"]["prompt_tokens"] == 10
+ assert "total_cost_usd" not in traj["final_metrics"]