mirror of
https://github.com/andrewyng/openworker.git
synced 2026-11-20 20:37:44 +00:00
4370 lines
219 KiB
Python
4370 lines
219 KiB
Python
"""TurnEngine — the owned agent loop.
|
|
|
|
Async, but with blocking provider/tool calls wrapped in `asyncio.to_thread` so the loop
|
|
(and any UI consuming its events) stays responsive. One user turn spans many model↔tool
|
|
iterations until the model stops requesting tools, a rail trips, or it's interrupted.
|
|
When the model requests several tool calls in one turn, low-risk ones (reads, searches)
|
|
execute concurrently; writes/shell stay strictly ordered.
|
|
|
|
Approvals are handled out-of-band via an injected async `approver`: when the permission
|
|
engine says `needs_user`, the engine emits `PERMISSION_REQUIRED` and awaits the approver.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from copy import deepcopy
|
|
|
|
import asyncio
|
|
import inspect
|
|
import functools
|
|
import hashlib
|
|
import json
|
|
import time
|
|
from dataclasses import dataclass, replace
|
|
from enum import Enum
|
|
from pathlib import Path
|
|
from typing import Any, AsyncIterator, Awaitable, Callable, Optional
|
|
|
|
from . import compaction as _compaction
|
|
from . import plan_steps
|
|
from . import provenance
|
|
from . import review_facts
|
|
from . import session_facts
|
|
from . import toolchain as _toolchain
|
|
from . import toolresult
|
|
from . import unattended as _attendance
|
|
from .events import Event, EventType
|
|
from .observability.decision import DecisionPath
|
|
from .observability.engine_hooks import ToolRun, TurnRecording, set_tool_run
|
|
from .observability.recorder import short_hash as _short_hash
|
|
from .observability import stamps as _stamps
|
|
from .observability.canonical import short_hash as _args_hash, text_hash as _text_hash
|
|
from .observability.scopes import recorded_scanner as _recorded_scanner
|
|
from .observability.provider_view import tag as _tag_provider, view_for_engine
|
|
from .observability.ids import new_ulid
|
|
|
|
# §8.4 retry guard: the reviewer pauses for the rest of the turn after this many denials
|
|
# IN A ROW (2→5 + streak semantics, owner ruling 2026-08-24 — a cumulative 2 silently
|
|
# downgraded long agentic turns to hand-approval after one over-strict pair).
|
|
# OPE-171: a reply cut off at the output-token limit (finish_reason "length") that
|
|
# carries no tool call is not an answer — typically thinking consumed the whole budget
|
|
# and nothing else came back. The engine nudges the model to act instead of ending the
|
|
# turn as "completed", at most this many times in a row; then the turn ends as
|
|
# "truncated" so callers can tell "finished" from "gave up".
|
|
MAX_TRUNCATION_CONTINUATIONS = 2
|
|
TRUNCATION_NUDGE = (
|
|
"Your previous reply hit the output-token limit before you took an action or "
|
|
"finished. Do not repeat the long reasoning. Decide the next concrete step and "
|
|
"call a tool now, or give the final answer briefly."
|
|
)
|
|
# What the provider sees in place of the cut-off reply: its partial thinking block has
|
|
# no signature (Anthropic rejects it on replay) and its content is empty or a fragment;
|
|
# the transcript keeps the original, the outbound view sends this.
|
|
TRUNCATION_STUB = "(reply cut off at the output-token limit before any action)"
|
|
# OPE-192: the per-turn context block is ephemeral and volatile (it carries a clock). It is
|
|
# sent as its own trailing message opening with this tag, so a provider can keep its cache
|
|
# breakpoint on the last STABLE block and leave the note outside the cached prefix.
|
|
EPHEMERAL_CONTEXT_OPEN = "<system-context>"
|
|
|
|
_REVIEWER_TRIP = 5
|
|
_REVIEWER_PAUSED_TEXT = (
|
|
"Auto-approve is paused for the rest of this turn — the reviewer blocked "
|
|
f"{_REVIEWER_TRIP} actions in a row, so approvals now come to you."
|
|
)
|
|
from .permissions import CLEARED_BY_MODE, Mode, PermissionEngine
|
|
from .providers import AssistantTurn, ProviderClient, ToolCall
|
|
from .risk import RiskClass, classify as _classify_risk
|
|
from .providers.errors import friendly_model_error
|
|
from .providers.openai_provider import looks_like_unparsed_tool_call, strip_dangling_tool_tag
|
|
from .tools import ToolRegistry
|
|
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
class ApprovalOutcome(str, Enum):
|
|
ONCE = "once"
|
|
ALWAYS_TOOL = "always_tool"
|
|
ALWAYS_COMMAND = "always_command"
|
|
ALWAYS_DOMAIN = "always_domain"
|
|
# OPE-219: the allowed-sites card's durable choice. The site joins the machine's
|
|
# sandbox list (Settings > Sandbox), for commands and web tools alike.
|
|
ALWAYS_SITE = "always_site"
|
|
# Session-wide grant for classifier-approved read-only shell commands (readonly.py).
|
|
READONLY_SESSION = "readonly_session"
|
|
# OPE-136 durable trust: persist a per-tool "don't ask" rule for an MCP tool —
|
|
# survives sessions, revocable on the server's detail page. MCP-only (validated
|
|
# server-side in manager._grant_offered, like every other grant).
|
|
ALWAYS_TRUST = "always_trust"
|
|
# OPE-136 run grant ("Allow for this request"): cover this exact tool for the
|
|
# remainder of the CURRENT run only — in-memory, cleared at the run boundary,
|
|
# nothing persisted. EXTERNAL-risk tools only (validated server-side).
|
|
THIS_RUN = "this_run"
|
|
DENY = "deny"
|
|
SUPERSEDED = "superseded"
|
|
|
|
|
|
def _readonly_ok(arguments: dict, shell: Optional[str] = "bash") -> bool:
|
|
command = str((arguments or {}).get("command", "") or "")
|
|
if not command:
|
|
return False
|
|
from .readonly import is_readonly_command
|
|
|
|
return is_readonly_command(command, shell=shell or "bash")
|
|
|
|
|
|
@dataclass
|
|
class PermissionRequest:
|
|
tool_name: str
|
|
arguments: dict[str, Any]
|
|
metadata: Any
|
|
reason: str
|
|
tool_call_id: Optional[str] = None # for durable resume (idempotent inbox item)
|
|
# Where an MCP call actually goes ({transport, host}, from the server DEF at
|
|
# registration) — carried on the request so a PARKED approval shows the same
|
|
# destination evidence as the live card (§35 parity). None for non-MCP tools.
|
|
mcp_destination: Optional[dict] = None
|
|
escalation: Optional[dict] = None
|
|
provenance: str = ""
|
|
|
|
|
|
Approver = Callable[[PermissionRequest], Awaitable[ApprovalOutcome]]
|
|
|
|
|
|
async def _deny_all(_request: PermissionRequest) -> ApprovalOutcome:
|
|
return ApprovalOutcome.DENY
|
|
|
|
|
|
# OPE-238: the approval origins that mean "ran without asking": auto-approve let the
|
|
# action through with no card. A card the user answered, a standing rule or trust the
|
|
# user set up, and the bypass modes are the user's own choice and are not listed.
|
|
_UNASKED_ORIGINS = frozenset({"gate_tier", "reviewer"})
|
|
# Every turn ends with exactly one of these; the summary goes just before it, so the
|
|
# event that ends a turn stays the last one (the headless runner reads it that way).
|
|
_TURN_ENDINGS = frozenset({EventType.TURN_END, EventType.INTERRUPTED, EventType.ERROR})
|
|
|
|
|
|
def _summarizes_turn(gen_fn: Callable[..., AsyncIterator[Event]]) -> Callable[..., AsyncIterator[Event]]:
|
|
"""Wrap a turn generator (run / retry / resume) so that, when any action ran without
|
|
asking, one TURN_SUMMARY event lists them just before the turn ends.
|
|
|
|
An index, not a copy: tool call id, tool name, origin, status and the reviewer's
|
|
one-line reason. The arguments and results are already in the tool events and the
|
|
audit log, which can be filtered by the same call id."""
|
|
|
|
@functools.wraps(gen_fn)
|
|
async def wrapper(self: "TurnEngine", *args: Any, **kwargs: Any) -> AsyncIterator[Event]:
|
|
inner = gen_fn(self, *args, **kwargs)
|
|
unasked: list[dict[str, Any]] = []
|
|
try:
|
|
async for event in inner:
|
|
if event.type is EventType.TOOL_FINISHED:
|
|
origin = event.data.get("approval_origin")
|
|
if origin in _UNASKED_ORIGINS:
|
|
unasked.append(
|
|
{
|
|
"tool_call_id": str(event.data.get("tool_call_id") or ""),
|
|
"name": str(event.data.get("name") or ""),
|
|
"origin": origin,
|
|
# "change" or "read": only changes count as changes.
|
|
"effect": str(event.data.get("approval_effect") or "change"),
|
|
"status": str(event.data.get("status") or ""),
|
|
**(
|
|
{"tier": str(event.data["approval_tier"])}
|
|
if event.data.get("approval_tier")
|
|
else {}
|
|
),
|
|
**(
|
|
{"note": str(event.data["approval_note"])}
|
|
if event.data.get("approval_note")
|
|
else {}
|
|
),
|
|
**(
|
|
{"exit_code": event.data["exit_code"]}
|
|
if "exit_code" in event.data
|
|
else {}
|
|
),
|
|
**({"timed_out": True} if event.data.get("timed_out") else {}),
|
|
**({"background": True} if event.data.get("background") else {}),
|
|
}
|
|
)
|
|
elif event.type in _TURN_ENDINGS and unasked:
|
|
yield Event(EventType.TURN_SUMMARY, _summary_payload(unasked))
|
|
unasked = []
|
|
yield event
|
|
finally:
|
|
# A surface that stops reading mid-turn closes this wrapper; close the turn
|
|
# itself too, at once, so its own cleanup (run grants) runs as before.
|
|
await inner.aclose()
|
|
|
|
return wrapper
|
|
|
|
|
|
# The engine's reviewer choice -> the recorded reviewer kind (recording format 1.0).
|
|
_REVIEWER_KINDS = {"session": "session_model", "openai-decisions": "openai_decisions", "jev": "typesafe_jev"}
|
|
|
|
|
|
def _records_turn(kind: str) -> Callable[[Callable[..., AsyncIterator[Event]]], Callable[..., AsyncIterator[Event]]]:
|
|
"""Record a turn entry point (run / retry / resume) for observability (E1).
|
|
|
|
`turn_started` goes out when the entry point emits TURN_START, `turn_ended` at its
|
|
TURN_END, INTERRUPTED or ERROR, and, for the paths that end with none of these (a
|
|
resume stopped mid-tools, a generator the surface abandoned), in the `finally`: then the
|
|
status is `interrupted` if Stop was pressed, else `unknown`. The caller says who started
|
|
the turn with `trigger=` (user, channel, schedule, team_wake; `unknown` if it does not
|
|
say), and a team worker's caller who woke it with `woken_by=` (1.2). Format 1.3: the
|
|
caller says why the turn started with `wake=` (`turn.wake`), an automation run's own
|
|
turn with `automation=`, and a team member's `team=` (`stamp.team`); with no `wake=`, the
|
|
reason follows the trigger (user, channel, schedule). While recording, UI events also
|
|
carry `turn_id`, `ts_ms`, and a tool's `step_id`."""
|
|
|
|
def deco(gen_fn: Callable[..., AsyncIterator[Event]]) -> Callable[..., AsyncIterator[Event]]:
|
|
@functools.wraps(gen_fn)
|
|
async def wrapper(self: "TurnEngine", *args: Any, trigger: str = "unknown",
|
|
woken_by: Optional[dict[str, Any]] = None, wake: Optional[dict[str, Any]] = None,
|
|
automation: Optional[dict[str, Any]] = None, team: Optional[dict[str, Any]] = None,
|
|
**kwargs: Any) -> AsyncIterator[Event]:
|
|
inner = gen_fn(self, *args, **kwargs)
|
|
obs = getattr(self, "_obs", None)
|
|
if obs is None or not obs.enabled:
|
|
try:
|
|
async for event in inner:
|
|
yield event
|
|
finally:
|
|
await inner.aclose()
|
|
return
|
|
started = False
|
|
try:
|
|
async for event in inner:
|
|
if event.type is EventType.TURN_START and not started:
|
|
started = True
|
|
self._begin_recorded_turn(kind, trigger, woken_by, wake=wake,
|
|
automation=automation, team=team)
|
|
if started and obs.in_turn:
|
|
self._observe_event(event)
|
|
yield event
|
|
finally:
|
|
await inner.aclose()
|
|
if started:
|
|
self._end_recorded_turn("interrupted" if self._cancel.is_set() else "unknown")
|
|
|
|
return wrapper
|
|
|
|
return deco
|
|
|
|
|
|
# `_wait_tool` kind by tool (observability §5.4); any other wait is an approval card.
|
|
_WAIT_KINDS = {
|
|
"ask_user": "question",
|
|
"propose_plan": "plan",
|
|
"propose_team": "team",
|
|
"propose_work_items": "items",
|
|
"request_connector": "connector",
|
|
"grant_connector": "connector",
|
|
"request_tool": "tool_install",
|
|
"request_directory": "directory",
|
|
}
|
|
|
|
|
|
def _result_sha256(result: Any) -> Optional[str]:
|
|
"""SHA-256 of a tool's raw result, as the bytes `result_bytes` counts (1.3)."""
|
|
try:
|
|
data = (result.encode("utf-8") if isinstance(result, str)
|
|
else json.dumps(result, default=str, ensure_ascii=False).encode("utf-8"))
|
|
except Exception: # noqa: BLE001
|
|
return None
|
|
return hashlib.sha256(data).hexdigest()
|
|
|
|
|
|
def _accepts_view(reviewer: Any) -> bool:
|
|
"""Whether this reviewer's `review` takes the provider view for its check (the session
|
|
model reviewer does; decision-model reviewers call their own service, E23)."""
|
|
try:
|
|
import inspect
|
|
|
|
return "view" in inspect.signature(reviewer.review).parameters
|
|
except (TypeError, ValueError):
|
|
return False
|
|
|
|
|
|
def _verdict_matches(result: str, approved: bool) -> bool:
|
|
"""A shadow check matched you when it would have allowed what you approved, or denied
|
|
what you denied; an unsure never matches."""
|
|
return (result == "allow" and approved) or (result == "deny" and not approved)
|
|
|
|
|
|
def _reviewer_skip(engine: "TurnEngine", decision: Any) -> str:
|
|
"""Why the auto-approver was not consulted on a call that needed a person (§8.2)."""
|
|
if decision.human_only:
|
|
return "skipped_human_only"
|
|
if engine.reviewer is not None and engine._reviewer_denials >= _REVIEWER_TRIP:
|
|
return "skipped_paused"
|
|
try:
|
|
attended = bool(engine.is_attended and engine.is_attended())
|
|
except Exception: # noqa: BLE001
|
|
attended = False
|
|
if engine.reviewer is not None and engine.reviewer_enabled and not attended:
|
|
return "skipped_unattended"
|
|
return "skipped_off"
|
|
|
|
|
|
def _wait_outcome(result: Any, interrupted: Any, kind: str, *, stopped: bool) -> str:
|
|
"""A wait step's `outcome`: approved, denied, answered or interrupted (§5.4). An approval
|
|
card's "interrupted" value is the same DENY a person can click, so Stop is told apart by
|
|
whether it was pressed."""
|
|
if result is interrupted and stopped:
|
|
return "interrupted"
|
|
if isinstance(result, ApprovalOutcome):
|
|
if result is ApprovalOutcome.DENY:
|
|
return "denied"
|
|
return "answered" if result is ApprovalOutcome.SUPERSEDED else "approved"
|
|
if isinstance(result, dict):
|
|
if result.get("error") == "interrupted by user":
|
|
return "interrupted"
|
|
if kind == "question":
|
|
return "answered" if result.get("answer") or result.get("answers") else "denied"
|
|
ok = result.get("approved") or result.get("granted") or result.get("installed")
|
|
return "approved" if ok else "denied"
|
|
return "answered" if result else "denied"
|
|
|
|
|
|
def _action_failed(action: dict[str, Any]) -> bool:
|
|
"""A listed action that changed nothing: the call errored, the command exited
|
|
non-zero, or it timed out. A background start is neither done nor failed."""
|
|
if action.get("status") != "ok":
|
|
return True
|
|
if action.get("timed_out"):
|
|
return True
|
|
code = action.get("exit_code")
|
|
return isinstance(code, int) and code != 0
|
|
|
|
|
|
def _summary_payload(actions: list[dict[str, Any]]) -> dict[str, Any]:
|
|
"""`count` is what the header says: changes that ran without asking and worked.
|
|
Failed attempts and read-only actions are listed, and counted apart, so the
|
|
number means "things that changed state and that you did not approve"."""
|
|
changes = [a for a in actions if a.get("effect") != "read"]
|
|
failed = [a for a in changes if _action_failed(a)]
|
|
reads = [a for a in actions if a.get("effect") == "read"]
|
|
return {
|
|
"count": len(changes) - len(failed),
|
|
"failed": len(failed),
|
|
"reads": len(reads),
|
|
"actions": actions,
|
|
}
|
|
def _settings_changed(verdict: Any) -> Any:
|
|
"""An `unsure` because approval settings changed mid-review. The message is shown on the
|
|
card for every reviewer, including the decision models that otherwise give no reason."""
|
|
msg = "Approval settings changed during review; a human decision is required."
|
|
extra = {"card_reason": msg} if hasattr(verdict, "card_reason") else {}
|
|
return replace(verdict, verdict="unsure", reason=msg, **extra)
|
|
|
|
|
|
def _args_fit(spec: Any, arguments: Any) -> bool:
|
|
"""Whether the arguments fit the tool's own parameters: no name it lacks, no required
|
|
one missing. True when that cannot be told (no function, or one taking anything)."""
|
|
func = getattr(spec, "func", None)
|
|
if func is None or not isinstance(arguments, dict):
|
|
return True
|
|
try:
|
|
inspect.signature(func).bind(**arguments)
|
|
except TypeError:
|
|
return False
|
|
except ValueError: # no signature to read
|
|
return True
|
|
return True
|
|
|
|
|
|
class TurnEngine:
|
|
def __init__(
|
|
self,
|
|
*,
|
|
provider: ProviderClient,
|
|
registry: ToolRegistry,
|
|
permissions: PermissionEngine,
|
|
model: str,
|
|
instructions: Optional[str] = None,
|
|
approver: Optional[Approver] = None,
|
|
max_iterations: int = 12,
|
|
model_settings: Optional[dict[str, Any]] = None,
|
|
messages: Optional[list[dict[str, Any]]] = None,
|
|
audit_sink: Optional[Callable[[dict[str, Any]], None]] = None,
|
|
context_provider: Optional[Callable[[], str]] = None,
|
|
directory_requester: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
plan_approver: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
question_asker: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
tool_requester: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
team_approver: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
items_approver: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
# Handles `request_connector` / `grant_connector` (spec §11.6): emits
|
|
# CONNECTOR_REQUESTED, waits for the human, returns {approved, …}.
|
|
connector_requester: Optional[
|
|
Callable[[dict[str, Any]], "Awaitable[dict[str, Any]]"]
|
|
] = None,
|
|
# Called (thread-safe, best-effort) when the user stops the turn — e.g. the
|
|
# executor's kill for a running shell command.
|
|
interrupt_hooks: Optional[list[Callable[[], None]]] = None,
|
|
# OPE-186 change 1: bound every tool result before it enters the conversation
|
|
# (head + marker + tail; full text in a spill file). None = the module default
|
|
# (10,000 bytes), 0 = off. See coworker/toolresult.py.
|
|
tool_result_max_bytes: Optional[int] = None,
|
|
tool_result_spill_dir: Optional[Path] = None,
|
|
) -> None:
|
|
self.provider = provider
|
|
self.registry = registry
|
|
self.permissions = permissions
|
|
self.model = model
|
|
self.approver = approver or _deny_all
|
|
self.max_iterations = max_iterations
|
|
self.model_settings = dict(model_settings or {})
|
|
self.messages: list[dict[str, Any]] = list(messages or [])
|
|
self._tool_timings: dict[str, dict[str, float]] = {}
|
|
self.audit_sink = audit_sink
|
|
# Returns an ephemeral `<system-context>` block appended to the LAST user message at
|
|
# send-time only (never persisted). We can't reliably inject system messages mid-thread
|
|
# across providers, so dynamic per-turn context (e.g. the live directory list) rides on
|
|
# the latest user turn. Returns "" when there's nothing to add.
|
|
self.context_provider = context_provider
|
|
# Handles the `request_directory` tool: emits a DIRECTORY_REQUESTED prompt, waits for the
|
|
# user to grant/decline a folder out-of-band, applies the grant to this live session, and
|
|
# returns the outcome. None on surfaces that can't prompt (the tool then no-ops).
|
|
self.directory_requester = directory_requester
|
|
# Handles the `request_tool` tool: emits TOOL_REQUESTED, waits for the user to install
|
|
# the pinned build or decline. None on surfaces that can't prompt (the tool then
|
|
# no-ops, and the agent is told so it can fall back openly rather than skip silently).
|
|
self.tool_requester = tool_requester
|
|
# Handles the `propose_plan` tool: emits PLAN_PROPOSED, waits for the user's decision.
|
|
# An approving result flips the live PermissionEngine out of plan mode (same session,
|
|
# context kept). None on surfaces that can't prompt (the tool then no-ops).
|
|
self.plan_approver = plan_approver
|
|
# Handles the `propose_team` tool (the staffing gate): emits TEAM_PROPOSED, waits
|
|
# for the user's decision; approval pre-spawns the worker sessions and the result
|
|
# carries the roster (actor ids). None on surfaces that can't prompt.
|
|
self.team_approver = team_approver
|
|
self.connector_requester = connector_requester
|
|
# Handles `propose_work_items` (the decomposition gate): emits ITEMS_PROPOSED,
|
|
# waits; approval creates the items on the board. Mode-independent by design —
|
|
# unlike propose_plan it carries no permission-mode semantics: propose_plan is
|
|
# an IMPLEMENTATION plan (steps/files, plan-mode exit); this is a team
|
|
# decomposition onto the board.
|
|
self.items_approver = items_approver
|
|
# Handles the `ask_user` tool: turns a question into an Inbox item and waits for the answer
|
|
# (answerable inline in a live session or from the Inbox when unattended). None on surfaces
|
|
# that can't ask (the tool then no-ops).
|
|
self.question_asker = question_asker
|
|
# Auto-compaction (OPE-27) — set post-construction by the surface/manager so the
|
|
# constructor footprint stays put. `compaction_settings` is a live getter (Settings
|
|
# changes apply without a rebuild); `is_attended` gates the failure prompt (None →
|
|
# treat as unattended: never park a background run on internal bookkeeping).
|
|
self.compaction_state: Optional[_compaction.CompactionState] = None
|
|
self.compaction_settings: Optional[Callable[[], dict[str, Any]]] = None
|
|
self.is_attended: Optional[Callable[[], bool]] = None
|
|
# Attendance (coworker/unattended.py): who answers when the agent asks. A live
|
|
# getter returning "attended" / "inbox" / "auto"; None reads as attended. In "auto"
|
|
# the engine answers questions, folder requests and pinned installs itself by fixed
|
|
# rule, and refuses any approval card only a person could clear — never a hang.
|
|
self.attendance: Optional[Callable[[], str]] = None
|
|
# Approvals are separate from questions. A surface that answers questions by rule
|
|
# (attendance "auto") while a person still answers approval cards sets this: a
|
|
# terminal run with --auto-answer. Unset, attendance "auto" covers both.
|
|
self.cards_reach_person: Optional[Callable[[], bool]] = None
|
|
self._dangerous_warned = False
|
|
# Session facts (spec Part 0 / §2.4) — the known world frozen at session start, plus
|
|
# the per-turn ingestion record. Set post-construction by the surface, same as
|
|
# compaction above, so the constructor footprint stays put. None ⇒ nothing recorded
|
|
# and behaviour is byte-identical; NOTHING consumes it in v1 either way.
|
|
self.session_facts: Optional[session_facts.SessionFacts] = None
|
|
# Auto-Approve reviewer (spec Part 8). Set post-construction; None ⇒ Mode.AUTO_APPROVE
|
|
# behaves exactly like INTERACTIVE. Consulted only on decisions the gate marked
|
|
# needs_user, only in AUTO_APPROVE mode, only when the session is attended (an
|
|
# unset is_attended counts as NOT attended here — automations never set it), and
|
|
# only until _REVIEWER_TRIP denials IN A ROW (§8.4 retry guard). Consecutive, not
|
|
# cumulative: an allow/unsure verdict or an ask_user answer resets the streak —
|
|
# the owner-hit 2026-08-24 was a 2-denial cumulative trip silently downgrading a
|
|
# long agentic turn to hand-approval for everything after one over-strict pair.
|
|
self.reviewer: Optional[Any] = None
|
|
self.reviewer_enabled = True # standalone injected reviewers; manager supplies live flag
|
|
self.reviewer_settings_epoch = 0
|
|
self.reviewer_settings_key = None
|
|
self._reviewer_denials = 0
|
|
self._reviewer_verdicts: dict[str, Any] = {}
|
|
self._reviewer_input_snapshots: dict[str, Any] = {}
|
|
# (c) How each consequential call got cleared, keyed by tool_call id:
|
|
# {"origin": "reviewer"|"bypass"|"user", "note": <reviewer reasoning>, "grant":
|
|
# <user outcome>}. Consumed by _record_result into the TOOL_FINISHED event AND
|
|
# into the tool message's `_display` sidecar, so the quiet provenance chips
|
|
# survive reload (owner ruling 2026-08-24) — display-only, never provider-visible.
|
|
self._approval_origins: dict[str, dict[str, str]] = {}
|
|
# Per-call override for the denied-tool-result text, keyed by tool_call id. An
|
|
# approver that resolves a request itself (a subagent's expired approval wait)
|
|
# sets this before returning DENY, so the model reads WHY instead of the
|
|
# generic "denied by user" (OPE-255 ruling: the response must say it expired).
|
|
self._deny_notes: dict[str, str] = {}
|
|
# OPE-232: set once a shell command has been cleared in the batch being authorized.
|
|
# The batch runs only after every call is cleared, and the shell persists, so a
|
|
# later command's folder is unknown from then on (see `current_shell_cwd`).
|
|
self._shell_cleared_in_batch = False
|
|
# OPE-237 (flag `auto_approve_plan_approval`): in auto-approve, `propose_plan` takes
|
|
# a list of steps, and the steps the user approved are evidence for exactly those
|
|
# actions until the request ends (cleared with the run grants in `run`).
|
|
self.plan_approval: bool = False
|
|
self._approved_plan: list[plan_steps.PlanStep] = []
|
|
# Shadow evaluation (spec Part 6 step 3): when True and a reviewer is attached, the
|
|
# reviewer records what it WOULD have decided on each approval card while the human
|
|
# still decides. Fire-and-forget — the card is never delayed, no decision is ever
|
|
# touched, and the verdict lands in the audit log (stage="reviewer_shadow", joined
|
|
# to the human's approval_resolved row by call_id).
|
|
self.reviewer_shadow = False
|
|
self._shadow_tasks: set[asyncio.Task] = set()
|
|
# One-shot "Allow anyway" grants (§8.4): minted ONLY by a human clicking the deny
|
|
# card, keyed on the exact tool + canonical arguments, consumed on first match. A
|
|
# re-proposal with even slightly different arguments does not match and goes back
|
|
# through the reviewer/card — deliberately narrow, deliberately not standing.
|
|
self._allow_anyway: set[tuple[str, str]] = set()
|
|
# ask_user answers for the reviewer's history (§8.2 — the missing third of the
|
|
# reply-tag feature: render_history prints the tag and the §8.3 instructions say to
|
|
# weigh it lower; this is the extractor that finally delivers the data). Captured at
|
|
# the moment the asker returns — the one point where the engine KNOWS the text came
|
|
# from the human, whichever authenticated surface answered (inline card, Inbox, or a
|
|
# bound channel; the same trust approval clicks already carry). ANSWERS ONLY, never
|
|
# the agent's question: agent-authored text stays out of the judge's view — showing
|
|
# the question too is step 2, evidence-gated on shadow data. Each entry is
|
|
# (anchor, text) where anchor = how many user messages existed at capture, so the
|
|
# merge in `_user_history` stays chronological. Runtime-only on purpose: a restart
|
|
# costs the reviewer context (more cards), never correctness.
|
|
self._ask_replies: list[tuple[int, str, str]] = [] # (anchor, answer, question)
|
|
# Extra user-facing fields for a tool's approval card, merged into the
|
|
# PERMISSION_REQUIRED payload — e.g. web_search's live provider name, so the card
|
|
# can say where queries actually go (§1.9). Set post-construction by the surface
|
|
# (the engine itself knows nothing about providers); None ⇒ no extras. Called at
|
|
# card time, not session start, so a mid-session Settings change shows through.
|
|
self.approval_extras: Optional[
|
|
Callable[[str, dict[str, Any]], dict[str, Any]]
|
|
] = None
|
|
# Harness-resolved original action for a lead's permission proxy. Never
|
|
# derived from the lead's note or another agent's conversation.
|
|
self.delegated_approval: Optional[Callable[[dict[str, Any]], dict[str, Any]]] = None
|
|
self.reviewer_context: Optional[Callable[[], dict[str, Any]]] = None
|
|
self.reviewer_owner_history: Optional[Callable[[], tuple[str, list[dict[str, Any]]]]] = None
|
|
self.reviewer_denial_message: Optional[str] = None
|
|
self._authorized_delegates: dict[str, dict] = {}
|
|
# What the agent itself created this session (OPE-114 §1). The reviewer never sees
|
|
# file contents, so `python scripts/setup.py` is unjudgeable from its text — but the
|
|
# engine knows whether it wrote or downloaded that file moments ago, and says so on
|
|
# the card and in the reviewer's request. Runtime-only, like `_ask_replies`: a
|
|
# restart costs context (more cards), never correctness.
|
|
self._agent_files = provenance.SessionFiles(permissions.workspace_root)
|
|
# The inert-writes tier (OPE-233) may rewrite a file the agent itself wrote: only
|
|
# the agent's own bytes are lost. An injected lookup (tests) is left alone.
|
|
if getattr(permissions, "agent_wrote", None) is None:
|
|
permissions.agent_wrote = self._agent_files.wrote
|
|
# OPE-235: what each shell command is about to bring in from outside, keyed by tool
|
|
# call id from just before it runs until its result is recorded.
|
|
self._intake_plans: dict[str, Any] = {}
|
|
# The secrets floor (OPE-236) asks the same record whether the agent put a
|
|
# secret-looking value into a file it is now sending.
|
|
if getattr(permissions, "agent_file_has_secret", None) is None:
|
|
permissions.agent_file_has_secret = self._agent_files.carries_secret
|
|
# Round-2 F-5: an upload the user approved as a plan step is a granted destination.
|
|
if getattr(permissions, "approved_plan_step", None) is None:
|
|
permissions.approved_plan_step = self._is_approved_plan_step
|
|
# OPE-235: whether outside content (web, email, connectors, downloads) has entered
|
|
# the agent's context this session; one of the reviewer's computed facts.
|
|
self._external_read = False
|
|
self._tool_result_max_bytes = (
|
|
toolresult.DEFAULT_TOOL_RESULT_MAX_BYTES
|
|
if tool_result_max_bytes is None
|
|
else int(tool_result_max_bytes)
|
|
)
|
|
self._tool_result_spill_dir = (
|
|
Path(tool_result_spill_dir) if tool_result_spill_dir is not None else None
|
|
)
|
|
# Completed tool calls so far, so a fact can say how many steps back the write was.
|
|
self._step = 0
|
|
self._last_context_tokens: Optional[int] = None
|
|
self.audit_context: dict[str, Any] = {}
|
|
# Observability (E1): the turn and step events this engine sends to its recorder.
|
|
# Off until a recorder is set (`engine.recorder = ...`), like the other surface hooks.
|
|
self._obs = TurnRecording(None, lambda: str(self.audit_context.get("session_id") or ""))
|
|
# The engine's own tagged view of its provider (observability E2, §3.3): every call
|
|
# it makes is recorded as a model step of the current turn, purpose `main`.
|
|
self.provider = view_for_engine(self.provider, self._obs)
|
|
self._call_index: dict[str, int] = {}
|
|
# Each proposed call's arguments, for the 1.2 tool fields of calls that never ran.
|
|
self._call_args: dict[str, Any] = {}
|
|
# Whether this machine has a sandbox switched on (stamp.sandbox.expected, 1.2): set
|
|
# by whoever builds the engine from the machine's setting; None = not known.
|
|
self.sandbox_expected: Optional[bool] = None
|
|
# Who answered a waiting call's card (observability §5.4): set by the server, which
|
|
# reads it from the Inbox.
|
|
self.resolver_of: Optional[Callable[[str], str]] = None
|
|
# Each tool call's decision path, built in `_authorize`, attached to its tool step
|
|
# (observability E4, §8.3); and where its card was shown.
|
|
self._decisions: dict[str, DecisionPath] = {}
|
|
self._card_where: dict[str, str] = {}
|
|
# Auto-approver check steps by tool call (E12), and shadow checks waiting to be
|
|
# compared with your answer: call id -> (step id, verdict or None).
|
|
self._review_steps: dict[str, str] = {}
|
|
self._turn_end_tasks: set[asyncio.Task] = set()
|
|
# The coworker fingerprint and the session-start context facts, set by the session
|
|
# build (observability E16, E5); and this turn's context block, to spot a change.
|
|
self.persona_fp: Optional[str] = None
|
|
# 1.3: which coworker ran (E25a) and the scan areas its manifest promises (E17c).
|
|
self.persona_id: Optional[str] = None
|
|
self.persona_coverage: list[str] = []
|
|
self.context_facts: dict[str, Any] = {}
|
|
self._last_context_block = ""
|
|
self._turn_context_hash: Optional[str] = None
|
|
self._context_turn: Optional[str] = None
|
|
self._stamp_seen: dict[str, Any] = {}
|
|
self._shadow_checks: dict[str, tuple[Optional[str], Any]] = {}
|
|
self._user_answers: dict[str, bool] = {}
|
|
if instructions and not (
|
|
self.messages and self.messages[0].get("role") == "system"
|
|
):
|
|
self._add_message({"role": "system", "content": instructions}, at=0)
|
|
self._cancel = asyncio.Event()
|
|
# Whether the latest assistant turn hit the output-token limit — decides which
|
|
# diagnosis a mangled (unparseable-args) tool call gets answered with.
|
|
self._turn_truncated = False
|
|
# Consecutive length-truncated, action-free replies nudged this turn (OPE-171).
|
|
self._continuations = 0
|
|
self._warned_context_fallback = False
|
|
# Each pending steering message: (text, optional MessageSource sidecar dict).
|
|
self._steering: list[tuple[str, Optional[dict[str, Any]], Optional[dict[str, Any]]]] = []
|
|
# tool_call.id → the standing rule that auto-allowed it ("tool → target"), so the
|
|
# TOOL_FINISHED event can carry the note to the tool card (§25).
|
|
self._standing_notes: dict[str, str] = {}
|
|
self._interrupt_hooks: list[Callable[[], None]] = list(interrupt_hooks or [])
|
|
|
|
# -- external controls ------------------------------------------------------
|
|
def _reset_cancel(self) -> None:
|
|
"""A new turn starts not stopped. The Stop flag is an asyncio.Event, which belongs to
|
|
the event loop that first waited on it; a turn running on another loop (each test
|
|
client socket has its own) could not wait on the old one: the wait failed at once,
|
|
the stream was read as stopped, and the turn ended with an empty answer while its
|
|
model call went on outside it. So a turn on a new loop gets a new flag."""
|
|
try:
|
|
loop = asyncio.get_running_loop()
|
|
except RuntimeError:
|
|
loop = None
|
|
if loop is not None and getattr(self._cancel, "_loop", None) not in (None, loop):
|
|
self._cancel = asyncio.Event()
|
|
else:
|
|
self._cancel.clear()
|
|
|
|
def request_interrupt(self) -> None:
|
|
"""Stop the turn as soon as possible, from ANY state: mid-stream (the producer
|
|
thread drops the stream between chunks), mid-tool (interrupt hooks kill the
|
|
running command), awaiting an approval/question/plan (the await resolves as
|
|
interrupted), or between iterations (the loop checkpoint). Every pending
|
|
tool_call still gets a tool-error result so the history never carries orphans
|
|
(hosted templates reject them, and durable-resume would re-prompt them)."""
|
|
self._cancel.set()
|
|
for hook in self._interrupt_hooks:
|
|
try:
|
|
hook()
|
|
except Exception:
|
|
pass # best-effort: a dead executor must not block the stop
|
|
|
|
async def _interruptible(self, coro: Any, interrupted: Any) -> Any:
|
|
"""Await `coro`, but resolve early with `interrupted` if the user stops the
|
|
turn. The pending task is cancelled so an answered-later Inbox card no-ops."""
|
|
task = asyncio.ensure_future(coro)
|
|
cancel_wait = asyncio.ensure_future(self._cancel.wait())
|
|
try:
|
|
done, _ = await asyncio.wait(
|
|
{task, cancel_wait}, return_when=asyncio.FIRST_COMPLETED
|
|
)
|
|
if task in done:
|
|
return task.result()
|
|
task.cancel()
|
|
return interrupted
|
|
finally:
|
|
cancel_wait.cancel()
|
|
|
|
async def _wait_tool(self, tool_call, coro, interrupted, kind: Optional[str] = None):
|
|
started, clock = time.time(), time.perf_counter()
|
|
# Observability E20: a wait step from the moment the card is shown to the answer, so
|
|
# a slow answer is never mistaken for a slow agent (§5.4).
|
|
kind = kind or _WAIT_KINDS.get(tool_call.name, "approval")
|
|
try:
|
|
attended = bool(self.is_attended and self.is_attended())
|
|
except Exception: # noqa: BLE001 - a broken getter must not break the wait
|
|
attended = False
|
|
step_id = self._obs.start_step(
|
|
kind="wait", name=kind, call_id=tool_call.id,
|
|
attrs={"for_call_id": tool_call.id, "kind": kind, "attended": attended,
|
|
"where": "session" if attended else "inbox",
|
|
"inbox_at": None if attended else int(started * 1000)},
|
|
)
|
|
self._obs.track_wait(tool_call.id, step_id)
|
|
result: Any = interrupted
|
|
failed = False
|
|
try:
|
|
result = await self._interruptible(coro, interrupted)
|
|
return result
|
|
except BaseException:
|
|
failed = True
|
|
raise
|
|
finally:
|
|
self._tool_timings.setdefault(tool_call.id, {}).update(waited_started=started, waited_ms=(time.perf_counter() - clock) * 1000)
|
|
self._obs.end_wait(tool_call.id)
|
|
if step_id is not None:
|
|
who = ""
|
|
if self.resolver_of is not None:
|
|
try:
|
|
who = str(self.resolver_of(tool_call.id) or "")
|
|
except Exception: # noqa: BLE001
|
|
who = ""
|
|
self._obs.end_step(
|
|
step_id, status="error" if failed else "ok",
|
|
attrs={"outcome": "interrupted" if failed else _wait_outcome(
|
|
result, interrupted, kind, stopped=self._cancel.is_set())},
|
|
content={"resolved_by": who} if who else {},
|
|
)
|
|
|
|
def note_wait_where(self, call_id: Optional[str], where: str) -> None:
|
|
"""Where a waiting call's card is shown, `session` or `inbox` (observability §5.4)."""
|
|
if call_id:
|
|
self._card_where[call_id] = where
|
|
self._obs.wait_where(call_id, where)
|
|
|
|
@property
|
|
def recorder(self) -> Any:
|
|
return self._obs.recorder
|
|
|
|
@recorder.setter
|
|
def recorder(self, value: Any) -> None:
|
|
self._obs.recorder = value
|
|
|
|
def _begin_recorded_turn(self, kind: str, trigger: str,
|
|
woken_by: Optional[dict[str, Any]] = None, *,
|
|
wake: Optional[dict[str, Any]] = None,
|
|
automation: Optional[dict[str, Any]] = None,
|
|
team: Optional[dict[str, Any]] = None) -> None:
|
|
"""`turn_started` (E1, technical design §4). For `run` the turn opens with your
|
|
message; for `resume`, with the assistant message whose calls are resumed; a `retry`
|
|
opens with the first message it adds, so its start waits for that."""
|
|
first: Optional[str] = None
|
|
if kind == "run":
|
|
first = next((m.get("mid") for m in reversed(self.messages) if m.get("role") == "user"), None)
|
|
elif kind == "resume":
|
|
first = next(
|
|
(m.get("mid") for m in reversed(self.messages)
|
|
if m.get("role") == "assistant" and m.get("tool_calls")),
|
|
None,
|
|
)
|
|
attended, reviewer = self._attended_now(), self._reviewer_facts()
|
|
stamp = self._turn_stamp()
|
|
if team and team.get("team_id") and team.get("role") in ("lead", "worker"):
|
|
stamp["team"] = {"team_id": str(team["team_id"]), "role": team["role"]} # 1.3, E18b
|
|
if wake is None:
|
|
# 1.3 (E18a): with no word from the caller, the reason follows the trigger.
|
|
wake = {"reason": {"user": "user", "channel": "channel", "schedule": "schedule"}.get(trigger, "unknown")}
|
|
turn_id = self._obs.begin_turn(
|
|
kind=kind,
|
|
trigger=trigger,
|
|
attrs={
|
|
"approval_mode": self.permissions.mode.value,
|
|
"attended": attended,
|
|
"reviewer": reviewer,
|
|
"max_iterations": self.max_iterations,
|
|
"woken_by": woken_by,
|
|
"wake": wake,
|
|
"automation": automation,
|
|
},
|
|
stamp=stamp,
|
|
first_message_id=first,
|
|
wait_for_first_message=kind == "retry",
|
|
)
|
|
# What `stamp_changed` compares against for the rest of the turn (V2-27).
|
|
self._stamp_seen = {"turn": turn_id, "attended": attended, "reviewer": reviewer,
|
|
"sandbox": stamp.get("sandbox")}
|
|
|
|
def _attended_now(self) -> bool:
|
|
try:
|
|
return bool(self.is_attended and self.is_attended())
|
|
except Exception: # noqa: BLE001 - a broken getter must not break the turn
|
|
return False
|
|
|
|
def _reviewer_facts(self) -> dict[str, Any]:
|
|
"""The turn's `reviewer` (observability §4): as at turn start, or now."""
|
|
reviewer_kind = (
|
|
_REVIEWER_KINDS.get(getattr(self, "reviewer_choice", "session"), "session_model")
|
|
if self.reviewer is not None else None
|
|
)
|
|
return {
|
|
"active": self._reviewer_active() if self.reviewer is not None else False,
|
|
"shadow": bool(self.reviewer_shadow),
|
|
"kind": reviewer_kind,
|
|
"model": getattr(self.reviewer, "model", None) if reviewer_kind == "session_model" else None,
|
|
}
|
|
|
|
def _sandbox_stamp(self) -> Optional[dict[str, Any]]:
|
|
"""The stamp's sandbox group now, with `expected` (format 1.2) when it is known. The
|
|
turn's stamp and the mid-turn comparison both use this, so they cannot differ by it."""
|
|
sandbox = _stamps.sandbox_stamp(getattr(self, "sandbox_workspace", None))
|
|
if sandbox and self.sandbox_expected is not None:
|
|
sandbox["expected"] = bool(self.sandbox_expected)
|
|
return sandbox
|
|
|
|
def _note_stamp(self) -> None:
|
|
"""A `stamp_changed` notice when attendance, the reviewer or the sandbox differ from
|
|
the turn's start or the last notice (observability §9, V2-27). The Unattended toggle
|
|
and the reviewer settings apply mid-turn, and the first turn makes the sandbox after
|
|
its stamp was taken, so the runner version arrives here. Only the keys that changed,
|
|
with their new values."""
|
|
obs = self._obs
|
|
seen = getattr(self, "_stamp_seen", None) or {}
|
|
if (not obs.enabled or not obs.in_turn or not getattr(obs, "records_context", True)
|
|
or seen.get("turn") != obs.turn_id):
|
|
return
|
|
changed: dict[str, Any] = {}
|
|
attended, reviewer = self._attended_now(), self._reviewer_facts()
|
|
if attended != seen.get("attended"):
|
|
changed["attended"] = seen["attended"] = attended
|
|
if reviewer != seen.get("reviewer"):
|
|
changed["reviewer"] = seen["reviewer"] = reviewer
|
|
try:
|
|
sandbox = self._sandbox_stamp()
|
|
except Exception: # noqa: BLE001 - a stamp never breaks a turn
|
|
sandbox = seen.get("sandbox")
|
|
if sandbox and sandbox != seen.get("sandbox"):
|
|
changed["stamp"] = {"sandbox": sandbox}
|
|
seen["sandbox"] = sandbox
|
|
if changed:
|
|
obs.instant_step(kind="notice", name="stamp_changed", status="ok", attrs=changed)
|
|
|
|
def _turn_stamp(self) -> dict[str, Any]:
|
|
"""Facts saved with the turn (observability §9): machine, model, sandbox, coworker."""
|
|
stamp: dict[str, Any] = {}
|
|
try:
|
|
stamp["machine"] = _stamps.machine_stamp()
|
|
stamp["model"] = _stamps.model_stamp(self.model)
|
|
sandbox = self._sandbox_stamp()
|
|
if sandbox:
|
|
stamp["sandbox"] = sandbox
|
|
if self.persona_fp:
|
|
stamp["persona_fp"] = self.persona_fp
|
|
if self.persona_id:
|
|
stamp["persona_id"] = self.persona_id # 1.3, E25a
|
|
if self.persona_coverage:
|
|
stamp["persona_coverage"] = list(self.persona_coverage) # 1.3, E17c
|
|
except Exception: # noqa: BLE001 - a stamp never breaks a turn
|
|
logger.exception("observability: could not stamp the turn")
|
|
return stamp
|
|
|
|
def _sandbox_note_added(self) -> bool:
|
|
"""Whether this turn's context holds the sandbox's own note: the agent's context
|
|
adds `sandbox_workspace.context()` when it returns text. A workspace with no
|
|
sandbox has no such text, so no note (fix list F-1: it was true whenever the
|
|
workspace could describe itself, which the no-sandbox one can)."""
|
|
context = getattr(getattr(self, "sandbox_workspace", None), "context", None)
|
|
if not callable(context):
|
|
return False
|
|
try:
|
|
return bool(context())
|
|
except Exception: # noqa: BLE001 - a recording never breaks a turn
|
|
return False
|
|
|
|
def _note_context(self) -> None:
|
|
"""The context step at the turn's first model call, and a `context_changed` notice
|
|
when the per-turn block changes later in the turn (observability E5, §5.6)."""
|
|
obs = self._obs
|
|
if not obs.enabled or not obs.in_turn or not getattr(obs, "records_context", True):
|
|
return
|
|
block = self._last_context_block or ""
|
|
block_hash = _short_hash(block) if block else None
|
|
# The menu this turn's block offered (set by the agent's context provider, which
|
|
# leaves out skills disabled for the session); else every skill the loader found.
|
|
offered = getattr(self, "skills_offered", None)
|
|
skills = sorted(offered if offered is not None
|
|
else getattr(getattr(self, "skill_loader", None), "_skills", None) or {})
|
|
per_turn = {
|
|
"mode_note": self.permissions.mode.value if self.permissions.mode in (Mode.PLAN, Mode.DISCUSS) else None,
|
|
"folders": len(getattr(self.permissions, "roots", None) or []),
|
|
"sandbox_note": self._sandbox_note_added(),
|
|
"skills_menu": len(skills),
|
|
"skills_hash": _short_hash(",".join(skills)) if skills else None,
|
|
}
|
|
if self._context_turn != obs.turn_id:
|
|
self._context_turn, self._turn_context_hash = obs.turn_id, block_hash
|
|
system = self.messages[0].get("content") if self.messages and self.messages[0].get("role") == "system" else None
|
|
attrs: dict[str, Any] = {
|
|
"session_prompt_hash": _short_hash(system) if isinstance(system, str) else None,
|
|
"per_turn": per_turn,
|
|
"size_chars": len(block),
|
|
"block_hash": block_hash,
|
|
}
|
|
if self.context_facts and not getattr(self, "_context_session_told", False):
|
|
attrs["session_start"] = dict(self.context_facts)
|
|
self._context_session_told = True
|
|
obs.instant_step(kind="context", name="context", status="ok", attrs=attrs)
|
|
elif block_hash != self._turn_context_hash:
|
|
self._turn_context_hash = block_hash
|
|
obs.instant_step(kind="notice", name="context_changed", status="ok",
|
|
attrs={"per_turn": per_turn, "size_chars": len(block), "block_hash": block_hash})
|
|
|
|
def _observe_event(self, event: Event) -> None:
|
|
"""Ids on a UI event, a call that never ran as a zero-length tool step, and the turn's
|
|
end (E1). The app ignores fields it does not know, so older screens keep working."""
|
|
obs = self._obs
|
|
event.data.setdefault("turn_id", obs.turn_id)
|
|
event.data.setdefault("ts_ms", time.time_ns() // 1_000_000)
|
|
if event.type is EventType.TOOL_PROPOSED and event.data.get("tool_call_id"):
|
|
self._call_args[str(event.data["tool_call_id"])] = event.data.get("arguments")
|
|
if event.type in (EventType.TOOL_STARTED, EventType.TOOL_FINISHED):
|
|
call_id = str(event.data.get("tool_call_id") or "")
|
|
if event.type is EventType.TOOL_FINISHED and call_id:
|
|
mid = next(
|
|
(m.get("mid") for m in reversed(self.messages)
|
|
if m.get("role") == "tool" and m.get("tool_call_id") == call_id),
|
|
None,
|
|
)
|
|
attrs: dict[str, Any] = {"risk_class": self._risk_class(str(event.data.get("name") or ""))}
|
|
path = self._decisions.pop(call_id, None)
|
|
if path is not None and obs.step_for_call(call_id) is None:
|
|
attrs["decision"] = path.finish(ran=event.data.get("status") == "ok")
|
|
elif path is None:
|
|
# An interactive tool (question, plan, folder…) skips the permission
|
|
# flow: no stage decided it (recording-format: origin null).
|
|
attrs["decision"] = {"path": [], "origin": None}
|
|
data = event.data
|
|
created = (data.get("display") or {}).get("team_created") if data.get("name") == "propose_team" else None
|
|
if created and created.get("team_id"):
|
|
# The team it created and its worker sessions: ids only (1.2, OB-7).
|
|
attrs["team"] = {"team_id": str(created["team_id"]), "worker_session_ids": [
|
|
str(w.get("session_id")) for w in created.get("workers") or [] if w.get("session_id")]}
|
|
if obs.step_for_call(call_id) is None:
|
|
attrs.update(self._call_facts(
|
|
str(data.get("name") or ""), self._call_args.get(call_id), ran=False,
|
|
status=str(data.get("status") or ""), reason=str(data.get("reason") or ""),
|
|
))
|
|
answered_by_stop = path is not None and (path.stage("resolved") or {}).get("outcome") == "interrupted"
|
|
if (data.get("status") == "denied" and self._cancel.is_set()
|
|
and (data.get("name") in _WAIT_KINDS or answered_by_stop)):
|
|
# A Stop while a card waited (approval, question, plan, folder) is not a
|
|
# refusal: the handler answers "denied", the step says interrupted (§5.3).
|
|
data = {**data, "status": "interrupted"}
|
|
obs.tool_finished(
|
|
data, message_id=mid, call_index=self._call_index.get(call_id),
|
|
attrs=attrs,
|
|
)
|
|
step_id = obs.step_for_call(call_id)
|
|
if step_id:
|
|
event.data.setdefault("step_id", step_id)
|
|
if event.type is EventType.TURN_END:
|
|
status = str(event.data.get("status") or "completed")
|
|
if status in ("max_iterations_exceeded", "truncated"):
|
|
obs.instant_step(kind="notice", name="step_limit" if status == "max_iterations_exceeded" else "truncated",
|
|
status="ok", attrs={})
|
|
self._end_recorded_turn(status)
|
|
elif event.type is EventType.INTERRUPTED:
|
|
self._end_recorded_turn("interrupted")
|
|
elif event.type is EventType.ERROR:
|
|
self._end_recorded_turn("error")
|
|
|
|
def _end_recorded_turn(self, status: str) -> None:
|
|
"""`turn_ended` with this moment's time. If shadow checks are still running in the
|
|
background, it is sent once they end (at most 30 s later), so their steps are not
|
|
closed as interrupted while they run; the turn's recorded end stays this moment."""
|
|
pending = self._obs.close_turn(status)
|
|
if pending is None:
|
|
return
|
|
running = [t for t in self._shadow_tasks if not t.done()]
|
|
if not running:
|
|
self._obs.emit_turn_ended(pending)
|
|
return
|
|
|
|
async def after_shadows() -> None:
|
|
try:
|
|
await asyncio.wait_for(asyncio.gather(*running, return_exceptions=True), 30)
|
|
except Exception: # noqa: BLE001 - a slow shadow check must not lose the turn's end
|
|
pass
|
|
self._obs.emit_turn_ended(pending)
|
|
|
|
task = asyncio.ensure_future(after_shadows())
|
|
self._turn_end_tasks.add(task)
|
|
task.add_done_callback(self._turn_end_tasks.discard)
|
|
|
|
def _risk_class(self, tool_name: str) -> Optional[str]:
|
|
try:
|
|
spec = self.registry.get(tool_name)
|
|
return _classify_risk(
|
|
tool_name, spec.metadata if spec else None, self.permissions.risk_overrides
|
|
).value
|
|
except Exception: # noqa: BLE001 - a fact, never a reason to fail a call
|
|
return None
|
|
|
|
def _add_message(self, message: dict[str, Any], *, at: Optional[int] = None) -> None:
|
|
"""Append (or, with `at`, insert) one message into the history, stamping its `mid`.
|
|
|
|
`mid` is a ULID that never changes, so a recorded step can point at the message it
|
|
produced even after a stub is inserted mid-history or the file is rewritten
|
|
(observability E21). It is a sidecar like `ts`: stripped before any provider sees it.
|
|
"""
|
|
message.setdefault("mid", new_ulid())
|
|
if at is None:
|
|
self.messages.append(message)
|
|
else:
|
|
self.messages.insert(at, message)
|
|
obs = getattr(self, "_obs", None)
|
|
if obs is not None:
|
|
obs.note_message(message)
|
|
|
|
def _timed_result(self, tool_call, result):
|
|
message = _tool_result_message(tool_call, result)
|
|
if tool_call.id in self._tool_timings:
|
|
message["timing"] = self._tool_timings.pop(tool_call.id)
|
|
return message
|
|
|
|
def queue_steering(
|
|
self, text: str, source: Optional[dict[str, Any]] = None,
|
|
activity: Optional[dict[str, Any]] = None,
|
|
) -> None:
|
|
self._steering.append((text, source, activity))
|
|
|
|
# -- main loop --------------------------------------------------------------
|
|
@_records_turn("run")
|
|
@_summarizes_turn
|
|
async def run(
|
|
self,
|
|
user_input: "str | list",
|
|
*,
|
|
source: Optional[dict[str, Any]] = None,
|
|
display: Optional[str] = None,
|
|
activity: Optional[dict[str, Any]] = None,
|
|
) -> AsyncIterator[Event]:
|
|
# `user_input` is a string, or OpenAI content-parts (text + image_url) for attachments.
|
|
# `source` (a MessageSource dict) is a display-only sidecar for connector messages: it
|
|
# rides on the persisted user message + the TURN_START event, but is stripped before the
|
|
# message reaches a provider (see `_outbound_messages`). `content` stays the framed text.
|
|
# `display` is the same split for force-run skills (SKILLS-SPEC §4.1 #3): the user's
|
|
# literal "/skill …" line for the transcript, while `content` carries the model-facing
|
|
# framing. `ts` (unix seconds, stamped on every appended message) is the same kind of
|
|
# sidecar.
|
|
# A restart can interrupt a turn between a tool_use and its result (a
|
|
# parked approval is the common case). The provider hard-rejects such
|
|
# a history, so a NEW turn must first close any orphaned calls with an
|
|
# honest stub — otherwise one interruption poisons the session forever.
|
|
self._repair_dangling_tool_calls()
|
|
message: dict[str, Any] = {
|
|
"role": "user",
|
|
"content": user_input,
|
|
"ts": time.time(),
|
|
}
|
|
if source is not None:
|
|
message["source"] = source
|
|
if display is not None:
|
|
message["_display"] = display
|
|
if activity:
|
|
message["_activity"] = activity
|
|
self._add_message(message)
|
|
self._reset_cancel()
|
|
if not self._dangerous_warned:
|
|
if self.permissions.mode is Mode.DANGEROUSLY_BYPASS_APPROVALS:
|
|
# Once per engine: the name is the warning, and the transcript keeps it.
|
|
self._append_notice("dangerous_mode", _attendance.DANGEROUS_MODE_WARNING)
|
|
self._dangerous_warned = True
|
|
if self.session_facts is not None:
|
|
self.session_facts.begin_turn()
|
|
# §8.4 retry guard resets per user turn: two reviewer denials in one turn route
|
|
# everything else that turn to the human. A fresh user message is a fresh brief.
|
|
self._reviewer_denials = 0
|
|
self._reviewer_verdicts.clear()
|
|
self._reviewer_input_snapshots.clear()
|
|
self._authorized_delegates.clear()
|
|
data: dict[str, Any] = {"input": user_input}
|
|
if source is not None:
|
|
data["source"] = source
|
|
if display is not None:
|
|
data["display"] = display
|
|
# OPE-136 run grants: a fresh run starts with a clean slate (belt — the
|
|
# finally below is the braces; an abandoned generator must not leak a
|
|
# previous answer's "Allow for this request" into this one).
|
|
self.permissions.clear_run_allowances()
|
|
self._approved_plan = []
|
|
yield Event(EventType.TURN_START, data)
|
|
try:
|
|
async for event in self._start_sandbox():
|
|
yield event
|
|
if event.type is EventType.ERROR:
|
|
return
|
|
async for event in self._loop():
|
|
yield event
|
|
finally:
|
|
# The run boundary IS the grant's expiry — normal finish, Stop, and
|
|
# generator teardown (disconnect) all land here.
|
|
self.permissions.clear_run_allowances()
|
|
self._approved_plan = []
|
|
|
|
def switch_model(self, model: str) -> Optional[str]:
|
|
"""Rebind the session's model mid-conversation (roadmap item 3). History is
|
|
canonical OpenAI shape and every provider converts per call, so the switch is just
|
|
the field write — plus a persisted notice marking WHERE it happened, with a
|
|
degradation warning when history carries images the new model can't see (those are
|
|
sent as placeholders — see `_outbound_messages`). Returns the notice text, or None
|
|
when nothing changed (same model, or first bind on a fresh session)."""
|
|
if not model or model == self.model:
|
|
return None
|
|
had_history = any(m.get("role") != "system" for m in self.messages)
|
|
self.model = model
|
|
# The reviewer judges with the session's own model (§1.5: "if it's trusted to
|
|
# drive the agent, it's strong enough to review it"). Bound once at session build,
|
|
# it would otherwise keep the OLD model for the rest of the session after a
|
|
# switch — silently reviewing with a model the user moved away from. A
|
|
# decision-model reviewer (OpenAI Decisions, Jev) judges with its own service's
|
|
# model, which a session switch must not change (its `model` is read-only).
|
|
if self.reviewer is not None:
|
|
from .decision_reviewer import DecisionReviewer
|
|
|
|
if not isinstance(self.reviewer, DecisionReviewer):
|
|
self.reviewer.model = model
|
|
if not had_history:
|
|
return None
|
|
from .providers.matrix import model_labels
|
|
|
|
text = f"Model switched to {model_labels().get(model, model)}"
|
|
try:
|
|
caps = self.provider.capabilities(model)
|
|
except Exception:
|
|
caps = None
|
|
if (
|
|
caps is not None
|
|
and not getattr(caps, "vision", False)
|
|
and self._history_has_images()
|
|
):
|
|
text += " — earlier images can't be read by this model"
|
|
self._append_notice("model_switch", text)
|
|
return text
|
|
|
|
def _history_has_images(self) -> bool:
|
|
return any(
|
|
isinstance(p, dict) and p.get("type") == "image_url"
|
|
for msg in self.messages
|
|
if isinstance(msg.get("content"), list)
|
|
for p in msg["content"]
|
|
)
|
|
|
|
def _tail_is_retriable_error(self) -> bool:
|
|
"""True when the history tail is an error notice, looking through any model_switch
|
|
notices appended after it (a switch must not consume the retry)."""
|
|
for message in reversed(self.messages):
|
|
if message.get("role") != "notice":
|
|
return False
|
|
if message.get("kind") == "model_switch":
|
|
continue
|
|
return message.get("kind") == "error"
|
|
return False
|
|
|
|
def _append_notice(self, kind: str, text: Optional[str] = None, **fields: Any) -> None:
|
|
"""Persist a turn-ending marker (error/interrupted) as a display-only `notice`
|
|
message: it survives reload like the transcript does, but `_outbound_messages`
|
|
drops the role so no provider ever sees it. Extra `fields` (e.g. the failing
|
|
MCP server's name) persist on the message for structured rendering."""
|
|
notice: dict[str, Any] = {"role": "notice", "kind": kind, "ts": time.time()}
|
|
if text:
|
|
notice["text"] = text
|
|
notice.update({k: v for k, v in fields.items() if v is not None})
|
|
self._add_message(notice)
|
|
if kind in ("interrupted", "error", "reviewer_paused"):
|
|
# A zero-length marker on the timeline (observability §5.8).
|
|
self._obs.instant_step(kind="notice", name=kind, status="ok", attrs={})
|
|
|
|
@_records_turn("retry")
|
|
@_summarizes_turn
|
|
async def retry(self) -> AsyncIterator[Event]:
|
|
"""Re-run the model loop after a provider error — no new user message; the failed
|
|
turn's input is already the tail of history. Guarded on the tail being an error
|
|
notice so a stray retry frame can't re-answer a completed turn. Trailing
|
|
model_switch notices don't break the guard — switching models and THEN retrying
|
|
is the intended recovery path (owner-hit 2026-07-23)."""
|
|
if not self._tail_is_retriable_error():
|
|
return
|
|
self._reset_cancel()
|
|
yield Event(EventType.TURN_START, {"input": ""})
|
|
async for event in self._start_sandbox():
|
|
yield event
|
|
if event.type is EventType.ERROR:
|
|
return
|
|
async for event in self._loop():
|
|
yield event
|
|
|
|
async def _start_sandbox(self) -> AsyncIterator[Event]:
|
|
"""The session's sandbox is made by its first turn, not when the session opens
|
|
(RunnerWorkspace(start=False)). Off the event loop: an OpenShell container takes
|
|
seconds. A sandbox that cannot be made ends the turn with the reason, and Retry
|
|
tries again."""
|
|
workspace = getattr(self, "sandbox_workspace", None)
|
|
start = getattr(workspace, "ensure_started", None)
|
|
if start is None or getattr(workspace, "started", True):
|
|
return
|
|
provider = str(getattr(getattr(workspace, "provider", None), "name", "") or "sandbox")
|
|
yield Event(EventType.SANDBOX_PREPARING, {"provider": provider})
|
|
try:
|
|
if "trigger" in inspect.signature(start).parameters:
|
|
await asyncio.to_thread(start, "turn_start")
|
|
else:
|
|
await asyncio.to_thread(start)
|
|
except Exception as exc:
|
|
text = f"The {provider} sandbox could not start: {exc}"
|
|
self._append_notice("error", text)
|
|
yield Event(EventType.ERROR, {"error": text, "error_type": type(exc).__name__})
|
|
return
|
|
info = workspace.describe()
|
|
self._note_stamp() # the runner's version is known only now (V2-28)
|
|
yield Event(EventType.SANDBOX_READY, {k: info.get(k) for k in ("provider", "enforcement", "reason", "sandbox") if info.get(k) is not None})
|
|
|
|
def on_sandbox(self, event: str, data: dict[str, Any]) -> None:
|
|
"""What the sandbox workspace tells the recording (observability OB-13): its start as a
|
|
`sandbox` setup step with its stages, and a restart as a `sandbox_restarted` notice.
|
|
Called from the thread that starts or restarts the sandbox; outside a turn nothing is
|
|
written."""
|
|
obs = self._obs
|
|
if not obs.enabled or not obs.in_turn:
|
|
return
|
|
provider = str(getattr(getattr(getattr(self, "sandbox_workspace", None), "provider", None), "name", "") or "sandbox")
|
|
if event == "setup_started":
|
|
self._sandbox_setup_step = obs.start_step(
|
|
kind="sandbox", name="setup",
|
|
attrs={"provider": provider, "stages": [], "failed_stage": None, "trigger": data.get("trigger") or "turn_start"},
|
|
)
|
|
elif event == "setup_ended":
|
|
step_id, self._sandbox_setup_step = getattr(self, "_sandbox_setup_step", None), None
|
|
log = data.get("log")
|
|
if step_id is None or log is None:
|
|
return
|
|
failed = data.get("error") is not None
|
|
obs.end_step(step_id, status="error" if failed else "ok",
|
|
attrs=log.attrs(provider, data.get("trigger") or "turn_start"))
|
|
if not failed and data.get("trigger") == "first_tool":
|
|
self._note_stamp() # the runner's version, as after a start at the turn's start
|
|
elif event == "restarted":
|
|
obs.instant_step(kind="notice", name="sandbox_restarted", status="ok",
|
|
attrs={"provider": provider, "reason": data.get("reason"), "how": data.get("how")})
|
|
|
|
@_records_turn("resume")
|
|
@_summarizes_turn
|
|
async def resume(self) -> AsyncIterator[Event]:
|
|
"""Continue a turn that was suspended at a prompt and persisted — durable resume after a
|
|
restart (or engine eviction). Re-process the trailing assistant message's UNANSWERED
|
|
tool-calls (the prompt callbacks find the already-resolved Inbox item and return without
|
|
re-prompting; answered calls are skipped, so nothing double-executes), then run the model
|
|
loop to finish the turn."""
|
|
pending = self._unanswered_trailing_tool_calls()
|
|
if not pending:
|
|
return
|
|
self._reset_cancel()
|
|
self._yield_for_wake = False
|
|
yield Event(EventType.TURN_START, {"input": "(resumed)"})
|
|
async for event in self._handle_tool_calls(pending):
|
|
yield event
|
|
yield Event(EventType.ITERATION_END, {"iteration": 0})
|
|
if not self._cancel.is_set():
|
|
if self._yield_for_wake:
|
|
yield Event(EventType.TURN_END, {"status": "sleeping", "iterations": 0})
|
|
return
|
|
async for event in self._loop():
|
|
yield event
|
|
|
|
def _repair_dangling_tool_calls(self) -> None:
|
|
"""Close every orphaned tool_use in history with a stub tool result.
|
|
|
|
An interrupted turn (restart mid-approval, crash between call and
|
|
result) leaves an assistant message whose tool_calls have no results;
|
|
providers reject the whole conversation for it. Stubs are inserted
|
|
IMMEDIATELY after the offending assistant message, keep the ids, and
|
|
say honestly what happened — the model may re-issue the call."""
|
|
answered = {
|
|
m.get("tool_call_id") for m in self.messages if m.get("role") == "tool"
|
|
}
|
|
i = 0
|
|
while i < len(self.messages):
|
|
msg = self.messages[i]
|
|
stubs = []
|
|
if msg.get("role") == "assistant" and msg.get("tool_calls"):
|
|
for tc in msg["tool_calls"]:
|
|
if tc.get("id") and tc["id"] not in answered:
|
|
stubs.append(
|
|
{
|
|
"role": "tool",
|
|
"tool_call_id": tc["id"],
|
|
"content": json.dumps(
|
|
{
|
|
"error": "tool call interrupted — no result "
|
|
"was recorded (the session was restarted). "
|
|
"Re-issue the call if it is still needed."
|
|
}
|
|
),
|
|
"ts": time.time(),
|
|
}
|
|
)
|
|
for offset, stub in enumerate(stubs, start=1):
|
|
self._add_message(stub, at=i + offset)
|
|
i += 1 + len(stubs)
|
|
|
|
def _unanswered_trailing_tool_calls(self) -> list[ToolCall]:
|
|
"""The tool-calls of the last assistant message that don't yet have a tool result —
|
|
i.e. the prompt we suspended on (+ any after it). Reconstructed from the persisted thread.
|
|
"""
|
|
answered = {
|
|
m.get("tool_call_id") for m in self.messages if m.get("role") == "tool"
|
|
}
|
|
for msg in reversed(self.messages):
|
|
if msg.get("role") == "user":
|
|
return []
|
|
if msg.get("role") == "assistant" and msg.get("tool_calls"):
|
|
out: list[ToolCall] = []
|
|
for tc in msg["tool_calls"]:
|
|
if tc.get("id") in answered:
|
|
continue
|
|
fn = tc.get("function") or {}
|
|
try:
|
|
args = json.loads(fn.get("arguments") or "{}")
|
|
except Exception:
|
|
args = {}
|
|
out.append(
|
|
ToolCall(id=tc.get("id"), name=fn.get("name"), arguments=args)
|
|
)
|
|
return out
|
|
return []
|
|
|
|
async def _loop(self) -> AsyncIterator[Event]:
|
|
self._yield_for_wake = False
|
|
iterations = 0
|
|
self._continuations = 0
|
|
while True:
|
|
if iterations >= self.max_iterations:
|
|
yield Event(
|
|
EventType.TURN_END,
|
|
{"status": "max_iterations_exceeded", "iterations": iterations},
|
|
)
|
|
return
|
|
iterations += 1
|
|
|
|
# Auto-compaction checkpoint (OPE-27): between tool turns and before a new
|
|
# turn's first call. Deliberately no "wrap up" warning to the model. The
|
|
# COMPACTING signal precedes the (multi-second) summarizer call so surfaces
|
|
# can show progress instead of a silent stall.
|
|
notice = None
|
|
if self._compaction_due():
|
|
yield Event(EventType.COMPACTING, {})
|
|
notice = await self._compact_now()
|
|
if notice:
|
|
record = self._compaction_record()
|
|
self._append_notice("compacted", notice, compaction=record)
|
|
yield Event(EventType.COMPACTED, {"text": notice, "compaction": record})
|
|
|
|
turn: Optional[AssistantTurn] = None
|
|
streamed: list[str] = []
|
|
streamed_reasoning: list[str] = []
|
|
|
|
def _partial_turn() -> AssistantTurn:
|
|
# What the user watched arrive — text and thinking, NO tool calls (any
|
|
# half-formed calls would either orphan or execute against the stop).
|
|
return AssistantTurn(
|
|
text="".join(streamed) or None,
|
|
reasoning="".join(streamed_reasoning) or None,
|
|
)
|
|
|
|
model_started, model_clock = time.time(), time.perf_counter()
|
|
try:
|
|
async for chunk in self._astream():
|
|
if chunk.reasoning_delta:
|
|
streamed_reasoning.append(chunk.reasoning_delta)
|
|
yield Event(
|
|
EventType.REASONING_DELTA, {"text": chunk.reasoning_delta}
|
|
)
|
|
if chunk.text_delta:
|
|
streamed.append(chunk.text_delta)
|
|
yield Event(
|
|
EventType.ASSISTANT_DELTA, {"text": chunk.text_delta}
|
|
)
|
|
if chunk.turn is not None:
|
|
turn = chunk.turn
|
|
except Exception as exc: # provider failure
|
|
# A raw context-overflow 400 (compaction mispredicted, e.g. the estimate
|
|
# path) routes into the compaction policy instead of surfacing. The retry
|
|
# is progress-guarded: each pass moves the boundary forward or gives up,
|
|
# so a model that keeps overflowing still terminates in the error path.
|
|
if _compaction.is_context_overflow(exc) and not self._cancel.is_set():
|
|
yield Event(EventType.COMPACTING, {})
|
|
notice = await self._compact_now(force=True)
|
|
if notice:
|
|
record = self._compaction_record()
|
|
self._append_notice("compacted", notice, compaction=record)
|
|
yield Event(
|
|
EventType.COMPACTED, {"text": notice, "compaction": record}
|
|
)
|
|
continue
|
|
# Same contract as the stop path below: the partial the user watched
|
|
# arrive survives the failure.
|
|
if streamed or streamed_reasoning:
|
|
self._add_message(_assistant_message(_partial_turn()))
|
|
friendly = friendly_model_error(self.model, exc)
|
|
payload = {
|
|
"error": friendly or str(exc),
|
|
"error_type": type(exc).__name__,
|
|
}
|
|
if friendly:
|
|
payload["raw"] = str(exc)
|
|
self._append_notice("error", friendly or str(exc))
|
|
yield Event(EventType.ERROR, payload)
|
|
return
|
|
if self._cancel.is_set() and turn is None:
|
|
# Stopped mid-stream: persist exactly what the user watched arrive.
|
|
if streamed or streamed_reasoning:
|
|
self._add_message(_assistant_message(_partial_turn()))
|
|
self._append_notice("interrupted")
|
|
yield Event(EventType.INTERRUPTED, {"iterations": iterations})
|
|
return
|
|
if turn is None:
|
|
turn = AssistantTurn()
|
|
if turn.usage is not None:
|
|
# The trigger signal: the prompt-side total that actually occupied the
|
|
# window on this round-trip (estimate fallback when never reported).
|
|
self._last_context_tokens = turn.usage.context_tokens
|
|
|
|
self._turn_truncated = turn.finish_reason == "length"
|
|
if not self._turn_truncated:
|
|
self._continuations = 0
|
|
_sanitize_mangled_calls(turn)
|
|
if not turn.tool_calls:
|
|
# One stray `<tool_call>` at the very end of an otherwise finished
|
|
# answer is noise, not a call: drop it and keep the answer.
|
|
cleaned, dangling = strip_dangling_tool_tag(turn.text)
|
|
if dangling and not looks_like_unparsed_tool_call(
|
|
cleaned, self.registry.schemas() or None
|
|
):
|
|
turn.text = cleaned
|
|
self._add_message(
|
|
_assistant_message(
|
|
turn,
|
|
model=self.model,
|
|
effort_setting=self.model_settings.get("reasoning_effort"),
|
|
)
|
|
)
|
|
self.messages[-1]["timing"] = {"model_started": model_started, "model_ms": (time.perf_counter() - model_clock) * 1000}
|
|
payload: dict[str, Any] = {
|
|
"text": turn.text,
|
|
"tool_calls": [tc.name for tc in turn.tool_calls],
|
|
}
|
|
if turn.reasoning:
|
|
payload["reasoning"] = turn.reasoning
|
|
if turn.usage is not None:
|
|
payload["usage"] = {"model": self.model, **turn.usage.as_dict()}
|
|
self._audit_usage(turn.usage)
|
|
if turn.finish_reason:
|
|
# How the reply ended (OPE-173): `stop` / `tool_calls` / `length`.
|
|
payload["finish_reason"] = turn.finish_reason
|
|
if turn.output_limit:
|
|
# The output ceiling the provider sent (OPE-177).
|
|
payload["max_output_tokens"] = turn.output_limit
|
|
effort_record = _effort_record(turn, self.model_settings.get("reasoning_effort"))
|
|
if effort_record:
|
|
payload["reasoning_effort"] = effort_record
|
|
if turn.served_by:
|
|
payload["served_by"] = turn.served_by
|
|
# Context panel (FB-015): the window occupancy after this reply landed.
|
|
payload["context"] = self.context_snapshot()
|
|
yield Event(EventType.ASSISTANT_MESSAGE, payload)
|
|
|
|
if not turn.tool_calls:
|
|
if self._steering:
|
|
self._inject_steering()
|
|
continue
|
|
if self._turn_truncated:
|
|
# OPE-171: cut off at the output limit with nothing actionable. The
|
|
# reply just persisted is marked for stub replay (see
|
|
# `_outbound_messages`); the model is asked to act, and the turn
|
|
# goes round again — unless it has already happened too often.
|
|
cut = self.messages[-1]
|
|
if cut.get("role") == "assistant":
|
|
cut["replay"] = "stub"
|
|
if self._continuations < MAX_TRUNCATION_CONTINUATIONS:
|
|
self._continuations += 1
|
|
self._add_message(
|
|
{
|
|
"role": "user",
|
|
"content": TRUNCATION_NUDGE,
|
|
"ts": time.time(),
|
|
"_display": {
|
|
"kind": "continuation",
|
|
"reason": "length",
|
|
"attempt": self._continuations,
|
|
},
|
|
}
|
|
)
|
|
yield Event(
|
|
EventType.CONTINUATION,
|
|
{
|
|
"reason": "length",
|
|
"attempt": self._continuations,
|
|
"remaining": MAX_TRUNCATION_CONTINUATIONS
|
|
- self._continuations,
|
|
"iterations": iterations,
|
|
"text": (
|
|
"Reply cut off at the output-token limit with no "
|
|
f"action; asking the model to continue "
|
|
f"({self._continuations} of "
|
|
f"{MAX_TRUNCATION_CONTINUATIONS})."
|
|
),
|
|
},
|
|
)
|
|
continue
|
|
text = (
|
|
f"{self.model}'s reply was cut off at the output-token limit with "
|
|
f"no action {self._continuations + 1} times in a row, so the turn "
|
|
"was stopped rather than reported as complete. Raise "
|
|
"max_output_tokens, lower the reasoning effort, or retry."
|
|
)
|
|
self._append_notice(
|
|
"truncated", text, continuations=self._continuations
|
|
)
|
|
yield Event(
|
|
EventType.TURN_END,
|
|
{
|
|
"status": "truncated",
|
|
"iterations": iterations,
|
|
"continuations": self._continuations,
|
|
"text": text,
|
|
},
|
|
)
|
|
return
|
|
# The model tried to call a tool and the syntax never parsed — salvage already
|
|
# had its go. Ending as "completed" here would present a half-written call as
|
|
# the answer, which is indistinguishable from the model deciding it was done;
|
|
# the user just sees narration trailing off into stray tags. Fail loudly
|
|
# instead, on the error path so the GUI offers Retry — this is drift, not a
|
|
# deterministic failure, so retrying the same model usually works.
|
|
if looks_like_unparsed_tool_call(turn.text, self.registry.schemas() or None):
|
|
message = (
|
|
f"{self.model} replied with a tool call this endpoint couldn't parse, "
|
|
"so the turn was stopped rather than answered from a partial call. "
|
|
"Retry, or switch to a larger model — smaller local models drift off "
|
|
"the tool-call format, especially with many tools in play."
|
|
)
|
|
self._append_notice("error", message)
|
|
yield Event(
|
|
EventType.ERROR,
|
|
{"error": message, "error_type": "UnparsedToolCall"},
|
|
)
|
|
return
|
|
yield Event(
|
|
EventType.TURN_END,
|
|
{"status": "completed", "iterations": iterations},
|
|
)
|
|
return
|
|
|
|
async for event in self._handle_tool_calls(turn.tool_calls):
|
|
yield event
|
|
|
|
yield Event(EventType.ITERATION_END, {"iteration": iterations})
|
|
|
|
if self._cancel.is_set():
|
|
self._append_notice("interrupted")
|
|
yield Event(EventType.INTERRUPTED, {"iterations": iterations})
|
|
return
|
|
if self._yield_for_wake and not self._steering:
|
|
yield Event(EventType.TURN_END, {"status": "sleeping", "iterations": iterations})
|
|
return
|
|
if self._steering:
|
|
self._inject_steering()
|
|
self._yield_for_wake = False
|
|
|
|
# -- auto-compaction (OPE-27) ------------------------------------------------
|
|
def _compaction_config(self) -> dict[str, Any]:
|
|
from . import model_config
|
|
|
|
cfg = dict(self.compaction_settings() or {}) if self.compaction_settings else {}
|
|
# The user's per-model settings (model_config.py): a saved window stands in for
|
|
# a model the matrix does not list; a saved threshold overrides the machine's.
|
|
saved_window = model_config.context_size_for(self.model)
|
|
saved_pct = model_config.compaction_threshold_for(self.model)
|
|
if saved_pct:
|
|
cfg["threshold_pct"] = saved_pct
|
|
if not cfg.get("context_window"):
|
|
from .providers.matrix import model_context_windows
|
|
|
|
cfg["context_window"] = model_context_windows().get(self.model) or saved_window
|
|
if not cfg["context_window"]:
|
|
# Ollama's window is the num_ctx we send (providers/ollama_context.py),
|
|
# not the 128k guess — compact before that window context-shifts.
|
|
from .providers.local_server import context_window_for as _server_window
|
|
from .providers.ollama_context import context_window_for
|
|
|
|
cfg["context_window"] = context_window_for(self.model) or _server_window(self.model)
|
|
if not cfg["context_window"] and not self._warned_context_fallback:
|
|
# OPE-170: an unlisted model compacts on the 128k guess, which for a
|
|
# 1M-window model means compacting at a tenth of the window and
|
|
# rebuilding the prompt cache each time. Say so once per engine.
|
|
self._warned_context_fallback = True
|
|
logger.warning(
|
|
"model %s has no context window in the model matrix; assuming "
|
|
"%d tokens (compaction at %d). Add a matrix row or set "
|
|
"context_window in the compaction settings.",
|
|
self.model,
|
|
_compaction.DEFAULT_CONTEXT_WINDOW,
|
|
_compaction.trigger_tokens(None),
|
|
)
|
|
cfg.setdefault("threshold_pct", _compaction.DEFAULT_THRESHOLD_PCT)
|
|
cfg.setdefault("cap_tokens", _compaction.DEFAULT_CAP_TOKENS)
|
|
cfg.setdefault("summary_max_tokens", _compaction.SUMMARY_MAX_TOKENS)
|
|
return cfg
|
|
|
|
def _compaction_due(self) -> bool:
|
|
"""The trigger check alone — cheap and side-effect free, so the loop can emit
|
|
the COMPACTING signal before committing to the (slow) summarizer call."""
|
|
cfg = self._compaction_config()
|
|
if cfg.get("enabled") is False:
|
|
return False
|
|
signal = self._last_context_tokens or _compaction.estimate_tokens(
|
|
self._outbound_messages()
|
|
)
|
|
return _compaction.should_compact(
|
|
signal,
|
|
cfg.get("context_window"),
|
|
threshold_pct=float(cfg["threshold_pct"]),
|
|
cap_tokens=int(cfg["cap_tokens"]),
|
|
)
|
|
|
|
def _compaction_record(self) -> Optional[dict[str, Any]]:
|
|
"""The compaction that just happened, as persisted on the `compacted` notice and
|
|
carried on the COMPACTED event (OPE-170 problem 2): summary text, working state,
|
|
the boundary into the canonical transcript, the summarizer model, and whether it
|
|
was the no-summary trim. Without it a saved session only showed THAT compaction
|
|
happened, not what was kept — the app's session record keeps only the latest
|
|
state, and exported trajectories / run records had nothing at all."""
|
|
state = self.compaction_state
|
|
return state.as_dict() if state is not None else None
|
|
|
|
def context_snapshot(self) -> dict[str, Any]:
|
|
"""What occupies the model's window right now (FB-015), for the GUI's Context
|
|
panel: `used` is the provider-reported prompt-side total from the latest round
|
|
trip when one exists (estimate fallback otherwise, flagged `estimated`); the
|
|
category split — system prompt / tool schemas / conversation — is always the
|
|
chars/4 estimate, so surfaces must present it as proportion, not ledger."""
|
|
msgs = self._outbound_messages()
|
|
system = _compaction.estimate_tokens(
|
|
[m for m in msgs if m.get("role") == "system"]
|
|
)
|
|
convo = _compaction.estimate_tokens(
|
|
[m for m in msgs if m.get("role") != "system"]
|
|
)
|
|
schemas = self.registry.schemas() or []
|
|
tools = (
|
|
len(json.dumps(schemas, ensure_ascii=False)) // 4 if schemas else 0
|
|
)
|
|
reported = int(self._last_context_tokens or 0)
|
|
snapshot: dict[str, Any] = {
|
|
"window": self._compaction_config().get("context_window"),
|
|
"used": reported or (system + tools + convo),
|
|
"estimated": not reported,
|
|
"breakdown": {"system": system, "tools": tools, "messages": convo},
|
|
}
|
|
state = self.compaction_state
|
|
if state is not None:
|
|
# Duck-typed on purpose: tests and embedders stub compaction_state with
|
|
# partial objects; the snapshot must degrade, never raise.
|
|
snapshot["compaction"] = {
|
|
"created_at": getattr(state, "created_at", None),
|
|
"messages": getattr(state, "boundary_index", None),
|
|
"trimmed": bool(getattr(state, "trimmed", False)),
|
|
}
|
|
return snapshot
|
|
|
|
async def _compact_now(self, *, force: bool = False) -> Optional[str]:
|
|
"""Run the compaction policy. Callers gate on `_compaction_due()` (or `force`,
|
|
the overflow path). Returns the user-facing notice text when the outbound view
|
|
changed, else None. Failure policy per spec: retry once (both modes); attended →
|
|
Retry / Trim prompt; unattended → auto-trim and continue (never park a run on
|
|
bookkeeping)."""
|
|
cfg = self._compaction_config()
|
|
pct = float(cfg["threshold_pct"])
|
|
cap = int(cfg["cap_tokens"])
|
|
window = cfg.get("context_window")
|
|
trigger = _compaction.trigger_tokens(window, threshold_pct=pct, cap_tokens=cap)
|
|
keep = int(_compaction.KEEP_RECENT_FRACTION * trigger)
|
|
# OPE-189: both budgets scale with the trigger, so lowering it to save tokens can't
|
|
# be undone by a block that keeps spending the freed space.
|
|
user_budget = _compaction.user_message_budget(trigger)
|
|
summary_max = int(
|
|
cfg.get("summary_max_tokens") or _compaction.SUMMARY_MAX_TOKENS
|
|
)
|
|
model = str(cfg.get("model") or "") or self.model
|
|
# Observability E4: a summary step, written only if a summary or trim happens (§5.7);
|
|
# its model calls are nested under it.
|
|
summary_step = self._obs.reserve_step()
|
|
tokens_before = self._last_context_tokens
|
|
try:
|
|
notice = await self._compact_with(summary_step, force=force, cfg=cfg, trigger=trigger,
|
|
keep=keep, user_budget=user_budget,
|
|
summary_max=summary_max, model=model)
|
|
except BaseException:
|
|
self._obs.drop_reserved(summary_step)
|
|
raise
|
|
children = self._obs.model_children(summary_step)
|
|
if notice is not None or children:
|
|
trimmed = notice is not None and notice.startswith("Context trimmed")
|
|
self._obs.finish_reserved(
|
|
summary_step, kind="summary", name="trim" if trimmed else "summary",
|
|
status="ok" if notice is not None else "error",
|
|
attrs={"reason": "overflow" if force else "threshold", "tokens_before": tokens_before,
|
|
"model_step_id": None if trimmed or not children else children[-1]},
|
|
wait_for_tokens_after=notice is not None,
|
|
)
|
|
else:
|
|
self._obs.drop_reserved(summary_step)
|
|
return notice
|
|
|
|
async def _compact_with(self, summary_step: Optional[str], *, force: bool, cfg: dict[str, Any],
|
|
trigger: int, keep: int, user_budget: int, summary_max: int,
|
|
model: str) -> Optional[str]:
|
|
def _build() -> Optional[_compaction.CompactionState]:
|
|
return _compaction.build_state(
|
|
self.messages,
|
|
provider=_tag_provider(self.provider, purpose="summary", parent=summary_step),
|
|
model=model,
|
|
keep_tokens=keep,
|
|
prior=self.compaction_state,
|
|
summary_max_tokens=summary_max,
|
|
user_budget_tokens=user_budget,
|
|
)
|
|
|
|
state: Optional[_compaction.CompactionState] = None
|
|
failed = False
|
|
for _attempt in range(2): # first try + the unconditional single retry
|
|
try:
|
|
state = await asyncio.to_thread(_build)
|
|
failed = False
|
|
break
|
|
except Exception:
|
|
failed = True
|
|
if failed and self.question_asker is not None and self.is_attended and self.is_attended():
|
|
while True:
|
|
# The "Retry or trim?" question is a wait, nested under the summary (E20).
|
|
wait_step = self._obs.start_step(
|
|
kind="wait", name="question", parent_step_id=summary_step,
|
|
attrs={"for_call_id": None, "kind": "question", "attended": True, "where": "session"},
|
|
)
|
|
answer = await self._interruptible(
|
|
self.question_asker(
|
|
{
|
|
"question": (
|
|
"Context compaction failed — the summarizer couldn't "
|
|
"condense this session's history. How should I proceed?"
|
|
),
|
|
"options": ["Retry", "Trim oldest 10%"],
|
|
"allow_text": False,
|
|
"header": "Compaction",
|
|
},
|
|
None,
|
|
),
|
|
interrupted=None,
|
|
)
|
|
self._obs.end_step(wait_step, attrs={"outcome": "answered" if answer else "interrupted"})
|
|
if not answer or answer.get("answer") != "Retry":
|
|
break
|
|
try:
|
|
state = await asyncio.to_thread(_build)
|
|
failed = False
|
|
break
|
|
except Exception:
|
|
continue
|
|
if state is not None:
|
|
# OPE-235: the summarizer read every message it summarized, so outside content
|
|
# there may survive in the summary; and the transcript below holds it verbatim.
|
|
state.carries_outside = self._outside_before(state.boundary_index, summarized=True)
|
|
# OPE-186 change 3: keep the compacted turns readable. The verbatim transcript
|
|
# up to the boundary goes to a file next to the spilled tool results, and the
|
|
# compacted block tells the model where it is, so a detail the summary dropped
|
|
# costs one read instead of being lost.
|
|
if self._tool_result_spill_dir is not None:
|
|
try:
|
|
self._tool_result_spill_dir.mkdir(parents=True, exist_ok=True)
|
|
path = (
|
|
self._tool_result_spill_dir
|
|
/ f"compacted-transcript-upto-{state.boundary_index:04d}.md"
|
|
)
|
|
path.write_text(
|
|
_compaction.render_transcript(self.messages, state.boundary_index),
|
|
encoding="utf-8",
|
|
errors="replace",
|
|
)
|
|
state.transcript_path = str(path)
|
|
if any(m.get("_outside") for m in self.messages[: state.boundary_index]):
|
|
self._agent_files.mark_outside(path)
|
|
except OSError:
|
|
pass
|
|
self.compaction_state = state
|
|
self._last_context_tokens = None # stale once the outbound view shrank
|
|
return "Context compacted — earlier turns were summarized"
|
|
if failed or force:
|
|
trimmed = _compaction.trim_state(
|
|
self.messages,
|
|
prior=self.compaction_state,
|
|
user_budget_tokens=user_budget,
|
|
)
|
|
if trimmed is not None:
|
|
# The trim drops its span without summarizing it; only an earlier summary
|
|
# (kept in the block) can still carry outside content.
|
|
trimmed.carries_outside = self._outside_before(trimmed.boundary_index, summarized=False)
|
|
self.compaction_state = trimmed
|
|
self._last_context_tokens = None
|
|
return "Context trimmed — oldest turns dropped (summary unavailable)"
|
|
return None
|
|
|
|
def _outside_before(self, boundary: int, *, summarized: bool) -> bool:
|
|
"""OPE-235: whether the compacted block for a new boundary carries outside content:
|
|
the earlier summary did, or this compaction summarized a message that brought some
|
|
in. Messages only trimmed away leave nothing behind (the block's mechanical parts
|
|
are the agent's own commands and the user's messages)."""
|
|
prior = self.compaction_state
|
|
if prior is not None and prior.carries_outside:
|
|
return True
|
|
if not summarized:
|
|
return False
|
|
start = prior.boundary_index if prior is not None else 0
|
|
return any(m.get("_outside") for m in self.messages[start:boundary])
|
|
|
|
# -- helpers ----------------------------------------------------------------
|
|
async def _astream(self):
|
|
"""Bridge the provider's blocking stream generator to the async loop via a
|
|
thread + queue, so text deltas surface live without blocking the event loop."""
|
|
loop = asyncio.get_running_loop()
|
|
queue: asyncio.Queue = asyncio.Queue()
|
|
tools = self.registry.schemas() or None
|
|
model, messages, settings = (
|
|
self.model,
|
|
self._outbound_messages(),
|
|
self.model_settings,
|
|
)
|
|
self._note_context()
|
|
self._note_stamp()
|
|
provider = self.provider
|
|
|
|
def produce():
|
|
try:
|
|
for chunk in provider.stream(
|
|
model=model, messages=messages, tools=tools, **settings
|
|
):
|
|
# User pressed Stop: drop the stream between chunks (reading the
|
|
# asyncio.Event's flag from a thread is safe; we only read).
|
|
if self._cancel.is_set():
|
|
break
|
|
loop.call_soon_threadsafe(queue.put_nowait, ("chunk", chunk))
|
|
except Exception as exc: # surfaced to the awaiting consumer
|
|
loop.call_soon_threadsafe(queue.put_nowait, ("error", exc))
|
|
finally:
|
|
loop.call_soon_threadsafe(queue.put_nowait, ("done", None))
|
|
|
|
loop.run_in_executor(None, produce)
|
|
while True:
|
|
# Race the queue against Stop so a stalled stream (no chunks arriving —
|
|
# the pre-first-token wait, a wedged connection) can't hold the turn.
|
|
get_task = asyncio.ensure_future(queue.get())
|
|
cancel_task = asyncio.ensure_future(self._cancel.wait())
|
|
done, _ = await asyncio.wait(
|
|
{get_task, cancel_task}, return_when=asyncio.FIRST_COMPLETED
|
|
)
|
|
cancel_task.cancel()
|
|
if get_task not in done:
|
|
get_task.cancel()
|
|
return # interrupted — the producer exits on its own next chunk
|
|
kind, payload = get_task.result()
|
|
if kind == "chunk":
|
|
yield payload
|
|
elif kind == "error":
|
|
raise payload
|
|
else:
|
|
return
|
|
|
|
async def _handle_tool_calls(
|
|
self, tool_calls: list[ToolCall]
|
|
) -> AsyncIterator[Event]:
|
|
"""Run one assistant turn's tool calls: authorize all of them first (sequentially —
|
|
approval prompts are interactive), then execute. Low-risk calls (reads, searches)
|
|
run concurrently; everything else runs one at a time in call order."""
|
|
# Auto-Approve: fire the reviewer for every call that will need it, all at once,
|
|
# BEFORE the sequential authorize loop (spec §8.6 — one action per request, sent
|
|
# concurrently; the wall-clock cost of reviewing N calls is one round-trip, and a
|
|
# verdict physically cannot land on the wrong action). The loop below stays
|
|
# sequential because approval cards are interactive and must reach the human one
|
|
# at a time, in call order.
|
|
self._shell_cleared_in_batch = False
|
|
# Each call's position in the model's list for this reply (canonical step order).
|
|
ids = {tc.id for tc in tool_calls}
|
|
listed = next(
|
|
(m["tool_calls"] for m in reversed(self.messages)
|
|
if m.get("role") == "assistant" and m.get("tool_calls")
|
|
and ids & {tc.get("id") for tc in m["tool_calls"]}),
|
|
[],
|
|
)
|
|
order = [tc.get("id") for tc in listed] or [tc.id for tc in tool_calls]
|
|
self._call_index = {cid: i for i, cid in enumerate(order) if cid}
|
|
await self._preconsult_reviewer(tool_calls)
|
|
cleared: list[ToolCall] = []
|
|
for tool_call in tool_calls:
|
|
if self._cancel.is_set():
|
|
# Stopped: every remaining call still gets an answer (no orphans).
|
|
yield self._interrupted_tool(tool_call)
|
|
continue
|
|
yield Event(
|
|
EventType.TOOL_PROPOSED,
|
|
# The id lets a surface pair this proposal with its own finished event
|
|
# (OPE-238): two same-named calls in one batch must not swap results.
|
|
{"name": tool_call.name, "arguments": tool_call.arguments, "tool_call_id": tool_call.id},
|
|
)
|
|
self._audit(tool_call, stage="proposed")
|
|
if _is_mangled(tool_call):
|
|
# The arguments never parsed as JSON (a `{"_raw": …}` fallback from the
|
|
# provider). Executing would produce a bare parameter error the model
|
|
# misreads — seen in the field as an endless "wrong parameter" retry
|
|
# loop. Answer with the ACTUAL diagnosis instead.
|
|
yield self._mangled_tool(tool_call)
|
|
continue
|
|
# `request_directory` and `propose_plan` are interactive: the user decides
|
|
# out-of-band and that decision IS the consent, so they skip the
|
|
# permission/registry path.
|
|
if tool_call.name == "request_directory":
|
|
async for event in self._handle_directory_request(tool_call):
|
|
yield event
|
|
continue
|
|
if tool_call.name == "request_tool":
|
|
async for event in self._handle_tool_request(tool_call):
|
|
yield event
|
|
continue
|
|
if tool_call.name == "propose_plan":
|
|
async for event in self._handle_plan_proposal(tool_call):
|
|
yield event
|
|
continue
|
|
if tool_call.name == "propose_team":
|
|
async for event in self._handle_team_proposal(tool_call):
|
|
yield event
|
|
continue
|
|
if tool_call.name in ("request_connector", "grant_connector"):
|
|
async for event in self._handle_connector_request(tool_call):
|
|
yield event
|
|
continue
|
|
if tool_call.name == "propose_work_items":
|
|
async for event in self._handle_items_proposal(tool_call):
|
|
yield event
|
|
continue
|
|
if tool_call.name == "ask_user":
|
|
async for event in self._handle_ask_user(tool_call):
|
|
yield event
|
|
continue
|
|
allowed = False
|
|
async for item in self._authorize(tool_call):
|
|
if isinstance(item, Event):
|
|
item.data["tool_call_id"] = tool_call.id
|
|
yield item
|
|
else:
|
|
allowed = item
|
|
if allowed:
|
|
cleared.append(tool_call)
|
|
if tool_call.name == "run_shell":
|
|
self._shell_cleared_in_batch = True
|
|
|
|
concurrent = (
|
|
[tc for tc in cleared if self._parallel_safe(tc)]
|
|
if len(cleared) > 1
|
|
else []
|
|
)
|
|
serial = [tc for tc in cleared if tc not in concurrent]
|
|
|
|
if concurrent:
|
|
for tool_call in concurrent:
|
|
yield Event(EventType.TOOL_STARTED, {"name": tool_call.name, "tool_call_id": tool_call.id})
|
|
self._audit(tool_call, stage="started")
|
|
outcomes = await asyncio.gather(
|
|
*[asyncio.to_thread(self._execute_sync, tc) for tc in concurrent]
|
|
)
|
|
for tool_call, (result, status) in zip(concurrent, outcomes):
|
|
yield self._record_result(tool_call, result, status)
|
|
|
|
for tool_call in serial:
|
|
if self._cancel.is_set():
|
|
yield self._interrupted_tool(tool_call)
|
|
continue
|
|
yield Event(EventType.TOOL_STARTED, {"name": tool_call.name, "tool_call_id": tool_call.id})
|
|
self._audit(tool_call, stage="started")
|
|
result, status = await asyncio.to_thread(self._execute_sync, tool_call)
|
|
yield self._record_result(tool_call, result, status)
|
|
|
|
def _mangled_tool(self, tool_call: ToolCall) -> Event:
|
|
"""Answer a tool call whose arguments never parsed, with the real diagnosis.
|
|
|
|
Two causes, two different cures — and the model can only pick the right one if
|
|
the error says which happened. Truncation (`finish_reason == "length"`) means
|
|
"same content, smaller pieces"; plain bad JSON means "re-send with the declared
|
|
parameters". Either way the raw text is NOT replayed into history: a stored
|
|
`{"_raw": …}` call reads as a worked example and teaches the model to emit
|
|
`_raw` on purpose (observed 2026-08-15), on top of re-sending the junk tokens
|
|
every turn."""
|
|
if self._turn_truncated:
|
|
reason = (
|
|
"your tool-call arguments were cut off by the output-token limit before "
|
|
"they finished streaming — the tool never received them. Produce the same "
|
|
"content in smaller pieces: several calls that each write or append a "
|
|
"section, keeping each call's content well under the limit. Do not retry "
|
|
"the identical oversized call."
|
|
)
|
|
else:
|
|
reason = (
|
|
"your tool-call arguments did not parse as a JSON object, so the tool "
|
|
"received nothing. `_raw` is not a parameter — it is the unparsed text of "
|
|
"the failed call. Re-issue the call using the tool's declared parameters."
|
|
)
|
|
self._add_message(_tool_error_message(tool_call, reason))
|
|
self._audit(tool_call, stage="finished", status="error", reason=reason)
|
|
return Event(
|
|
EventType.TOOL_FINISHED,
|
|
{"name": tool_call.name, "tool_call_id": tool_call.id, "status": "error", "reason": reason},
|
|
)
|
|
|
|
def _interrupted_tool(self, tool_call: ToolCall) -> Event:
|
|
"""The stop-path answer for a call that will not run: a tool-error result in the
|
|
history (hosted chat templates reject orphaned tool_calls, and durable-resume
|
|
would otherwise re-prompt it) + the finished event for the tool card."""
|
|
self._add_message(_tool_error_message(tool_call, "interrupted by user"))
|
|
self._audit(
|
|
tool_call, stage="finished", status="interrupted", reason="user stop"
|
|
)
|
|
return Event(
|
|
EventType.TOOL_FINISHED,
|
|
{"name": tool_call.name, "tool_call_id": tool_call.id, "status": "interrupted", "reason": "stopped"},
|
|
)
|
|
|
|
def _parallel_safe(self, tool_call: ToolCall) -> bool:
|
|
# Only metadata-declared low-risk tools (reads, searches, git queries) run
|
|
# concurrently; writes, shell, and anything unannotated stay strictly ordered.
|
|
spec = self.registry.get(tool_call.name)
|
|
metadata = spec.metadata if spec else None
|
|
return getattr(metadata, "risk_level", "") == "low" and not getattr(
|
|
metadata, "requires_approval", False
|
|
)
|
|
|
|
# -- Auto-Approve reviewer (spec Part 8) ----------------------------------------
|
|
|
|
def _auto_answering(self) -> bool:
|
|
"""Attendance is "auto": nobody will answer, so the engine answers by fixed rule."""
|
|
try:
|
|
return self.attendance is not None and self.attendance() == _attendance.AUTO
|
|
except Exception: # noqa: BLE001 - a broken getter must read as attended
|
|
return False
|
|
|
|
def _nobody_answers_cards(self) -> bool:
|
|
"""No person can answer an approval card: attendance "auto", unless the surface
|
|
says cards still reach a person."""
|
|
if self.cards_reach_person is not None:
|
|
try:
|
|
if self.cards_reach_person():
|
|
return False
|
|
except Exception: # noqa: BLE001 - a broken getter must not open a card nobody sees
|
|
pass
|
|
return self._auto_answering()
|
|
|
|
def _reviewer_active(self) -> bool:
|
|
"""The reviewer is consulted only when ALL of these hold. Any miss ⇒ today's
|
|
behaviour (the card). Someone must be accountable for the asks it cannot clear:
|
|
a person attending (`is_attended` unset counts as NOT attended, so automations —
|
|
which never set it — can never be reviewed; §1.5), or attendance "auto", where
|
|
every escalation is refused by rule instead of parked."""
|
|
from .permissions import Mode
|
|
|
|
return (
|
|
self.reviewer is not None
|
|
and self.reviewer_enabled
|
|
and self.permissions.mode is Mode.AUTO_APPROVE
|
|
and (
|
|
(self.is_attended is not None and self.is_attended())
|
|
or self._auto_answering()
|
|
)
|
|
and self._reviewer_denials < _REVIEWER_TRIP
|
|
)
|
|
|
|
def _user_history(self) -> tuple[str, list[dict[str, Any]]]:
|
|
"""(current request, earlier unsourced user messages), extracted
|
|
mechanically (§8.2). Never agent output, never tool results, never a summary.
|
|
|
|
`ask_user` answers are merged in from `_ask_replies` (captured as they arrived, not
|
|
parsed out of tool envelopes), tagged `is_reply` so `render_history` prints the
|
|
"[reply to a question the agent asked]" marker the §8.3 instructions already know
|
|
how to weigh. A reply is always HISTORY, never the current request — "ok proceed"
|
|
must not become the headline the action is judged against.
|
|
|
|
Attachments collapse to neutral markers via `reviewer_text` (§4.4): the reviewer
|
|
learns a file was attached, never what it says — an attachment body is
|
|
outside-authored text riding a user turn."""
|
|
from .attachments import reviewer_text
|
|
|
|
texts: list[str] = []
|
|
for msg in self.messages:
|
|
if msg.get("role") != "user" or msg.get("source"):
|
|
continue
|
|
text = reviewer_text(msg.get("content"))
|
|
if text:
|
|
texts.append(text)
|
|
if not texts:
|
|
return "", [
|
|
{"text": t, "is_reply": True, **({"question": q} if q else {})}
|
|
for _, t, q in self._ask_replies
|
|
]
|
|
history: list[dict[str, Any]] = []
|
|
for i, t in enumerate(texts[:-1], start=1):
|
|
history.append({"text": t})
|
|
history.extend(
|
|
{"text": r, "is_reply": True, **({"question": q} if q else {})}
|
|
for a, r, q in self._ask_replies
|
|
if a == i
|
|
)
|
|
# Replies captured during the current turn (anchor == len(texts)) — or after an
|
|
# anchor message that was itself empty/skipped — land at the tail, so a same-turn
|
|
# consent is already visible to the reviewer for the very next action.
|
|
history.extend(
|
|
{"text": r, "is_reply": True, **({"question": q} if q else {})}
|
|
for a, r, q in self._ask_replies
|
|
if a >= len(texts)
|
|
)
|
|
return texts[-1], history
|
|
|
|
def _review_inputs(self) -> tuple[str, list[dict[str, Any]], dict]:
|
|
try:
|
|
request, history = self.reviewer_owner_history() if self.reviewer_owner_history else self._user_history()
|
|
context = self.reviewer_context() if self.reviewer_context else {}
|
|
return request, deepcopy(history), deepcopy(context)
|
|
except Exception:
|
|
return "", [], {"context_unavailable": True}
|
|
|
|
def _downloaded_target(self, tool_call: ToolCall) -> Optional[Any]:
|
|
"""A file this call would run that the agent DOWNLOADED this session, or None.
|
|
Fetch-then-execute has no quiet legitimate form, so it reaches a person over both
|
|
the reviewer and any command allowlist (OPE-114 §1)."""
|
|
match = self._agent_files.match(
|
|
tool_call.name, tool_call.arguments, step=self._step
|
|
)
|
|
return match if match is not None and match.downloaded else None
|
|
|
|
def _provenance(self, tool_call: ToolCall) -> str:
|
|
"""One line naming a file this call would run that the agent itself created, or ""
|
|
(§8.2). Fixed vocabulary — never file contents, never outside-authored text, so the
|
|
no-untrusted-content rule holds."""
|
|
match = self._agent_files.match(
|
|
tool_call.name, tool_call.arguments, step=self._step
|
|
)
|
|
return match.render() if match else ""
|
|
|
|
def current_shell_cwd(self) -> Optional[str]:
|
|
"""OPE-232 / OPE-234: the persistent shell's current folder, or None when it cannot be known
|
|
for the call being checked: no shell, or a shell command already cleared in this
|
|
batch may move it before this one runs."""
|
|
if self._shell_cleared_in_batch:
|
|
return None
|
|
executor = getattr(self, "executor", None)
|
|
cwd = getattr(executor, "cwd", None) if executor is not None else None
|
|
return str(cwd) if cwd else None
|
|
|
|
def _outside_in_context(self) -> bool:
|
|
"""OPE-235: whether content from outside is still in what the agent is sent: a tool
|
|
result marked `_outside` after the compaction boundary, or a compacted summary that
|
|
was written from one. Outside text can carry instructions for as long as the agent
|
|
can see it, so the line lasts exactly that long."""
|
|
state = self.compaction_state
|
|
start = 0
|
|
if state is not None and 0 < state.boundary_index < len(self.messages):
|
|
if state.carries_outside:
|
|
return True
|
|
start = state.boundary_index
|
|
return any(m.get("_outside") for m in self.messages[start:])
|
|
|
|
def _shell_cwd(self) -> Optional[str]:
|
|
executor = getattr(self, "executor", None)
|
|
cwd = getattr(executor, "cwd", None) if executor is not None else None
|
|
return str(cwd) if cwd else None
|
|
|
|
def _facts_kw(
|
|
self, tool_call: ToolCall, request: str, history: list[dict[str, Any]]
|
|
) -> dict[str, Any]:
|
|
"""OPE-235: what code can check about this call, as `{"facts": [...]}` for the
|
|
reviewer, or {} when there is nothing to say (so reviewers that predate facts keep
|
|
working). Fixed vocabulary (review_facts.py); a failure here never blocks a review."""
|
|
try:
|
|
from .permissions import write_paths
|
|
from .risk import WRITE_TOOLS
|
|
|
|
targets: list[Path] = []
|
|
if tool_call.name in WRITE_TOOLS:
|
|
paths, _located = write_paths(tool_call.name, tool_call.arguments or {})
|
|
targets = [self.permissions._candidate(p) for p in paths]
|
|
spec = self.registry.get(tool_call.name)
|
|
facts = review_facts.compute_facts(
|
|
tool_call.name,
|
|
tool_call.arguments or {},
|
|
user_texts=[request, *(str(h.get("text", "")) for h in history)],
|
|
external_read=self._outside_in_context(),
|
|
write_targets=targets,
|
|
metadata=spec.metadata if spec else None,
|
|
egress_host=self.permissions.egress_host,
|
|
cwd=self.permissions._shell_base(),
|
|
)
|
|
except Exception: # noqa: BLE001 - facts inform the reviewer, never gate it
|
|
facts = []
|
|
# OPE-237: one fixed line, matched by code; the plan's text never travels.
|
|
# Only when the action IS a step: an action outside the plan gets exactly
|
|
# the facts it would get without one (a "not in the plan" line made the
|
|
# reviewer refuse harmless extras, found live 26 Oct 2026).
|
|
if self._is_approved_plan_step(tool_call.name, tool_call.arguments or {}):
|
|
facts.append(review_facts.PLAN_STEP)
|
|
return {"facts": facts} if facts else {}
|
|
|
|
def _is_approved_plan_step(self, tool_name: str, arguments: dict[str, Any]) -> bool:
|
|
"""Whether this exact call is a step of the plan the user approved (OPE-237)."""
|
|
if not self._approved_plan:
|
|
return False
|
|
return bool(plan_steps.match_step(
|
|
self._approved_plan,
|
|
tool_name,
|
|
arguments or {},
|
|
resolve=self.permissions._candidate,
|
|
egress_host=self.permissions.egress_host,
|
|
# A command's paths are judged from the shell's folder (OPE-232); when it
|
|
# cannot be known, no shell action is a step.
|
|
shell_base=self.permissions.shell_cwd,
|
|
))
|
|
|
|
async def _preconsult_reviewer(self, tool_calls: list[ToolCall]) -> None:
|
|
"""Fire one reviewer request per call that will escalate, all concurrently, and
|
|
park the verdicts for `_authorize` to consume. One action per request — there is
|
|
no verdict list to pair back, so a verdict cannot land on the wrong action (§8.6).
|
|
Skips calls the gate already decides (allow or hard-deny): the reviewer only ever
|
|
sees what would otherwise become an approval card (§1.2)."""
|
|
if not self._reviewer_active() or not tool_calls:
|
|
return
|
|
interactive = {"request_directory", "propose_plan", "ask_user"}
|
|
pending: list[ToolCall] = []
|
|
for tool_call in tool_calls:
|
|
# Resolve parked worker calls at authorization time, not speculatively.
|
|
if tool_call.name == "decide_worker_call":
|
|
continue
|
|
if tool_call.name in interactive or tool_call.id in self._reviewer_verdicts:
|
|
continue
|
|
spec = self.registry.get(tool_call.name)
|
|
if spec is None:
|
|
continue
|
|
decision = self.permissions.evaluate(
|
|
tool_call.name, tool_call.arguments, spec.metadata
|
|
)
|
|
# human_only asks never reach the reviewer — same rule as `_authorize`.
|
|
if (
|
|
not decision.allowed
|
|
and decision.needs_user
|
|
and not decision.human_only
|
|
and self._downloaded_target(tool_call) is None
|
|
):
|
|
pending.append(tool_call)
|
|
if not pending:
|
|
return
|
|
request, history, context = self._review_inputs()
|
|
consulted_reviewer = self.reviewer
|
|
settings_epoch = self.reviewer_settings_epoch
|
|
verdicts = await asyncio.gather(
|
|
*[
|
|
self._recorded_review(
|
|
consulted_reviewer, tc,
|
|
request=request,
|
|
history=history,
|
|
tool_name=tc.name,
|
|
arguments=tc.arguments,
|
|
provenance=self._provenance(tc),
|
|
**({"action_context": context} if context else {}),
|
|
**self._facts_kw(tc, request, history),
|
|
)
|
|
for tc in pending
|
|
]
|
|
)
|
|
for tc, verdict in zip(pending, verdicts):
|
|
if (self.reviewer is not consulted_reviewer
|
|
or self.reviewer_settings_epoch != settings_epoch
|
|
or not self._reviewer_active()
|
|
or (request, history, context) != self._review_inputs()):
|
|
verdict = _settings_changed(verdict)
|
|
self._review_context_changed(tc.id)
|
|
self._reviewer_verdicts[tc.id] = verdict
|
|
self._reviewer_input_snapshots[tc.id] = (request, history, context)
|
|
|
|
async def _recorded_review(self, reviewer: Any, tool_call: ToolCall, *, shadow: bool = False,
|
|
**review_kw: Any) -> Any:
|
|
"""One auto-approver check, recorded as its own step (observability E12, §5.5),
|
|
linked to the tool call by `call_id`; the reviewer's model call is nested in it."""
|
|
kind = _REVIEWER_KINDS.get(getattr(self, "reviewer_choice", "session"), "session_model")
|
|
step_id = self._obs.start_step(
|
|
kind="auto_approver", name=tool_call.name, call_id=tool_call.id, shadow=shadow,
|
|
attrs={"mode": "shadow" if shadow else "live",
|
|
"reviewer": {"kind": kind, "external": kind != "session_model",
|
|
"model": getattr(reviewer, "model", None) if kind == "session_model" else None}},
|
|
)
|
|
if step_id is not None and _accepts_view(reviewer):
|
|
# A decision-model reviewer has no provider of its own: its request is recorded
|
|
# through the engine's view (E23).
|
|
review_kw["view"] = _tag_provider(getattr(reviewer, "provider", None) or self.provider,
|
|
parent=step_id, call_id=tool_call.id,
|
|
shadow=shadow, purpose="auto_approver")
|
|
try:
|
|
verdict = await reviewer.review(**review_kw)
|
|
except BaseException:
|
|
self._obs.end_step(step_id, status="error", attrs={"result": "could_not_run"})
|
|
raise
|
|
if step_id is not None:
|
|
failed = bool(getattr(verdict, "error", False))
|
|
result = "could_not_run" if failed else verdict.verdict
|
|
attrs: dict[str, Any] = {"result": result,
|
|
"usage_reported": self._obs.child_usage_reported(step_id)}
|
|
for key in ("score", "cutoff"):
|
|
if getattr(verdict, key, None) is not None:
|
|
attrs[key] = getattr(verdict, key)
|
|
if shadow:
|
|
answer = self._user_answers.pop(tool_call.id, None)
|
|
attrs["matched_user"] = None if failed or answer is None else _verdict_matches(result, answer)
|
|
if answer is None and not failed:
|
|
self._shadow_checks[tool_call.id] = (step_id, result)
|
|
else:
|
|
denials = self._reviewer_denials + 1 if result == "deny" else 0
|
|
attrs["breaker"] = {"denials_in_row": denials, "tripped": denials >= _REVIEWER_TRIP}
|
|
self._review_steps[tool_call.id] = step_id
|
|
reason = getattr(verdict, "reason", "") or ""
|
|
content: dict[str, Any] = {"reason": reason} if reason else {}
|
|
# A decision model's answers: each question's probability of "yes" (§5.5, §5.9).
|
|
# There is no single score or cut-off (several questions, each with its own
|
|
# threshold), so those stay null.
|
|
probabilities = getattr(verdict, "probabilities", None)
|
|
if isinstance(probabilities, dict) and probabilities:
|
|
content["questions"] = [
|
|
{"name": name, "answer": "yes" if float(p) >= 0.5 else "no", "score": round(float(p), 4)}
|
|
for name, p in probabilities.items()
|
|
if not str(name).startswith("_") and isinstance(p, (int, float))
|
|
]
|
|
self._obs.end_step(step_id, status="error" if failed else "ok", attrs=attrs, content=content)
|
|
return verdict
|
|
|
|
def _review_context_changed(self, call_id: str) -> None:
|
|
"""The request, history or settings changed while the check ran: the engine treats
|
|
it as unsure, and the step's result says so (§8.2)."""
|
|
self._obs.update_step(self._review_steps.pop(call_id, None), attrs={"result": "context_changed"})
|
|
|
|
def _note_user_answer(self, call_id: str, *, approved: bool) -> None:
|
|
"""Your answer on a card, compared with a shadow check's verdict (`matched_user`)."""
|
|
waiting = self._shadow_checks.pop(call_id, None)
|
|
if waiting is not None:
|
|
step_id, result = waiting
|
|
self._obs.update_step(step_id, attrs={"matched_user": _verdict_matches(result, approved)})
|
|
elif self.reviewer_shadow:
|
|
self._user_answers[call_id] = approved
|
|
|
|
async def _consult_reviewer(self, tool_call: ToolCall) -> Any:
|
|
"""The parked verdict from `_preconsult_reviewer`, or a fresh single call."""
|
|
verdict = self._reviewer_verdicts.pop(tool_call.id, None)
|
|
snapshot = self._reviewer_input_snapshots.pop(tool_call.id, None)
|
|
if verdict is not None:
|
|
if snapshot is not None and snapshot != self._review_inputs():
|
|
from .reviewer import Verdict
|
|
self._review_context_changed(tool_call.id)
|
|
return Verdict("unsure", "Approval context changed since review; a human must decide.")
|
|
return verdict
|
|
request, history, context = self._review_inputs()
|
|
delegated = self._delegated_context(tool_call)
|
|
if delegated:
|
|
from .reviewer import Verdict
|
|
if delegated.get("hard_deny") or delegated.get("human_only"):
|
|
return Verdict("unsure", delegated["reason"])
|
|
verdict = await self._recorded_review(
|
|
self.reviewer, tool_call,
|
|
request=request, history=history,
|
|
tool_name=delegated["tool"], arguments=delegated["arguments"],
|
|
provenance=delegated.get("provenance", ""),
|
|
action_context=delegated["context"],
|
|
)
|
|
if delegated != self._delegated_context(tool_call) or (request, history, context) != self._review_inputs():
|
|
return Verdict("unsure", "The worker request or its permissions changed during review. Review the current request.")
|
|
return verdict
|
|
result = await self._recorded_review(
|
|
self.reviewer, tool_call,
|
|
request=request,
|
|
history=history,
|
|
tool_name=tool_call.name,
|
|
arguments=tool_call.arguments,
|
|
provenance=self._provenance(tool_call),
|
|
**({"action_context": context} if context else {}),
|
|
**self._facts_kw(tool_call, request, history),
|
|
)
|
|
if (request, history, context) != self._review_inputs():
|
|
from .reviewer import Verdict
|
|
self._review_context_changed(tool_call.id)
|
|
return Verdict("unsure", "Approval context changed during review; review the current request.")
|
|
return result
|
|
|
|
def _delegated_context(self, tool_call: ToolCall) -> dict | None:
|
|
if tool_call.name != "decide_worker_call" or str(tool_call.arguments.get("decision", "")).lower().strip() != "allow":
|
|
return None
|
|
try:
|
|
if self.delegated_approval:
|
|
result = self.delegated_approval(tool_call.arguments)
|
|
if isinstance(result, dict) and result.get("hard_deny"):
|
|
return deepcopy(result)
|
|
if isinstance(result, dict) and isinstance(result.get("tool"), str) and isinstance(result.get("arguments"), dict) and isinstance(result.get("context"), dict):
|
|
return deepcopy(result)
|
|
except Exception:
|
|
pass
|
|
return {"hard_deny": True, "reason": "The original worker request cannot be verified."}
|
|
|
|
@staticmethod
|
|
def _action_key(tool_name: str, arguments: dict[str, Any] | None) -> tuple[str, str]:
|
|
try:
|
|
canon = json.dumps(arguments or {}, sort_keys=True, ensure_ascii=False)
|
|
except (TypeError, ValueError):
|
|
canon = str(arguments)
|
|
return (tool_name, canon)
|
|
|
|
def approve_action_once(self, tool_name: str, arguments: dict[str, Any] | None) -> None:
|
|
"""Register a one-shot human approval for this EXACT action (§8.4 "Allow anyway").
|
|
|
|
Called by the server when the user clicks the deny card — a human decision made
|
|
with the full reviewer reason in front of them. The next proposal of the identical
|
|
action (same tool, byte-identical canonical arguments) runs without the reviewer or
|
|
a card; anything that differs at all still goes through the normal flow. Never
|
|
standing: consumed on first use."""
|
|
self._allow_anyway.add(self._action_key(tool_name, arguments))
|
|
if self.audit_sink is not None:
|
|
try:
|
|
self.audit_sink(
|
|
{
|
|
**self.audit_context,
|
|
"tool": tool_name,
|
|
"arguments": arguments or {},
|
|
"stage": "allow_anyway_granted",
|
|
"status": "granted",
|
|
"reason": "user approved via the deny card (one-shot, exact action)",
|
|
}
|
|
)
|
|
except Exception:
|
|
pass
|
|
|
|
def _consume_allow_anyway(self, tool_call: ToolCall) -> bool:
|
|
key = self._action_key(tool_call.name, tool_call.arguments)
|
|
if key in self._allow_anyway:
|
|
self._allow_anyway.discard(key)
|
|
return True
|
|
return False
|
|
|
|
def _spawn_shadow_review(self, tool_call: ToolCall) -> None:
|
|
"""Shadow evaluation (spec Part 6 step 3): record what the reviewer WOULD have
|
|
decided about this card, without touching anything. Fire-and-forget — the card
|
|
renders immediately; the verdict lands in the audit log when the call returns,
|
|
joined to the human's `approval_resolved` row by `call_id`. There is deliberately
|
|
no code path from a shadow verdict to a decision."""
|
|
if self.reviewer is None or not self.reviewer_shadow:
|
|
return
|
|
if tool_call.name == "decide_worker_call":
|
|
# Only the current, resolved action can be reviewed. This proxy uses
|
|
# the on-demand live path; never send just its ID to the shadow judge.
|
|
return
|
|
request, history, context = self._review_inputs()
|
|
prov = self._provenance(tool_call)
|
|
|
|
async def _shadow() -> None:
|
|
try:
|
|
verdict = await self._recorded_review(
|
|
self.reviewer, tool_call, shadow=True,
|
|
request=request,
|
|
history=history,
|
|
provenance=prov,
|
|
tool_name=tool_call.name,
|
|
arguments=tool_call.arguments,
|
|
**({"action_context": context} if context else {}),
|
|
**self._facts_kw(tool_call, request, history),
|
|
)
|
|
self._audit(
|
|
tool_call,
|
|
stage="reviewer_shadow",
|
|
status=verdict.verdict,
|
|
reason=verdict.reason,
|
|
reviewer=getattr(self, "reviewer_choice", "session"),
|
|
call_id=tool_call.id,
|
|
tokens_in=verdict.tokens_in,
|
|
tokens_out=verdict.tokens_out,
|
|
cache_read=verdict.cache_read,
|
|
cache_write=verdict.cache_write,
|
|
)
|
|
except Exception:
|
|
pass # shadow must never surface a failure
|
|
|
|
task = asyncio.create_task(_shadow())
|
|
self._shadow_tasks.add(task)
|
|
task.add_done_callback(self._shadow_tasks.discard)
|
|
|
|
async def drain_shadow_reviews(self) -> None:
|
|
"""Await in-flight shadow verdicts (tests and orderly shutdown; never the hot path),
|
|
and the recorded turn ends that waited for them."""
|
|
if self._shadow_tasks:
|
|
await asyncio.gather(*list(self._shadow_tasks), return_exceptions=True)
|
|
if self._turn_end_tasks:
|
|
await asyncio.gather(*list(self._turn_end_tasks), return_exceptions=True)
|
|
|
|
async def _authorize(self, tool_call: ToolCall) -> "AsyncIterator[Event | bool]":
|
|
"""Permission flow for one call (TOOL_PROPOSED is emitted by the caller). Yields
|
|
its events, then True/False (allowed) last. Denied/unknown calls get their
|
|
tool-error message appended here."""
|
|
from .permissions import standing_rule_candidate
|
|
|
|
spec = self.registry.get(tool_call.name)
|
|
metadata = spec.metadata if spec else None
|
|
|
|
decision = self.permissions.evaluate(
|
|
tool_call.name, tool_call.arguments, metadata
|
|
)
|
|
delegated = self._delegated_context(tool_call)
|
|
if delegated and delegated.get("hard_deny"):
|
|
decision = replace(decision, allowed=False, needs_user=False, reason=delegated["reason"])
|
|
elif delegated and delegated.get("human_only") and (decision.allowed or decision.needs_user):
|
|
decision = replace(decision, allowed=False, needs_user=True, human_only=True, reason=delegated["reason"])
|
|
allowed = decision.allowed
|
|
reason = decision.reason
|
|
|
|
# OPE-114 §1: running something the agent DOWNLOADED this session is the classic
|
|
# fetch-then-execute chain, and there is no quiet legitimate version of it — so it
|
|
# goes to a person, over both the reviewer and any command allowlist that would
|
|
# otherwise wave it through (a `python` prefix rule must not vouch for a script
|
|
# pulled off the internet a moment ago). A hard deny is left untouched: this floor
|
|
# only ever tightens an allow, never loosens a block. Agent-WRITTEN files are not
|
|
# floored — "write this script and run it" is ordinary work — they travel as a fact
|
|
# for the reviewer to weigh instead.
|
|
provenance_note = self._provenance(tool_call)
|
|
if self._downloaded_target(tool_call) is not None and (
|
|
decision.needs_user or allowed
|
|
):
|
|
if self.permissions.mode is Mode.DANGEROUSLY_BYPASS_APPROVALS:
|
|
# The dangerous mode grants this floor too — recorded like every other
|
|
# clearance, with the provenance fact the card would have carried.
|
|
allowed = True
|
|
reason = f"{CLEARED_BY_MODE}: file the agent downloaded — {provenance_note}"
|
|
decision = replace(
|
|
decision, allowed=True, reason=reason, needs_user=False, human_only=False
|
|
)
|
|
else:
|
|
allowed = False
|
|
reason = f"this file was downloaded by the agent this session — {provenance_note}"
|
|
decision = replace(
|
|
decision,
|
|
allowed=False,
|
|
reason=reason,
|
|
needs_user=True,
|
|
human_only=True,
|
|
)
|
|
|
|
path = self._decisions[tool_call.id] = DecisionPath()
|
|
path.permission(
|
|
allowed=allowed, needs_user=decision.needs_user, human_only=decision.human_only,
|
|
reason=reason, tier=decision.tier if allowed else None,
|
|
)
|
|
if not allowed and decision.needs_user:
|
|
try:
|
|
# A session grant covered it, but Auto-Approve hands it to the reviewer (§8.3).
|
|
if self.permissions.session_grant_suspended(tool_call.name, tool_call.arguments, metadata):
|
|
path.add("grant", "suspended_in_auto_approve")
|
|
except Exception: # noqa: BLE001 - a recording fact never breaks a call
|
|
pass
|
|
|
|
# OPE-233: an Auto-Approve gate tier let this call run without the reviewer —
|
|
# recorded, never invisible (transcript chip + audit row), like every other
|
|
# cardless origin.
|
|
if allowed and decision.tier:
|
|
# OPE-234: a read-only command has its own origin. It changes nothing, so it
|
|
# is not one of the "changes made without asking" (OPE-238), and its chip
|
|
# says what kind of thing ran.
|
|
origin = "readonly_tier" if decision.tier == "readonly_command" else "gate_tier"
|
|
self._approval_origins[tool_call.id] = {"origin": origin, "note": reason}
|
|
self._audit(tool_call, stage="auto_allowed", status="allowed", reason=reason)
|
|
elif decision.tier and decision.tier_audit_only and decision.needs_user:
|
|
# Audit mode: the decision is unchanged; the record notes what the tier WOULD
|
|
# have done, so it can be measured before anyone switches it on.
|
|
self._audit(
|
|
tool_call,
|
|
stage="gate_tier_shadow",
|
|
status="would_allow",
|
|
reason=f"{decision.tier}: {decision.tier_note}",
|
|
)
|
|
|
|
if allowed and decision.rule:
|
|
# A task-scoped standing rule auto-allowed this call: audit the exact rule
|
|
# (§25 invariant — every auto-allowed call cites its rule) and remember it so
|
|
# the tool card can say "allowed by standing rule".
|
|
self._standing_notes[tool_call.id] = decision.rule
|
|
self._audit(
|
|
tool_call, stage="auto_allowed", status="allowed", reason=reason
|
|
)
|
|
|
|
# (c) Bypass mode ran a consequential call no other rule allowed: annotate it.
|
|
# "full access" is the exact reason string of permissions.py's bypass branch.
|
|
if allowed and decision.reason == "full access":
|
|
self._approval_origins[tool_call.id] = {"origin": "bypass"}
|
|
# (d) The dangerous mode crossed a floor a person would otherwise have seen:
|
|
# annotated AND audited per call, so the record can count exactly what was cleared.
|
|
if allowed and decision.reason.startswith("cleared by mode"):
|
|
self._approval_origins[tool_call.id] = {
|
|
"origin": "bypass",
|
|
"note": decision.reason,
|
|
}
|
|
self._audit(
|
|
tool_call, stage="auto_allowed", status="allowed", reason=decision.reason
|
|
)
|
|
|
|
# OPE-136: a trusted-MCP allow ran cardless on standing config (a user trust
|
|
# rule, or the legacy server flag) — audited and chip-annotated like every
|
|
# other cardless origin ("recorded, never invisible"). Prefix-matched against
|
|
# permissions.py's two trusted-branch reason strings — and the chip keeps the
|
|
# two apart: "your trust rule" points at the tool page's Revoke, "server
|
|
# trust" at the mcp.json flag. One generic label made a user believe the
|
|
# SERVER had marked their own rule (owner-hit 2026-08-30).
|
|
if allowed and decision.reason.startswith("trusted MCP tool"):
|
|
origin = (
|
|
"trusted_rule"
|
|
if "user trust rule" in decision.reason
|
|
else "trusted_server"
|
|
)
|
|
self._approval_origins[tool_call.id] = {"origin": origin}
|
|
self._audit(
|
|
tool_call, stage="auto_allowed", status="allowed", reason=reason
|
|
)
|
|
|
|
# OPE-136 run grant: a covered call ran cardless under the user's in-run
|
|
# "Allow for this request" click — silent to attention, never invisible to
|
|
# the record (transcript chip + audit row, like every cardless origin).
|
|
if allowed and decision.reason == "tool allowed for this request":
|
|
self._approval_origins[tool_call.id] = {"origin": "run_grant"}
|
|
self._audit(
|
|
tool_call, stage="auto_allowed", status="allowed", reason=reason
|
|
)
|
|
|
|
if not allowed and decision.needs_user and self._consume_allow_anyway(tool_call):
|
|
# §8.4 "Allow anyway": the human already approved this exact action from the
|
|
# deny card. One-shot — consumed above; a different action never matches.
|
|
allowed = True
|
|
reason = "approved by user (allow anyway)"
|
|
path.add("grant", "allow_anyway")
|
|
self._audit(tool_call, stage="auto_allowed", status="allowed", reason=reason)
|
|
|
|
# A lead DENYING one of its workers' waiting calls runs nothing: the worker is told
|
|
# no and moves on, and the human can still answer the worker directly. Under
|
|
# Auto-Approve that needs neither the reviewer nor a card (live 2026-09-17: the
|
|
# human was asked to "Allow" a denial). An ALLOW still goes to the reviewer below,
|
|
# and a Manual lead still asks for both — that mode means "show me everything".
|
|
if (
|
|
not allowed
|
|
and decision.needs_user
|
|
and not decision.human_only
|
|
and tool_call.name == "decide_worker_call"
|
|
and self.permissions.mode is Mode.AUTO_APPROVE
|
|
and str((tool_call.arguments or {}).get("decision", "")).strip().lower() == "deny"
|
|
):
|
|
allowed = True
|
|
reason = "a lead's denial of a worker's call runs nothing"
|
|
path.add("grant", "lead_denial")
|
|
self._audit(tool_call, stage="auto_allowed", status="allowed", reason=reason)
|
|
|
|
consulted_live = False
|
|
unsure_note = "" # the reviewer's hesitation, when an unsure verdict raised the card
|
|
# The card's wording when the reviewer gives no reason (decision models, OPE-224):
|
|
# "reviewer_asks" for a judgment, "reviewer_unavailable" when it could not run.
|
|
unsure_silent_kind = ""
|
|
if (
|
|
not allowed
|
|
and decision.needs_user
|
|
and not decision.human_only
|
|
and self._reviewer_active()
|
|
):
|
|
# The one thing the reviewer may do: turn "ask the human" into "go ahead" —
|
|
# never "blocked" into "go ahead" (§1.2; hard denies never reach this branch
|
|
# because needs_user is False on them). `human_only` asks (git hooks, CI
|
|
# configs, unscopable writes) skip the reviewer entirely: their floor is that
|
|
# a PERSON sees them, and a verdict here would be that floor's bypass.
|
|
consulted_live = True
|
|
consulted_reviewer = self.reviewer
|
|
settings_epoch = self.reviewer_settings_epoch
|
|
verdict = await self._consult_reviewer(tool_call)
|
|
settings_changed = (self.reviewer is not consulted_reviewer
|
|
or self.reviewer_settings_epoch != settings_epoch
|
|
or not self._reviewer_active())
|
|
if settings_changed:
|
|
verdict = _settings_changed(verdict)
|
|
self._review_context_changed(tool_call.id)
|
|
path.add("auto_approver", "context_changed" if settings_changed
|
|
else "could_not_run" if getattr(verdict, "error", False) else verdict.verdict)
|
|
self._audit(
|
|
tool_call,
|
|
stage="reviewer_verdict",
|
|
status=verdict.verdict,
|
|
reason=verdict.reason,
|
|
reviewer=getattr(self, "reviewer_choice", "session"),
|
|
tokens_in=verdict.tokens_in,
|
|
tokens_out=verdict.tokens_out,
|
|
cache_read=verdict.cache_read,
|
|
cache_write=verdict.cache_write,
|
|
)
|
|
# What the card may show. A decision-model verdict carries `card_reason` (empty:
|
|
# those reviewers give no explanation, owner ruling 2026-10-16); the session-model
|
|
# reviewer's one-line reason is shown as before. The audit keeps `reason` in full.
|
|
card_note = getattr(verdict, "card_reason", verdict.reason)
|
|
if verdict.verdict == "allow":
|
|
allowed = True
|
|
self._reviewer_denials = 0 # streak semantics: any non-deny resets
|
|
self._approval_origins[tool_call.id] = {
|
|
"origin": "reviewer", **({"note": card_note} if card_note else {})
|
|
}
|
|
reason = f"allowed by reviewer: {verdict.reason}"
|
|
elif verdict.verdict == "deny":
|
|
# §8.4 deny asymmetry — full reason to the USER (event + audit above),
|
|
# terse non-diagnostic refusal to the AGENT. The sanctioned way around a
|
|
# deny is ask the human, never reshape the request.
|
|
from .reviewer import AGENT_DENY_MESSAGE
|
|
|
|
self._reviewer_denials += 1
|
|
tripped = self._reviewer_denials == _REVIEWER_TRIP
|
|
if tripped:
|
|
# (a) The breaker must never trip silently (owner catch 2026-08-24):
|
|
# persist a notice so reloads see it too.
|
|
self._append_notice("reviewer_paused", _REVIEWER_PAUSED_TEXT)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"status": "denied",
|
|
"reason": "blocked by the safety reviewer",
|
|
**({"reviewer_reason": card_note} if card_note else {}),
|
|
"allow_anyway": True,
|
|
**({"reviewer_paused": _REVIEWER_PAUSED_TEXT} if tripped else {}),
|
|
},
|
|
)
|
|
deny_msg = _tool_error_message(tool_call, self.reviewer_denial_message or AGENT_DENY_MESSAGE)
|
|
deny_msg["_display"] = {
|
|
"approval_origin": "reviewer_denied",
|
|
**({"approval_note": card_note} if card_note else {}),
|
|
}
|
|
self._add_message(deny_msg)
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status="denied",
|
|
reason=f"denied by reviewer: {verdict.reason}",
|
|
)
|
|
yield False
|
|
return
|
|
# "unsure" falls through to today's card — the human decides.
|
|
if verdict.verdict == "unsure":
|
|
self._reviewer_denials = 0 # streak semantics: any non-deny resets
|
|
unsure_note = card_note
|
|
if not card_note:
|
|
unsure_silent_kind = "reviewer_unavailable" if verdict.error else "reviewer_asks"
|
|
|
|
if (not allowed and decision.needs_user and not consulted_live
|
|
and self.permissions.mode is Mode.AUTO_APPROVE):
|
|
path.add("auto_approver", _reviewer_skip(self, decision))
|
|
|
|
if not allowed and decision.needs_user and self._nobody_answers_cards():
|
|
# Attendance "auto": nobody can answer a card, and the mode did not allow
|
|
# the call — so the answer is no, recorded, never a hang. (The dangerous mode
|
|
# never reaches here: it grants the floors before a card exists.)
|
|
reason = "refused: no one is available to approve this (attendance: auto)"
|
|
self._approval_origins[tool_call.id] = {
|
|
"origin": "unattended_auto",
|
|
"grant": "deny",
|
|
**({"note": unsure_note} if unsure_note else {}),
|
|
}
|
|
self._audit(
|
|
tool_call,
|
|
stage="approval_resolved",
|
|
call_id=tool_call.id,
|
|
status="denied",
|
|
approval="auto_refused",
|
|
reason=reason,
|
|
)
|
|
decision = replace(decision, needs_user=False)
|
|
path.add("card", "auto_refused")
|
|
|
|
if not allowed and decision.needs_user:
|
|
escalation = (
|
|
{"kind": "human_required", "reason": decision.reason} if decision.human_only else
|
|
{"kind": "reviewer_unsure", "reason": unsure_note} if unsure_note else
|
|
{"kind": unsure_silent_kind, "reason": ""} if unsure_silent_kind else
|
|
{"kind": "reviewer_unavailable", "reason": ""} if self.permissions.mode is Mode.AUTO_APPROVE else None
|
|
)
|
|
# Shadow evaluation: record what the reviewer would have said about this card.
|
|
# Skipped when the live path already consulted it (an `unsure` falling through
|
|
# to the card is already audited as reviewer_verdict — no double spend).
|
|
if not consulted_live:
|
|
self._spawn_shadow_review(tool_call)
|
|
yield Event(
|
|
EventType.PERMISSION_REQUIRED,
|
|
{
|
|
"name": tool_call.name,
|
|
"arguments": tool_call.arguments,
|
|
"reason": decision.reason,
|
|
"escalation": escalation,
|
|
# An `unsure` verdict raised this card: the reviewer's one-line reason
|
|
# answers "why am I being asked?" in place (owner ask 2026-08-24).
|
|
**(
|
|
{"reviewer_unsure": unsure_note}
|
|
if consulted_live and verdict.verdict == "unsure" and unsure_note
|
|
else {}
|
|
),
|
|
"category": getattr(metadata, "category", ""),
|
|
# OPE-219: the host the sandbox's allowed-sites wall stopped. The card
|
|
# says so and offers to add the site to the machine's list.
|
|
**({"site_wall": decision.site} if decision.site else {}),
|
|
# The agent asked for sites its commands cannot reach: the card names
|
|
# them, gives the agent's reason, and says whether the sandbox has in
|
|
# fact blocked each one (the person's check on the request).
|
|
**(
|
|
{"network_request": self._network_request_payload(tool_call, decision)}
|
|
if decision.network_hosts
|
|
else {}
|
|
),
|
|
# The exact target a standing rule could pin, or None when the call
|
|
# isn't eligible (no declared target arg / exec risk). Surfaces use it
|
|
# to offer "Allow every time" on automation-run approval cards only.
|
|
# OPE-114 §1: the fact neither the reviewer nor the human could get
|
|
# from the command text alone.
|
|
"provenance": provenance_note,
|
|
"standing_target": standing_rule_candidate(
|
|
tool_call.name,
|
|
tool_call.arguments,
|
|
metadata,
|
|
self.permissions.risk_overrides,
|
|
),
|
|
# True when this shell command classifies as read-only — the card
|
|
# offers "Allow read-only commands for this session" only then.
|
|
"readonly_ok": _readonly_ok(tool_call.arguments, self.permissions.shell_kind),
|
|
# OPE-136 finding 4: where an MCP call actually goes, stamped at
|
|
# registration (mcp/tools.py) from the server def — so the card's
|
|
# scope chip can say "leaves this computer → host" instead of the
|
|
# catch-all "stays on this computer". None for non-MCP tools.
|
|
**(
|
|
{"mcp_destination": dest}
|
|
if (
|
|
dest := getattr(
|
|
spec.func, "__coworker_mcp_destination__", None
|
|
)
|
|
if spec
|
|
else None
|
|
)
|
|
else {}
|
|
),
|
|
**(
|
|
self.approval_extras(tool_call.name, tool_call.arguments)
|
|
if self.approval_extras
|
|
else {}
|
|
),
|
|
},
|
|
)
|
|
self._audit(
|
|
tool_call,
|
|
stage="approval_requested",
|
|
reason=decision.reason,
|
|
call_id=tool_call.id,
|
|
)
|
|
outcome = await self._wait_tool(tool_call,
|
|
kind="approval", coro=self.approver(
|
|
PermissionRequest(
|
|
tool_name=tool_call.name,
|
|
arguments=tool_call.arguments,
|
|
metadata=metadata,
|
|
reason=decision.reason,
|
|
tool_call_id=tool_call.id,
|
|
escalation=escalation,
|
|
provenance=provenance_note,
|
|
mcp_destination=(
|
|
getattr(spec.func, "__coworker_mcp_destination__", None)
|
|
if spec
|
|
else None
|
|
),
|
|
)
|
|
),
|
|
interrupted=ApprovalOutcome.DENY,
|
|
)
|
|
path.add("card", "parked_inbox" if self._card_where.pop(tool_call.id, "") == "inbox" else "shown_session")
|
|
path.resolved(
|
|
outcome.value if isinstance(outcome, ApprovalOutcome) else str(outcome),
|
|
interrupted=outcome is ApprovalOutcome.DENY and self._cancel.is_set(),
|
|
)
|
|
if not self._cancel.is_set() and outcome is not ApprovalOutcome.SUPERSEDED:
|
|
self._note_user_answer(tool_call.id, approved=outcome is not ApprovalOutcome.DENY)
|
|
if outcome is ApprovalOutcome.SUPERSEDED:
|
|
result = {
|
|
"skipped": True,
|
|
"reason": "The worker request was already resolved. No further action was taken.",
|
|
}
|
|
self._approval_origins.pop(tool_call.id, None)
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(tool_call, stage="approval_resolved", call_id=tool_call.id, status="superseded", reason=result["reason"])
|
|
self._audit(tool_call, stage="finished", status="skipped", reason=result["reason"])
|
|
yield Event(EventType.TOOL_FINISHED, {
|
|
"name": tool_call.name, "status": "ok", "result_preview": json.dumps(result),
|
|
"superseded_worker_call": (tool_call.arguments or {}).get("call_id") if tool_call.name == "decide_worker_call" else None,
|
|
})
|
|
yield False
|
|
return
|
|
if outcome is ApprovalOutcome.DENY:
|
|
allowed, reason = (
|
|
False,
|
|
self._deny_notes.pop(tool_call.id, None)
|
|
or ("interrupted by user" if self._cancel.is_set() else "denied by user"),
|
|
)
|
|
self._approval_origins[tool_call.id] = {
|
|
"origin": "user",
|
|
"grant": "deny",
|
|
**({"note": unsure_note} if unsure_note else {}),
|
|
}
|
|
self._audit(
|
|
tool_call,
|
|
stage="approval_resolved",
|
|
call_id=tool_call.id,
|
|
status="denied",
|
|
approval=outcome.value,
|
|
reason=reason,
|
|
)
|
|
else:
|
|
if decision.network_hosts:
|
|
# Any approval of a network request opens the sites for this session;
|
|
# "Always allow" also stores them. Never a tool-wide grant: each ask
|
|
# for a new site gets its own card.
|
|
self.permissions.allow_network_hosts(
|
|
decision.network_hosts,
|
|
always=outcome is ApprovalOutcome.ALWAYS_SITE,
|
|
)
|
|
elif outcome is ApprovalOutcome.ALWAYS_TOOL:
|
|
self.permissions.allow_tool_for_session(tool_call.name)
|
|
elif outcome is ApprovalOutcome.ALWAYS_COMMAND:
|
|
self.permissions.allow_command_for_session(
|
|
str(tool_call.arguments.get("command", ""))
|
|
)
|
|
elif outcome is ApprovalOutcome.ALWAYS_DOMAIN:
|
|
self.permissions.allow_domain_for_session(
|
|
str(tool_call.arguments.get("url", ""))
|
|
)
|
|
elif outcome is ApprovalOutcome.ALWAYS_SITE and decision.site:
|
|
self.permissions.allow_site_always(decision.site)
|
|
# A session grant given on the allowed-sites card must also open the
|
|
# wall for that site, or the next call would raise the same card
|
|
# (web_search has no url: its site is the search provider's host).
|
|
if decision.site and outcome in (
|
|
ApprovalOutcome.ALWAYS_TOOL,
|
|
ApprovalOutcome.ALWAYS_DOMAIN,
|
|
):
|
|
self.permissions.allow_site_for_session(decision.site)
|
|
elif outcome is ApprovalOutcome.READONLY_SESSION:
|
|
self.permissions.allow_readonly_for_session()
|
|
elif outcome is ApprovalOutcome.ALWAYS_TRUST:
|
|
# Durable per-tool trust (OPE-136 §4): lands in the user-local
|
|
# override store, so tomorrow's sessions stay quiet too.
|
|
self.permissions.grant_trust_for_tool(tool_call.name)
|
|
elif outcome is ApprovalOutcome.THIS_RUN:
|
|
# Run grant: dies with the current answer (cleared in run()).
|
|
self.permissions.allow_tool_for_run(tool_call.name)
|
|
allowed, reason = True, "approved by user"
|
|
self._approval_origins[tool_call.id] = {
|
|
"origin": "user",
|
|
"grant": outcome.value,
|
|
**({"note": unsure_note} if unsure_note else {}),
|
|
}
|
|
self._audit(
|
|
tool_call,
|
|
stage="approval_resolved",
|
|
call_id=tool_call.id,
|
|
status="approved",
|
|
approval=outcome.value,
|
|
reason=reason,
|
|
)
|
|
|
|
if allowed and delegated and delegated != self._delegated_context(tool_call):
|
|
allowed, reason = False, "The worker request or its permissions changed. Request a fresh decision."
|
|
|
|
if not allowed:
|
|
if spec is None:
|
|
reason = f"unknown tool: {tool_call.name}"
|
|
err_msg = _tool_error_message(tool_call, reason)
|
|
if tool_call.id in self._tool_timings:
|
|
err_msg["timing"] = self._tool_timings.pop(tool_call.id)
|
|
origin = self._approval_origins.pop(tool_call.id, None)
|
|
if origin:
|
|
err_msg["_display"] = {
|
|
"approval_origin": origin.get("origin", ""),
|
|
**({"approval_note": origin["note"]} if origin.get("note") else {}),
|
|
**({"approval_grant": origin["grant"]} if origin.get("grant") else {}),
|
|
}
|
|
self._add_message(err_msg)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{"name": tool_call.name, "status": "denied", "reason": reason},
|
|
)
|
|
self._audit(tool_call, stage="finished", status="denied", reason=reason)
|
|
yield False
|
|
return
|
|
|
|
if spec is None:
|
|
self._add_message(
|
|
_tool_error_message(tool_call, f"unknown tool: {tool_call.name}")
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{"name": tool_call.name, "status": "error", "reason": "unknown tool"},
|
|
)
|
|
yield False
|
|
return
|
|
|
|
if delegated:
|
|
self._authorized_delegates[tool_call.id] = delegated
|
|
origin = self._approval_origins.get(tool_call.id)
|
|
if origin and origin.get("origin") in _UNASKED_ORIGINS:
|
|
# OPE-238: what the turn summary needs to count honestly: did this call
|
|
# change anything, and which tier (if any) let it through.
|
|
origin["effect"] = self._effect(tool_call, metadata, decision.tier)
|
|
if decision.tier:
|
|
origin["tier"] = decision.tier
|
|
yield True
|
|
|
|
def _effect(self, tool_call: ToolCall, metadata: Any, tier: str) -> str:
|
|
""""change" or "read", from the risk class the permission engine already uses.
|
|
A shell command is a change unless the read-only classifier said otherwise;
|
|
connector and MCP calls that reached a cardless origin are writes or sends
|
|
(connector reads never gate); a web read is a read."""
|
|
if tier == "readonly_command":
|
|
return "read"
|
|
risk = _classify_risk(tool_call.name, metadata, self.permissions.risk_overrides)
|
|
if risk in (RiskClass.WRITE_LOCAL, RiskClass.EXEC, RiskClass.EXTERNAL):
|
|
return "change"
|
|
return "read"
|
|
|
|
def _execute_sync(self, tool_call: ToolCall) -> tuple[Any, str]:
|
|
"""Execute one authorized call (runs in a worker thread). Recorded as a tool step
|
|
from here to the RAW result, before `_record_result` shortens it (E1)."""
|
|
step_id = self._obs.start_step(
|
|
kind="tool", name=tool_call.name, call_id=tool_call.id,
|
|
call_index=self._call_index.get(tool_call.id),
|
|
)
|
|
# A tool that starts its own work (the explore helper, E6) records it under this step.
|
|
outer = set_tool_run(ToolRun(step_id=step_id, turn_id=self._obs.turn_id,
|
|
view=self.provider, recording=self._obs, call_id=tool_call.id))
|
|
try:
|
|
result, status = self._execute_call(tool_call)
|
|
finally:
|
|
set_tool_run(outer)
|
|
blocked = result.pop("_blocked", None) if isinstance(result, dict) else None
|
|
if step_id is not None:
|
|
attrs = self._tool_step_attrs(tool_call, {**result, "_blocked": blocked} if blocked else result, status)
|
|
step_status = status
|
|
if self._cancel.is_set() and isinstance(result, dict) and result.get("error"):
|
|
# Stop killed it (a shell command answers "interrupted by user"): §7.4.
|
|
step_status = "interrupted"
|
|
self._obs.end_step(
|
|
step_id, status=step_status, attrs=attrs,
|
|
content={"blocked": blocked} if blocked else {},
|
|
wait_for_tool_message=True,
|
|
)
|
|
return result, status
|
|
|
|
def _tool_step_attrs(self, tool_call: ToolCall, result: Any, status: str = "ok") -> dict[str, Any]:
|
|
attrs: dict[str, Any] = {"risk_class": self._risk_class(tool_call.name)}
|
|
path = self._decisions.pop(tool_call.id, None)
|
|
if path is not None:
|
|
attrs["decision"] = path.finish(ran=True)
|
|
try:
|
|
attrs["result_bytes"] = len(
|
|
result.encode("utf-8") if isinstance(result, str)
|
|
else json.dumps(result, default=str, ensure_ascii=False).encode("utf-8")
|
|
)
|
|
except Exception: # noqa: BLE001
|
|
pass
|
|
if isinstance(result, dict) and isinstance(result.get("exit_code"), int):
|
|
attrs["exit_code"] = result["exit_code"]
|
|
attrs["sandbox"] = self._sandbox_facts(result)
|
|
attrs.update(self._call_facts(tool_call.name, tool_call.arguments, ran=True,
|
|
status=status, result=result, risk=attrs["risk_class"]))
|
|
return attrs
|
|
|
|
def _call_facts(self, name: str, arguments: Any, *, ran: bool, status: str, result: Any = None,
|
|
reason: str = "", risk: Optional[str] = None) -> dict[str, Any]:
|
|
"""The tool fields of recording format 1.2 that the Issues checks read (phase-2
|
|
design §4): ids and flags only, never text. Facts never break a call."""
|
|
out: dict[str, Any] = {}
|
|
try:
|
|
mangled = isinstance(arguments, dict) and "_raw" in arguments
|
|
out["args_hash"] = None if mangled or arguments is None else _args_hash(arguments)
|
|
spec = self.registry.get(name)
|
|
out["repeat_ok"] = bool(getattr(getattr(spec, "metadata", None), "repeat_ok", False))
|
|
out["result_error"] = bool(ran and status == "ok" and isinstance(result, dict) and result.get("error"))
|
|
if status != "error":
|
|
out["error_kind"] = None
|
|
elif ran:
|
|
# Arguments the tool does not take, or a required one missing, fail at the call
|
|
# itself: the model's mistake, not the tool's (found by the labelling judge).
|
|
out["error_kind"] = "raised" if _args_fit(spec, arguments) else "bad_arguments"
|
|
elif mangled:
|
|
out["error_kind"] = "bad_arguments"
|
|
elif spec is None or reason.startswith("unknown tool"):
|
|
out["error_kind"] = "unknown_tool"
|
|
else:
|
|
out["error_kind"] = "raised"
|
|
if not ran:
|
|
out["reaches_network"] = None
|
|
else:
|
|
command = arguments.get("command") if isinstance(arguments, dict) and name == "run_shell" else None
|
|
out["reaches_network"] = bool(
|
|
(risk or self._risk_class(name)) == "egress"
|
|
or (isinstance(command, str) and review_facts.shell_reaches_network(command))
|
|
)
|
|
if name == "run_shell":
|
|
# 1.3 (E17b): the scanner this command runs, by the signals.yaml word rule.
|
|
# A scanner that is not installed did not scan (signals 0.7 `scanners.not_found`,
|
|
# P3B-1): on Windows that exits 1, the same code as "found something", so its
|
|
# output and error tell them apart.
|
|
command = arguments.get("command") if isinstance(arguments, dict) else None
|
|
res = result if isinstance(result, dict) else {}
|
|
out["scanner"] = _recorded_scanner(command, ran=ran and bool(res), exit_code=res.get("exit_code"),
|
|
output=res.get("output"), error=res.get("error"))
|
|
# 1.3 (E17b): the full SHA-256 of the raw result, the evidence card's "output sha256".
|
|
out["result_sha256"] = _result_sha256(result) if ran else None
|
|
if name == "todo_write" and isinstance(arguments, dict):
|
|
entries = arguments.get("todos", arguments.get("items")) or []
|
|
items = []
|
|
for entry in entries if isinstance(entries, list) else []:
|
|
text = str(entry.get("content", "")) if isinstance(entry, dict) else str(entry)
|
|
st = entry.get("status", "pending") if isinstance(entry, dict) else "pending"
|
|
st = "done" if st in ("done", "completed") else st if st in ("pending", "in_progress") else "pending"
|
|
items.append({"h": _text_hash(text), "s": st})
|
|
out["plan"] = {"items": items}
|
|
except Exception: # noqa: BLE001 - recording never breaks a call
|
|
logger.exception("observability: could not record a tool call's facts")
|
|
return out
|
|
|
|
@staticmethod
|
|
def _sandbox_notice_id(text: Any) -> Optional[str]:
|
|
"""`restart` or `regrant` for the sandbox notice a command's result carries, else None."""
|
|
if not isinstance(text, str) or not text:
|
|
return None
|
|
from .sandbox.workspace import REGRANT_NOTICE, RESTART_NOTICE
|
|
|
|
return "restart" if text == RESTART_NOTICE else "regrant" if text == REGRANT_NOTICE else None
|
|
|
|
def _sandbox_facts(self, result: Any) -> Optional[dict[str, Any]]:
|
|
"""Per-call sandbox facts (observability E13, §9.3): whether this sandbox can report
|
|
blocked sites now, and how many connections it refused during the call. None when
|
|
the call did not run in a sandbox."""
|
|
ws = getattr(self, "sandbox_workspace", None)
|
|
if ws is None or not hasattr(ws, "reports_blocked"):
|
|
return None
|
|
blocked = result.get("_blocked") if isinstance(result, dict) else None
|
|
told = result.get("sandbox_notice") if isinstance(result, dict) else None
|
|
return {
|
|
"blocked_known": bool(getattr(ws, "reports_blocked", False)),
|
|
"blocked_count": sum(int(b.get("count") or 0) for b in blocked or []),
|
|
# The restart the agent was told of with this result (OB-13): the same short id
|
|
# as the `sandbox_restarted` notice's `how`.
|
|
"notice": self._sandbox_notice_id(told),
|
|
}
|
|
|
|
def _execute_call(self, tool_call: ToolCall) -> tuple[Any, str]:
|
|
started, clock = time.time(), time.perf_counter()
|
|
try:
|
|
delegated = self._authorized_delegates.pop(tool_call.id, None)
|
|
if delegated and delegated != self._delegated_context(tool_call):
|
|
return {"error": "The worker request or its permissions changed before execution. Request a fresh decision."}, "error"
|
|
try:
|
|
# OPE-235: note what a shell command will bring in before it runs, so the
|
|
# folders it adds to can be compared afterwards.
|
|
plan = self._agent_files.before(
|
|
tool_call.name, tool_call.arguments, cwd=self._shell_cwd()
|
|
)
|
|
if plan is not None:
|
|
self._intake_plans[tool_call.id] = plan
|
|
except Exception: # noqa: BLE001 - bookkeeping never blocks a tool
|
|
pass
|
|
return self.registry.execute(tool_call.name, tool_call.arguments), "ok"
|
|
except Exception as exc:
|
|
return {"error": str(exc), "error_type": type(exc).__name__}, "error"
|
|
finally:
|
|
self._tool_timings.setdefault(tool_call.id, {}).update(tool_started=started, tool_ms=(time.perf_counter() - clock) * 1000)
|
|
|
|
def _record_result(self, tool_call: ToolCall, result: Any, status: str) -> Event:
|
|
spec = self.registry.get(tool_call.name)
|
|
if (
|
|
status == "ok" and isinstance(result, dict) and result.get("ok")
|
|
and spec and getattr(spec.func, "__coworker_yields_turn__", False)
|
|
):
|
|
self._yield_for_wake = True
|
|
self._step += 1
|
|
plan = self._intake_plans.pop(tool_call.id, None)
|
|
outside = False
|
|
if status == "ok":
|
|
# OPE-235: whether this result brings outside content into the agent's context
|
|
# (marked on its message below). Checked before recording, so reading a file
|
|
# that came from outside in an EARLIER call counts, not the download itself.
|
|
cwd = plan.cwd if plan is not None else self._shell_cwd()
|
|
try:
|
|
outside = (
|
|
review_facts.is_external_read(
|
|
tool_call.name, tool_call.arguments, spec.metadata if spec else None
|
|
)
|
|
or (plan is not None and plan.brings_outside_in)
|
|
or self._agent_files.reads_outside(
|
|
tool_call.name, tool_call.arguments, cwd=cwd
|
|
)
|
|
)
|
|
except Exception: # noqa: BLE001 - a fact, never a reason to fail a call
|
|
outside = True
|
|
# Only successful calls: a write that raised left nothing on disk to run.
|
|
self._agent_files.record(
|
|
tool_call.name, tool_call.arguments, result, step=self._step, cwd=cwd, plan=plan
|
|
)
|
|
# A `_display` key on a tool result is user-facing metadata the AGENT must
|
|
# never see (e.g. how many gmail hits the privacy filters hid — a count
|
|
# the model could probe around). Lift it onto the message as a sidecar
|
|
# (like `source`), stripped from every provider feed in
|
|
# `_outbound_messages` but persisted for the GUI's tool card.
|
|
display: Optional[dict[str, Any]] = None
|
|
if isinstance(result, dict) and "_display" in result:
|
|
display = result.get("_display") or None
|
|
result = {k: v for k, v in result.items() if k != "_display"}
|
|
origin = self._approval_origins.pop(tool_call.id, None)
|
|
# OPE-238: the facts the turn summary shows, kept with the result so a reload
|
|
# shows the same thing the live view did: whether the call failed, and for a
|
|
# shell command its exit status, time-out, or background start.
|
|
outcome = _call_outcome(tool_call, result, status)
|
|
if origin:
|
|
# Provenance survives reload via the same display-only sidecar as the privacy
|
|
# counts (owner ruling 2026-08-24) — `_outbound_messages` strips it, so no
|
|
# provider ever sees it.
|
|
display = {
|
|
**(display or {}),
|
|
**_origin_fields(origin),
|
|
**outcome,
|
|
}
|
|
elif outcome:
|
|
display = {**(display or {}), **outcome}
|
|
# OPE-186 change 1: what the model sees (and re-reads on every later turn) is
|
|
# bounded here, once, for every tool. Provenance above recorded the full result.
|
|
result = toolresult.bound_tool_result(
|
|
result,
|
|
max_bytes=self._tool_result_max_bytes,
|
|
spill_dir=self._tool_result_spill_dir,
|
|
step=self._step,
|
|
tool_name=tool_call.name,
|
|
)
|
|
message = self._timed_result(tool_call, result)
|
|
if display:
|
|
message["_display"] = display
|
|
if outside:
|
|
message["_outside"] = True
|
|
# A result too large for the context was spilled to a file the agent may read
|
|
# back later: that file is outside content too.
|
|
if self._tool_result_spill_dir is not None:
|
|
for spilled in self._tool_result_spill_dir.glob(f"{self._step:04d}-*"):
|
|
self._agent_files.mark_outside(spilled)
|
|
self._add_message(message)
|
|
hidden = int((display or {}).get("hidden_by_filters") or 0)
|
|
stripped = int((display or {}).get("hidden_fields") or 0)
|
|
if hidden or stripped:
|
|
# The out-of-band trace the user CAN see: rule class + count, never content.
|
|
parts = []
|
|
if hidden:
|
|
parts.append(f"{hidden} result(s) hidden")
|
|
if stripped:
|
|
parts.append(f"{stripped} field value(s) stripped")
|
|
self._audit(
|
|
tool_call,
|
|
stage="filtered",
|
|
status="hidden",
|
|
reason=" · ".join(parts) + " by privacy filters",
|
|
)
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
self._note_ingestion(tool_call, status)
|
|
rule = self._standing_notes.pop(tool_call.id, "")
|
|
return Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"status": status,
|
|
"tool_call_id": tool_call.id,
|
|
"result_preview": _preview(result),
|
|
**({"display": display} if display else {}),
|
|
**({"standing_rule": rule} if rule else {}),
|
|
# (c) quiet provenance chip — same fields the `_display` sidecar persists.
|
|
**(_origin_fields(origin) if origin else {}),
|
|
**{k: v for k, v in outcome.items() if k != "status"},
|
|
},
|
|
)
|
|
|
|
def _note_ingestion(self, tool_call: ToolCall, status: str) -> None:
|
|
"""Record that outside content entered this session, and from where. The fact and
|
|
the source only — never the content, not even truncated.
|
|
|
|
**Nothing consumes this in v1.** It exists so that when the reviewer is eventually
|
|
offered the fact (v2, `PRV-1`), the question "would it have changed a verdict?" can
|
|
be answered by replaying a shadow run instead of re-argued. See
|
|
`session_facts.py` and the spec's Part 0.
|
|
|
|
Failed calls are skipped: a fetch that errored brought nothing in.
|
|
"""
|
|
if self.session_facts is None or status != "ok":
|
|
return
|
|
spec = self.registry.get(tool_call.name)
|
|
if not session_facts.is_ingesting(spec.metadata if spec else None):
|
|
return
|
|
record = self.session_facts.note(tool_call.name, tool_call.arguments)
|
|
self._audit(tool_call, **record.to_audit())
|
|
|
|
def _audit_usage(self, usage: Any) -> None:
|
|
"""One content-blind audit row per model round-trip (spec §5: the per-turn usage
|
|
event), so exported token columns are honest — tool rows only ever carried the
|
|
reviewer's own tokens. Stage "usage", the model in the (sanitized) args."""
|
|
if self.audit_sink is None:
|
|
return
|
|
try:
|
|
self.audit_sink(
|
|
{
|
|
**self.audit_context,
|
|
"stage": "usage",
|
|
"status": "ok",
|
|
"tool": "",
|
|
"arguments": {"model": self.model},
|
|
"tokens_in": int(getattr(usage, "input", 0) or 0),
|
|
"tokens_out": int(getattr(usage, "output", 0) or 0),
|
|
"cache_read": int(getattr(usage, "cache_read", 0) or 0),
|
|
"cache_write": int(getattr(usage, "cache_write", 0) or 0),
|
|
}
|
|
)
|
|
except Exception:
|
|
pass
|
|
|
|
def _audit(self, tool_call: ToolCall, **event: Any) -> None:
|
|
if self.audit_sink is None:
|
|
return
|
|
payload = {
|
|
**self.audit_context,
|
|
"tool": tool_call.name,
|
|
"arguments": tool_call.arguments,
|
|
# Every row carries the tool call's own ID so an external sink can join a
|
|
# `started` to its matching `finished` when the same tool+arguments runs more
|
|
# than once in a turn. Stamped here, at the one common boundary, so a new call
|
|
# site can't forget it. `**event` spreads last: a call site that means
|
|
# something else by `call_id` still wins.
|
|
"call_id": tool_call.id,
|
|
**event,
|
|
}
|
|
try:
|
|
self.audit_sink(payload)
|
|
except Exception:
|
|
pass
|
|
|
|
async def _handle_items_proposal(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""The decomposition gate: emit the proposed items, await the user's decision.
|
|
Approval creates them on the board (server-side, inside the approver) and the
|
|
result carries their ids; rejection returns feedback for a revised split."""
|
|
from .teams.proposals import validate_work_proposal
|
|
args = tool_call.arguments or {}
|
|
problem = None
|
|
try:
|
|
args = validate_work_proposal(args)
|
|
except ValueError as error:
|
|
problem = str(error)
|
|
if problem:
|
|
result: dict[str, Any] = {
|
|
"approved": False,
|
|
"error": problem,
|
|
}
|
|
elif self.items_approver is None:
|
|
result = {
|
|
"approved": False,
|
|
"error": "item proposals aren't available in this surface",
|
|
}
|
|
else:
|
|
yield Event(
|
|
EventType.ITEMS_PROPOSED,
|
|
{**args, "tool_call_id": tool_call.id},
|
|
)
|
|
self._audit(tool_call, stage="items_proposed")
|
|
result = await self._wait_tool(tool_call,
|
|
self.items_approver(dict(args), tool_call.id),
|
|
interrupted={"approved": False, "error": "interrupted by user"},
|
|
) or {"approved": False, "error": "no response"}
|
|
|
|
status = "ok" if result.get("approved") else "denied"
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"status": status,
|
|
"result_preview": _preview(result),
|
|
"tool_call_id": tool_call.id,
|
|
},
|
|
)
|
|
|
|
async def _handle_connector_request(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""`request_connector` (ask the human to connect a service) and `grant_connector`
|
|
(a lead asks the human to give one of its workers a connector) — spec §11.6.
|
|
Both are human gates: emit CONNECTOR_REQUESTED, await the out-of-band verdict,
|
|
hand it back. Declining is a normal outcome the coworker must work around and
|
|
say so; it is never an error."""
|
|
args = tool_call.arguments or {}
|
|
request = "grant" if tool_call.name == "grant_connector" else "connect"
|
|
connector = str(args.get("connector", "")).strip().lower()
|
|
worker = str(args.get("worker", "")).strip()
|
|
reason = str(args.get("reason", "")).strip()
|
|
if not connector or (request == "grant" and not worker):
|
|
result: dict[str, Any] = {
|
|
"approved": False,
|
|
"error": "name the connector" + (" and the worker" if request == "grant" else ""),
|
|
}
|
|
elif self.connector_requester is None:
|
|
result = {"approved": False, "error": "connector requests aren't available here"}
|
|
else:
|
|
yield Event(
|
|
EventType.CONNECTOR_REQUESTED,
|
|
{"request": request, "connector": connector, "worker": worker, "reason": reason},
|
|
)
|
|
self._audit(tool_call, stage="connector_requested", reason=reason)
|
|
result = await self._wait_tool(tool_call,
|
|
self.connector_requester(dict(args), tool_call.id),
|
|
interrupted={"approved": False, "error": "interrupted by user"},
|
|
) or {"approved": False, "error": "no response"}
|
|
if not result.get("approved"):
|
|
result.setdefault(
|
|
"guidance",
|
|
"The user declined. Carry on without it and say plainly what you could not do.",
|
|
)
|
|
status = "ok" if result.get("approved") else "denied"
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(tool_call, stage="finished", status=status, result=result, result_preview=_preview(result))
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{"name": tool_call.name, "tool_call_id": tool_call.id, "status": status, "result_preview": _preview(result)},
|
|
)
|
|
|
|
async def _handle_team_proposal(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""The staffing gate: emit the proposed roster, await the user's out-of-band
|
|
decision. Approval PRE-SPAWNS the worker sessions (server-side, inside the
|
|
approver) and the result carries the roster with actor ids so the lead can
|
|
assign; rejection returns the user's feedback for a revised proposal."""
|
|
from .teams.proposals import validate_team_proposal
|
|
from .teams.model import BoardError
|
|
args = tool_call.arguments or {}
|
|
problem = None
|
|
try:
|
|
args = validate_team_proposal(args)
|
|
validator = getattr(self.team_approver, "validate", None)
|
|
if validator:
|
|
validator(args)
|
|
except (ValueError, BoardError) as error:
|
|
problem = str(error)
|
|
members = args.get("members", []) if isinstance(args, dict) else []
|
|
if problem:
|
|
result: dict[str, Any] = {
|
|
"approved": False,
|
|
"error": problem,
|
|
}
|
|
elif self.team_approver is None:
|
|
result = {
|
|
"approved": False,
|
|
"error": "team staffing isn't available in this surface",
|
|
}
|
|
else:
|
|
yield Event(
|
|
EventType.TEAM_PROPOSED,
|
|
{
|
|
**args,
|
|
"tool_call_id": tool_call.id,
|
|
"members": members,
|
|
"enable_chat": bool(args.get("enable_chat", False)),
|
|
},
|
|
)
|
|
self._audit(tool_call, stage="team_proposed")
|
|
result = await self._wait_tool(tool_call,
|
|
self.team_approver(dict(args), tool_call.id),
|
|
interrupted={"approved": False, "error": "interrupted by user"},
|
|
) or {"approved": False, "error": "no response"}
|
|
|
|
status = "ok" if result.get("approved") else "denied"
|
|
message = self._timed_result(tool_call, result)
|
|
created = None
|
|
if result.get("approved") and result.get("team_id"):
|
|
created = {"team_id": result["team_id"], "workers": result.get("workers") or []}
|
|
message["_display"] = {"team_created": created}
|
|
self._add_message(message)
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"status": status,
|
|
"result_preview": _preview(result),
|
|
"display": {"team_created": created} if created else {},
|
|
"tool_call_id": tool_call.id,
|
|
},
|
|
)
|
|
|
|
async def _handle_plan_proposal(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""Emit the plan for review, await the user's out-of-band decision, and apply it:
|
|
approval flips the live PermissionEngine out of plan mode (the same session keeps
|
|
going, with all its exploration context); rejection keeps plan mode and returns
|
|
the user's feedback so the agent can revise."""
|
|
if self.permissions.mode is Mode.AUTO_APPROVE and self.plan_approval:
|
|
async for event in self._handle_step_plan(tool_call):
|
|
yield event
|
|
return
|
|
args = tool_call.arguments or {}
|
|
plan = str(args.get("plan", ""))
|
|
if self.permissions.mode is not Mode.PLAN:
|
|
# The tool is always registered (mode can flip mid-session), but proposing a
|
|
# plan only means something while the session is actually in plan mode. The
|
|
# right next step differs by mode: discuss stays read-only, so the agent
|
|
# should talk through the change; write-capable modes should just do it.
|
|
if self.permissions.mode is Mode.DISCUSS:
|
|
error = (
|
|
"not in plan mode — this is discuss mode (read-only), so describe "
|
|
"the proposed changes in chat instead"
|
|
)
|
|
else:
|
|
error = "not in plan mode — proceed with the work directly"
|
|
result: dict[str, Any] = {"approved": False, "error": error}
|
|
elif self.plan_approver is None:
|
|
result = {
|
|
"approved": False,
|
|
"error": "plan approval isn't available here",
|
|
}
|
|
else:
|
|
yield Event(EventType.PLAN_PROPOSED, {"plan": plan})
|
|
self._audit(tool_call, stage="plan_proposed")
|
|
result = await self._wait_tool(tool_call,
|
|
self.plan_approver(dict(args), tool_call.id),
|
|
interrupted={"approved": False, "error": "interrupted by user"},
|
|
) or {
|
|
"approved": False,
|
|
"error": "no response",
|
|
}
|
|
|
|
if result.get("approved"):
|
|
# The approver may pick the post-plan mode ("interactive" asks per write,
|
|
# "auto" executes the approved plan without further prompts).
|
|
try:
|
|
self.permissions.mode = Mode(str(result.get("mode", "interactive")))
|
|
except ValueError:
|
|
self.permissions.mode = Mode.INTERACTIVE
|
|
result = {
|
|
**result,
|
|
"mode": self.permissions.mode.value,
|
|
"note": "plan approved — implement it now",
|
|
}
|
|
|
|
status = "ok" if result.get("approved") else "denied"
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"tool_call_id": tool_call.id,
|
|
"status": status,
|
|
"result_preview": _preview(result),
|
|
},
|
|
)
|
|
|
|
async def _handle_step_plan(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""OPE-237: a plan in auto-approve. The user approves all of its steps or sends it
|
|
back; the mode never changes. Approved steps are kept (targets only, never the
|
|
summary) for `_facts_kw` to match later actions against, until the request ends."""
|
|
args = tool_call.arguments or {}
|
|
plan = str(args.get("plan", ""))
|
|
steps, dropped = plan_steps.normalize_steps(args.get("steps"))
|
|
if self._auto_answering():
|
|
result: dict[str, Any] = {
|
|
"approved": False,
|
|
"error": "No one is available to approve a plan. Carry on with the work; "
|
|
"each action is reviewed as usual.",
|
|
}
|
|
elif self.plan_approver is None:
|
|
result = {"approved": False, "error": "plan approval is not available here"}
|
|
elif not steps:
|
|
result = {
|
|
"approved": False,
|
|
"error": "list every action in `steps` (kind write / delete / run / send, its "
|
|
"target, and for send the destination), then propose again",
|
|
**({"dropped_steps": dropped} if dropped else {}),
|
|
}
|
|
else:
|
|
shown = [
|
|
{
|
|
**step.as_dict(),
|
|
"risky": plan_steps.step_is_risky(step, resolve=self.permissions._candidate)
|
|
or (step.kind in ("write", "delete") and not self.permissions._under_writable_root(step.target)),
|
|
}
|
|
for step in steps
|
|
]
|
|
yield Event(
|
|
EventType.PLAN_PROPOSED,
|
|
{"plan": plan, "steps": shown, "auto_approve": True, "tool_call_id": tool_call.id},
|
|
)
|
|
self._audit(tool_call, stage="plan_proposed")
|
|
decision = await self._wait_tool(
|
|
tool_call,
|
|
self.plan_approver({**args, "plan": plan, "steps": shown}, tool_call.id),
|
|
interrupted={"approved": False, "error": "interrupted by user"},
|
|
) or {"approved": False, "error": "no response"}
|
|
if decision.get("approved"):
|
|
self._approved_plan = steps # a later plan replaces an earlier one
|
|
result = {
|
|
"approved": True,
|
|
"steps": [step.as_dict() for step in steps],
|
|
"note": "plan approved for this request: carry out exactly these steps; "
|
|
"anything else is reviewed as usual",
|
|
**({"dropped_steps": dropped} if dropped else {}),
|
|
}
|
|
else:
|
|
result = {
|
|
"approved": False,
|
|
**({"error": decision["error"]} if decision.get("error") else {}),
|
|
"feedback": decision.get("feedback") or "the user rejected the plan",
|
|
}
|
|
|
|
status = "ok" if result.get("approved") else "denied"
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"status": status,
|
|
"tool_call_id": tool_call.id,
|
|
"result_preview": _preview(result),
|
|
},
|
|
)
|
|
|
|
async def _handle_tool_request(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""Emit the install prompt, await the user's decision, hand the outcome back.
|
|
|
|
Declining is a normal outcome, not an error: the result tells the agent to fall back
|
|
and disclose the gap, because a security report that quietly loses a check is worse
|
|
than one that says which checks it couldn't run.
|
|
"""
|
|
args = tool_call.arguments or {}
|
|
name = str(args.get("name", "")).strip()
|
|
reason = str(args.get("reason", ""))
|
|
fallback_guidance = (
|
|
"Continue without it: use a fallback check if you have one, and say in "
|
|
"your report which checks were degraded."
|
|
)
|
|
|
|
if not name or (self.tool_requester is None and not self._auto_answering()):
|
|
result: dict[str, Any] = {
|
|
"installed": False,
|
|
"error": "tool requests aren't available here",
|
|
"guidance": fallback_guidance,
|
|
}
|
|
elif _toolchain.describe(name) is not None and self._auto_answering():
|
|
# Attendance "auto": nobody will approve the card, and the install is the
|
|
# verified pinned build (version + digest fixed in the catalog) — run it and
|
|
# record the outcome. The rule follows the catalog, not a list of names.
|
|
info = _toolchain.describe(name) or {}
|
|
self._audit(tool_call, stage="tool_auto_install", reason=reason)
|
|
try:
|
|
path = await asyncio.to_thread(_toolchain.install, name)
|
|
result = {
|
|
"installed": True,
|
|
"path": path,
|
|
"version": info.get("version", ""),
|
|
"note": "installed by the unattended-auto rule (pinned, checksum-verified)",
|
|
}
|
|
except Exception as exc: # noqa: BLE001 - the agent must hear why
|
|
result = {
|
|
"installed": False,
|
|
"error": f"install failed: {exc}",
|
|
"guidance": fallback_guidance,
|
|
}
|
|
elif _toolchain.describe(name) is None:
|
|
# Not in the pinned catalog: no card at all (owner-hit 2026-08-20 — agents
|
|
# routed ordinary brew/pip installs through the install card, which could
|
|
# only fail after approval). The agent has a shell with its own approval
|
|
# flow; steer it there instead of at the user.
|
|
catalog = ", ".join(sorted(_toolchain.MANAGED))
|
|
result = {
|
|
"installed": False,
|
|
"error": (
|
|
f"'{name}' is not in the pinned tool catalog ({catalog})."
|
|
),
|
|
"guidance": (
|
|
"Install it yourself with the shell (brew/pip/…, subject to the "
|
|
"normal command approval), or continue without it and say in your "
|
|
"report which checks were degraded."
|
|
),
|
|
}
|
|
else:
|
|
# The prompt must say up front whether WE can install this (pinned build for
|
|
# this platform) — a card that offers Install for a tool we can't fetch turns
|
|
# the user's approval into a guaranteed error. Absence of metadata means NO.
|
|
info = _toolchain.describe(name)
|
|
yield Event(
|
|
EventType.TOOL_REQUESTED,
|
|
{
|
|
"name": name,
|
|
"reason": reason,
|
|
"installable": info is not None,
|
|
"version": (info or {}).get("version", ""),
|
|
"summary": (info or {}).get("summary", ""),
|
|
"source": (info or {}).get("source", ""),
|
|
},
|
|
)
|
|
self._audit(tool_call, stage="tool_requested", reason=reason)
|
|
result = await self._wait_tool(tool_call,
|
|
self.tool_requester(dict(args), tool_call.id),
|
|
interrupted={"installed": False, "error": "interrupted by user"},
|
|
) or {"installed": False, "error": "no response"}
|
|
if not result.get("installed"):
|
|
# The card says "or install it yourself and continue" — honor it. A user
|
|
# who brewed the tool mid-prompt and clicked Continue has PROVIDED it,
|
|
# not declined it; find their copy before treating this as a refusal.
|
|
found = _toolchain.resolve(name)
|
|
if found:
|
|
result = {
|
|
"installed": True,
|
|
"path": found,
|
|
"note": (
|
|
"the user provided their own copy instead of the managed "
|
|
"install — use it from this path"
|
|
),
|
|
}
|
|
if not result.get("installed"):
|
|
result.setdefault(
|
|
"guidance",
|
|
"Continue without it: use a fallback check if you have one, and say in "
|
|
"your report which checks were degraded.",
|
|
)
|
|
|
|
status = "ok" if result.get("installed") else "denied"
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"tool_call_id": tool_call.id,
|
|
"status": status,
|
|
"result_preview": _preview(result),
|
|
},
|
|
)
|
|
|
|
def _network_request_payload(self, tool_call: ToolCall, decision: Any) -> dict[str, Any]:
|
|
"""What the network-access card shows: each site, and how long ago the session's
|
|
sandbox last blocked it (None when no command has tried it). `evidence` is false
|
|
where the sandbox cannot say what it blocked; the card then claims nothing."""
|
|
last: dict[str, float] = {}
|
|
workspace = getattr(self, "sandbox_workspace", None)
|
|
evidence = bool(getattr(workspace, "reports_blocked", False))
|
|
try:
|
|
for when, entry in (workspace.blocked_since(0.0) if evidence else []):
|
|
last[entry] = max(when, last.get(entry, 0.0))
|
|
except Exception: # noqa: BLE001 - evidence is a help, never a reason to fail the card
|
|
last, evidence = {}, False
|
|
now = time.time()
|
|
return {
|
|
"reason": str((tool_call.arguments or {}).get("reason", ""))[:500],
|
|
"evidence": evidence,
|
|
"hosts": [
|
|
{"host": entry, "blocked_seconds_ago": (max(0, int(now - last[entry])) if entry in last else None)}
|
|
for entry in decision.network_hosts
|
|
],
|
|
}
|
|
|
|
async def _handle_directory_request(
|
|
self, tool_call: ToolCall
|
|
) -> AsyncIterator[Event]:
|
|
"""Emit the grant prompt, await the user's out-of-band decision (which the requester also
|
|
applies to this session's roots), and return the outcome as the tool result."""
|
|
args = tool_call.arguments or {}
|
|
if self._auto_answering():
|
|
# Attendance "auto": there is no picker and no person to choose. The reply
|
|
# says what the agent can still do, and to stop rather than guess when the
|
|
# task truly needs the user. No grant, no card.
|
|
unscoped = self.permissions.mode is Mode.DANGEROUSLY_BYPASS_APPROVALS
|
|
result: dict[str, Any] = {
|
|
"granted": False,
|
|
"error": (
|
|
_attendance.AUTO_DIRECTORY_REPLY_UNSCOPED
|
|
if unscoped
|
|
else _attendance.AUTO_DIRECTORY_REPLY
|
|
),
|
|
}
|
|
self._audit(
|
|
tool_call,
|
|
stage="directory_auto_refused",
|
|
reason=str(args.get("reason", "")),
|
|
)
|
|
elif self.directory_requester is None:
|
|
result = {
|
|
"granted": False,
|
|
"error": "directory requests aren't available here",
|
|
}
|
|
else:
|
|
yield Event(
|
|
EventType.DIRECTORY_REQUESTED,
|
|
{
|
|
"reason": str(args.get("reason", "")),
|
|
"path": str(args.get("path", "")),
|
|
"writable": bool(args.get("writable", False)),
|
|
# Root promotion (workspace-scratch-design.md §5): the agent asks for
|
|
# the folder to become the session's primary workspace — the consent
|
|
# card must say so, it's a different grant than a plain extra root.
|
|
"primary": bool(args.get("primary", False)),
|
|
},
|
|
)
|
|
self._audit(
|
|
tool_call,
|
|
stage="directory_requested",
|
|
reason=str(args.get("reason", "")),
|
|
)
|
|
result = await self._wait_tool(tool_call,
|
|
self.directory_requester(dict(args), tool_call.id),
|
|
interrupted={"granted": False, "error": "interrupted by user"},
|
|
) or {
|
|
"granted": False,
|
|
"error": "no response",
|
|
}
|
|
|
|
status = "ok" if result.get("granted") else "denied"
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"tool_call_id": tool_call.id,
|
|
"status": status,
|
|
"result_preview": _preview(result),
|
|
},
|
|
)
|
|
|
|
async def _handle_ask_user(self, tool_call: ToolCall) -> AsyncIterator[Event]:
|
|
"""Emit the question, await the user's out-of-band answer (inline in the live session or
|
|
from the Inbox when unattended), and return it as the tool result."""
|
|
args = tool_call.arguments or {}
|
|
question = str(args.get("question", "")).strip()
|
|
# Grouped form (OPE-51): `questions` alone is a valid call — the singular field may be
|
|
# empty. The asker normalizes/validates the entries; here only "is anything asked?".
|
|
if not question:
|
|
for entry in args.get("questions") or []:
|
|
if isinstance(entry, dict) and str(entry.get("question", "")).strip():
|
|
question = str(entry["question"]).strip()
|
|
break
|
|
if not question or (self.question_asker is None and not self._auto_answering()):
|
|
result: dict[str, Any] = {
|
|
"answer": "",
|
|
"error": (
|
|
"no question was asked"
|
|
if not question
|
|
else "asking isn't available here"
|
|
),
|
|
}
|
|
elif self._auto_answering():
|
|
# Attendance "auto": the fixed least-destructive answer stands in for the
|
|
# person, one copy per grouped question, keyed the way the surfaces key them.
|
|
grouped = [
|
|
entry
|
|
for entry in (args.get("questions") or [])
|
|
if isinstance(entry, dict) and str(entry.get("question", "")).strip()
|
|
]
|
|
if grouped:
|
|
result = {
|
|
"answers": {
|
|
str(entry.get("header") or entry.get("question")): _attendance.AUTO_QUESTION_ANSWER
|
|
for entry in grouped
|
|
}
|
|
}
|
|
else:
|
|
result = {"answer": _attendance.AUTO_QUESTION_ANSWER}
|
|
self._audit(tool_call, stage="question_auto_answered", reason=question)
|
|
else:
|
|
# The asker is mode-aware (attended → live inline prompt; unattended → Inbox), so it
|
|
# owns surfacing the question. The engine just awaits the answer.
|
|
self._audit(tool_call, stage="question_requested", reason=question)
|
|
result = await self._wait_tool(tool_call,
|
|
self.question_asker(dict(args), tool_call.id),
|
|
interrupted={"answer": "", "error": "interrupted by user"},
|
|
) or {
|
|
"answer": "",
|
|
"error": "no response",
|
|
}
|
|
|
|
# A skipped question answers None (OPE-153), so an all-skipped card is "denied" like an
|
|
# unanswered one — `answers` being non-empty isn't enough on its own.
|
|
replies = result.get("answers")
|
|
status = (
|
|
"ok"
|
|
if (
|
|
result.get("answer")
|
|
or (isinstance(replies, dict) and any(v is not None for v in replies.values()))
|
|
)
|
|
else "denied"
|
|
)
|
|
if status == "ok":
|
|
self._note_ask_replies(result, question)
|
|
self._add_message(self._timed_result(tool_call, result))
|
|
self._audit(
|
|
tool_call,
|
|
stage="finished",
|
|
status=status,
|
|
result=result,
|
|
result_preview=_preview(result),
|
|
)
|
|
yield Event(
|
|
EventType.TOOL_FINISHED,
|
|
{
|
|
"name": tool_call.name,
|
|
"tool_call_id": tool_call.id,
|
|
"status": status,
|
|
"result_preview": _preview(result),
|
|
},
|
|
)
|
|
|
|
def _note_ask_replies(
|
|
self, result: dict[str, Any], question: str = ""
|
|
) -> None:
|
|
"""Record the user's ask_user answer(s) for the reviewer's history (§8.2),
|
|
together with the agent's question — shown to the judge explicitly framed as
|
|
agent-authored data (same Rule-3 discipline as tool arguments), so a structured
|
|
answer counts as evidence for exactly the question's scope (owner ruling
|
|
2026-08-24). Anchored to the number of user messages present now, so the merge
|
|
stays chronological however the session continues.
|
|
|
|
A fresh answer also resets the §8.4 denial streak: the user is present and just
|
|
gave direction — the reviewer deserves a fresh look at what follows."""
|
|
self._reviewer_denials = 0
|
|
anchor = sum(1 for m in self.messages if m.get("role") == "user" and not m.get("source"))
|
|
answers = result.get("answers")
|
|
# Skipped questions answer None (OPE-153) — dropped here, else str(None) files "None"
|
|
# as something the user actually said.
|
|
values = (
|
|
[str(v) for v in answers.values() if v is not None]
|
|
if isinstance(answers, dict)
|
|
else [str(result.get("answer") or "")]
|
|
)
|
|
q = (question or "").strip()
|
|
for text in values:
|
|
text = text.strip()
|
|
if text:
|
|
self._ask_replies.append((anchor, text, q))
|
|
|
|
def _inject_steering(self) -> None:
|
|
for text, source, activity in self._steering:
|
|
message: dict[str, Any] = {
|
|
"role": "user",
|
|
"content": text,
|
|
"ts": time.time(),
|
|
}
|
|
if source is not None:
|
|
message["source"] = source
|
|
if activity:
|
|
message["_activity"] = activity
|
|
self._add_message(message)
|
|
self._steering = []
|
|
|
|
def _outbound_messages(self) -> list[dict[str, Any]]:
|
|
"""`self.messages` prepared for the provider. The SOLE provider feed (see `_astream`).
|
|
|
|
Every message is stripped of the display-only sidecars — `source`, `_display`, `ts`
|
|
and `mid` — (providers reject unknown keys), unconditionally — whether or not a
|
|
`<system-context>` block is added. When a context
|
|
provider yields a non-empty string, an ephemeral `<system-context>` block is appended to the
|
|
last user message. A partial assistant turn abandoned by a turn that died mid-stream —
|
|
identified by the error/interrupted notice that follows it — is dropped too: display-only
|
|
like the notices, and rejected outright by several providers as the final message.
|
|
Never mutates `self.messages`, so none of this is persisted/replayed.
|
|
"""
|
|
# Strip the display-only sidecars — `source` (connector cards), `_display`
|
|
# (e.g. filter-hidden counts), `ts` (append-time timestamps), `mid` (stable message ids), `reasoning`
|
|
# (thinking text), `usage` (token counts), `finish_reason` (how the reply ended)
|
|
# and `max_output_tokens` (the ceiling sent) — copying only messages that carry
|
|
# one. Whole `notice` messages (error/interrupted/model-switch markers) are
|
|
# display-only too: dropped entirely.
|
|
_SIDECARS = (
|
|
"source",
|
|
"_activity",
|
|
"timing",
|
|
"_display",
|
|
"_outside",
|
|
"ts",
|
|
"mid",
|
|
"reasoning",
|
|
"usage",
|
|
"finish_reason",
|
|
"max_output_tokens",
|
|
"reasoning_effort",
|
|
"served_by",
|
|
"replay",
|
|
)
|
|
# Auto-compaction (OPE-27): everything before the boundary is represented by the
|
|
# compacted block. Outbound-only — the canonical history stays intact — and the
|
|
# block+tail are byte-stable between turns, so prompt caching keeps working.
|
|
source_messages = _compaction.apply_to_outbound(
|
|
self.messages, self.compaction_state
|
|
)
|
|
# Runtime receipts stay out of provider payloads. Reminder/board context is
|
|
# earlier agent context, not words attributed to the incoming user and never
|
|
# a system instruction. Keep the actual user message verbatim and last.
|
|
expanded = []
|
|
for msg in source_messages:
|
|
context = (msg.get("_activity") or {}).get("text")
|
|
if context:
|
|
expanded.append({"role": "assistant", "content": context})
|
|
expanded.append(msg)
|
|
source_messages = expanded
|
|
# A turn that dies mid-stream (provider error, interrupt) leaves its partial assistant
|
|
# message in the transcript — so the user can still see what streamed — followed by the
|
|
# notice saying why it stopped. That partial is display-only in the same sense the
|
|
# notices are: not a turn the model finished, and several providers reject it as the
|
|
# FINAL message. Gemini 400s ("Requests ending with a model turn are not supported"),
|
|
# Claude 4.6+ 400s ("does not support assistant message prefill"), and one ending in
|
|
# whitespace 400s on older Claude ("final assistant content cannot end with trailing
|
|
# whitespace"). `retry()` replays the same tail, so the session wedges for good.
|
|
# The trailing notice is what identifies it: a COMPLETED turn's assistant message looks
|
|
# identical but has no error/interrupted notice after it, and must be kept (its `extras`
|
|
# sidecar is replayed back to the owning provider). Trailing `tool_calls` mean a turn
|
|
# suspended awaiting durable resume (see `resume`), never an abandoned one. Consecutive
|
|
# failed retries stack one partial each, so walk back through the whole run.
|
|
abandoned: set[int] = set()
|
|
failed = False
|
|
for i in range(len(source_messages) - 1, -1, -1):
|
|
message = source_messages[i]
|
|
if message.get("role") == "notice":
|
|
failed = failed or message.get("kind") in ("error", "interrupted")
|
|
continue
|
|
if (
|
|
failed
|
|
and message.get("role") == "assistant"
|
|
and not message.get("tool_calls")
|
|
):
|
|
abandoned.add(i)
|
|
failed = False # that notice belongs to this partial
|
|
continue
|
|
break
|
|
out = [
|
|
(
|
|
# OPE-171: a length-truncated, action-free reply is replayed as a stub.
|
|
{"role": "assistant", "content": TRUNCATION_STUB}
|
|
if msg.get("replay") == "stub"
|
|
else {k: v for k, v in msg.items() if k not in _SIDECARS}
|
|
if any(s in msg for s in _SIDECARS)
|
|
else msg
|
|
)
|
|
for i, msg in enumerate(source_messages)
|
|
if msg.get("role") != "notice" and i not in abandoned
|
|
]
|
|
# PDF attachments (stored as `file` parts) are adapted to the ACTIVE model right
|
|
# here — never in the persisted history — so a mid-session model switch always
|
|
# re-decides: native PDF models get the real document, the rest get the local
|
|
# text-extract/page-image fallback (pdf_support.py).
|
|
if any(
|
|
isinstance(p, dict) and p.get("type") == "file"
|
|
for msg in out
|
|
if isinstance(msg.get("content"), list)
|
|
for p in msg["content"]
|
|
):
|
|
caps = self.provider.capabilities(self.model)
|
|
if not getattr(caps, "pdf", False):
|
|
from . import pdf_support
|
|
|
|
out = [
|
|
(
|
|
{
|
|
**msg,
|
|
"content": pdf_support.adapt_content(msg["content"], caps),
|
|
}
|
|
if isinstance(msg.get("content"), list)
|
|
else msg
|
|
)
|
|
for msg in out
|
|
]
|
|
|
|
# Images get the same per-turn treatment: a model without vision receives a visible
|
|
# placeholder instead of a payload it would reject. Like the PDF path, this re-decides
|
|
# per call, so a mid-session switch to/from a vision model always does the right thing.
|
|
if any(
|
|
isinstance(p, dict) and p.get("type") == "image_url"
|
|
for msg in out
|
|
if isinstance(msg.get("content"), list)
|
|
for p in msg["content"]
|
|
):
|
|
caps = self.provider.capabilities(self.model)
|
|
if not getattr(caps, "vision", False):
|
|
placeholder = {
|
|
"type": "text",
|
|
"text": "[image attachment — not viewable by this model]",
|
|
}
|
|
out = [
|
|
(
|
|
{
|
|
**msg,
|
|
"content": [
|
|
(
|
|
placeholder
|
|
if isinstance(p, dict)
|
|
and p.get("type") == "image_url"
|
|
else p
|
|
)
|
|
for p in msg["content"]
|
|
],
|
|
}
|
|
if isinstance(msg.get("content"), list)
|
|
else msg
|
|
)
|
|
for msg in out
|
|
]
|
|
|
|
context = (
|
|
self.context_provider() if self.context_provider is not None else ""
|
|
) or ""
|
|
self._last_context_block = context
|
|
if not context:
|
|
return out
|
|
# The block rides on the LAST user message — one shape for every provider. In a
|
|
# chat that is the newest message; in a tool loop (tool results carry role "tool")
|
|
# it is the task prompt, message one. That is only safe because the block holds
|
|
# nothing that moves on its own. OPE-192: it used to open with a `Now:` line to the
|
|
# minute, so every minute crossing rewrote message one, and a provider's prompt
|
|
# cache is reusable only up to the first byte that differs — the whole conversation
|
|
# was re-processed (measured: 16 of 105 calls on one Fable 5.1 attempt held 95% of
|
|
# its cache writes; on the Kimi K3 run 60% of minute crossings missed vs 1.5%
|
|
# otherwise). The time is a tool now (`current_time`). What is left — folders,
|
|
# skill menu, mode notices — changes only when the user changes something, so the
|
|
# outbound history stays byte-identical turn to turn. Ephemeral: never persisted.
|
|
block = (
|
|
f"\n\n{EPHEMERAL_CONTEXT_OPEN}\n"
|
|
"(automatic per-turn context, not part of the user's message)\n"
|
|
f"{context}\n</system-context>"
|
|
)
|
|
for i in range(len(out) - 1, -1, -1):
|
|
if out[i].get("role") != "user":
|
|
continue
|
|
msg = dict(out[i])
|
|
content = msg.get("content")
|
|
if isinstance(content, str):
|
|
msg["content"] = content + block
|
|
elif isinstance(content, list): # content-parts (text + images)
|
|
msg["content"] = [*content, {"type": "text", "text": block}]
|
|
else:
|
|
msg["content"] = block
|
|
out[i] = msg
|
|
break
|
|
return out
|
|
|
|
|
|
def _effort_record(turn: AssistantTurn, setting: Optional[str]) -> Optional[dict[str, Any]]:
|
|
"""What the run record says about reasoning effort for this reply (OPE-176): the
|
|
provider's own mapping when it reported one; otherwise, when a level was configured,
|
|
an explicit "requested but not reported" so the setting is never silently lost."""
|
|
if turn.effort:
|
|
return dict(turn.effort)
|
|
if setting:
|
|
return {
|
|
"requested": setting,
|
|
"effective": None,
|
|
"note": "provider did not report an effort parameter (no knob on this path)",
|
|
}
|
|
return None
|
|
|
|
|
|
def _assistant_message(
|
|
turn: AssistantTurn, model: Optional[str] = None, effort_setting: Optional[str] = None
|
|
) -> dict[str, Any]:
|
|
message: dict[str, Any] = {
|
|
"role": "assistant",
|
|
"content": turn.text or "",
|
|
"ts": time.time(),
|
|
}
|
|
if turn.usage is not None:
|
|
# Display/aggregation sidecar (like `reasoning`): persisted with the message,
|
|
# stripped before provider calls. Tagged with the model that produced it so
|
|
# per-model rollups survive mid-session model switches.
|
|
message["usage"] = {"model": model, **turn.usage.as_dict()}
|
|
if turn.finish_reason:
|
|
# How the reply ended, in the engine's normalised vocabulary (`stop` /
|
|
# `tool_calls` / `length`; unknown provider values pass through). Persisted
|
|
# so a saved session can tell "chose to stop" from "hit the output limit"
|
|
# without re-deriving it from token counts (OPE-173). Omitted — never null —
|
|
# for partial turns and providers that report no stop reason. Stripped before
|
|
# every provider call (`_outbound_messages`). The provider's raw value, where
|
|
# it differs, lives in that provider's sidecar (e.g. `_anthropic.stop_reason`).
|
|
message["finish_reason"] = turn.finish_reason
|
|
if turn.output_limit:
|
|
# The per-reply output ceiling the provider actually sent (OPE-177), so a
|
|
# `length` finish can be read against the limit that produced it. Display
|
|
# sidecar like `usage`: stripped before every provider call.
|
|
message["max_output_tokens"] = turn.output_limit
|
|
effort_record = _effort_record(turn, effort_setting)
|
|
if effort_record:
|
|
# The reasoning-effort mapping for this reply (OPE-176). Display sidecar like
|
|
# `usage`: stripped before every provider call.
|
|
message["reasoning_effort"] = effort_record
|
|
if turn.served_by:
|
|
# The upstream host a router reported for this reply (display sidecar).
|
|
message["served_by"] = turn.served_by
|
|
if turn.reasoning:
|
|
# Display-only thinking text — rendered by the GUI, stripped for every provider
|
|
# (`_outbound_messages`); provider-private replay blocks go via `extras` instead.
|
|
message["reasoning"] = turn.reasoning
|
|
if turn.extras:
|
|
# Provider-private sidecars (e.g. `_gemini` thought signatures) persist with the
|
|
# message; the owning provider reattaches them, the rest strip them (base.py).
|
|
message.update(turn.extras)
|
|
if turn.tool_calls:
|
|
message["tool_calls"] = [
|
|
{
|
|
"id": tc.id,
|
|
"type": "function",
|
|
"function": {"name": tc.name, "arguments": json.dumps(tc.arguments)},
|
|
}
|
|
for tc in turn.tool_calls
|
|
]
|
|
return message
|
|
|
|
|
|
_MANGLED_PREVIEW_CHARS = 200
|
|
|
|
|
|
def _is_mangled(tool_call: ToolCall) -> bool:
|
|
"""Provider arg-parsers fall back to `{"_raw": <unparsed text>}` when a tool call's
|
|
arguments aren't a JSON object (typically a stream truncated mid-arguments)."""
|
|
return set(tool_call.arguments or {}) == {"_raw"}
|
|
|
|
|
|
def _sanitize_mangled_calls(turn: AssistantTurn) -> None:
|
|
"""Shrink each mangled call's stored raw text to a short preview BEFORE the turn
|
|
enters history. The full text is junk (half a JSON document): replaying it costs
|
|
thousands of tokens per turn and, worse, teaches the model that `_raw` is a real
|
|
parameter shape it should imitate."""
|
|
for tc in turn.tool_calls:
|
|
if _is_mangled(tc):
|
|
raw = str(tc.arguments.get("_raw") or "")
|
|
if len(raw) > _MANGLED_PREVIEW_CHARS:
|
|
tc.arguments = {
|
|
"_raw": raw[:_MANGLED_PREVIEW_CHARS]
|
|
+ f"… [unparsed tool-call text, {len(raw)} chars, truncated in history]"
|
|
}
|
|
|
|
|
|
def _tool_result_message(tool_call: ToolCall, result: Any) -> dict[str, Any]:
|
|
content = result if isinstance(result, str) else json.dumps(result, default=str)
|
|
return {
|
|
"role": "tool",
|
|
"tool_call_id": tool_call.id,
|
|
"content": content,
|
|
"ts": time.time(),
|
|
}
|
|
|
|
|
|
def _origin_fields(origin: dict[str, Any]) -> dict[str, Any]:
|
|
"""The approval-provenance fields, as the TOOL_FINISHED event and the persisted
|
|
`_display` sidecar both carry them."""
|
|
return {
|
|
"approval_origin": origin.get("origin", ""),
|
|
**({"approval_note": origin["note"]} if origin.get("note") else {}),
|
|
**({"approval_grant": origin["grant"]} if origin.get("grant") else {}),
|
|
**({"approval_tier": origin["tier"]} if origin.get("tier") else {}),
|
|
**({"approval_effect": origin["effect"]} if origin.get("effect") else {}),
|
|
}
|
|
|
|
|
|
def _call_outcome(tool_call: ToolCall, result: Any, status: str) -> dict[str, Any]:
|
|
"""What the turn summary needs beyond the 300-char preview (OPE-238): a non-ok
|
|
status, and for `run_shell` the exit code (None when unknown), whether it timed
|
|
out, and whether it was only started in the background."""
|
|
out: dict[str, Any] = {}
|
|
if status != "ok":
|
|
out["status"] = status
|
|
if tool_call.name == "run_shell" and isinstance(result, dict):
|
|
if result.get("task_id") and result.get("status") == "running":
|
|
out["background"] = True
|
|
elif "exit_code" in result:
|
|
code = result.get("exit_code")
|
|
out["exit_code"] = code if isinstance(code, int) and not isinstance(code, bool) else None
|
|
if result.get("timed_out"):
|
|
out["timed_out"] = True
|
|
return out
|
|
|
|
|
|
def _tool_error_message(tool_call: ToolCall, reason: str) -> dict[str, Any]:
|
|
return {
|
|
"role": "tool",
|
|
"tool_call_id": tool_call.id,
|
|
"content": json.dumps({"error": "tool call not executed", "reason": reason}),
|
|
"ts": time.time(),
|
|
}
|
|
|
|
|
|
def _preview(value: Any, max_chars: int = 300) -> str:
|
|
text = value if isinstance(value, str) else json.dumps(value, default=str)
|
|
text = text.replace("\n", "\\n")
|
|
return text if len(text) <= max_chars else text[: max_chars - 3] + "..."
|