Skip to content
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.py
index 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] = 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 (
@@ -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__})
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})
@_records_turn("resume")
@@ -1621,6 +1661,7 @@ class TurnEngine:
self.model_settings,
)
self._note_context()
+ self._note_stamp()
provider = self.provider
def produce():
diff --git a/coworker/observability/stamps.py b/coworker/observability/stamps.py
index 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 None
try:
- 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 None
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 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.tsx
index 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.json
index 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.json
index 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.py
index 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"]