Skip to content
Python

Subagents keep a full record, plus observability fixes (#852)

Rohit Prasad6daa7816d097
diff --git a/RESULTS-OB7.md b/RESULTS-OB7.md
deleted file mode 100644
index ba205fad..00000000
--- a/RESULTS-OB7.md
+++ /dev/null
@@ -1,91 +0,0 @@
-# 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/audit.py b/coworker/audit.py
index a81a68f5..9a423cea 100644
--- a/coworker/audit.py
+++ b/coworker/audit.py
@@ -93,6 +93,10 @@ class AuditStore:
# (OPE-224): "session", "openai-decisions" or "jev". Lets shadow results be
# summarised per reviewer instead of mixing them.
("reviewer", "TEXT DEFAULT ''"),
+ # Async subagents (OPE-262): the background child that made this call, as
+ # its task id ("agent-3"), under the PARENT session's id — so one query
+ # answers "what did agent-3 touch" without leaving the session's log.
+ ("subagent", "TEXT DEFAULT ''"),
):
try:
self._conn.execute(
@@ -137,8 +141,8 @@ class AuditStore:
self._conn.execute(
"""
INSERT INTO audit_events
- (session_id, agent, workspace, connector, tool, stage, status, approval, args, result_preview, reason, resource, call_id, tokens_in, tokens_out, cache_read, cache_write, actor, approved_by, reviewer)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ (session_id, agent, workspace, connector, tool, stage, status, approval, args, result_preview, reason, resource, call_id, tokens_in, tokens_out, cache_read, cache_write, actor, approved_by, reviewer, subagent)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
event.get("session_id") or "",
@@ -161,6 +165,7 @@ class AuditStore:
str(event.get("actor") or ""),
str(event.get("approved_by") or ""),
str(event.get("reviewer") or ""),
+ str(event.get("subagent") or ""),
),
)
self._conn.commit()
diff --git a/coworker/observability/recorder.py b/coworker/observability/recorder.py
index 6d6b0d85..c7f6771a 100644
--- a/coworker/observability/recorder.py
+++ b/coworker/observability/recorder.py
@@ -39,6 +39,29 @@ SCHEMA_VERSION = 1 # turn.schema_version: the record layout of format 1.x (§4,
# The canonical order (recording-format.md section 4): the kind order used after start time
# and the zero-length-first rule.
+class _StepMap(dict):
+ """The recorder's steps, stamped with a creation ordinal on insert: the tiebreak for
+ steps that started in the same millisecond (the canonical order's last word)."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self._ordinals: dict[str, int] = {}
+ self._next = 0
+
+ def __setitem__(self, key: str, value: Any) -> None:
+ if key not in self._ordinals:
+ self._next += 1
+ self._ordinals[key] = self._next
+ super().__setitem__(key, value)
+
+ def __delitem__(self, key: str) -> None:
+ super().__delitem__(key)
+ self._ordinals.pop(key, None)
+
+ def ordinal(self, step_id: str) -> int:
+ return self._ordinals.get(step_id, 0)
+
+
KIND_ORDER = {
"context": 0,
"summary": 1,
@@ -224,7 +247,13 @@ class Recorder:
def __init__(self, store: Optional["RecordingStore"] = None):
self.store = store
self.turns: dict[str, Turn] = {}
- self.steps: dict[str, Step] = {}
+ self.steps: dict[str, Step] = _StepMap()
+ # Work to run after the lock is released (the Issues checks at a turn's end): the
+ # recorder's one lock is on every engine's hot path, so nothing slow runs under it.
+ self._after_fold: list[Callable[[], None]] = []
+ # Model steps that follow a same-millisecond tool step of their turn (see _key);
+ # recomputed before every sort.
+ self._late_models: set[str] = set()
self._lock = threading.RLock()
self._turn_count: dict[str, int] = {} # session_id -> turns seen, for `seq`
self._listeners: list[Callable[[dict[str, Any]], None]] = []
@@ -262,13 +291,20 @@ class Recorder:
# -- the event sink (recording-format.md section 2.3) ----------------------------------
def emit(self, ev: dict[str, Any]) -> None:
"""Fold one recording event. Never raises: recording must not break a turn."""
+ after: list[Callable[[], None]] = []
try:
with self._lock:
self._fold(ev)
listeners = list(self._listeners)
+ after, self._after_fold = self._after_fold, []
except Exception:
log.exception("recorder: could not fold %s", ev.get("type"))
return
+ for fn in after:
+ try:
+ fn()
+ except Exception:
+ log.exception("recorder: deferred work failed")
for fn in listeners:
try:
fn(ev)
@@ -330,24 +366,28 @@ class Recorder:
s.duration_ms = max(0, turn.ended_at - s.started_at)
s.status, s.closed_by_turn = "interrupted", True
fill_unended(s.kind, s.attrs)
- self._assign_seq()
+ # Only this turn is re-sequenced (seq restarts per turn, so other turns are
+ # untouched) — not every step in memory (OPE-261).
+ mine = self._assign_seq(turn.turn_id)
self._write_turn(turn)
- for s in self.steps.values():
- if s.turn_id == turn.turn_id:
- self._write_step(s)
- self._check_turn(turn)
+ for s in mine:
+ self._write_step(s)
+ # The Issues checks run AFTER the lock is released: snapshot the records now.
+ turn_rec, step_recs = turn.record(), [s.record() for s in mine]
+ self._after_fold.append(lambda: self._check_turn(turn.turn_id, turn_rec, step_recs))
self._forget_old_turns(ev["mono_ms"])
- def _check_turn(self, turn: "Turn") -> None:
+ def _check_turn(self, turn_id: str, turn_rec: dict[str, Any],
+ step_recs: list[dict[str, Any]]) -> None:
"""The Issues checks over the turn just ended (OB-3), stored with it as not yet seen.
- A check never breaks the recording."""
+ Runs outside the recorder's lock on record snapshots. A check never breaks the
+ recording."""
if self.store is None:
return
try:
from . import signals
- steps = [s.record() for s in self.steps.values() if s.turn_id == turn.turn_id]
- self.store.write_issues(turn.turn_id, signals.check_turn(turn.record(), steps))
+ self.store.write_issues(turn_id, signals.check_turn(turn_rec, step_recs))
except Exception: # noqa: BLE001
log.exception("recording: the Issues checks failed for a turn")
@@ -424,10 +464,8 @@ class Recorder:
turn = self.turns.get(s.turn_id) if s.turn_id else None
if turn is not None and turn.mono_end is not None:
# A step of a turn that already ended (an after-turn call): place it in order now.
- self._assign_seq()
- for x in self.steps.values():
- if x.turn_id == turn.turn_id:
- self._write_step(x)
+ for x in self._assign_seq(turn.turn_id):
+ self._write_step(x)
if self.store is not None:
# A late step (the title call after the answer) counts in its turn (S3-03).
self.store.refresh_usage(turn.turn_id)
@@ -444,8 +482,21 @@ class Recorder:
return (
s.started_at,
0 if s.duration_ms == 0 else 1, # a zero-length step first
- KIND_ORDER.get(s.kind, 9),
+ # Frozen format-1.0 kind order, with ONE causal correction (OPE-261): a model
+ # call created after a tool call in the same millisecond of its turn sorts
+ # with the tools, by creation order — a fast tool and the model call that
+ # followed it must never swap. Nothing else the corpus pins moves.
+ KIND_ORDER["tool"] if s.step_id in self._late_models else KIND_ORDER.get(s.kind, 9),
+ # Only the late model carries its creation ordinal: it lands after the tools
+ # of that millisecond, while tools keep ordering among themselves by call
+ # position (frozen), never by thread timing.
+ self.steps.ordinal(s.step_id) if s.step_id in self._late_models else 0,
s.call_index or 0,
+ # Tool steps in the same millisecond at the same call position (consecutive
+ # single calls): creation order, never the name — otherwise `nope_tool` sorts
+ # ahead of the `read_file` that ran before it (a 50% flake in the Issues
+ # checks, OPE-261). Other kinds keep the frozen name order.
+ self.steps.ordinal(s.step_id) if s.kind == "tool" else 0,
s.name,
# Ties the key above leaves (two helpers starting at once, a live and a shadow
# check of one call): the parent's call position, then call id, then shadow.
@@ -454,9 +505,31 @@ class Recorder:
s.shadow,
)
- def _assign_seq(self) -> list[Step]:
+ def _mark_late_models(self) -> None:
+ first_tool: dict[tuple[Optional[str], int], int] = {}
+ for s in self.steps.values():
+ if s.kind == "tool":
+ k = (s.turn_id, s.started_at)
+ o = self.steps.ordinal(s.step_id)
+ if k not in first_tool or o < first_tool[k]:
+ first_tool[k] = o
+ self._late_models = {
+ s.step_id for s in self.steps.values()
+ if s.kind == "model"
+ and first_tool.get((s.turn_id, s.started_at), 10**12) < self.steps.ordinal(s.step_id)
+ }
+
+ def _assign_seq(self, turn_id: Optional[str] = None) -> list[Step]:
"""Turns by (started_at, turn_id), each turn's steps in canonical order; then steps
- with no known turn (proxy calls) by the same key. `seq` restarts at 1 in every turn."""
+ with no known turn (proxy calls) by the same key. `seq` restarts at 1 in every turn.
+ With `turn_id`, only that turn is re-sequenced (its steps, in order) — the per-turn
+ restart makes the other turns independent, so a turn's end never re-sorts them all."""
+ self._mark_late_models()
+ if turn_id is not None and turn_id in self.turns:
+ mine = sorted((s for s in self.steps.values() if s.turn_id == turn_id), key=self._key)
+ for i, s in enumerate(mine, 1):
+ s.seq = i
+ return mine
by_turn: dict[Optional[str], list[Step]] = {}
for s in self.steps.values():
by_turn.setdefault(s.turn_id if s.turn_id in self.turns else None, []).append(s)
diff --git a/coworker/server/app.py b/coworker/server/app.py
index be9bb6d1..9db748c1 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -22,7 +22,7 @@ from contextlib import asynccontextmanager
from pathlib import Path
from typing import Any, Optional
-from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
+from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse, Response
@@ -500,6 +500,15 @@ def create_app(manager: SessionManager) -> FastAPI:
rows.sort(key=lambda r: r.get("created") or 0, reverse=True)
return {"agents": [{k: v for k, v in r.items() if k != "report"} for r in rows]}
+ @app.get("/v1/sessions/{session_id}/tasks/{task_id}/transcript")
+ def get_session_task_transcript(session_id: str, task_id: str) -> dict[str, Any]:
+ # Subagent durability (OPE-262): the child's full message log, on demand only —
+ # for an audit or a future read-only viewer. Never streamed.
+ messages = manager.agent_task_store.read_transcript(session_id, task_id)
+ if messages is None:
+ raise HTTPException(status_code=404, detail="no transcript for that subagent run")
+ return {"task_id": task_id, "messages": messages}
+
@app.get("/v1/sessions/{session_id}/reviewer-stats")
def get_reviewer_stats(session_id: str) -> dict[str, Any]:
# Auto-Approve metering (§1.7): checks/verdicts/tokens from the durable audit rows.
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index ab062b5c..261b3744 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -7266,18 +7266,36 @@ class SessionManager:
with self._live_steps_lock:
batch = self._live_steps.setdefault(session_id, [])
batch.append(event)
- first = len(batch) == 1
- if first:
+ # Bounded: with no reader draining it, the batch can't grow without end.
+ if len(batch) > self.LIVE_STEP_BATCH_MAX:
+ del batch[: len(batch) - self.LIVE_STEP_BATCH_MAX]
+ # One flush in flight per session, tracked explicitly — not "the batch just
+ # went from empty to one" — so a scheduling failure is retried by the next
+ # event instead of stalling the session for good (OPE-261).
+ pending = getattr(self, "_live_flush_pending", None)
+ if pending is None:
+ pending = self._live_flush_pending = set()
+ schedule = session_id not in pending
+ if schedule:
+ pending.add(session_id)
+ if schedule:
try:
loop.call_soon_threadsafe(
loop.call_later, self.LIVE_STEP_BATCH_S, self._send_live_steps, session_id
)
except RuntimeError:
- pass # the loop is closed: the server is stopping
+ # The loop is closed or stale: let the next event try again (on a live loop).
+ with self._live_steps_lock:
+ self._live_flush_pending.discard(session_id)
+
+ LIVE_STEP_BATCH_MAX = 500
def _send_live_steps(self, session_id: str) -> None:
with self._live_steps_lock:
events = self._live_steps.pop(session_id, [])
+ pending = getattr(self, "_live_flush_pending", None)
+ if pending is not None:
+ pending.discard(session_id)
if events and self.has_session_clients(session_id):
asyncio.ensure_future(self.broadcast_session(session_id, {"type": "step", "events": events}))
diff --git a/coworker/tools/agent_tasks.py b/coworker/tools/agent_tasks.py
index 42866f00..19e2e569 100644
--- a/coworker/tools/agent_tasks.py
+++ b/coworker/tools/agent_tasks.py
@@ -101,11 +101,62 @@ class AgentTaskStore:
self.put(session_id, rows)
return rows
+ # -- transcripts (OPE-262): one JSON file per child, beside the run record ----------------
+
+ def _transcript_dir(self, session_id: str) -> Optional[Path]:
+ if self.path is None:
+ return None
+ return self.path.parent / "agent_transcripts" / session_id
+
+ def write_transcript(self, session_id: str, task_id: str, messages: list[dict[str, Any]]) -> None:
+ d = self._transcript_dir(session_id)
+ if d is None:
+ return
+ d.mkdir(parents=True, exist_ok=True)
+ target = d / f"{task_id}.json"
+ tmp = target.with_suffix(".json.tmp")
+ tmp.write_text(json.dumps(messages, default=str), encoding="utf-8")
+ tmp.replace(target)
+
+ def read_transcript(self, session_id: str, task_id: str) -> Optional[list[dict[str, Any]]]:
+ d = self._transcript_dir(session_id)
+ if d is None:
+ return None
+ target = d / f"{task_id}.json"
+ if not target.is_file():
+ return None
+ try:
+ data = json.loads(target.read_text(encoding="utf-8"))
+ except Exception:
+ return None
+ return data if isinstance(data, list) else None
+
+ def _drop_transcripts(self, session_id: str, task_ids: Optional[set[str]] = None) -> None:
+ """Remove a session's transcript files — all of them, or just `task_ids`."""
+ d = self._transcript_dir(session_id)
+ if d is None or not d.is_dir():
+ return
+ for f in d.glob("*.json"):
+ if task_ids is None or f.stem in task_ids:
+ try:
+ f.unlink()
+ except OSError:
+ pass
+ if task_ids is None:
+ try:
+ d.rmdir()
+ except OSError:
+ pass
+
def put(self, session_id: str, rows: list[dict[str, Any]]) -> None:
live = [r for r in rows if r.get("status") in ("running", "waiting")]
done = [r for r in rows if r.get("status") not in ("running", "waiting")]
done.sort(key=lambda r: r.get("finished") or r.get("created") or 0, reverse=True)
keep = live + done[:_KEEP_FINISHED]
+ # Retention covers the transcripts too: a pruned run loses its file.
+ pruned = {str(r.get("id")) for r in done[_KEEP_FINISHED:] if r.get("id")}
+ if pruned:
+ self._drop_transcripts(session_id, pruned)
for r in keep:
rep = r.get("report") or ""
if len(rep) > _REPORT_STORE_MAX:
@@ -122,6 +173,7 @@ class AgentTaskStore:
if session_id in self._sessions:
del self._sessions[session_id]
self._save()
+ self._drop_transcripts(session_id)
INHERIT_INSTRUCTIONS = """You are a background subagent of the main coworker, working inside the same \
workspace with the same tools and the same permissions. The user sees your approval requests in the \
@@ -291,6 +343,9 @@ class AgentTaskRegistry:
elif event.type == EventType.ASSISTANT_MESSAGE:
if event.data.get("text"):
report = event.data["text"]
+ # Durability (OPE-262): the transcript on disk after every reply, so
+ # an audit sees the child's conversation even if the app dies mid-run.
+ self._persist_transcript(task)
u = event.data.get("usage")
if isinstance(u, dict):
key = str(u.get("model") or "unknown")
@@ -308,8 +363,19 @@ class AgentTaskRegistry:
status = f"error: {event.data.get('error', '')}"
except Exception as exc: # the child must never take the parent surface down
status = f"error: {exc}"
+ self._persist_transcript(task)
self._finish(task, report, status)
+ def _persist_transcript(self, task: AgentTask) -> None:
+ """The child's full message log, written beside the run record (owner ruling
+ 2026-11-07): never streamed, never in Recents, always there for an audit."""
+ if self.store is None or not self.session_id or task.engine is None:
+ return
+ try:
+ self.store.write_transcript(self.session_id, task.id, list(task.engine.messages))
+ except Exception:
+ pass # a persistence hiccup must never take a child run down
+
def _finish(self, task: AgentTask, report: str, status: str) -> None:
# The spawn step's helper pill (attrs.helper, same shape as explore's): model
# calls, tool calls and tokens the child spent, stamped when it ends. Display
@@ -435,6 +501,7 @@ def agent_task_tools(
instructions=INHERIT_INSTRUCTIONS,
max_iterations=_CHILD_MAX_ITERATIONS,
model_settings=model_settings,
+ audit_sink=getattr(parent, "audit_sink", None),
)
wrapped = registry._wrap_approver(task, child)
if wrapped is not None:
@@ -452,6 +519,7 @@ def agent_task_tools(
model=model,
model_settings=model_settings,
max_iterations=_CHILD_MAX_ITERATIONS,
+ audit_sink=getattr(registry.parent, "audit_sink", None),
)
def _launch(task: AgentTask, user_input: str) -> None:
@@ -512,6 +580,10 @@ def agent_task_tools(
t.engine = _build_child(t, child_provider)
if t.obs is not None:
t.engine._obs = t.obs
+ # Audit (OPE-262): the child's rows carry the PARENT session's context plus its
+ # own task id, so `/v1/audit?session_id=` answers "what did agent-N touch".
+ parent_ctx = dict(getattr(registry.parent, "audit_context", None) or {})
+ t.engine.audit_context = {**parent_ctx, "subagent": t.id}
registry._emit("agent_task_started", t)
_launch(t, task)
return {
diff --git a/coworker/tools/subagent.py b/coworker/tools/subagent.py
index 7dd1de27..ad142d06 100644
--- a/coworker/tools/subagent.py
+++ b/coworker/tools/subagent.py
@@ -48,8 +48,11 @@ def build_explorer_engine(
model: str,
model_settings: Optional[dict[str, Any]] = None,
max_iterations: int = _CHILD_MAX_ITERATIONS,
+ audit_sink: Optional[Any] = None,
) -> TurnEngine:
- """A child engine with the Code agent's read-only tools and a fresh context."""
+ """A child engine with the Code agent's read-only tools and a fresh context.
+ `audit_sink`: the parent's, so the child's reads land in the session's audit log
+ (the caller stamps `audit_context` with the child's identity)."""
ws = str(Path(workspace).resolve())
registry = ToolRegistry()
# Read-only slice of the Code agent's toolset, with the same toolkit replacements
@@ -75,6 +78,7 @@ def build_explorer_engine(
instructions=EXPLORER_INSTRUCTIONS,
max_iterations=max_iterations,
model_settings=model_settings,
+ audit_sink=audit_sink,
)
diff --git a/surfaces/gui/src/api.ts b/surfaces/gui/src/api.ts
index 9b94000d..5407bd5d 100644
--- a/surfaces/gui/src/api.ts
+++ b/surfaces/gui/src/api.ts
@@ -3125,7 +3125,19 @@ export interface FailedInARow {
// machine's with each joined machine's (through the controller's proxy), and every
// automation call goes to the machine its task came from, as sessions do.
const automationMachines = new Map<string, string>();
-const automationBase = (id: string): string => engineBase(automationMachines.get(id) ?? null);
+// The map is filled by getAutomations(); a call made before the list ever loaded (a reload
+// straight into a remote automation's page) would route to the local engine and 404. So
+// an unknown id loads the list once first (OPE-261).
+async function automationBase(id: string): Promise<string> {
+ if (!automationMachines.has(id)) {
+ try {
+ await getAutomations();
+ } catch {
+ /* offline: fall through to the local engine, as before */
+ }
+ }
+ return engineBase(automationMachines.get(id) ?? null);
+}
export function machineOfAutomation(id: string): string | null {
return automationMachines.get(id) ?? null;
}
@@ -3200,7 +3212,7 @@ export function connectEvents(
/** Advance the automation's seen mark — clears its unseen-runs badge (UX-023). */
export async function markAutomationSeen(id: string): Promise<{ ok: boolean }> {
- const res = await fetch(`${automationBase(id)}/v1/automations/${id}/seen`, { method: "POST" });
+ const res = await fetch(`${await automationBase(id)}/v1/automations/${id}/seen`, { method: "POST" });
return res.json();
}
@@ -3223,7 +3235,7 @@ export async function createAutomation(payload: {
}
export async function getAutomation(id: string): Promise<{ task: Automation; runs: AutomationRun[]; failed_in_a_row?: FailedInARow | null }> {
- const res = await fetch(`${automationBase(id)}/v1/automations/${encodeURIComponent(id)}`);
+ const res = await fetch(`${await automationBase(id)}/v1/automations/${encodeURIComponent(id)}`);
const body = await res.json();
// A remote automation's run sessions live on its machine: route them there.
const mid = automationMachines.get(id) ?? null;
@@ -3233,7 +3245,7 @@ export async function getAutomation(id: string): Promise<{ task: Automation; run
}
export async function updateAutomation(id: string, changes: Record<string, any>) {
- const res = await fetch(`${automationBase(id)}/v1/automations/${encodeURIComponent(id)}`, {
+ const res = await fetch(`${await automationBase(id)}/v1/automations/${encodeURIComponent(id)}`, {
method: "PATCH",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(changes),
@@ -3242,7 +3254,7 @@ export async function updateAutomation(id: string, changes: Record<string, any>)
}
export async function deleteAutomation(id: string) {
- const res = await fetch(`${automationBase(id)}/v1/automations/${encodeURIComponent(id)}`, { method: "DELETE" });
+ const res = await fetch(`${await automationBase(id)}/v1/automations/${encodeURIComponent(id)}`, { method: "DELETE" });
return res.json();
}
@@ -3258,7 +3270,7 @@ export interface PreparedRun {
/** Prepare a live manual run: returns the session to open + the opening prompt to send. */
export async function runAutomation(id: string): Promise<PreparedRun> {
- const res = await fetch(`${automationBase(id)}/v1/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
+ const res = await fetch(`${await automationBase(id)}/v1/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
const body = await res.json();
if (body?.session_id) registerSessionMachine(body.session_id, automationMachines.get(id) ?? null);
return body;
@@ -3267,7 +3279,7 @@ export async function runAutomation(id: string): Promise<PreparedRun> {
/** Mark a manual run complete after its first turn finished. */
export async function finalizeAutomationRun(id: string, runId: string) {
const res = await fetch(
- `${automationBase(id)}/v1/automations/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/finalize`,
+ `${await automationBase(id)}/v1/automations/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/finalize`,
{ method: "POST" },
);
return res.json();
diff --git a/tests/test_agent_tasks.py b/tests/test_agent_tasks.py
index e34d5c82..01c3f8cd 100644
--- a/tests/test_agent_tasks.py
+++ b/tests/test_agent_tasks.py
@@ -234,6 +234,63 @@ async def test_registry_persists_runs_and_rehydrates_without_id_collisions(tmp_p
assert t.id != snap[0]["id"]
+async def test_child_tool_calls_are_audited_under_the_parent_with_the_task_id(tmp_path):
+ """OPE-262: a child's reads land in the SESSION's audit log, stamped with its task id."""
+ from coworker.audit import AuditStore
+
+ store = AuditStore(tmp_path / "audit.db")
+ provider = DualRoleProvider({"task": "map the repo", "label": "audited run"})
+ engine, registry = _parent(tmp_path, provider)
+ engine.audit_sink = store.append
+ engine.audit_context = {"session_id": "sess-audit", "agent": "security", "workspace": str(tmp_path)}
+ (tmp_path / "notes.txt").write_text("x", encoding="utf-8")
+
+ [e async for e in engine.run("go")]
+ assert await _wait_for(lambda: registry.snapshot() and registry.snapshot()[0]["status"] == "done")
+
+ rows = store.list(session_id="sess-audit", limit=200)
+ child_rows = [r for r in rows if r.get("subagent")]
+ assert child_rows, "the child's calls must reach the parent session's audit log"
+ assert {r["subagent"] for r in child_rows} == {registry.snapshot()[0]["id"]}
+ assert all(r["session_id"] == "sess-audit" for r in child_rows)
+ # The parent's own spawn_agent row stays unstamped: it is the parent acting.
+ assert any(r["tool"] == "spawn_agent" and not r.get("subagent") for r in rows)
+
+
+async def test_child_transcript_is_persisted_pruned_and_purged(tmp_path):
+ """OPE-262: the child's full message log lives beside the run record, on demand."""
+ from coworker.tools.agent_tasks import AgentTaskStore, _KEEP_FINISHED
+
+ store = AgentTaskStore(tmp_path / "agent_tasks.json")
+ provider = DualRoleProvider({"task": "map the repo", "label": "kept run"})
+ engine, registry = _parent(tmp_path, provider)
+ registry.attach_store(store, "sess-t")
+ [e async for e in engine.run("go")]
+ assert await _wait_for(lambda: registry.snapshot() and registry.snapshot()[0]["status"] == "done")
+ task_id = registry.snapshot()[0]["id"]
+
+ transcript = store.read_transcript("sess-t", task_id)
+ assert transcript, "the finished child's transcript must be on disk"
+ assert transcript[0]["role"] == "system" # the explorer's own instructions
+ assert any(m.get("role") == "assistant" and "all clear" in str(m.get("content")) for m in transcript)
+ assert store.read_transcript("sess-t", "agent-999") is None
+
+ # Retention: a run pruned past the finished cap loses its transcript file too.
+ rows = store.load("sess-t")
+ newer = time.time() + 60 # all NEWER than the real run, so the real run is what gets pruned
+ for i in range(_KEEP_FINISHED + 1):
+ rows.append({"id": f"agent-{100 + i}", "status": "done", "created": newer + i, "finished": newer + i})
+ store.put("sess-t", rows)
+ assert store.read_transcript("sess-t", task_id) is None
+
+ # Deleting the session purges whatever is left.
+ store.write_transcript("sess-t", "agent-150", [{"role": "user", "content": "x"}])
+ store.drop("sess-t")
+ assert store.read_transcript("sess-t", "agent-150") is None
+
+
@pytest.mark.asyncio
async def test_cancel_stops_a_running_child(tmp_path):
class SlowChildProvider(DualRoleProvider):
diff --git a/tests/test_live_steps_forwarding.py b/tests/test_live_steps_forwarding.py
new file mode 100644
index 00000000..9c410a0b
--- /dev/null
+++ b/tests/test_live_steps_forwarding.py
@@ -0,0 +1,79 @@
+"""OPE-261: the live-step batch forwarder must never stall a session for good.
+
+The old logic scheduled a flush only when a batch went from empty to one event; if that
+one scheduling call failed (a closed or stale loop), the batch stayed non-empty forever
+and no later event ever scheduled again. Now one flush is tracked explicitly per session
+and a failure is retried by the next event; the batch is bounded too.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from types import SimpleNamespace
+
+from coworker.server.manager import SessionManager
+
+
+class _DeadLoop:
+ def call_soon_threadsafe(self, *a, **k):
+ raise RuntimeError("Event loop is closed")
+
+ def call_later(self, *a, **k): # pragma: no cover - never reached on the dead loop
+ raise AssertionError
+
+
+class _LiveLoop:
+ def __init__(self):
+ self.scheduled = []
+
+ def call_soon_threadsafe(self, fn, *args):
+ # The forwarder hands over `loop.call_later` plus its arguments; record the intent.
+ self.scheduled.append((fn, args))
+
+ def call_later(self, *a, **k): # pragma: no cover - the stub never runs the timer
+ raise AssertionError("call_later is scheduled through call_soon_threadsafe, not called directly")
+
+
+def _forwarder(loop):
+ """The forwarder with just the state it touches (SessionManager is heavy to build)."""
+ me = SimpleNamespace(
+ _loop=loop,
+ _live_loop=None,
+ _live_steps={},
+ _live_steps_lock=threading.Lock(),
+ LIVE_STEP_BATCH_S=SessionManager.LIVE_STEP_BATCH_S,
+ LIVE_STEP_BATCH_MAX=SessionManager.LIVE_STEP_BATCH_MAX,
+ sent=[],
+ )
+ me._send_live_steps = lambda sid: SessionManager._send_live_steps(me, sid)
+ me.has_session_clients = lambda sid: False # pop-and-drop path in _send_live_steps
+ me.forward = lambda ev: SessionManager._forward_recording_event(me, ev)
+ return me
+
+
+def test_a_failed_schedule_is_retried_by_the_next_event():
+ dead, live = _DeadLoop(), _LiveLoop()
+ me = _forwarder(dead)
+ me.forward({"session_id": "s1", "type": "step_started"})
+ assert me._live_steps["s1"] and "s1" not in me._live_flush_pending # retry allowed
+
+ me._loop = live # the next event arrives on a live loop
+ me.forward({"session_id": "s1", "type": "step_ended"})
+ assert len(live.scheduled) == 1, "the second event must schedule the flush the first could not"
+ assert "s1" in me._live_flush_pending
+
+
+def test_one_flush_in_flight_per_session_and_the_batch_is_bounded():
+ live = _LiveLoop()
+ me = _forwarder(live)
+ for i in range(SessionManager.LIVE_STEP_BATCH_MAX + 50):
+ me.forward({"session_id": "s1", "type": "step_started", "i": i})
+ assert len(live.scheduled) == 1 # not one per event
+ assert len(me._live_steps["s1"]) == SessionManager.LIVE_STEP_BATCH_MAX
+
+ # The flush clears the pending flag so a later burst schedules again.
+ me._send_live_steps("s1")
+ assert "s1" not in me._live_flush_pending and "s1" not in me._live_steps
+ me.forward({"session_id": "s1", "type": "step_started"})
+ assert len(live.scheduled) == 2