Skip to content
Python

feat(observability): helper summaries, team ids, woken_by and worker rows (OB-7)

Devika Verma898e02b3bbb1
diff --git a/RESULTS-OB7.md b/RESULTS-OB7.md
new file mode 100644
index 00000000..ba205fad
--- /dev/null
+++ b/RESULTS-OB7.md
@@ -0,0 +1,91 @@
+# OB-7: helpers and team workers in the timeline
+
+**Context.** A turn can hand work to a helper (the `explore` agent) or to a team worker. Before this change, the Steps panel showed a helper's steps always open, with nothing on the `explore` row about how the helper ended. A lead's timeline had no trace of the workers it woke. TeamView's token totals also missed helper tokens, because it read them from the transcript and helper calls are not in the transcript (V2-29).
+
+This branch builds OB-7 as Part E (§13) of `docs/observability/phase-2/technical-design.md` designs it. The recording fields follow `recording-format.md` §3.11 and `recording-format.schema.json` 1.2.
+
+Branch `wip/ob7-nesting`, started from `wip/ob3-issues` (`208c03f7`). Not pushed, not merged.
+
+## What was built
+
+**E6b: what the helper did, on the `explore` step.**
+- The `explore` step now has `attrs.helper = {index, status, model_calls, tool_calls, tokens}`. It is for display only: the pill still adds up the helper's own model steps.
+- `index` is the explore call's place among the turn's explore calls, in the order the model listed them. So two helpers run in parallel are always Helper 1 and Helper 2, whichever thread starts first.
+- `status` is `ok`, `step_limit` (the helper used its 10 steps), `error` or `interrupted`.
+- The helper's model calls now go through the helper's own recording, which counts them. Before, they went straight to the parent's recording, so nothing could count them.
+- Files: `tools/subagent.py`, `observability/engine_hooks.py` (`HelperRecording`, `TurnRecording.helper_index`).
+
+**E19a: team ids on team tool steps, and who woke a worker.**
+- Team tool steps carry `attrs.team = {team_id, item_id?, worker_session_id?}`. It holds ids only, never titles or text.
+ - The board tools (`create_item`, `assign`, `transition`, `comment`) are covered in `teams/tools.py`.
+ - `steer_worker`, `post_chat` and `decide_worker_call` are covered in `server/manager.py`.
+ - An approved `propose_team` also carries `worker_session_ids`, the sessions it created. This is set in `engine.py` `_observe_event`, because `propose_team` is a waiting tool that never runs through the normal tool path.
+ - A tool adds these ids through one small hook, `note_team()` in `engine_hooks.py`. It writes to the running tool's own step. Outside a recorded tool call it does nothing.
+- A worker's turn carries `woken_by = {lead_session_id, team_id, item_ids, via}`.
+ - The manager works it out when it wakes a worker (`_woken_by` in `server/manager.py`).
+ - `via` is `steer` for `steer_worker`, `mention` when the wake holds only team-chat lines, `board` for other board activity, and `timer` for a timer.
+ - `item_ids` lists every item the wake's rows name, once each. So a batched wake shows all of its items.
+ - The engine takes it as a new `woken_by=` keyword on its turn entry points (`engine.py`), next to `trigger=`.
+- A `steer_worker` delivery is recorded as `trigger: team_wake` with `via: steer`, not as `channel`. The trigger fix was already on the base branch (OB-3); this branch adds `via`.
+
+**E19b: worker rows in the lead's timeline, worked out on read.**
+- `RecordingStore.worker_turns(lead_session_id, since_ms)` finds the worker turns whose `woken_by.lead_session_id` is the lead.
+- `read_api.worker_rows()` puts each one under the first lead turn that had not ended when it started. That is the lead turn it started in, or, if it started between two lead turns, the next one. A worker turn that starts after the lead's last turn ended waits for the lead's next turn.
+- `GET …/recording/turns` now gives each lead turn a `workers` list. Each row has: session, turn, turn number, the worker's name from the team record, start, length, status, tokens, `item_ids` and `via`.
+- The worker's tokens are display only. They are not in the lead's pill or the lead's turn usage.
+
+**E19c: TeamView's totals come from the recording.**
+- `teams/summary.py` now reads each member's tokens from its recording, counted the way the session's pill counts them, so helper tokens are included.
+- A recording can be missing older turns, from before recording existed or deleted by "Keep for". So any transcript message older than the first recorded turn is still counted from the transcript.
+- With no recording at all, TeamView works as before.
+
+**E11 (part): the Steps panel.**
+- Under each `explore` row there is now a summary row, "Helper 1 · 6 steps · 12.3k tokens · ok". The helper's steps are folded behind it by default; a click opens or closes them.
+- While a helper still runs, or in a recording from before 1.2, the summary is counted from the helper's nested steps instead.
+- Each worker row shows "Worker qa · turn 3", the worker's tokens as a badge, the turn's length, and an "Open worker session ↗" link. Rows sit in time order among the lead's steps.
+- Strings are in English and Chinese.
+- Files: `StepsPanel.tsx`, `api.ts`, `styles.css`, `locales/en.json`, `locales/zh.json`, and a one-line `onOpenSession` prop in `App.tsx`. The `StepsPanel.tsx` changes are limited to the helper and worker rows.
+
+**Export.** A worker turn's span carries `openworker.team.id` and `openworker.lead.session.id`. `export_spans.py` already did this in OB-6, so it is not changed here; a test now covers it.
+
+## Differences from the design
+
+1. **Worker timers count as team wakes.** Before, only a lead's timer was `team_wake`; a worker's timer was `schedule`. The design lists `timer` as a `via`, which needs a worker's timer turn to be a team wake. So a worker's timer is now `trigger: team_wake` with `via: timer`. A session outside a team still records `schedule`.
+2. **Worker board calls carry ids too.** The design's lead-side list is satisfied. A worker's own `create_item`, `transition` and `comment` also carry `attrs.team`, because the same tools serve both roles.
+3. **Unknown ids are left out, not set to `null`.** `item_id` and `worker_session_id` are left out when not known. The schema accepts both forms.
+4. **One more helper status.** `attrs.helper.status` can also be `interrupted` (a Stop), which the 1.2 schema allows and §13.3 does not list.
+5. **The summary is its own row.** The helper summary is a separate row under the `explore` row, so the `explore` row can still be selected for its details.
+6. **Per-item tokens still come from the transcript.** In TeamView, each item's tokens are still read from the transcript, because helper calls cannot be tied to an item there. Only member and team totals, and the usage chart's points, come from the recording.
+
+## Tests run
+
+- **New: `tests/test_observability_team_helpers.py`, 14 tests, all passed.** They cover:
+ - the helper summary, and that the pill counts helper tokens once;
+ - two parallel helpers numbered in the model's order;
+ - a helper at its step limit;
+ - the ids on the board tools, with no text in the step;
+ - an approved `propose_team` naming the worker sessions it created;
+ - `note_team` doing nothing outside a recorded tool call;
+ - the ids on `steer_worker`, `decide_worker_call` and `post_chat`;
+ - `woken_by` for steer, board (a batched wake), mention and timer; none for a lead or a solo session; and the schema check;
+ - where worker rows go: inside a lead turn, between two lead turns, under a running lead turn, two workers woken by one action, and after the lead's last turn;
+ - the read API through a real store, with the worker's tokens kept out of the lead's pill;
+ - TeamView totals that include helper tokens and older transcript messages;
+ - the worker span's team and lead names.
+- **Related Python files, run one file at a time.** Covered: all 13 `tests/test_observability_*.py` files (golden 91 and schema 10 included), every `tests/test_team_*.py`, `test_subagent.py`, `test_engine.py`, and the other files that use the code changed here (wakes, deliveries, subscriptions, personas, gates, worker connectors).
+ - Everything passed except 3 tests. None of the 3 touches code changed here; all are Windows failures from the known baseline:
+ - `test_board_image_lifecycle::test_escape_and_symlink_to_ungranted_file_are_denied` and `test_team_rehearsal_fixes::test_runtime_facts_do_not_read_configuration_or_follow_workspace_symlinks` need symlink rights (WinError 1314);
+ - `test_board_image_lifecycle::test_concurrent_identical_uploads_dedupe_without_shared_temp_race` hits a Windows lock on a file rename in the attachment store (WinError 5).
+ - These 3 were not run again on the base branch.
+ - `test_team_file_artifacts.py` passed with its known Windows hang, `test_text_pages_pin_version_and_replay`, left out.
+- **GUI.**
+ - `StepsPanel.test.tsx`: 21 tests passed, 5 of them new (folding, a running helper, the worker row and its link, no link without a handler, and Chinese).
+ - The full unit suite (`npm run test`): 67 files, 650 tests passed.
+ - `tsc --noEmit` is clean.
+
+## What is not verified
+
+- **Not tried in the running app.** Nothing was checked in a browser or the desktop app, and no real team run was made: port 8765 and the GUI on 1420 belong to another session. The panel was checked only through unit tests.
+- **Worker rows do not appear live.** The lead's panel picks up a new worker row only when it reloads its turns, after the lead's own step events or a turn's end. A worker turn that starts while the lead is idle shows the next time the lead's turns are loaded.
+- **Recording gaps stay gaps.** If recording was off for some turns in the middle of a session, TeamView's total from the recording misses those turns.
+- **Export names not checked against a real backend.** The export names `openworker.team.id` and `openworker.lead.session.id` match `attributes.yaml` (they are marked `verified: false` there). They were not sent to a real backend. The docs repo was not edited.
diff --git a/coworker/engine.py b/coworker/engine.py
index 28e99932..5a7b51df 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -209,11 +209,12 @@ def _records_turn(kind: str) -> Callable[[Callable[..., AsyncIterator[Event]]],
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). While recording, UI events also carry `turn_id`, `ts_ms`, and a tool's `step_id`."""
+ say), and a team worker's caller who woke it with `woken_by=` (1.2). 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", **kwargs: Any) -> AsyncIterator[Event]:
+ async def wrapper(self: "TurnEngine", *args: Any, trigger: str = "unknown",
+ woken_by: 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:
@@ -228,7 +229,7 @@ def _records_turn(kind: str) -> Callable[[Callable[..., AsyncIterator[Event]]],
async for event in inner:
if event.type is EventType.TURN_START and not started:
started = True
- self._begin_recorded_turn(kind, trigger)
+ self._begin_recorded_turn(kind, trigger, woken_by)
if started and obs.in_turn:
self._observe_event(event)
yield event
@@ -688,7 +689,8 @@ class TurnEngine:
def recorder(self, value: Any) -> None:
self._obs.recorder = value
- def _begin_recorded_turn(self, kind: str, trigger: str) -> None:
+ def _begin_recorded_turn(self, kind: str, trigger: str,
+ woken_by: 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."""
@@ -711,6 +713,7 @@ class TurnEngine:
"attended": attended,
"reviewer": reviewer,
"max_iterations": self.max_iterations,
+ "woken_by": woken_by,
},
stamp=stamp,
first_message_id=first,
@@ -852,6 +855,11 @@ class TurnEngine:
# 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,
diff --git a/coworker/observability/engine_hooks.py b/coworker/observability/engine_hooks.py
index ef796952..47e0287b 100644
--- a/coworker/observability/engine_hooks.py
+++ b/coworker/observability/engine_hooks.py
@@ -21,6 +21,7 @@ import threading
import time
from typing import Any, Callable, Optional
+from .calculator import step_total
from .ids import new_ulid
from .recorder import EVENT_V, Recorder, now_ms
@@ -53,6 +54,7 @@ class TurnRecording:
self._reserved: dict[str, dict[str, Any]] = {} # summary steps written at their end (E4)
self._tokens_after_for: Optional[str] = None # a summary waiting for the next main call
self._child_usage: dict[str, bool] = {} # parent step -> its model call reported usage
+ self._explore_calls: dict[str, int] = {} # call_id -> 1st, 2nd… explore call of this turn (E6b)
@property
def enabled(self) -> bool:
@@ -96,6 +98,7 @@ class TurnRecording:
self._tool_ends.clear()
self._reply_end = None
self._waits.clear()
+ self._explore_calls.clear()
ev = self._base("turn_started", self.turn_id, self._turn_session)
ev.update({"kind": kind, "trigger": trigger, "first_message_id": first_message_id,
"attrs": copy.deepcopy(attrs), "stamp": copy.deepcopy(stamp)})
@@ -159,6 +162,22 @@ class TurnRecording:
self._send(ev)
elif message.get("role") == "assistant":
self._flush_reply(mid)
+ for tc in message.get("tool_calls") or []:
+ if (tc.get("function") or {}).get("name") == "explore" and tc.get("id"):
+ self._explore_calls.setdefault(tc["id"], len(self._explore_calls) + 1)
+
+ def helper_index(self, step_id: Optional[str]) -> int:
+ """The explore call's position among this turn's explore calls, in the order the model
+ listed them (E6b): two helpers run in parallel are Helper 1 and Helper 2 whichever
+ thread starts first."""
+ with self._lock:
+ call_id = (self._ident.get(step_id or "") or {}).get("call_id")
+ index = self._explore_calls.get(call_id or "")
+ if index is None: # a call the transcript never listed: after the listed ones
+ index = len(self._explore_calls) + 1
+ if call_id:
+ self._explore_calls[call_id] = index
+ return index
# -- steps ----------------------------------------------------------------------------------
def start_step(self, *, kind: str, name: str, call_id: Optional[str] = None,
@@ -408,6 +427,23 @@ def set_tool_run(run: Optional[ToolRun]) -> Optional[ToolRun]:
return outer
+def note_team(team_id: Optional[str], *, item_id: Any = None, worker_session_id: Optional[str] = None,
+ worker_session_ids: Optional[list[str]] = None) -> None:
+ """`attrs.team` on the running team tool's step (1.2, OB-7): ids only, no text. A team
+ tool calls it while it runs; outside a recorded tool call it does nothing."""
+ run = current_tool_run()
+ if run is None or run.step_id is None or not team_id:
+ return
+ team: dict[str, Any] = {"team_id": str(team_id)}
+ if item_id is not None and item_id != "":
+ team["item_id"] = str(item_id)
+ if worker_session_id:
+ team["worker_session_id"] = str(worker_session_id)
+ if worker_session_ids is not None:
+ team["worker_session_ids"] = [str(s) for s in worker_session_ids]
+ run.recording.update_step(run.step_id, attrs={"team": team})
+
+
class HelperRecording:
"""The recording of an explore helper's engine (§5.3, E6). Its steps go to the parent's
recording, on the parent's turn, nested under the `explore` step. Its own turn events are
@@ -420,6 +456,27 @@ class HelperRecording:
def __init__(self, parent: TurnRecording, parent_step_id: str, turn_id: Optional[str]) -> None:
self.parent, self.parent_step_id = parent, parent_step_id
self.turn_id = turn_id
+ self.index = parent.helper_index(parent_step_id)
+ self._lock = threading.Lock()
+ self._kinds: dict[str, str] = {} # the helper's open steps: step_id -> kind
+ self.model_calls = self.tool_calls = self.tokens = 0
+
+ def _count(self, kind: str, attrs: Optional[dict[str, Any]]) -> None:
+ with self._lock:
+ if kind == "model":
+ self.model_calls += 1
+ self.tokens += step_total({"attrs": attrs or {}}) or 0
+ elif kind == "tool":
+ self.tool_calls += 1
+
+ def summary(self, engine_status: str) -> dict[str, Any]:
+ """`attrs.helper` for the explore step (1.2, E6b), for display only: the pill adds up
+ the helper's own model steps, never this."""
+ status = {"completed": "ok", "truncated": "ok", "max_iterations_exceeded": "step_limit",
+ "interrupted": "interrupted"}.get(engine_status, "error")
+ with self._lock:
+ return {"index": self.index, "status": status, "model_calls": self.model_calls,
+ "tool_calls": self.tool_calls, "tokens": self.tokens}
@property
def recorder(self) -> Any:
@@ -455,7 +512,11 @@ class HelperRecording:
kw.setdefault("parent_step_id", None)
kw["parent_step_id"] = kw["parent_step_id"] or self.parent_step_id
kw["turn_id"] = self.turn_id
- return self.parent.start_step(**kw)
+ step_id = self.parent.start_step(**kw)
+ if step_id is not None:
+ with self._lock:
+ self._kinds[step_id] = kw["kind"]
+ return step_id
def end_step(self, step_id: Optional[str], **kw: Any) -> None:
kw.pop("wait_for_tool_message", None)
@@ -463,6 +524,10 @@ class HelperRecording:
attrs = kw.get("attrs")
if attrs is not None and "decision" in attrs:
attrs["decision"] = {"helper": True}
+ with self._lock:
+ kind = self._kinds.pop(step_id or "", None)
+ if kind is not None:
+ self._count(kind, attrs)
self.parent.end_step(step_id, **kw)
def instant_step(self, **kw: Any) -> None:
@@ -471,6 +536,10 @@ class HelperRecording:
attrs["decision"] = {"helper": True}
step_id = self.start_step(kind=kw["kind"], name=kw["name"], call_id=kw.get("call_id"),
call_index=kw.get("call_index"))
+ with self._lock:
+ self._kinds.pop(step_id or "", None)
+ if step_id is not None:
+ self._count(kw["kind"], attrs)
self.parent.end_step(step_id, status=kw["status"], attrs=attrs,
message_id=kw.get("message_id"))
diff --git a/coworker/observability/read_api.py b/coworker/observability/read_api.py
index efb9fc95..8fdd0b45 100644
--- a/coworker/observability/read_api.py
+++ b/coworker/observability/read_api.py
@@ -7,6 +7,7 @@ existing machine proxy for remote and cloud machines.
- `step`: one step in full: content, the exchange rebuilt from its pieces, the transcript
message it points at (cut at 4 KB), the audit rows with its call id, and its child steps.
- `usage`: the session's token numbers for the pill and its popover, and context fill.
+- `worker_rows`: a team lead's turns, the worker turns each one woke (OB-7, derived on read).
"""
from __future__ import annotations
@@ -38,6 +39,41 @@ def turns(recording: dict[str, Any]) -> list[dict[str, Any]]:
return out
+def worker_rows(lead_turns: list[dict[str, Any]],
+ worker_turns: list[tuple[dict[str, Any], list[dict[str, Any]]]],
+ names: Callable[[str], Optional[str]] = lambda session_id: None) -> dict[str, list[dict[str, Any]]]:
+ """Each lead turn's worker rows (phase-2 design §13.3): the worker turns its lead woke
+ that started inside it. One that started after the lead turn ended belongs to the lead's
+ next turn; one after the last lead turn ended waits for the next. The tokens are display
+ only: they are the worker's, in its pill and in TeamView, never in the lead's pill.
+ `names` gives a worker's name from the team record."""
+ def end(t: dict[str, Any]) -> float:
+ if t.get("duration_ms") is not None:
+ return t["started_at"] + t["duration_ms"]
+ # Still running: open-ended. Found open after a crash (no length): ends where it began.
+ return float("inf") if t.get("status") == "running" else t["started_at"]
+
+ ordered = sorted(lead_turns, key=lambda t: (t.get("started_at") or 0, t.get("turn_id") or ""))
+ out: dict[str, list[dict[str, Any]]] = {t["turn_id"]: [] for t in ordered}
+ for wt, steps in worker_turns:
+ at = wt.get("started_at") or 0
+ # The first lead turn not yet over when the worker turn started: the one it started
+ # in, or, if it started between two lead turns, the next one.
+ home = next((t for t in ordered if at < end(t)), None)
+ if home is None:
+ continue
+ woken = wt.get("woken_by") or {}
+ use = calculator.usage({"steps": steps}, turn_id=wt["turn_id"])
+ out[home["turn_id"]].append({
+ "session_id": wt["session_id"], "turn_id": wt["turn_id"], "seq": wt.get("seq"),
+ "name": names(wt["session_id"]), "started_at": at, "duration_ms": wt.get("duration_ms"),
+ "status": wt.get("status"), "tokens": use["pill"], "at_least": use["at_least"],
+ "team_id": woken.get("team_id"), "item_ids": list(woken.get("item_ids") or []),
+ "via": woken.get("via"),
+ })
+ return out
+
+
def turn_steps(recording: dict[str, Any], turn_id: str) -> list[dict[str, Any]]:
return [_light(s) for s in recording.get("steps") or [] if s.get("turn_id") == turn_id]
diff --git a/coworker/observability/store.py b/coworker/observability/store.py
index 412a2348..3470d6a6 100644
--- a/coworker/observability/store.py
+++ b/coworker/observability/store.py
@@ -596,6 +596,27 @@ class RecordingStore:
).fetchone()
return int(row["n"])
+ def worker_turns(self, lead_session_id: str, since_ms: int = 0) -> list[tuple[dict[str, Any], list[dict[str, Any]]]]:
+ """Team workers' turns woken by this lead (`woken_by.lead_session_id`, 1.2), started at
+ or after `since_ms`, each with its steps: what the lead's timeline shows as worker rows
+ (OB-7, derived on read, never copied into the lead's recording)."""
+ self.flush()
+ with self._lock:
+ rows = self._conn.execute(
+ "SELECT * FROM turns WHERE woken_by IS NOT NULL AND started_at >= ? "
+ "AND json_extract(woken_by, '$.lead_session_id') = ? ORDER BY started_at, turn_id",
+ (since_ms, lead_session_id),
+ ).fetchall()
+ ids = [r["turn_id"] for r in rows]
+ steps = self._conn.execute(
+ f"SELECT * FROM steps WHERE turn_id IN ({', '.join('?' * len(ids))}) ORDER BY seq",
+ ids,
+ ).fetchall() if ids else []
+ by_turn: dict[str, list[dict[str, Any]]] = {}
+ for s in steps:
+ by_turn.setdefault(s["turn_id"], []).append(_step_record(s))
+ return [(_turn_record(r), by_turn.get(r["turn_id"], [])) for r in rows]
+
def load_recording(self, session_id: str) -> dict[str, Any]:
"""A session's recording as format 1.0 JSON: {"turns": [...], "steps": [...]}.
Turns by (started_at, turn_id); each turn's steps by `seq`."""
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index d010cd3b..1d7dd839 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -47,6 +47,7 @@ from ..observability import Recorder, RecordingStore
from ..observability import read_api as recording_api
from ..observability import signals as recording_signals
from ..observability.export import ObservabilityExport
+from ..observability.engine_hooks import note_team
from ..observability.provider_view import RecordingProvider, tag as tag_provider
from ..remote.audit_export import load_policy
from ..config import load_config, workspace_allowed_commands
@@ -1343,6 +1344,8 @@ class SessionManager:
return {"error": "this session does not lead a team"}
handle = (worker or "").strip().lower()
member = next((w for w in team.workers if w.actor == handle), None)
+ # Ids on the lead's `decide_worker_call` step (OB-7); nothing outside a recorded call.
+ note_team(team.team_id, worker_session_id=member.session_id if member else None)
if member is None:
return {"error": f"no worker named '{worker}' on this team"}
item = self.inbox.get(call_id)
@@ -2872,6 +2875,20 @@ class SessionManager:
persona=agent.name,
session_id=session_id,
)
+ def team_identity():
+ # Resolve live membership, never a model-supplied team/board id.
+ team = self.teams.for_lead_session(session_id)
+ if team is None:
+ member = self.teams.for_worker_session(session_id)
+ if member is not None and member[1].actor == actor.id:
+ team = member[0]
+ return team.team_id if team is not None and team.space == space else ""
+
+ def worker_session(worker_actor: str) -> Optional[str]:
+ # The session of a worker on this session's team, for the step's ids (OB-7).
+ team = self.teams.get(team_identity())
+ return next((w.session_id for w in (team.workers if team else []) if w.actor == worker_actor), None)
+
tools = board_tools(
self.team_store,
space=space,
@@ -2881,20 +2898,13 @@ class SessionManager:
# added or revoked since this engine was built. No engine => no access.
roots=lambda: getattr(self._engines.get(session_id), "roots", []),
on_change=self.kick_team_tick,
+ team_id=team_identity,
+ worker_session=worker_session,
) + journal_tools(
self.journal_store, actor=actor, space=space
)
from ..teams.artifacts import artifact_tools
- def team_identity():
- # Resolve live membership, never a model-supplied team/board id.
- team = self.teams.for_lead_session(session_id)
- if team is None:
- member = self.teams.for_worker_session(session_id)
- if member is not None and member[1].actor == actor.id:
- team = member[0]
- return team.team_id if team is not None and team.space == space else ""
-
tools += artifact_tools(self.team_store, self.attachment_store, space=space,
actor=actor, roots=lambda: getattr(self._engines.get(session_id), "roots", []),
team_identity=team_identity,
@@ -2922,6 +2932,7 @@ class SessionManager:
team, handle, actor = manager._chat_identity(session_id, role)
if team is None:
return {"error": "this session is not part of a team"}
+ note_team(team.team_id, item_id=record_on_item)
if not team.chat_enabled or not team.chat_group:
return {"error": "team chat is not enabled for this team"}
try:
@@ -3051,6 +3062,7 @@ class SessionManager:
if team is None:
return {"error": "no team yet — propose one with propose_team first"}
match = next((w for w in team.workers if w.actor == worker), None)
+ note_team(team.team_id, worker_session_id=match.session_id if match else None)
if match is None:
return {
"error": f"no worker '{worker}' on this team",
@@ -3237,6 +3249,33 @@ class SessionManager:
),
}
+ def _woken_by(self, session_id: str, source: Optional[dict[str, Any]], wake=None) -> Optional[dict[str, Any]]:
+ """A team worker's turn: who woke it (observability 1.2, OB-7). `via` is `steer` for the
+ lead's `steer_worker`, `timer` for a timer, `mention` for a wake made only of team-chat
+ lines, else `board`. `item_ids` are the items the wake's rows name. A lead's own turns
+ have none: nothing above the lead woke it."""
+ found = self.teams.for_worker_session(session_id)
+ if found is None:
+ return None
+ team = found[0]
+ source = source or {}
+ rows = list((source.get("board") or {}).get("rows") or [])
+ if source.get("connector") == "team":
+ via = "steer"
+ elif source.get("connector") == "board" and rows and all(r.get("kind") == "chat" for r in rows):
+ via = "mention"
+ elif source.get("connector") == "board":
+ via = "board"
+ else:
+ via = "timer" if wake is not None else "board"
+ item_ids: list[str] = []
+ for row in rows:
+ item = row.get("item")
+ if item is not None and str(item) not in item_ids:
+ item_ids.append(str(item))
+ return {"lead_session_id": team.lead_session, "team_id": team.team_id,
+ "item_ids": item_ids, "via": via}
+
def kick_team_tick(self) -> None:
"""Nudge the wake plumbing from outside the turn loop — e.g. after an
external board client writes through the `/v1/board` API, so a review or a
@@ -6334,11 +6373,29 @@ class SessionManager:
rec = self.recordings_store.load_recording(session_id)
issues = self._recording_issues(session_id, rec)
turns = recording_api.turns(rec)
+ workers = self._recording_worker_rows(session_id, turns)
for t in turns:
r = issues.get(t["turn_id"]) or {}
t["issues"] = {"warn": int(r.get("warn") or 0), "info": int(r.get("info") or 0)}
+ if workers.get(t["turn_id"]):
+ t["workers"] = workers[t["turn_id"]]
return {"turns": turns}
+ def _recording_worker_rows(self, session_id: str, turns: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+ """A team lead's worker rows (OB-7): its workers' turns that it woke, under the lead
+ turn each started in. The worker's name comes from the team record."""
+ if not turns:
+ return {}
+ found = self.recordings_store.worker_turns(session_id, since_ms=min(t["started_at"] for t in turns))
+ if not found:
+ return {}
+
+ def name(worker_session_id: str) -> Optional[str]:
+ member = self.teams.for_worker_session(worker_session_id)
+ return member[1].actor if member is not None else None
+
+ return recording_api.worker_rows(turns, found, names=name)
+
def recording_turn_issues(self, session_id: str, turn_id: str) -> dict[str, Any]:
"""The Issues tab of one turn (OB-3): its issues, the checks that were fine, the ones
not run here, and the signals.yaml version that made them."""
@@ -7398,16 +7455,20 @@ class SessionManager:
source = self._board_source(team, message, rows=activity["board_rows"])
source["board"]["check_in"] = True
# 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).
+ # team timers (a lead's or a worker's) wake a team; any other session's 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"
+ in_team = (self.teams.for_lead_session(session_id) is not None
+ or self.teams.for_worker_session(session_id) is not None)
+ trigger = "team_wake" if in_team else "schedule"
else:
trigger = "channel"
- async for event in engine.run(message, source=source, activity=activity, trigger=trigger):
+ woken_by = self._woken_by(session_id, source, wake) if trigger == "team_wake" else None
+ async for event in engine.run(message, source=source, activity=activity, trigger=trigger,
+ woken_by=woken_by):
# Stream every event to any socket viewing this session, so a background turn
# (channel delivery, self-wake, durable resume) is seen live — not just on reselect.
await self.broadcast_session(
diff --git a/coworker/teams/summary.py b/coworker/teams/summary.py
index 0b892211..c1a0d2d6 100644
--- a/coworker/teams/summary.py
+++ b/coworker/teams/summary.py
@@ -38,6 +38,38 @@ def add_tokens(rows) -> dict:
return {key: sum(row.get(key, 0) for row in rows) for key in KINDS}
+def recorded_usage(manager, session_id):
+ """A member's tokens from its recording, the way its pill counts them: every model call
+ the session made, helpers (explore) included, which the transcript does not hold (V2-29,
+ OB-7). None when nothing was recorded, so the transcript's numbers are used instead.
+ Returns (tokens by kind, usage points, partial, when the first recorded turn started in
+ epoch seconds): turns before it (before recording, or past "Keep for") are not in it."""
+ store = getattr(manager, "recordings_store", None)
+ if store is None:
+ return None
+ try:
+ rec = store.load_recording(session_id)
+ except Exception: # noqa: BLE001 - TeamView never fails on a recording it cannot read
+ return None
+ if not rec.get("turns"):
+ return None
+ rows, points, partial = [], [], False
+ for step in rec.get("steps") or []:
+ a = step.get("attrs") or {}
+ if step.get("kind") != "model" or a.get("purpose") == "proxy" or a.get("error"):
+ continue
+ u = a.get("usage") or {}
+ if not u.get("reported"):
+ partial = True
+ continue
+ row = {"input": u.get("input_fresh"), "cache_read": u.get("cache_read"),
+ "output": u.get("output"), "cache_write": u.get("cache_write")}
+ rows.append(tokens(row))
+ points.append({"ts": (step.get("started_at") or 0) / 1000, "tokens": sum(rows[-1].values())})
+ first = min(t.get("started_at") or 0 for t in rec["turns"]) / 1000
+ return add_tokens(rows), points, partial, first
+
+
def compact_usage_points(points, buckets=120):
"""Bound the optional chart payload, preserving every recorded token by role."""
points = sorted(points, key=lambda p: p["ts"])
@@ -244,9 +276,18 @@ def make_summary(manager, team, now):
total = add_tokens(
usage or [tokens(u) for u in (record.usage if record else {}).values()]
)
+ # The recording, when there is one: the same count as the session's pill.
+ # Messages from before the first recorded turn are counted from the transcript.
+ recorded = recorded_usage(manager, sid)
+ if recorded is not None:
+ older = [m for m in messages if m.get("role") == "assistant" and isinstance(m.get("usage"), dict)
+ and stamp((m.get("timing") or {}).get("model_started") or m.get("ts")) < recorded[3]]
+ total = add_tokens([recorded[0], *(tokens(m["usage"]) for m in older)])
+ usage_points.extend({**point, "role": role} for point in recorded[1] if point["ts"])
step = None
for m in messages:
- if m.get("role") == "assistant" and isinstance(m.get("usage"), dict):
+ if m.get("role") == "assistant" and isinstance(m.get("usage"), dict) and (
+ recorded is None or stamp((m.get("timing") or {}).get("model_started") or m.get("ts")) < recorded[3]):
ts = stamp((m.get("timing") or {}).get("model_started") or m.get("ts"))
if ts:
usage_points.append(
@@ -281,7 +322,7 @@ def make_summary(manager, team, now):
"workspace": record.workspace if record else "",
"running": manager.is_running(sid),
"tokens": total,
- "usage_partial": any(
+ "usage_partial": recorded[2] if recorded is not None else any(
m.get("role") == "assistant" and not m.get("usage")
for m in messages
),
diff --git a/coworker/teams/tools.py b/coworker/teams/tools.py
index de2913f8..efddc3ed 100644
--- a/coworker/teams/tools.py
+++ b/coworker/teams/tools.py
@@ -11,10 +11,11 @@ session) and passes it at construction — the model never self-reports provenan
from __future__ import annotations
-from typing import Callable, Optional
+from typing import Any, Callable, Optional
import aisuite as ai
+from ..observability.engine_hooks import note_team
from .journal import JournalStore
from .model import Actor, BoardError, Role
from .proposals import WORK_PROPOSAL_SCHEMA, TEAM_PROPOSAL_SCHEMA, PROPOSAL_GUIDANCE
@@ -98,8 +99,12 @@ def board_tools(
attachments=None,
roots: Callable[[], list] = lambda: [],
on_change: Callable[[], None] = lambda: None,
+ team_id: Callable[[], str] = lambda: "",
+ worker_session: Callable[[str], Optional[str]] = lambda actor: None,
) -> list:
"""The board verbs for one agent, pre-bound to its space and identity.
+ `team_id` and `worker_session` give the ids the recording puts on the call's step
+ (observability 1.2 `attrs.team`); they never change what a call does.
Authority is enforced twice on purpose: the returned set is role-filtered
(a worker never even sees `assign`), and the store re-checks every call —
@@ -111,6 +116,10 @@ def board_tools(
on_change()
return mutation_receipt(result)
+ def recorded(item: Any = None, assignee: str = "") -> None:
+ note_team(team_id(), item_id=item,
+ worker_session_id=worker_session(assignee) if assignee else None)
+
def create_item(
title: str,
criteria: str,
@@ -135,6 +144,7 @@ def board_tools(
)
if "error" not in result:
on_change()
+ recorded(result.get("id"))
return item_snapshot(result)
def list_items(state: str = "", assignee: str = "", after_item: int = 0, limit: int = 50) -> dict:
@@ -198,6 +208,7 @@ def board_tools(
in_progress, blocked, or review (attach the blocker or a hand-off summary
as `comment`, and artifact pointers — branch, report, session — as
`refs`); done requires review verification first."""
+ recorded(item)
return receipt(_call(
store.transition,
space,
@@ -216,6 +227,7 @@ def board_tools(
wake the lead. Set needs_attention=True for an explicit question/decision;
blockers use transition to blocked. Publish evidence first, then one
concise transition to review with its artifact refs: that is the handoff."""
+ recorded(item)
return receipt(_call(
store.comment,
space,
@@ -236,6 +248,7 @@ def board_tools(
def assign(item: int, assignee: str) -> dict:
"""Assign a work item to a worker coworker. The item itself becomes the
worker's assignment — write the description and criteria accordingly."""
+ recorded(item, assignee)
return receipt(_call(store.assign, space, actor, item, assignee))
def link(src: int, kind: str, dst: int) -> dict:
diff --git a/coworker/tools/subagent.py b/coworker/tools/subagent.py
index ce5c8b70..7dd1de27 100644
--- a/coworker/tools/subagent.py
+++ b/coworker/tools/subagent.py
@@ -100,19 +100,22 @@ def explorer_tools(
"""
# Observability E6: the helper's model and tool calls are recorded under this
# `explore` step, on the parent's turn, with purpose `helper`.
+ # Its model calls go through the helper's recording too, which counts them (E6b).
run = current_tool_run()
helper_provider = provider
+ helper: Optional[HelperRecording] = None
if run is not None and run.step_id is not None:
+ helper = HelperRecording(run.recording, run.step_id, run.turn_id)
helper_provider = tag_provider(run.view, purpose="helper", parent=run.step_id,
- turn=run.turn_id)
+ turn=run.turn_id, sink=helper)
engine = build_explorer_engine(
workspace=workspace,
provider=helper_provider,
model=model,
model_settings=model_settings,
)
- if run is not None and run.step_id is not None:
- engine._obs = HelperRecording(run.recording, run.step_id, run.turn_id)
+ if helper is not None:
+ engine._obs = helper
async def _run() -> tuple[str, str]:
report, status = "", "unknown"
@@ -126,7 +129,13 @@ def explorer_tools(
return report, status
# Tools execute in a worker thread (no running loop), so asyncio.run is safe.
- report, status = asyncio.run(_run())
+ report, status = "", "error"
+ try:
+ report, status = asyncio.run(_run())
+ finally:
+ if helper is not None:
+ # E6b: what the helper did, on the explore step, for display only.
+ run.recording.update_step(run.step_id, attrs={"helper": helper.summary(status)})
if not report:
return {"error": f"explorer produced no report (status: {status})"}
result: dict[str, Any] = {"report": report}
diff --git a/tests/test_observability_team_helpers.py b/tests/test_observability_team_helpers.py
new file mode 100644
index 00000000..9d459f57
--- /dev/null
+++ b/tests/test_observability_team_helpers.py
@@ -0,0 +1,413 @@
+"""Observability Phase 2, OB-7: helpers and team workers in the timeline (design §13).
+
+- E6b: the `explore` step carries `attrs.helper`, `{index, status, model_calls, tool_calls,
+ tokens}`, for display only. The pill still adds up the helper's own model steps.
+- E19a: team tool steps carry `attrs.team` (ids only); worker turns carry `woken_by`; a
+ `steer_worker` delivery is `trigger: team_wake` with `via: steer`, not `channel`.
+- E19b: the read API lists, under each lead turn, the worker turns that lead woke during it.
+ Their tokens are display only, never in the lead's pill.
+- E19c: TeamView's totals come from the recording, so helper tokens count (V2-29).
+- Export: a worker turn's span carries `openworker.team.id` and `openworker.lead.session.id`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import json
+import threading
+from pathlib import Path
+
+import jsonschema
+
+from coworker.engine import TurnEngine
+from coworker.observability import Recorder, calculator, export_spans, read_api
+from coworker.observability.engine_hooks import ToolRun, note_team, set_tool_run
+from coworker.observability.provider_view import RecordingProvider
+from coworker.permissions import Mode, PermissionEngine
+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient, ToolCall
+from coworker.providers.base import TokenUsage
+from coworker.teams import Actor, Role, TeamStore, board_tools
+from coworker.teams.registry import TeamWorker
+from coworker.teams.tools import propose_team_tool
+from coworker.tools import ToolRegistry
+from coworker.tools.subagent import explorer_tools
+
+proposals = importlib.import_module("proposal_fixtures")
+SCHEMA = json.loads((Path(__file__).parent / "corpora/observability/recording-format.schema.json").read_text("utf-8"))
+
+
+def _check(recording):
+ validator = jsonschema.validators.validator_for(SCHEMA)(SCHEMA)
+ errors = sorted(validator.iter_errors(recording), key=lambda e: list(e.absolute_path))
+ assert not errors, "\n".join(f"{list(e.absolute_path)}: {e.message[:300]}" for e in errors[:8])
+
+
+# -- E6b: the helper's summary on the explore step ----------------------------------------------
+
+class _ByTask(ProviderClient):
+ """Answers each conversation by its first user message, so parallel helpers each get
+ their own script whichever thread asks first."""
+
+ def __init__(self, scripts):
+ self._scripts = {k: list(v) for k, v in scripts.items()}
+ self._lock = threading.Lock()
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ first = next(m["content"] for m in messages if m.get("role") == "user")
+ key = next(k for k in self._scripts if k in str(first))
+ with self._lock:
+ turn = self._scripts[key].pop(0)
+ return AssistantTurn(text=turn, usage=TokenUsage(input=50, output=5)) if isinstance(turn, str) else turn
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _calls(*calls):
+ return AssistantTurn(tool_calls=[ToolCall(id=c, name=n, arguments=a) for c, n, a in calls],
+ finish_reason="tool_calls", usage=TokenUsage(input=100, output=10))
+
+
+def _explore_engine(tmp_path, scripts):
+ (tmp_path / "notes.txt").write_text("Friday release", encoding="utf-8")
+ base = RecordingProvider(_ByTask(scripts))
+ registry = ToolRegistry()
+ registry.register_all(explorer_tools(workspace=tmp_path, provider=base, model="openai:model-x"))
+ engine = TurnEngine(provider=base, registry=registry,
+ permissions=PermissionEngine(workspace_root=tmp_path, mode=Mode.BYPASS_APPROVALS),
+ model="openai:model-x")
+ engine.audit_context = {"session_id": "sess_lead"}
+ rec = Recorder()
+ engine.recorder = rec
+ return engine, rec
+
+
+def _run(engine, text):
+ async def go():
+ return [ev async for ev in engine.run(text, trigger="user")]
+
+ return asyncio.run(go())
+
+
+def test_the_explore_step_says_what_its_helper_did(tmp_path):
+ engine, rec = _explore_engine(tmp_path, {
+ "use explore": [_calls(("c1", "explore", {"task": "alpha: what is in notes.txt?"})),
+ AssistantTurn(text="Friday.", usage=TokenUsage(input=10, output=1))],
+ "alpha": [_calls(("h1", "read_file", {"path": "notes.txt"}), ("h2", "list_files", {})),
+ "It says Friday release"],
+ })
+ _run(engine, "use explore")
+ d = rec.as_dict()
+ [explore] = [s for s in d["steps"] if s["name"] == "explore"]
+ # Two helper model calls: 110 + 55 tokens; two tool calls.
+ assert explore["attrs"]["helper"] == {"index": 1, "status": "ok", "model_calls": 2,
+ "tool_calls": 2, "tokens": 165}
+ # The pill counts the helper's own model steps once, never the summary as well:
+ # lead 110 + 11, helper 110 + 55.
+ assert calculator.usage(d)["pill"] == 110 + 11 + 110 + 55
+ _check(d)
+
+
+def test_two_helpers_in_parallel_are_numbered_in_the_models_order(tmp_path):
+ engine, rec = _explore_engine(tmp_path, {
+ "use explore": [_calls(("c1", "explore", {"task": "alpha"}), ("c2", "explore", {"task": "beta"})),
+ AssistantTurn(text="done")],
+ "alpha": ["alpha report"],
+ "beta": [_calls(("b1", "read_file", {"path": "notes.txt"})), "beta report"],
+ })
+ _run(engine, "use explore")
+ d = rec.as_dict()
+ by_call = {s["call_id"]: s["attrs"]["helper"] for s in d["steps"] if s["name"] == "explore"}
+ assert by_call["c1"]["index"] == 1 and by_call["c1"]["model_calls"] == 1
+ assert by_call["c2"]["index"] == 2 and by_call["c2"]["tool_calls"] == 1
+ _check(d)
+
+
+def test_a_helper_that_hits_its_step_limit_says_so(tmp_path):
+ loop = [_calls((f"h{i}", "list_files", {})) for i in range(12)]
+ engine, rec = _explore_engine(tmp_path, {
+ "use explore": [_calls(("c1", "explore", {"task": "alpha"})), AssistantTurn(text="partial")],
+ "alpha": loop,
+ })
+ _run(engine, "use explore")
+ d = rec.as_dict()
+ [explore] = [s for s in d["steps"] if s["name"] == "explore"]
+ helper = explore["attrs"]["helper"]
+ assert helper["status"] == "step_limit"
+ assert helper["model_calls"] == 10 # the helper's limit
+ _check(d)
+
+
+# -- E19a: ids on the team tool steps -----------------------------------------------------------
+
+class _Script(ProviderClient):
+ def __init__(self, turns):
+ self._turns = list(turns)
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ turn = self._turns.pop(0)
+ return AssistantTurn(text=turn, usage=TokenUsage(input=10, output=1)) if isinstance(turn, str) else turn
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _team_engine(tmp_path, turns, tools):
+ registry = ToolRegistry()
+ registry.register_all(tools)
+ engine = TurnEngine(provider=_Script(turns), registry=registry,
+ permissions=PermissionEngine(workspace_root=tmp_path, mode=Mode.BYPASS_APPROVALS),
+ model="openai:model-x")
+ engine.audit_context = {"session_id": "sess_lead"}
+ rec = Recorder()
+ engine.recorder = rec
+ return engine, rec
+
+
+def test_the_leads_board_calls_carry_the_team_and_item_ids(tmp_path):
+ store = TeamStore(tmp_path / "teams.db")
+ lead = Actor(id="lead", role=Role.LEAD, session_id="sess_lead")
+ tools = board_tools(store, space="proj", actor=lead, team_id=lambda: "team-1",
+ worker_session=lambda actor: {"sam": "sess_sam"}.get(actor))
+ engine, rec = _team_engine(tmp_path, [
+ _calls(("c1", "create_item", {"title": "Invoice PDF", "criteria": "tests pass"})),
+ _calls(("c2", "assign", {"item": 1, "assignee": "sam"}),
+ ("c3", "comment", {"item": 1, "body": "use the new template"}),
+ ("c4", "list_items", {})),
+ "assigned",
+ ], tools)
+ _run(engine, "plan the work")
+ store.close()
+ d = rec.as_dict()
+ team = {s["name"]: s["attrs"].get("team") for s in d["steps"] if s["kind"] == "tool"}
+ assert team["create_item"] == {"team_id": "team-1", "item_id": "1"}
+ assert team["assign"] == {"team_id": "team-1", "item_id": "1", "worker_session_id": "sess_sam"}
+ assert team["comment"] == {"team_id": "team-1", "item_id": "1"}
+ assert team["list_items"] is None # a read, not a team action
+ # Ids only: no title, criteria or comment text in the step.
+ assert "Invoice" not in json.dumps([s["attrs"] for s in d["steps"]])
+ _check(d)
+
+
+def test_an_approved_propose_team_names_the_worker_sessions_it_created(tmp_path):
+ engine, rec = _team_engine(tmp_path, [
+ _calls(("p1", "propose_team", proposals.team_proposal())), "staffed",
+ ], [propose_team_tool()])
+
+ async def approve(args, call_id):
+ return {"approved": True, "team_id": "team-1",
+ "workers": [{"actor": "sam", "session_id": "sess_sam"}, {"actor": "kim", "session_id": "sess_kim"}]}
+
+ engine.team_approver = approve
+ _run(engine, "staff it")
+ d = rec.as_dict()
+ [step] = [s for s in d["steps"] if s["kind"] == "tool" and s["name"] == "propose_team"]
+ assert step["attrs"]["team"] == {"team_id": "team-1", "worker_session_ids": ["sess_sam", "sess_kim"]}
+ _check(d)
+
+
+class _Steps:
+ def __init__(self):
+ self.updates = []
+
+ def update_step(self, step_id, attrs=None, content=None):
+ self.updates.append((step_id, attrs))
+
+
+def _in_tool_run(fn):
+ rec = _Steps()
+ outer = set_tool_run(ToolRun(step_id="step-1", turn_id="turn-1", view=None, recording=rec))
+ try:
+ result = fn()
+ finally:
+ set_tool_run(outer)
+ return result, [a["team"] for _, a in rec.updates]
+
+
+def test_note_team_does_nothing_outside_a_recorded_tool_call():
+ note_team("team-1", item_id=3) # no tool run on this thread: nothing to write to
+ _, seen = _in_tool_run(lambda: note_team("", item_id=3))
+ assert seen == [] # no team: nothing recorded
+
+
+def _manager(tmp_path, monkeypatch, provider=None):
+ from coworker.server.manager import SessionManager
+
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ (tmp_path / "repo").mkdir(exist_ok=True)
+ return SessionManager(workspace=str(tmp_path / "repo"), data_dir=tmp_path / "data", provider=provider)
+
+
+def _team(mgr):
+ return mgr.teams.create(space="proj", lead_session="sess_lead", lead_actor="lead",
+ workers=[TeamWorker(actor="sam", persona="swe-worker", session_id="sess_sam"),
+ TeamWorker(actor="kim", persona="swe-worker", session_id="sess_kim")])
+
+
+def test_steer_worker_and_decide_worker_call_name_the_worker_session(tmp_path, monkeypatch):
+ mgr = _manager(tmp_path, monkeypatch)
+ team = _team(mgr)
+ steer = mgr._steer_tool("sess_lead")
+ _, seen = _in_tool_run(lambda: steer(worker="kim", message="switch to the API docs"))
+ assert seen == [{"team_id": team.team_id, "worker_session_id": "sess_kim"}]
+ _, seen = _in_tool_run(lambda: steer(worker="nobody", message="x"))
+ assert seen == [{"team_id": team.team_id}] # the team, but no such worker
+ result, seen = _in_tool_run(lambda: mgr.decide_worker_call("sess_lead", "sam", "call-9", "allow"))
+ assert "error" in result # no parked call: the ids are still on the step
+ assert seen == [{"team_id": team.team_id, "worker_session_id": "sess_sam"}]
+ asyncio.run(mgr.aclose())
+
+
+def test_post_chat_carries_the_team_and_the_item_it_records_on(tmp_path, monkeypatch):
+ mgr = _manager(tmp_path, monkeypatch)
+ team = _team(mgr)
+ post = mgr._post_chat_tool("sess_sam", "worker")
+ _, seen = _in_tool_run(lambda: post(text="@lead done?", record_on_item=4))
+ assert seen == [{"team_id": team.team_id, "item_id": "4"}]
+ asyncio.run(mgr.aclose())
+
+
+# -- E19a: who woke a worker's turn -------------------------------------------------------------
+
+def _woken(mgr, session_id, message, source, wake=None):
+ asyncio.run(mgr.deliver_to_session(session_id, message, source=source, wake=wake))
+ turns = mgr.recordings_store.load_recording(session_id)["turns"]
+ return turns[-1]
+
+
+def test_a_worker_turn_records_who_woke_it(tmp_path, monkeypatch):
+ mgr = _manager(tmp_path, monkeypatch, provider=_Script(["on it", "ok", "seen", "hi"]))
+ team = _team(mgr)
+ mgr.get_engine("sess_sam", agent="chat")
+ steer = _woken(mgr, "sess_sam", "[Lead] switch to the API docs",
+ {"connector": "team", "sender_name": "lead"})
+ assert steer["trigger"] == "team_wake" # V2-30: not `channel`
+ assert steer["woken_by"] == {"lead_session_id": "sess_lead", "team_id": team.team_id,
+ "item_ids": [], "via": "steer"}
+ rows = [{"item": 3, "kind": "assigned"}, {"item": 5, "kind": "comment"}, {"item": 3, "kind": "moved"}]
+ board = mgr._woken_by("sess_sam", {"connector": "board", "board": {"rows": rows}})
+ assert board == {"lead_session_id": "sess_lead", "team_id": team.team_id,
+ "item_ids": ["3", "5"], "via": "board"} # batched: every item, once
+ mention = mgr._woken_by("sess_sam", {"connector": "board", "board": {"rows": [{"kind": "chat"}]}})
+ assert mention["via"] == "mention"
+ assert mgr._woken_by("sess_sam", None, wake=object())["via"] == "timer"
+ # A lead's own turns, and sessions outside a team, have none.
+ assert mgr._woken_by("sess_lead", {"connector": "team"}) is None
+ mgr.get_engine("sess_solo", agent="chat")
+ solo = _woken(mgr, "sess_solo", "hello", {"connector": "slack", "sender_name": "pat"})
+ assert solo["trigger"] == "channel" and "woken_by" not in solo
+ _check(mgr.recordings_store.load_recording("sess_sam"))
+ asyncio.run(mgr.aclose())
+
+
+# -- E19b: worker rows under the lead's turns ---------------------------------------------------
+
+def _turn(tid, sid, start, dur, *, status="completed", woken_by=None, seq=1):
+ t = {"turn_id": tid, "session_id": sid, "seq": seq, "kind": "run", "trigger": "user", "started_at": start,
+ "duration_ms": dur, "status": status, "incomplete": False, "approval_mode": "interactive",
+ "attended": True, "reviewer": {"active": False, "shadow": False, "kind": None, "model": None},
+ "stamp": {}, "first_message_id": None, "last_message_id": None, "schema_version": 1}
+ if woken_by:
+ t["trigger"], t["woken_by"] = "team_wake", woken_by
+ return t
+
+
+def _model(step_id, tid, sid, start, tokens, purpose="main"):
+ return {"step_id": step_id, "turn_id": tid, "session_id": sid, "parent_step_id": None, "seq": 1,
+ "kind": "model", "name": "model", "started_at": start, "duration_ms": 10, "status": "ok",
+ "call_id": None, "call_index": None, "message_id": None, "shadow": False, "after_turn": False,
+ "attrs": {"purpose": purpose, "model": "openai:model-x",
+ "usage": {"reported": True, "input_fresh": tokens - 1, "output": 1}},
+ "content": {}}
+
+
+def _by(team_id="team-1", items=("3",), via="board"):
+ return {"lead_session_id": "sess_lead", "team_id": team_id, "item_ids": list(items), "via": via}
+
+
+def test_worker_turns_are_listed_under_the_lead_turn_they_started_in():
+ lead = [_turn("L1", "sess_lead", 1000, 1000, seq=1), _turn("L2", "sess_lead", 5000, 1000, seq=2),
+ _turn("L3", "sess_lead", 9000, None, status="running", seq=3)]
+ workers = [
+ (_turn("W1", "sess_sam", 1500, 400, woken_by=_by(), seq=3), [_model("m1", "W1", "sess_sam", 1500, 12000)]),
+ (_turn("W2", "sess_kim", 1600, 400, woken_by=_by(items=("3", "4"))), []), # one action, two workers
+ (_turn("W3", "sess_sam", 3000, 100, woken_by=_by(), seq=4), []), # after L1 ended: in L2
+ (_turn("W4", "sess_sam", 9500, None, status="running", woken_by=_by(via="steer"), seq=5), []),
+ ]
+ rows = read_api.worker_rows(lead, workers, names={"sess_sam": "sam", "sess_kim": "kim"}.get)
+ assert [r["turn_id"] for r in rows["L1"]] == ["W1", "W2"]
+ assert [r["turn_id"] for r in rows["L2"]] == ["W3"]
+ assert [r["turn_id"] for r in rows["L3"]] == ["W4"] # the running lead turn is open-ended
+ assert rows["L1"][0] == {"session_id": "sess_sam", "turn_id": "W1", "seq": 3, "name": "sam",
+ "started_at": 1500, "duration_ms": 400, "status": "completed", "tokens": 12000,
+ "at_least": False, "team_id": "team-1", "item_ids": ["3"], "via": "board"}
+ assert rows["L1"][1]["item_ids"] == ["3", "4"]
+
+
+def test_a_worker_turn_after_the_last_lead_turn_waits_for_the_next():
+ lead = [_turn("L1", "sess_lead", 1000, 1000)]
+ rows = read_api.worker_rows(lead, [(_turn("W1", "sess_sam", 2500, 10, woken_by=_by()), [])])
+ assert rows == {"L1": []}
+
+
+def test_the_read_api_lists_worker_rows_and_keeps_their_tokens_out_of_the_leads_pill(tmp_path, monkeypatch):
+ mgr = _manager(tmp_path, monkeypatch)
+ _team(mgr)
+ store = mgr.recordings_store
+ store.write_turn(_turn("L1", "sess_lead", 1000, 5000))
+ store.write_step(_model("lm", "L1", "sess_lead", 1100, 300))
+ store.write_turn(_turn("W1", "sess_sam", 2000, 1000, woken_by=_by()))
+ store.write_step(_model("wm", "W1", "sess_sam", 2100, 12000))
+ store.write_turn(_turn("X1", "sess_other", 2000, 1000, woken_by={**_by(), "lead_session_id": "sess_x"}))
+ [turn] = mgr.recording_turns("sess_lead")["turns"]
+ [row] = turn["workers"]
+ assert (row["name"], row["session_id"], row["tokens"]) == ("sam", "sess_sam", 12000)
+ assert turn["usage"]["pill"] == 300 # the worker's 12000 are display only
+ assert mgr.recording_usage("sess_lead")["pill"] == 300
+ assert "workers" not in mgr.recording_turns("sess_sam")["turns"][0]
+ asyncio.run(mgr.aclose())
+
+
+# -- E19c: TeamView's totals from the recording (V2-29) -----------------------------------------
+
+def test_team_view_totals_count_helper_tokens_from_the_recording(tmp_path, monkeypatch):
+ from coworker.sessions import SessionRecord
+
+ mgr = _manager(tmp_path, monkeypatch)
+ mgr.session_store.save(SessionRecord(session_id="sess_lead", workspace=str(tmp_path / "repo"),
+ model="model-x", mode="interactive", agent="swe-lead"))
+ team = mgr.teams.create(space=mgr._board_space("sess_lead"), lead_session="sess_lead", lead_actor="lead",
+ workers=[TeamWorker(actor="sam", persona="swe-worker", session_id="sess_sam")])
+ use = {"input": 29, "cache_read": 0, "output": 1, "cache_write": 0}
+ mgr.session_store.save(SessionRecord(
+ session_id="sess_sam", workspace=str(tmp_path / "repo"), model="model-x", mode="interactive",
+ agent="swe-worker", messages=[
+ {"role": "assistant", "content": "before recording", "ts": 10, "usage": use}, # 30
+ {"role": "assistant", "content": "recorded", "ts": 25, "usage": use}, # 30, in the recording
+ ]))
+ store = mgr.recordings_store
+ store.write_turn(_turn("W1", "sess_sam", 20_000, 10_000, woken_by=_by()))
+ store.write_step(_model("wm", "W1", "sess_sam", 25_000, 30))
+ store.write_step({**_model("wh", "W1", "sess_sam", 25_500, 100, purpose="helper"), "seq": 2})
+ summary = mgr.team_summary(team.team_id)
+ sam = next(w for w in summary["workers"] if w["actor"] == "sam")
+ # 30 from before the first recorded turn (transcript), 30 main + 100 helper (recording).
+ assert sum(sam["tokens"].values()) == 160
+ assert sum(sam["tokens"].values()) == mgr.recording_usage("sess_sam")["pill"] + 30
+ asyncio.run(mgr.aclose())
+
+
+# -- export: a worker turn's span joins the lead's trace ----------------------------------------
+
+def _root_span(turn):
+ spans = export_spans.build_turn_spans(turn, [], sw=export_spans.switches_from({}), dialect="otlp",
+ get_piece=lambda k: None, masker=export_spans.Masker())
+ return next(s for s in spans if s["parent_span_id"] is None)
+
+
+def test_a_worker_turns_span_names_its_team_and_lead():
+ root = _root_span(_turn("W1", "sess_sam", 2000, 1000, woken_by=_by()))
+ assert root["attrs"]["openworker.team.id"] == "team-1"
+ assert root["attrs"]["openworker.lead.session.id"] == "sess_lead"
+ assert "openworker.team.id" not in _root_span(_turn("L1", "sess_lead", 1000, 5000))["attrs"]