Skip to content
Python

Make idle check-ins cancellable and batch team wakes

Rohit C Prasadfaa047cc6cb1
diff --git a/coworker/engine.py b/coworker/engine.py
index 77def1e2..5fe1d4a0 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -294,7 +294,7 @@ class TurnEngine:
self._continuations = 0
self._warned_context_fallback = False
# Each pending steering message: (text, optional MessageSource sidecar dict).
- self._steering: list[tuple[str, Optional[dict[str, Any]]]] = []
+ self._steering: list[tuple[str, Optional[dict[str, Any]], Optional[dict[str, Any]]]] = []
# tool_call.id → the standing rule that auto-allowed it ("tool → target"), so the
# TOOL_FINISHED event can carry the note to the tool card (§25).
self._standing_notes: dict[str, str] = {}
@@ -345,9 +345,10 @@ class TurnEngine:
return message
def queue_steering(
- self, text: str, source: Optional[dict[str, Any]] = None
+ self, text: str, source: Optional[dict[str, Any]] = None,
+ activity: Optional[dict[str, Any]] = None,
) -> None:
- self._steering.append((text, source))
+ self._steering.append((text, source, activity))
# -- main loop --------------------------------------------------------------
async def run(
@@ -356,6 +357,7 @@ class TurnEngine:
*,
source: Optional[dict[str, Any]] = None,
display: Optional[str] = None,
+ activity: Optional[dict[str, Any]] = None,
) -> AsyncIterator[Event]:
# `user_input` is a string, or OpenAI content-parts (text + image_url) for attachments.
# `source` (a MessageSource dict) is a display-only sidecar for connector messages: it
@@ -379,6 +381,8 @@ class TurnEngine:
message["source"] = source
if display is not None:
message["_display"] = display
+ if activity:
+ message["_activity"] = activity
self.messages.append(message)
self._cancel.clear()
if self.session_facts is not None:
@@ -793,11 +797,12 @@ class TurnEngine:
self._append_notice("interrupted")
yield Event(EventType.INTERRUPTED, {"iterations": iterations})
return
- if self._yield_for_wake:
+ if self._yield_for_wake and not self._steering:
yield Event(EventType.TURN_END, {"status": "sleeping", "iterations": iterations})
return
if self._steering:
self._inject_steering()
+ self._yield_for_wake = False
# -- auto-compaction (OPE-27) ------------------------------------------------
def _compaction_config(self) -> dict[str, Any]:
@@ -2335,7 +2340,7 @@ class TurnEngine:
self._ask_replies.append((anchor, text, q))
def _inject_steering(self) -> None:
- for text, source in self._steering:
+ for text, source, activity in self._steering:
message: dict[str, Any] = {
"role": "user",
"content": text,
@@ -2343,6 +2348,8 @@ class TurnEngine:
}
if source is not None:
message["source"] = source
+ if activity:
+ message["_activity"] = activity
self.messages.append(message)
self._steering = []
@@ -2364,6 +2371,7 @@ class TurnEngine:
# display-only too: dropped entirely.
_SIDECARS = (
"source",
+ "_activity",
"timing",
"_display",
"ts",
@@ -2381,6 +2389,16 @@ class TurnEngine:
source_messages = _compaction.apply_to_outbound(
self.messages, self.compaction_state
)
+ # Runtime receipts stay out of provider payloads. Reminder/board context is
+ # earlier agent context, not words attributed to the incoming user and never
+ # a system instruction. Keep the actual user message verbatim and last.
+ expanded = []
+ for msg in source_messages:
+ context = (msg.get("_activity") or {}).get("text")
+ if context:
+ expanded.append({"role": "assistant", "content": context})
+ expanded.append(msg)
+ source_messages = expanded
out = [
(
# OPE-171: a length-truncated, action-free reply is replayed as a stub.
diff --git a/coworker/selfwake.py b/coworker/selfwake.py
index d244084f..ad9fa0b5 100644
--- a/coworker/selfwake.py
+++ b/coworker/selfwake.py
@@ -26,6 +26,7 @@ KIND_EVENT = "event" # wake when a named connector/webhook event fires (Phase 3
STATE_PENDING = "pending"
STATE_DUE = "due"
STATE_FIRED = "fired"
+STATE_CANCELLED = "cancelled"
def _now() -> datetime:
@@ -43,6 +44,8 @@ class Wake:
event_key: Optional[str] = None # for on-event wakes
note: str = ""
created_at: str = field(default_factory=lambda: _now().isoformat())
+ cancellation_reason: str = ""
+ context_delivered: bool = False
class WakeStore:
@@ -50,21 +53,44 @@ class WakeStore:
self.path = Path(path) if path else None
self._lock = threading.Lock()
self._wakes: dict[str, Wake] = {}
+ self.stopped_sessions: set[str] = set()
if self.path and self.path.is_file():
- for raw in json.loads(self.path.read_text(encoding="utf-8")).get(
- "wakes", []
- ):
+ saved = json.loads(self.path.read_text(encoding="utf-8"))
+ self.stopped_sessions = set(saved.get("stopped_sessions", []))
+ for raw in saved.get("wakes", []):
w = Wake(**raw)
self._wakes[w.id] = w
+ # Older versions accumulated timers. Keep only the newest pending
+ # sleep per session while retaining the replaced records for audit.
+ newest = {}
+ migrated = False
+ for w in sorted(self._wakes.values(), key=lambda w: w.created_at):
+ if w.kind != KIND_TIMER or w.state not in (STATE_PENDING, STATE_DUE):
+ continue
+ old = newest.get(w.session_id)
+ if old:
+ old.state = STATE_CANCELLED
+ old.cancellation_reason = "replaced by a newer sleep"
+ old.context_delivered = True
+ migrated = True
+ newest[w.session_id] = w
+ if migrated:
+ self._save()
def _save(self) -> None:
if not self.path:
return
self.path.parent.mkdir(parents=True, exist_ok=True)
- self.path.write_text(
- json.dumps({"wakes": [asdict(w) for w in self._wakes.values()]}, indent=2),
+ temporary = self.path.with_suffix(self.path.suffix + ".tmp")
+ temporary.write_text(
+ json.dumps(
+ {"wakes": [asdict(w) for w in self._wakes.values()],
+ "stopped_sessions": sorted(self.stopped_sessions)},
+ indent=2,
+ ),
encoding="utf-8",
)
+ temporary.replace(self.path)
def add_timer(self, session_id: str, fire_at: datetime, *, note: str = "") -> Wake:
w = Wake(
@@ -75,6 +101,12 @@ class WakeStore:
note=note,
)
with self._lock:
+ for old in self._wakes.values():
+ if (old.session_id == session_id and old.kind == KIND_TIMER
+ and old.state in (STATE_PENDING, STATE_DUE)):
+ old.state = STATE_CANCELLED
+ old.cancellation_reason = "replaced by a newer sleep"
+ old.context_delivered = True
self._wakes[w.id] = w
self._save()
return w
@@ -101,7 +133,9 @@ class WakeStore:
"""Timer wakes whose fire time has passed, plus completion/event wakes marked due."""
now = now or _now()
out = []
- for w in self._wakes.values():
+ with self._lock:
+ snapshot = list(self._wakes.values())
+ for w in snapshot:
if w.state != STATE_PENDING and w.state != STATE_DUE:
continue
if (
@@ -140,17 +174,61 @@ class WakeStore:
def mark_fired(self, wake_id: str) -> None:
with self._lock:
w = self._wakes.get(wake_id)
- if w is not None:
+ if w is not None and w.state in (STATE_PENDING, STATE_DUE):
w.state = STATE_FIRED
self._save()
+ def cancel_sleep(self, session_id: str, reason: str) -> None:
+ """Retain cancelled reminders durably until an incoming turn records them."""
+ with self._lock:
+ changed = False
+ for w in self._wakes.values():
+ if (w.session_id == session_id and w.kind == KIND_TIMER
+ and w.state in (STATE_PENDING, STATE_DUE)):
+ w.state = STATE_CANCELLED
+ w.cancellation_reason = reason
+ changed = True
+ if changed:
+ self._save()
+
+ def set_stopped(self, session_id: str, stopped: bool) -> None:
+ with self._lock:
+ if stopped:
+ self.stopped_sessions.add(session_id)
+ else:
+ self.stopped_sessions.discard(session_id)
+ self._save()
+
+ def cancelled_context(self, session_id: str) -> list[Wake]:
+ with self._lock:
+ return [
+ w for w in self._wakes.values()
+ if w.session_id == session_id and w.state == STATE_CANCELLED
+ and not w.context_delivered
+ ]
+
+ def acknowledge(self, wake_ids: list[str]) -> None:
+ """Called only after a durable incoming-message receipt exists."""
+ with self._lock:
+ changed = False
+ for wake_id in wake_ids:
+ w = self._wakes.get(wake_id)
+ if w is not None and not w.context_delivered:
+ if w.state in (STATE_PENDING, STATE_DUE):
+ w.state = STATE_FIRED
+ w.context_delivered = True
+ changed = True
+ if changed:
+ self._save()
+
def pending(self, session_id: Optional[str] = None) -> list[Wake]:
- return [
- w
- for w in self._wakes.values()
- if w.state != STATE_FIRED
- and (session_id is None or w.session_id == session_id)
- ]
+ with self._lock:
+ return [
+ w
+ for w in self._wakes.values()
+ if w.state in (STATE_PENDING, STATE_DUE)
+ and (session_id is None or w.session_id == session_id)
+ ]
def selfwake_tools(store: WakeStore, session_id: str) -> list:
@@ -159,7 +237,8 @@ def selfwake_tools(store: WakeStore, session_id: str) -> list:
def sleep_for(seconds: int, note: str = "") -> dict:
"""Suspend and wake this session after `seconds` (a relative wait: "check again in
5 minutes" is sleep_for(300)). Use it for polling/waiting without burning context
- while idle. No clock arithmetic needed — the runtime computes the wake time."""
+ while idle. Replaces the previous sleep. Earlier board/user activity cancels
+ it and carries your optional reminder note forward. No clock arithmetic needed."""
secs = int(seconds)
if secs <= 0:
raise ValueError("sleep_for needs a positive number of seconds")
@@ -170,7 +249,9 @@ def selfwake_tools(store: WakeStore, session_id: str) -> list:
"""Suspend and wake this session at an ISO-8601 timestamp (timezone-aware; bare
timestamps are read as UTC) — for an absolute time ("at 09:00 tomorrow"). Call
`current_time` first if you need today's date or the timezone; for a relative wait
- use sleep_for instead."""
+ use sleep_for instead. Replaces the previous sleep and cancels on earlier
+ board/user activity, carrying the optional reminder note into that activity.
+ This is an idle check-in deadline, not a persistent appointment."""
when = datetime.fromisoformat(when_iso)
if when.tzinfo is None:
when = when.replace(tzinfo=timezone.utc)
diff --git a/coworker/server/app.py b/coworker/server/app.py
index b96016b8..b4a40597 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -2550,6 +2550,7 @@ def create_app(manager: SessionManager) -> FastAPI:
)
if item.state == "pending":
manager.persist_session(session_id)
+ manager.note_worker_waiting(session_id, "ask_user", prompt_id=item.id, preview=item.title)
if item.visibility == VIS_INBOX:
await _mirror(item)
else:
@@ -2874,7 +2875,8 @@ def create_app(manager: SessionManager) -> FastAPI:
events = (
engine.retry()
if retry
- else engine.run(content, display=display)
+ else engine.run(content, display=display,
+ activity=manager.prepare_activity(session_id, "user activity"))
)
async for event in events:
data = event.data
@@ -3029,7 +3031,7 @@ def create_app(manager: SessionManager) -> FastAPI:
else:
engine.approve_action_once(name, arguments or {})
elif kind == "interrupt":
- engine.request_interrupt()
+ manager.stop_session(session_id)
elif kind == "retry":
# Re-run after a provider error (engine guards on the error-notice
# tail, so a stray frame is a no-op that still ends with turn_done).
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 0f06cf25..77526027 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -379,6 +379,9 @@ class SessionManager:
# board; the log carries only `attachment://` refs.
self.attachment_store = AttachmentStore(base / "attachments")
self._team_inflight: set[str] = set()
+ self._team_batch_deadlines: dict[str, float] = {}
+ self._team_batch_handles: dict[str, Any] = {}
+ self._activity_acknowledged: set[str] = set()
# Lead-session last-turn timestamps for the check-in backstop (monotonic-ish
# wall clock; restart resets the clock rather than firing a wake storm).
self._team_last_alive: dict[str, float] = {}
@@ -688,6 +691,7 @@ class SessionManager:
) -> Optional[TurnEngine]:
engine = self._engines.get(session_id)
self.reconcile_obsolete_prompts(session_id)
+ self.reconcile_activity_receipts(session_id)
if engine is not None:
self.sync_worker_mode(session_id, engine)
if approver is not None:
@@ -1416,6 +1420,7 @@ class SessionManager:
): # durable resume re-raised an already-answered prompt
return answer_result(item.questions, item.resolution)
self.persist_session(session_id) # the pending tool call is now on disk
+ self.note_worker_waiting(session_id, "ask_user", prompt_id=item.id, preview=item.title)
await self.mirror_inbox_item(item)
answer = await self.inbox.wait(item.id)
return answer_result(item.questions, answer)
@@ -2955,9 +2960,12 @@ class SessionManager:
# a running team — and it de-facto covers a worker dying without a transition
# (its item goes stale; the backstop wake surfaces it in the digest).
TEAM_LEAD_BACKSTOP_SECS = 600
+ TEAM_BATCH_SECONDS = 2.0
def _lead_backstop_due(self, team) -> bool:
sid = team.lead_session
+ if sid in self.wakes.stopped_sessions:
+ return False
if self.is_running(sid) or sid in self._team_inflight:
return False
if self.wakes.pending(sid):
@@ -3004,6 +3012,9 @@ class SessionManager:
async def _drain_team_member(
self, team, *, session_id: str, actor: str, is_lead: bool
) -> int:
+ self.reconcile_activity_receipts(session_id)
+ if session_id in self.wakes.stopped_sessions:
+ return 0
# Interest follows the assignment relation: everyone's feed is the events
# on their slice (assigned ∪ filed) — comments, moves, reassignments. The
# lead additionally subscribes to the board-wide decision classes.
@@ -3049,42 +3060,139 @@ class SessionManager:
if engine is not None:
engine.request_interrupt()
if not directs and not subs and not chats:
+ self._clear_team_batch(session_id)
+ return 0
+ message, rows = self._team_digest(
+ team, directs, subs, chats, is_lead=is_lead, reader=actor
+ )
+ if not rows:
+ self._consume_board_receipt(self._board_receipt(team, actor, directs, subs, chats, chat_handle))
+ self._clear_team_batch(session_id)
return 0
+ if is_lead:
+ deadline = self._team_batch_deadlines.setdefault(session_id, time.monotonic() + self.TEAM_BATCH_SECONDS)
+ urgent = any(r.get("kind") == "waiting" or (r.get("to") == "blocked" and not r.get("historical")) for r in rows)
+ timer_due = any(w.session_id == session_id and w.kind == "timer" for w in self.wakes.due())
+ if not urgent and not timer_due and time.monotonic() < deadline:
+ if session_id not in self._team_batch_handles:
+ loop = asyncio.get_running_loop()
+ def flush():
+ self._team_batch_handles.pop(session_id, None)
+ asyncio.create_task(self.team_tick())
+ self._team_batch_handles[session_id] = loop.call_later(max(0, deadline - time.monotonic()), flush)
+ return 0
if self.is_running(session_id) or session_id in self._team_inflight:
return 0 # it will drain on its next turn end / next tick
if not self.teams.count_wake(team.team_id, cap=self.TEAM_WAKE_CAP_PER_HOUR):
logger.warning("team %s paused for budget this hour", team.team_id)
return 0
- message, rows = self._team_digest(
- team, directs, subs, chats, is_lead=is_lead, reader=actor
- )
+ self._clear_team_batch(session_id)
self._team_inflight.add(session_id)
source = self._board_source(team, message, rows=rows)
async def _deliver() -> None:
try:
await self.deliver_to_session(session_id, message, source=source)
- # Consume only after the turn dispatched: a crash before this replays
- # the batch next tick (at-least-once, never silently lost).
- # The feed cursor advances past BOTH batches: a subs event deduped
- # out of directs must not replay as a direct next tick.
- delivered = [e["seq"] for e in directs] + [e["seq"] for e in subs]
- if delivered:
- self.team_store.consume_feed(team.space, actor, max(delivered))
- if subs:
- self.team_store.consume_subscription(
- team.space, actor, subs[-1]["seq"]
- )
- if chats:
- self.chat_store.consume(
- team.chat_group, chat_handle, chats[-1]["seq"]
- )
+ # Cursors are acknowledged with the persisted incoming turn, not
+ # after model completion. A user turn can consume this batch first.
finally:
self._team_inflight.discard(session_id)
+ self.kick_team_tick()
asyncio.create_task(_deliver())
return 1
+ def _clear_team_batch(self, session_id: str) -> None:
+ self._team_batch_deadlines.pop(session_id, None)
+ handle = self._team_batch_handles.pop(session_id, None)
+ if handle is not None:
+ handle.cancel()
+
+ @staticmethod
+ def _board_receipt(team, actor, directs, subs, chats, chat_handle) -> dict:
+ return {"space": team.space, "actor": actor,
+ "feed": max([e["seq"] for e in directs + subs], default=0),
+ "subscription": max([e["seq"] for e in subs], default=0),
+ "chat_group": team.chat_group, "chat_handle": chat_handle,
+ "chat": max([e["seq"] for e in chats], default=0)}
+
+ def _consume_board_receipt(self, receipt: dict) -> None:
+ if receipt.get("feed"):
+ self.team_store.consume_feed(receipt["space"], receipt["actor"], receipt["feed"])
+ if receipt.get("subscription"):
+ self.team_store.consume_subscription(receipt["space"], receipt["actor"], receipt["subscription"])
+ if receipt.get("chat"):
+ self.chat_store.consume(receipt["chat_group"], receipt["chat_handle"], receipt["chat"])
+
+ def _pending_board_context(self, session_id: str) -> tuple[str, list, dict]:
+ team = self.teams.for_lead_session(session_id)
+ is_lead = team is not None
+ found = self.teams.for_worker_session(session_id) if not team else None
+ if found:
+ team, worker = found
+ if team is None or team.paused:
+ return "", [], {}
+ actor = team.lead_actor if is_lead else worker.actor
+ directs = self.team_store.feed_for(team.space, actor)
+ subs = self.team_store.subscribed_events(team.space, actor) if is_lead else []
+ engine = self._engines.get(session_id)
+ queued = [(a or {}).get("board") or {} for _, _, a in (engine._steering if engine else [])]
+ feed_through = max([r.get("feed", 0) for r in queued], default=0)
+ sub_through = max([r.get("subscription", 0) for r in queued], default=0)
+ directs = [e for e in directs if e["seq"] > feed_through]
+ subs = [e for e in subs if e["seq"] > sub_through]
+ seen = {e["seq"] for e in subs}
+ directs = [e for e in directs if e["seq"] not in seen]
+ handle = "lead" if is_lead else actor
+ chats = self.chat_store.unread_for(team.chat_group, handle) if team.chat_enabled and team.chat_group else []
+ chat_through = max([r.get("chat", 0) for r in queued], default=0)
+ chats = [e for e in chats if e["seq"] > chat_through]
+ receipt = self._board_receipt(team, actor, directs, subs, chats, handle)
+ if not is_lead:
+ directs = [e for e in directs if e["kind"] != WORKER_WAITING]
+ text, rows = self._team_digest(team, directs, subs, chats, is_lead=is_lead, reader=actor)
+ return text if rows else "", rows, receipt
+
+ def prepare_activity(self, session_id: str, reason: str, *, wake=None, include_board=True) -> dict:
+ """Cancel idle sleep and gather context; acknowledgement waits for durable input."""
+ self.reconcile_activity_receipts(session_id)
+ if reason == "user activity":
+ self.wakes.set_stopped(session_id, False)
+ if wake is None or wake.kind != "timer":
+ self.wakes.cancel_sleep(session_id, reason)
+ cancelled = self.wakes.cancelled_context(session_id)
+ engine = self._engines.get(session_id)
+ queued_ids = {wid for _, _, a in (engine._steering if engine else [])
+ for wid in (a or {}).get("wake_ids", [])}
+ cancelled = [w for w in cancelled if w.id not in queued_ids]
+ notes = [f"The earlier check-in ({w.fire_at}) was cancelled because {w.cancellation_reason}."
+ + (f" Earlier agent reminder: {w.note}" if w.note else "") for w in cancelled]
+ text, rows, receipt = self._pending_board_context(session_id) if include_board else ("", [], {})
+ if text and reason != "board activity":
+ notes.append(text)
+ if notes:
+ notes.insert(0, "Runtime activity context. Reminders below were written by the agent earlier; newer user instructions take precedence.")
+ return {"id": uuid.uuid4().hex, "text": "\n\n".join(notes), "wake_ids": [w.id for w in cancelled] + ([wake.id] if wake else []),
+ "board": receipt, "board_text": text, "board_rows": rows}
+
+ def reconcile_activity_receipts(self, session_id: str) -> None:
+ record = self.session_store.load(session_id)
+ messages = record.messages if record else []
+ for message in messages:
+ receipt = message.get("_activity")
+ if receipt and receipt.get("id") not in self._activity_acknowledged:
+ self.wakes.acknowledge(receipt.get("wake_ids", []))
+ self._consume_board_receipt(receipt.get("board") or {})
+ self._activity_acknowledged.add(receipt.get("id"))
+
+ def stop_session(self, session_id: str) -> None:
+ self.wakes.set_stopped(session_id, True)
+ self.wakes.cancel_sleep(session_id, "the user stopped the session")
+ self._clear_team_batch(session_id)
+ engine = self._engines.get(session_id)
+ if engine is not None:
+ engine.request_interrupt()
+
# Long comment/hand-off bodies are already durable on the board — the wake
# message's job is to say what needs DECISIONS, not to re-carry the evidence
# into the recipient's context on every wake (owner ruling 2026-08-16). The
@@ -3119,7 +3227,12 @@ class SessionManager:
)
lines: list[str] = []
rows: list[dict] = []
- for event in sorted(directs + subs, key=lambda e: e["seq"]):
+ ordered = sorted(directs + subs, key=lambda e: e["seq"])
+ first = {}
+ for event in ordered:
+ first.setdefault(event.get("item_id"), event["seq"])
+ # Group related changes, preserving every ordered transition within an item.
+ for event in sorted(ordered, key=lambda e: (first[e.get("item_id")], e["seq"])):
item_id = event.get("item_id")
payload = event.get("payload") or {}
item = None
@@ -3173,6 +3286,9 @@ class SessionManager:
to = payload.get("to", "?")
comment = clamp(payload.get("comment") or "")
note = f" — “{comment}”" if comment else ""
+ historical = bool(item and item.get("state") != to)
+ if historical:
+ note += f" (historical transition; current state: {item['state']})"
if to == "canceled" and not is_lead:
lines.append(
f"{title} was CANCELED by {event['actor']}{note} — stop any"
@@ -3187,6 +3303,8 @@ class SessionManager:
"from": payload.get("from"),
"refs": payload.get("refs") or [],
"to": to,
+ "historical": historical,
+ "current_state": item.get("state") if item else None,
"note": self._clamp(
payload.get("comment") or "", self.DIGEST_CLAMP_UI
),
@@ -3202,6 +3320,15 @@ class SessionManager:
lines.append(f"{event['actor']} is waiting for the lead or user{(' on ' + title) if item_id is not None else ''}.")
rows.append({**row, "kind": "waiting", "tool": payload.get("tool") or "", "prompt_id": payload.get("prompt_id", "")})
continue
+ prompt = self.inbox.get(payload.get("prompt_id", ""))
+ if prompt is None or prompt.state != "pending":
+ continue # resolved/reissued approvals are history, not decisions
+ if prompt.kind != "approval":
+ lines.append(f"{event['actor']} needs a human answer: {clamp(prompt.title)}."
+ " The user answers in the worker session or Inbox; do not use decide_worker_call for this question.")
+ rows.append({**row, "kind": "waiting", "tool": payload.get("tool") or "ask_user",
+ "note": self._clamp(prompt.title, self.DIGEST_CLAMP_UI), "prompt_id": prompt.id})
+ continue
# §11.6: a worker parked on a tool call under a Manual lead — the lead
# decides (its decision asks the human), or the human answers directly.
tool = payload.get("tool") or "a tool"
@@ -3245,6 +3372,7 @@ class SessionManager:
"Team update — your team needs decisions:\n"
+ body
+ "\n\nFull hand-off comments live on the board (get_item)."
+ " Act on current state only, not historical transitions."
" Verify review items against their acceptance criteria (then"
" done, or send back with a comment), unblock or reassign blocked"
" items, and triage new filings. Steer only where needed."
@@ -5139,6 +5267,20 @@ class SessionManager:
is dropped, never fatal to the turn (delivery is socket-independent)."""
if message.get("type") == "turn_start":
self.reconcile_obsolete_prompts(session_id)
+ engine = self._engines.get(session_id)
+ if message.get("type") == "iteration_end" and engine and engine._steering:
+ # A sleep tool may finish after steering was queued. The accepted
+ # interruption still wins; carry that newly registered note too.
+ extra = self.prepare_activity(session_id, "user activity", include_board=False)
+ text, source, activity = engine._steering[0]
+ activity = activity or extra
+ if activity is not extra:
+ activity["text"] = "\n\n".join(filter(None, [activity.get("text"), extra["text"]]))
+ activity["wake_ids"] = list(dict.fromkeys(activity.get("wake_ids", []) + extra["wake_ids"]))
+ engine._steering[0] = (text, source, activity)
+ if message.get("type") in {"turn_start", "iteration_end", "permission_required", "turn_done"}:
+ self.persist_session(session_id)
+ self.reconcile_activity_receipts(session_id)
data = message.get("data") or {}
if message.get("type") == "permission_required" and data.get("name") == "decide_worker_call":
worker_call = self.worker_call_for(data.get("arguments") or {}, lead_session=session_id)
@@ -5151,6 +5293,9 @@ class SessionManager:
self.unregister_session_client(session_id, cb)
async def aclose(self) -> None:
+ for handle in self._team_batch_handles.values():
+ handle.cancel()
+ self._team_batch_handles.clear()
await self.scheduler.stop()
await self.stop_gateway()
await self.mcp.aclose()
@@ -5586,14 +5731,14 @@ class SessionManager:
# -- self-wake resumption ---------------------------------------------------
async def _scheduler_tick(self) -> None:
- """The shared per-tick work: resume due self-wakes, then drain team queues.
+ """Drain team queues before due sleeps so simultaneous activity combines.
Team deliveries dispatch as tasks (a long worker turn must not stall the
scheduler)."""
- await self.resume_due_wakes()
try:
await self.team_tick()
except Exception:
logger.exception("team tick failed")
+ await self.resume_due_wakes()
async def resume_due_wakes(self) -> int:
"""Resume sessions whose self-wakes are due (called each scheduler tick). A suspended
@@ -5602,13 +5747,25 @@ class SessionManager:
"""
resumed = 0
for wake in self.wakes.due():
- try:
- await self._resume_wake(wake)
- resumed += 1
- except Exception:
- pass
- finally:
- self.wakes.mark_fired(wake.id)
+ self.reconcile_activity_receipts(wake.session_id)
+ if wake not in self.wakes.pending(wake.session_id):
+ continue
+ if self.is_running(wake.session_id) or wake.session_id in self._team_inflight:
+ continue
+ if wake.kind == "timer" and wake.session_id in self.wakes.stopped_sessions:
+ self.wakes.cancel_sleep(wake.session_id, "the user stopped the session")
+ continue
+ self._team_inflight.add(wake.session_id)
+ async def deliver(wake=wake):
+ try:
+ await self._resume_wake(wake)
+ except Exception:
+ logger.exception("self-wake delivery failed for %s", wake.session_id)
+ finally:
+ self._team_inflight.discard(wake.session_id)
+ self.kick_team_tick()
+ asyncio.create_task(deliver())
+ resumed += 1
return resumed
def mark_running(self, session_id: str) -> None:
@@ -5631,6 +5788,8 @@ class SessionManager:
def mark_idle(self, session_id: str) -> None:
self._running_sessions.discard(session_id)
+ if session_id in self.wakes.stopped_sessions:
+ self.wakes.cancel_sleep(session_id, "the user stopped the session")
if session_id in self._stale_engines:
self._stale_engines.discard(session_id)
self._engines.pop(session_id, None)
@@ -5665,11 +5824,11 @@ class SessionManager:
digest = self.team_staleness_digest(wake.session_id)
if digest:
message = f"{message}\n\n{digest}"
- await self.deliver_to_session(wake.session_id, message)
+ await self.deliver_to_session(wake.session_id, message, wake=wake)
async def deliver_to_session(
- self, session_id: str, message: str, *, source: Optional[dict[str, Any]] = None
- ) -> None:
+ self, session_id: str, message: str, *, source: Optional[dict[str, Any]] = None, wake=None
+ ) -> bool:
"""Deliver an out-of-band message to a (durable) session — the agent stays resumable
forever, so this works with no live socket. Busy (mid tool-loop): steer it into the live
turn at its next step (don't start a colliding run). Idle: run a fresh background turn
@@ -5679,12 +5838,29 @@ class SessionManager:
"""
engine = self.get_engine(session_id)
if engine is None:
- return
+ return False
+ board_delivery = (source or {}).get("connector") == "board"
+ if wake is not None and wake not in self.wakes.pending(session_id):
+ return False # user/board activity won the scheduled-task race
+ if board_delivery and session_id in self.wakes.stopped_sessions:
+ return False
+ if board_delivery and not self._pending_board_context(session_id)[0]:
+ # Backstop messages are not feed deliveries.
+ if (source or {}).get("board", {}).get("rows"):
+ return False
if not self.try_mark_running(session_id):
- engine.queue_steering(message, source)
- return
+ if board_delivery or wake is not None:
+ return False # defer; never inject routine wakes into a running turn
+ activity = self.prepare_activity(session_id, "user activity")
+ engine.queue_steering(message, source, activity)
+ return True
try:
- async for event in engine.run(message, source=source):
+ reason = "board activity" if board_delivery else "a scheduled check-in" if wake else "user activity"
+ activity = self.prepare_activity(session_id, reason, wake=wake)
+ if board_delivery and activity["board_text"]:
+ message = activity["board_text"]
+ source = {**source, "text": message, "board": {"rows": activity["board_rows"]}}
+ async for event in engine.run(message, source=source, activity=activity):
# 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(
@@ -5699,6 +5875,7 @@ class SessionManager:
)
self.unrouted.record(session_id, "-", message, reason=reason)
self.save(session_id, engine)
+ self.reconcile_activity_receipts(session_id)
except (
Exception
) as exc: # an unexpected raise out of the turn must not be swallowed
@@ -5710,6 +5887,7 @@ class SessionManager:
finally:
self.mark_idle(session_id)
await self.broadcast_session(session_id, {"type": "turn_done", "data": {}})
+ return True
# -- channel subscriptions (inbound messaging) ------------------------------
async def _dispatch_inbound(self, event) -> None:
diff --git a/tests/test_idle_checkins.py b/tests/test_idle_checkins.py
new file mode 100644
index 00000000..43866775
--- /dev/null
+++ b/tests/test_idle_checkins.py
@@ -0,0 +1,321 @@
+"""Idle deadlines, durable acceptance and batched lead delivery."""
+
+import asyncio
+import json
+from datetime import datetime, timedelta, timezone
+
+from coworker.selfwake import WakeStore, selfwake_tools
+from coworker.teams import Actor, Role
+from test_engine import ScriptedProvider, _text_turn
+from test_team_live_gaps import manager
+from test_team_reader_recovery import create_item
+
+
+def timer(manager, seconds=180, note="Verify Maya's tests"):
+ return manager.wakes.add_timer("lead", datetime.now(timezone.utc) + timedelta(seconds=seconds), note=note)
+
+
+def review(manager):
+ space, lead, item = create_item(manager)
+ worker = Actor(id="sam", role=Role.WORKER)
+ manager.team_store.transition(space, worker, item["id"], "in_progress")
+ manager.team_store.transition(space, worker, item["id"], "review", comment="Tests passed", refs=["test_billing.py"])
+ return space, item
+
+
+async def drain(manager):
+ team = manager.teams.for_lead_session("lead")
+ return await manager._drain_team_member(team, session_id="lead", actor="lead", is_lead=True)
+
+
+async def finish(manager):
+ for _ in range(100):
+ await asyncio.sleep(.01)
+ if not manager._team_inflight and not manager.is_running("lead"):
+ return
+ raise AssertionError("delivery did not finish")
+
+
+def test_both_sleep_tools_replace_each_other_without_changing_subscriptions(tmp_path):
+ store = WakeStore(tmp_path / "wakes.json")
+ relative, absolute, job, event = selfwake_tools(store, "lead")
+ first = relative(180, "Old")
+ second = absolute((datetime.now(timezone.utc) + timedelta(seconds=100)).isoformat(), "New")
+ job("job"); event("event")
+ assert first["wake_id"] not in {w.id for w in store.pending()}
+ assert len(store.pending()) == 3
+ store.cancel_sleep("lead", "board activity")
+ reloaded = WakeStore(store.path)
+ assert {w.kind for w in reloaded.pending()} == {"completion", "event"}
+ assert [w.id for w in reloaded.cancelled_context("lead")] == [second["wake_id"]]
+ assert reloaded.due(datetime.now(timezone.utc) + timedelta(days=1)) == []
+
+
+def test_reminder_survives_crash_before_input_and_acknowledges_saved_input(manager):
+ wake = timer(manager)
+ activity = manager.prepare_activity("lead", "user activity")
+ assert wake.id in activity["wake_ids"]
+ assert WakeStore(manager.wakes.path).cancelled_context("lead")
+ record = manager.session_store.load("lead")
+ record.messages.append({"role": "user", "content": "New scope", "_activity": activity})
+ manager.session_store.save(record)
+ # Simulate restart after saving input but before acknowledging the wake.
+ manager.wakes = WakeStore(manager.wakes.path)
+ manager.reconcile_activity_receipts("lead")
+ assert not manager.wakes.cancelled_context("lead")
+ assert not manager.prepare_activity("lead", "user activity")["wake_ids"]
+
+
+def test_user_input_is_verbatim_with_prior_reminder_and_board_context(manager):
+ manager.provider = ScriptedProvider([_text_turn("Understood")])
+ review(manager)
+ wake = timer(manager)
+ asyncio.run(manager.deliver_to_session("lead", "Ignore the old scope; inspect only."))
+ engine = manager.get_engine("lead")
+ user = next(m for m in engine.messages if m["role"] == "user")
+ assert user["content"] == "Ignore the old scope; inspect only."
+ assert "Verify Maya's tests" in user["_activity"]["text"]
+ assert "review" in user["_activity"]["text"]
+ outbound = engine._outbound_messages()
+ index = next(i for i, m in enumerate(outbound) if isinstance(m.get("content"), str) and m["content"].startswith(user["content"]))
+ assert outbound[index - 1]["role"] == "assistant"
+ assert "newer user instructions take precedence" in outbound[index - 1]["content"]
+ assert all("_activity" not in m for m in outbound)
+ assert wake.state == "cancelled" and wake.context_delivered
+ assert not manager._pending_board_context("lead")[0]
+
+
+def test_busy_timer_defers_instead_of_steering_or_being_lost(manager):
+ timer(manager, -1)
+ manager.mark_running("lead")
+ assert asyncio.run(manager.resume_due_wakes()) == 0
+ assert len(manager.wakes.due()) == 1
+
+
+def test_due_timer_and_board_produce_one_turn(manager):
+ manager.provider = ScriptedProvider([_text_turn("Checked")])
+ review(manager)
+ wake = timer(manager, -1)
+ async def run():
+ assert await drain(manager) == 1
+ assert await manager.resume_due_wakes() == 0
+ await finish(manager)
+ assert await manager.resume_due_wakes() == 0
+ asyncio.run(run())
+ messages = manager.session_store.load("lead").messages
+ assert len([m for m in messages if m["role"] == "user"]) == 1
+ assert wake.state == "cancelled" and wake.context_delivered
+
+
+def test_user_wins_queued_board_dispatch(manager):
+ manager.provider = ScriptedProvider([_text_turn("Following your scope")])
+ manager.TEAM_BATCH_SECONDS = 0
+ review(manager)
+ timer(manager)
+ async def run():
+ assert await drain(manager) == 1
+ # The board task is scheduled but has not claimed the session yet.
+ await manager.deliver_to_session("lead", "User's new scope")
+ await finish(manager)
+ assert await drain(manager) == 0
+ asyncio.run(run())
+ messages = manager.session_store.load("lead").messages
+ assert [m["content"] for m in messages if m["role"] == "user"] == ["User's new scope"]
+
+
+def test_stop_cancels_sleep_and_blocks_automatic_board_restart(manager):
+ wake = timer(manager)
+ review(manager)
+ manager.stop_session("lead")
+ assert asyncio.run(drain(manager)) == 0
+ assert not manager.wakes.pending("lead")
+ assert WakeStore(manager.wakes.path).stopped_sessions == {"lead"}
+ manager.provider = ScriptedProvider([_text_turn("Continuing")])
+ asyncio.run(manager.deliver_to_session("lead", "Continue with the new scope"))
+ assert "lead" not in manager.wakes.stopped_sessions
+ assert wake.context_delivered
+
+
+def test_fixed_batch_window_does_not_slide_and_sends_all_items(manager):
+ manager.provider = ScriptedProvider([_text_turn("Reviewing both")])
+ review(manager)
+ async def run():
+ assert await drain(manager) == 0
+ deadline = manager._team_batch_deadlines["lead"]
+ review(manager)
+ assert await drain(manager) == 0
+ assert manager._team_batch_deadlines["lead"] == deadline
+ manager._team_batch_deadlines["lead"] = 0
+ assert await drain(manager) == 1
+ await finish(manager)
+ asyncio.run(run())
+ messages = [m for m in manager.session_store.load("lead").messages if m["role"] == "user"]
+ assert len(messages) == 1
+ rows = messages[0]["source"]["board"]["rows"]
+ assert len([r for r in rows if r.get("to") == "review"]) == 2
+
+
+def test_approval_bypasses_window_and_keeps_independent_prompt_ids(manager):
+ manager.provider = ScriptedProvider([_text_turn("Waiting for the human")])
+ ids = []
+ for _ in range(2):
+ prompt = manager.inbox.add_approval("worker", "Run tests")
+ ids.append(prompt.id)
+ manager.note_worker_waiting("worker", "run_shell", prompt_id=prompt.id, preview="python -m unittest")
+ async def run():
+ assert await drain(manager) == 1
+ await finish(manager)
+ asyncio.run(run())
+ message = next(m for m in manager.session_store.load("lead").messages if m["role"] == "user")
+ assert {r["prompt_id"] for r in message["source"]["board"]["rows"]} == set(ids)
+
+
+def test_resolved_approval_does_not_wake_or_cancel_sleep(manager):
+ wake = timer(manager)
+ prompt = manager.inbox.add_approval("worker", "Run tests")
+ manager.note_worker_waiting("worker", "run_shell", prompt_id=prompt.id)
+ manager.inbox.resolve(prompt.id, "deny")
+ assert asyncio.run(drain(manager)) == 0
+ assert wake.state == "pending"
+
+
+def test_status_only_does_not_cancel_sleep(manager):
+ space, lead, item = create_item(manager)
+ worker = Actor(id="sam", role=Role.WORKER)
+ manager.team_store.transition(space, worker, item["id"], "in_progress")
+ manager.team_store.set_status(space, worker, item["id"], "Checking tests")
+ wake = timer(manager)
+ assert asyncio.run(drain(manager)) == 0
+ assert wake.state == "pending"
+
+
+def test_expiry_records_one_receipt_and_no_second_wake(manager):
+ manager.provider = ScriptedProvider([_text_turn("Checked")])
+ wake = timer(manager, -1)
+ async def run():
+ assert await manager.resume_due_wakes() == 1
+ await finish(manager)
+ assert await manager.resume_due_wakes() == 0
+ asyncio.run(run())
+ assert wake.state == "fired" and wake.context_delivered
+
+
+def test_reopened_review_is_marked_historical(manager):
+ space, item = review(manager)
+ manager.team_store.transition(space, Actor(id="lead", role=Role.LEAD), item["id"], "in_progress", comment="Needs another test")
+ text, rows, receipt = manager._pending_board_context("lead")
+ assert "historical transition; current state: in_progress" in text
+ assert next(r for r in rows if r.get("to") == "review")["historical"] is True
+
+
+def test_failed_delivery_keeps_due_timer(manager, monkeypatch):
+ wake = timer(manager, -1)
+ monkeypatch.setattr(manager, "get_engine", lambda *a: None)
+ async def run():
+ assert await manager.resume_due_wakes() == 1
+ await finish(manager)
+ asyncio.run(run())
+ assert wake in manager.wakes.due()
+ assert wake.state == "pending"
+
+
+def test_persisted_board_receipt_recovers_after_crash(manager):
+ review(manager)
+ activity = manager.prepare_activity("lead", "user activity")
+ record = manager.session_store.load("lead")
+ record.messages.append({"role": "user", "content": "Review", "_activity": activity})
+ manager.session_store.save(record)
+ assert manager._pending_board_context("lead")[0]
+ manager.reconcile_activity_receipts("lead")
+ assert not manager._pending_board_context("lead")[0]
+
+
+def test_question_is_urgent_but_not_an_approval(manager):
+ prompt = manager.inbox.add_question("worker", "Which invoice?")
+ manager.note_worker_waiting("worker", "ask_user", prompt_id=prompt.id)
+ text, rows, _ = manager._pending_board_context("lead")
+ assert "needs a human answer" in text
+ assert "Answer with decide_worker_call" not in text
+ assert rows[0]["kind"] == "waiting"
+
+
+def test_blocker_bypasses_batch_window(manager):
+ manager.provider = ScriptedProvider([_text_turn("Checking blocker")])
+ space, _, item = create_item(manager)
+ manager.team_store.transition(space, Actor(id="sam", role=Role.WORKER), item["id"], "in_progress")
+ manager.team_store.transition(space, Actor(id="sam", role=Role.WORKER), item["id"], "blocked", comment="Need fixture")
+ async def run():
+ assert await drain(manager) == 1
+ await finish(manager)
+ asyncio.run(run())
+
+
+def test_stop_catches_sleep_registered_late_in_interrupted_turn(manager):
+ manager.stop_session("lead")
+ wake = timer(manager)
+ manager.mark_idle("lead")
+ assert wake.state == "cancelled"
+ assert not manager.wakes.pending("lead")
+
+
+def test_idle_batch_flushes_without_waiting_for_scheduler(manager):
+ manager.TEAM_BATCH_SECONDS = .02
+ manager.provider = ScriptedProvider([_text_turn("Reviewing")])
+ review(manager)
+ async def run():
+ assert await drain(manager) == 0
+ # Limit this test's automatic tick to the lead, not the sample worker.
+ async def lead_tick():
+ return await drain(manager)
+ manager.team_tick = lead_tick
+ await asyncio.sleep(.05)
+ await finish(manager)
+ asyncio.run(run())
+ assert len([m for m in manager.session_store.load("lead").messages if m["role"] == "user"]) == 1
+
+
+def test_multiple_steering_messages_carry_reminder_and_board_only_once(manager):
+ manager.provider = ScriptedProvider([_text_turn("Following the new scope")])
+ engine = manager.get_engine("lead")
+ review(manager)
+ timer(manager)
+ manager.mark_running("lead")
+ async def run():
+ await manager.deliver_to_session("lead", "First instruction")
+ await manager.deliver_to_session("lead", "Second instruction")
+ first = engine._steering[0][2]
+ second = engine._steering[1][2]
+ assert first["wake_ids"] and not second["wake_ids"]
+ assert first["board_text"] and not second["board_text"]
+ late = timer(manager, note="Registered while interrupted")
+ await manager.broadcast_session("lead", {"type": "iteration_end", "data": {}})
+ assert late.state == "cancelled"
+ assert late.id in engine._steering[0][2]["wake_ids"]
+ engine._inject_steering()
+ manager.save("lead", engine)
+ manager.reconcile_activity_receipts("lead")
+ assert not manager.wakes.cancelled_context("lead")
+ assert not manager._pending_board_context("lead")[0]
+ asyncio.run(run())
+
+
+def test_unsaved_in_memory_receipt_does_not_acknowledge_context(manager):
+ engine = manager.get_engine("lead")
+ timer(manager)
+ activity = manager.prepare_activity("lead", "user activity")
+ engine.messages.append({"role": "user", "content": "New scope", "_activity": activity})
+ manager.reconcile_activity_receipts("lead")
+ assert manager.wakes.cancelled_context("lead")
+
+
+def test_legacy_multiple_timers_migrate_to_latest_sleep(tmp_path):
+ path = tmp_path / "wakes.json"
+ # Fixture construction only: emulate a persisted record from the old runtime.
+ path.write_text(json.dumps({"wakes": [
+ {"id": "old", "session_id": "lead", "kind": "timer", "created_at": "2026-09-19T01:00:00Z"},
+ {"id": "new", "session_id": "lead", "kind": "timer", "created_at": "2026-09-19T02:00:00Z"}
+ ]}))
+ store = WakeStore(path)
+ assert [w.id for w in store.pending("lead")] == ["new"]
+ assert not store.cancelled_context("lead")
+ assert [w.id for w in WakeStore(path).pending("lead")] == ["new"]
diff --git a/tests/test_self_wake.py b/tests/test_self_wake.py
index 3106fde0..6491bc4b 100644
--- a/tests/test_self_wake.py
+++ b/tests/test_self_wake.py
@@ -62,5 +62,5 @@ def test_selfwake_tools(tmp_path):
assert wake_on_event("alert-fired")["event_key"] == "alert-fired"
pend = store.pending("s1")
- assert len(pend) == 4
+ assert len(pend) == 3 # the second sleep replaces the first
assert {w.kind for w in pend} == {"timer", "completion", "event"}