Python
fix(observability): record mid-turn setting changes, sandbox sites and steering (OPE-244)
Devika Verma5021a37e5563
diff --git a/coworker/engine.py b/coworker/engine.pyindex 191fb2e9..c94c11b2 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -575,6 +575,7 @@ class TurnEngine:self._last_context_block = ""self._turn_context_hash: Optional[str] = Noneself._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 (@@ -693,31 +694,69 @@ class TurnEngine:if m.get("role") == "assistant" and m.get("tool_calls")),None,)- reviewer_kind = (- _REVIEWER_KINDS.get(getattr(self, "reviewer_choice", "session"), "session_model")- if self.reviewer is not None else None- )- try:- attended = bool(self.is_attended and self.is_attended())- except Exception: # noqa: BLE001 - a broken getter must not break the turn- attended = False- self._obs.begin_turn(+ attended, reviewer = self._attended_now(), self._reviewer_facts()+ stamp = self._turn_stamp()+ turn_id = self._obs.begin_turn(kind=kind,trigger=trigger,attrs={"approval_mode": self.permissions.mode.value,"attended": attended,- "reviewer": {- "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,- },+ "reviewer": reviewer,},- stamp=self._turn_stamp(),+ 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 _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 = _stamps.sandbox_stamp(getattr(self, "sandbox_workspace", None))+ 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."""@@ -1059,6 +1098,7 @@ class TurnEngine:yield Event(EventType.ERROR, {"error": text, "error_type": type(exc).__name__})returninfo = 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})@_records_turn("resume")@@ -1621,6 +1661,7 @@ class TurnEngine:self.model_settings,)self._note_context()+ self._note_stamp()provider = self.providerdef produce():diff --git a/coworker/observability/stamps.py b/coworker/observability/stamps.pyindex 6b3d0c23..db608238 100644--- a/coworker/observability/stamps.py+++ b/coworker/observability/stamps.py@@ -101,10 +101,23 @@ def sandbox_stamp(workspace: Any) -> Optional[dict[str, Any]]:def _site_count(workspace: Any) -> Optional[int]:- sites = getattr(getattr(workspace, "provider", None), "allowed_sites", None)+ """How many sites the sandbox lets through: its profile's own hosts, the machine's added+ hosts and the hosts the copied logins need (OpenShell). None for the `open` profile (any+ host) or a sandbox that keeps no list. No provider has an `allowed_sites` list, which the+ first version read, so this was always None (V2-28)."""+ from ..sandbox import network_profiles++ provider = getattr(workspace, "provider", None)+ profile = getattr(provider, "profile", None)+ extra = getattr(provider, "extra_hosts", None)+ if not isinstance(profile, str) or extra is None:+ return Nonetry:- return len(sites) if sites is not None else None- except TypeError:+ if network_profiles.is_open(profile):+ return None+ copied = getattr(getattr(provider, "copied", None), "hosts", None) or []+ return len({*network_profiles.hosts(profile), *extra, *copied})+ except (ValueError, TypeError):return Nonediff --git a/coworker/server/manager.py b/coworker/server/manager.pyindex e1fddf3d..54be9087 100644--- a/coworker/server/manager.py+++ b/coworker/server/manager.py@@ -7311,9 +7311,11 @@ class SessionManager:# semantics intact while grouping check-ins in the transcript.source = self._board_source(team, message, rows=activity["board_rows"])source["board"]["check_in"] = True- # Who started the turn (observability §4): board activity and team timers wake a- # team; a session's own timer is a schedule; anything else came from a channel.- if board_delivery:+ # Who started the turn (observability §4): board activity, a lead's steering and+ # team timers wake a team; a session's own timer is a schedule; anything else came+ # from a channel. Steering arrives as the `team` connector (`steer_worker`); it+ # was recorded as `channel` (V2-30).+ if board_delivery or (source or {}).get("connector") == "team":trigger = "team_wake"elif wake is not None:trigger = "team_wake" if self.teams.for_lead_session(session_id) is not None else "schedule"diff --git a/surfaces/gui/src/components/StepsPanel.tsx b/surfaces/gui/src/components/StepsPanel.tsxindex 2ee15617..e116611e 100644--- a/surfaces/gui/src/components/StepsPanel.tsx+++ b/surfaces/gui/src/components/StepsPanel.tsx@@ -678,11 +678,18 @@ function Inspector({ d, turn, steps, sessionId, t }: { d: any; turn: RecordedTur[t("steps.detail.tokens_after"), a.tokens_after == null ? "—" : formatTokens(a.tokens_after)]);}if (d.kind === "context") rows.push([t("steps.detail.session_prompt"), <span className="steps-mono">{a.session_prompt_hash || "—"}</span>]);+ const changed = d.kind === "notice" && d.name === "stamp_changed" ? stampChanges(a, t) : [];const showsContext = d.kind === "context" || (d.kind === "notice" && d.name === "context_changed");return (<><h3 className="steps-h3"><span className={`steps-kind k-${kind}`} />{stepLabel(d, t)}<span className={`steps-pill ${pill.cls}`}>{pill.text}</span></h3><Kv rows={rows} />+ {changed.length > 0 && (+ <>+ <Sec label={t("steps.insp.changed")} />+ <Kv rows={changed} />+ </>+ )}{showsContext && (<><Sec label={d.kind === "context" ? t("steps.insp.context_added") : t("steps.insp.context_now")} />@@ -704,6 +711,28 @@ function Inspector({ d, turn, steps, sessionId, t }: { d: any; turn: RecordedTur);}+/** A `stamp_changed` notice's new values: only the keys that changed (attended, reviewer,+ * the sandbox group). */+function stampChanges(a: Record<string, any>, t: T): [string, React.ReactNode][] {+ const out: [string, React.ReactNode][] = [];+ if (typeof a.attended === "boolean")+ out.push([t("steps.insp.changed_attended"), t(a.attended ? "steps.insp.attended_yes" : "steps.insp.attended_no")]);+ if (a.reviewer) {+ const who = reviewerLabel(a.reviewer, t);+ out.push([t("steps.insp.changed_reviewer"),+ a.reviewer.active && who ? who+ : a.reviewer.shadow && who ? t("steps.reviewer.shadow", { reviewer: who })+ : t("steps.insp.reviewer_off")]);+ }+ const sb = a.stamp?.sandbox;+ if (sb) {+ const extra = [sb.sites != null ? t("steps.insp.sites", { count: sb.sites }) : "",+ sb.runner_version ? t("steps.insp.runner", { version: sb.runner_version }) : ""].filter(Boolean);+ out.push([t("steps.insp.changed_sandbox"), [stampLine({ sandbox: sb }, t), ...extra].join(" · ")]);+ }+ return out;+}+function InputBox({ lines, t }: { lines: string[]; t: T }) {const [all, setAll] = useState(false);const shown = all ? lines : lines.slice(-3);diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.jsonindex 17421ede..3fde17f6 100644--- a/surfaces/gui/src/locales/en.json+++ b/surfaces/gui/src/locales/en.json@@ -3119,7 +3119,17 @@"after": "after {{t}}","match": "Match","matched": "same as you",- "not_matched": "different from you"+ "not_matched": "different from you",+ "changed": "What changed",+ "changed_attended": "Someone at the app",+ "attended_yes": "yes: cards are shown in the session",+ "attended_no": "no: cards go to the Inbox",+ "changed_reviewer": "Auto-approver",+ "reviewer_off": "off",+ "changed_sandbox": "Sandbox",+ "sites_one": "{{count}} site",+ "sites_other": "{{count}} sites",+ "runner": "runner {{version}}"},"loading": "Loading…","load_error": "Steps could not be loaded.",diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.jsonindex 60dc3e08..e9ea1241 100644--- a/surfaces/gui/src/locales/zh.json+++ b/surfaces/gui/src/locales/zh.json@@ -3073,7 +3073,16 @@"after": "{{t}} 后","match": "是否一致","matched": "与你相同",- "not_matched": "与你不同"+ "not_matched": "与你不同",+ "changed": "变化内容",+ "changed_attended": "有人在应用中",+ "attended_yes": "是:卡片显示在会话中",+ "attended_no": "否:卡片进入收件箱",+ "changed_reviewer": "自动批准",+ "reviewer_off": "关闭",+ "changed_sandbox": "沙盒",+ "sites_other": "{{count}} 个站点",+ "runner": "运行器 {{version}}"},"loading": "加载中…","load_error": "无法加载步骤。",diff --git a/tests/test_observability_stamps_context.py b/tests/test_observability_stamps_context.pyindex 72d06638..7f26a5a9 100644--- a/tests/test_observability_stamps_context.py+++ b/tests/test_observability_stamps_context.py@@ -211,3 +211,101 @@ def test_the_skills_menu_is_the_one_offered_this_turn(tmp_path):menus = [s["attrs"]["per_turn"] for s in rec.as_dict()["steps"] if s["kind"] == "context"]assert [m["skills_menu"] for m in menus] == [2, 1]assert menus[0]["skills_hash"] != menus[1]["skills_hash"]+++def test_sites_count_the_profile_the_machine_list_and_the_logins_hosts():+ """V2-28: the stamp's `sites` read a list no provider has, so it was always None."""+ provider = type("P", (), {"profile": "allowlist", "extra_hosts": ["a.example:443", "b.example:443"],+ "copied": type("C", (), {"hosts": ["a.example:443", "c.example:443"]})()})()+ ws = type("W", (), {"provider": provider})()+ assert stamps._site_count(ws) == 3+ provider.profile = "open"+ assert stamps._site_count(ws) is None # any host: no count+ assert stamps._site_count(type("W", (), {"provider": object()})()) is None # keeps no list+++class _LateSandbox:+ """A sandbox the first turn makes after the turn's stamp was taken."""++ reports_blocked = False++ def __init__(self):+ self.started = False+ self.provider = type("P", (), {"name": "openshell", "profile": "allowlist", "extra_hosts": ["x.example:443"]})()++ def ensure_started(self):+ self.started = True++ def describe(self):+ info = {"provider": "openshell", "enforcement": "full"}+ if self.started:+ info["runner"] = {"runner_version": "0.4.1"}+ return info+++def test_the_sandbox_made_by_the_first_turn_is_restamped(tmp_path):+ """V2-28: the runner's version is known only once the sandbox started, after the stamp."""+ engine, rec = _engine(tmp_path, [_call("c1", "look", {"path": "x"}), AssistantTurn(text="ok"),+ AssistantTurn(text="again")])+ engine.sandbox_workspace = _LateSandbox()+ _run(engine)+ d = rec.as_dict()+ assert "runner_version" not in d["turns"][0]["stamp"]["sandbox"]+ [notice] = [s for s in d["steps"] if s["kind"] == "notice"]+ assert notice["name"] == "stamp_changed"+ assert notice["attrs"] == {"stamp": {"sandbox": {"provider": "openshell", "enforcement": "full",+ "profile": "allowlist", "sites": 1,+ "runner_version": "0.4.1"}}}+ _run(engine, "again") # the next turn's stamp has it, and nothing changes in it+ d = rec.as_dict()+ assert d["turns"][1]["stamp"]["sandbox"]["runner_version"] == "0.4.1"+ assert [s["name"] for s in d["steps"] if s["kind"] == "notice"] == ["stamp_changed"]+++def test_attendance_changing_mid_turn_is_a_stamp_changed_notice(tmp_path):+ """V2-27: the Unattended toggle applies mid-turn; the turn keeps its start value and a+ notice carries the new one, with only the key that changed."""+ attended = {"now": True}+ engine, rec = _engine(tmp_path, [_call("c1", "look", {"path": "x"}), AssistantTurn(text="ok")])+ engine.is_attended = lambda: attended["now"]+ original = engine._execute_sync++ def run_tool(*a, **kw):+ attended["now"] = False # you switched to Unattended while the tool ran+ return original(*a, **kw)++ engine._execute_sync = run_tool+ _run(engine)+ d = rec.as_dict()+ assert d["turns"][0]["attended"] is True+ [notice] = [s for s in d["steps"] if s["kind"] == "notice"]+ assert notice["name"] == "stamp_changed" and notice["attrs"] == {"attended": False}+++def test_a_turn_where_nothing_changes_has_no_stamp_notice(tmp_path):+ engine, rec = _engine(tmp_path, [_call("c1", "look", {"path": "x"}), _call("c2", "look", {"path": "y"}),+ AssistantTurn(text="ok")])+ engine.is_attended = lambda: True+ _run(engine)+ assert not [s for s in rec.as_dict()["steps"] if s["kind"] == "notice"]+++def test_a_leads_steering_wakes_the_worker_as_a_team(tmp_path, monkeypatch):+ """V2-30: `steer_worker` delivers through the `team` connector; it was recorded as `channel`."""+ from coworker.providers import AssistantTurn as _T+ from coworker.server.manager import SessionManager++ mgr = SessionManager(workspace=tmp_path, provider=_Scripted([_T(text="on it"), _T(text="hi")]))+ engine = mgr.get_engine("W", agent="chat")+ seen: list[str] = []+ real_run = engine.run++ def run(*a, trigger="user", **kw):+ seen.append(trigger)+ return real_run(*a, trigger=trigger, **kw)++ monkeypatch.setattr(engine, "run", run)+ asyncio.run(mgr.deliver_to_session("W", "[Lead] switch to the API docs",+ source={"connector": "team", "sender_name": "lead"}))+ asyncio.run(mgr.deliver_to_session("W", "hello", source={"connector": "slack", "sender_name": "pat"}))+ assert seen == ["team_wake", "channel"]