"""Observability × async subagents (the gap between OPE-244 and the subagents feature merged 2026-11-07): a background spawn_agent child records like explore's helper — its model and tool steps nest under the spawn_agent step on the parent's turn, its tokens reach the ledger, and the spawn step gains `attrs.helper` when it finishes, even though the child outlives the turn. """ from __future__ import annotations import asyncio import time from coworker.engine import TurnEngine from coworker.observability import Recorder 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.tools import ToolRegistry from coworker.tools.agent_tasks import agent_task_tools class _DualProvider(ProviderClient): """Scripts the parent (spawn, then done) and the explorer child (one read, then a report), told apart by the child's system prompt.""" def complete(self, *, model, messages, tools=None, **settings): head = messages[0] if messages else {} is_child = head.get("role") == "system" and "read-only code explorer" in str( head.get("content", "") ) had_tool = any(m.get("role") == "tool" for m in messages) if is_child: if had_tool: return AssistantTurn( text="report: notes.txt says Friday release", usage=TokenUsage(input=70, output=7), ) return AssistantTurn( tool_calls=[ToolCall(id="h1", name="read_file", arguments={"path": "notes.txt"})], finish_reason="tool_calls", ) if not had_tool: return AssistantTurn( tool_calls=[ ToolCall( id="c1", name="spawn_agent", arguments={"task": "what is in notes.txt?", "label": "notes check"}, ) ], finish_reason="tool_calls", ) return AssistantTurn(text="spawned, moving on", usage=TokenUsage(input=50, output=5)) def capabilities(self, model): return ModelCapabilities(tools=True) def test_background_child_records_under_the_spawn_step(tmp_path): (tmp_path / "notes.txt").write_text("Friday release", encoding="utf-8") base = RecordingProvider(_DualProvider()) tools, tasks = agent_task_tools(workspace=tmp_path, provider=base, model="openai:model-a") registry = ToolRegistry() registry.register_all(tools) engine = TurnEngine( provider=base, registry=registry, permissions=PermissionEngine(workspace_root=tmp_path, mode=Mode.BYPASS_APPROVALS), model="openai:model-a", ) tasks.bind(engine) engine.agent_tasks = tasks engine.audit_context = {"session_id": "sess_bg"} rec = Recorder() engine.recorder = rec async def go(): return [ev async for ev in engine.run("survey the notes in the background")] asyncio.run(go()) deadline = time.time() + 10 while time.time() < deadline: snap = tasks.snapshot() if snap and snap[0]["status"] == "done": break time.sleep(0.05) assert tasks.snapshot()[0]["status"] == "done" d = rec.as_dict() [spawn] = [s for s in d["steps"] if s["kind"] == "tool" and s["name"] == "spawn_agent"] nested = [s for s in d["steps"] if s.get("parent_step_id") == spawn["step_id"]] kinds = {(s["kind"], (s.get("attrs") or {}).get("purpose")) for s in nested} assert ("model", "helper") in kinds, "the child's model calls must record as helper steps" assert ("tool", None) in kinds, "the child's read must nest under the spawn step" [read] = [s for s in nested if s["kind"] == "tool"] assert read["name"] == "read_file" and read["attrs"]["decision"] == {"helper": True} # Detached helpers mark every step after_turn, so the §7.4 turn-end sweep can never # close a step the still-running child owns (the race this test exists to pin). assert all(s.get("after_turn") for s in nested) assert all(s.get("status") != "interrupted" for s in nested) # The child never becomes a second turn, and the spawn step carries the summary # pill with the tokens the child actually spent. assert len(d["turns"]) == 1 helper = (spawn.get("attrs") or {}).get("helper") assert helper is not None, "the finished child must stamp attrs.helper on its spawn step" assert helper["status"] == "ok" assert helper["model_calls"] >= 1 and helper["tokens"] > 0