Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

10.0 KB
Raw Blame
"""The Managed Deep Agents waker, on public runtime schedules only.

A wake-up is a one-time schedule on the lead's own thread (`runtime.schedules.create(at=..., new_thread
=False)`). It survives redeploys, runs with the thread's channel binding (so its reply posts to the
Slack thread and `upload_files` works), and counts as delivered only once the woken run reports it
started: the run's first hook writes the wake key to the deployment store and this waker polls it.

Constraints from managed-deepagents 0.9.3 (docs/architecture/orchestration.md):

- `at` is rounded up to the next whole minute and must be at least one minute ahead, so a wake-up
  lands 60-120 s after the event, plus the scheduler's own lag. The harness inbox already
  coalesces events, so one schedule carries everything that happened meanwhile.
- A schedule can only be created from a run's runtime, for that run's thread. The waker keeps each
  thread's latest `runtime.schedules` in memory; after a restart a thread has none until a run on
  it happens. So while a thread has background work it holds one sentinel schedule
  `SENTINEL_MINUTES` ahead, which this process pushes forward every `POSTPONE_SECONDS`: it fires
  only once the process that kept moving it is gone, and that turn's sweep reports what the
  restart interrupted. Should it fire while the work still runs here (a postponement failed), the
  turn ends in code without a model call (`QuietReplyMiddleware`).
- Every scheduled run's reply is posted (MDA's schedule delivery runs after every authored hook),
  so a `[quiet]` reply becomes a one-line status (`middleware/quiet.py`).
- Agent-owned same-thread schedules need a channel binding; runs without one (Studio, the API) use
  the caller as the owner.
- Each owner can hold at most `MDA_MAX_AGENT_SCHEDULES` (default 20) unexpired schedules.
"""

from __future__ import annotations

import asyncio
import logging
import time
from collections.abc import Callable
from dataclasses import dataclass, field
from datetime import UTC, datetime, timedelta
from typing import Any

from langgraph.config import get_config

from design_agent.harness.protocols import WakeReceipt, WakeTarget
from design_agent.harness.tasks import running
from design_agent.middleware.quiet import SENTINEL_MARK, latest_human
from design_agent.runtime.waker import wake_key, wake_marker

_LOGGER = logging.getLogger(__name__)

STARTED_NAMESPACE = ("design_agent", "wake_started")
#: The schedule API refuses anything under a minute ahead; this rounds up to the minute after.
LEAD_SECONDS = 61
SENTINEL_MINUTES = 15
POSTPONE_SECONDS = 300.0
START_TIMEOUT_SECONDS = 300.0
POLL_SECONDS = 5.0


def _thread_of(runtime: Any) -> str:
    """The run's thread: a tool's runtime carries its config; a lifecycle hook's reads the
    ambient run config."""
    config = getattr(runtime, "config", None)
    if not config:
        try:
            config = get_config()
        except RuntimeError:
            config = {}
    return str((config.get("configurable") or {}).get("thread_id") or "")


@dataclass
class _Route:
    schedules: Any
    owner: dict[str, str]
    store: Any
    sentinel: str | None = None
    keeper: asyncio.Task[None] | None = None


@dataclass
class MdaScheduleWaker:
    """`harness.protocols.Waker` on MDA runtime schedules (module doc)."""

    clock: Callable[[], datetime] = field(default=lambda: datetime.now(UTC))
    poll_seconds: float = POLL_SECONDS
    postpone_seconds: float = POSTPONE_SECONDS
    start_timeout_seconds: float = START_TIMEOUT_SECONDS
    _routes: dict[str, _Route] = field(default_factory=dict)
    _pending: dict[str, str] = field(default_factory=dict)

    async def capture(self, runtime: Any) -> WakeTarget | None:
        """Keep where this thread's lead can be woken, from a live run's runtime."""
        thread_id = _thread_of(runtime)
        schedules = getattr(runtime, "schedules", None)
        if not thread_id or schedules is None:
            return None
        owner = (
            {"type": "agent"} if getattr(runtime, "channel", None) is not None else {"type": "user"}
        )
        previous = self._routes.get(thread_id)
        route = _Route(schedules, owner, getattr(runtime, "store", None))
        if previous is not None:
            route.sentinel, route.keeper = previous.sentinel, previous.keeper
        self._routes[thread_id] = route
        return WakeTarget(thread_id, channel={"owner": owner["type"]})

    async def wake(self, target: WakeTarget, message: str, *, dedupe_key: str) -> WakeReceipt:
        route = self._routes.get(target.thread_id)
        if route is None:
            return WakeReceipt(
                False, detail="no live route to this thread; its next run carries the news"
            )
        if dedupe_key not in self._pending:
            at = self.clock() + timedelta(seconds=LEAD_SECONDS)
            record = await route.schedules.create(
                owner=route.owner,
                at=at,
                prompt=f"{message}\n\n{wake_marker(dedupe_key)}",
                new_thread=False,
                metadata={"design_agent": "wake"},
            )
            self._pending[dedupe_key] = str(record["id"])
        if await self._started(route.store, dedupe_key):
            self._pending.pop(dedupe_key, None)
            return WakeReceipt(True)
        return WakeReceipt(False, detail="the scheduled wake-up has not started yet")

    async def _started(self, store: Any, key: str) -> bool:
        if store is None:
            return True  # nothing to confirm with; MDA owns the schedule from here
        deadline = time.monotonic() + self.start_timeout_seconds
        while time.monotonic() < deadline:
            item = await store.aget(STARTED_NAMESPACE, key)
            if item is not None:
                await store.adelete(STARTED_NAMESPACE, key)
                return True
            await asyncio.sleep(self.poll_seconds)
        return False

    async def schedule(self, target: WakeTarget, at: datetime, message: str) -> str:
        route = self._routes.get(target.thread_id)
        if route is None:
            raise RuntimeError("check-ins need a live run on this thread")
        earliest = self.clock() + timedelta(seconds=LEAD_SECONDS)
        record = await route.schedules.create(
            owner=route.owner,
            at=max(at, earliest),
            prompt=message,
            new_thread=False,
            metadata={"design_agent": "check-in"},
        )
        return str(record["id"])

    async def cancel(self, schedule_id: str) -> None:
        for route in self._routes.values():
            try:
                await route.schedules.delete(schedule_id, owner=route.owner)
                return
            except Exception as error:  # noqa: BLE001 - not this owner's, or already gone
                _LOGGER.debug(
                    "[waker] schedule %s not deleted here: %s", schedule_id, type(error).__name__
                )

    async def watchdog(self, target: WakeTarget, active: bool) -> None:
        """Hold one sentinel per thread while it has background work, kept ahead (module doc)."""
        route = self._routes.get(target.thread_id)
        if route is None:
            return
        if active and route.sentinel is None:
            route.sentinel = await self._arm(route)
        if active and (route.keeper is None or route.keeper.done()):
            route.keeper = asyncio.get_running_loop().create_task(
                self._keep(target.thread_id), name=f"sentinel {target.thread_id}"
            )
        elif not active:
            await self._disarm(route)

    async def _keep(self, thread_id: str) -> None:
        """Push the thread's sentinel forward while its work runs here; drop it after."""
        while True:
            await asyncio.sleep(self.postpone_seconds)
            route = self._routes.get(thread_id)
            if route is None:
                return
            if not running(thread_id):
                route.keeper = None
                await self._disarm(route)
                return
            old, route.sentinel = route.sentinel, await self._arm(route)
            if old is not None and route.sentinel is not None:
                await self.cancel(old)
            elif route.sentinel is None:
                route.sentinel = old  # keep the one there is rather than none

    async def _disarm(self, route: _Route) -> None:
        if route.keeper is not None and route.keeper is not asyncio.current_task():
            route.keeper.cancel()
        route.keeper = None
        if route.sentinel is not None:
            sentinel, route.sentinel = route.sentinel, None
            await self.cancel(sentinel)

    async def _arm(self, route: _Route) -> str | None:
        try:
            record = await route.schedules.create(
                owner=route.owner,
                at=self.clock() + timedelta(minutes=SENTINEL_MINUTES),
                prompt=(
                    f"{SENTINEL_MARK}>\nA restart may have stopped background work on this "
                    "thread. Tell the person in a line what stopped and offer to resume it; if "
                    "nothing did, reply exactly [quiet]."
                ),
                new_thread=False,
                metadata={"design_agent": "watchdog"},
            )
        except Exception as error:  # noqa: BLE001 - e.g. the owner's schedule cap; work goes on
            _LOGGER.warning("[waker] sentinel not armed: %s", str(error)[:200])
            return None
        return str(record["id"])

    async def on_turn_start(self, runtime: Any, messages: list[Any]) -> None:
        """Confirm a wake-up started; re-arm the sentinel when it is the one that fired."""
        text = latest_human(messages)
        key = wake_key(text)
        store = getattr(runtime, "store", None)
        if key and store is not None:
            await store.aput(STARTED_NAMESPACE, key, {"at": time.time()})
        if SENTINEL_MARK in text:
            target = await self.capture(runtime)
            if target is not None:
                self._routes[target.thread_id].sentinel = None  # this one has fired
                await self.watchdog(target, bool(running(target.thread_id)))