Skip to content

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

8.3 KB
Raw Blame
"""The notice the lead is woken with: what happened in the background, and what is still running.

A notice is a message appended to the lead's conversation (never edited, so the prompt cache
holds) that says how each helper ended with its report, what helpers and
watches reported, which check-ins came due, what still runs, and what the lead might do next. It is
rendered from the events the inbox delivers, so a new kind of source only needs a line format here.

Two things stay out of it on purpose:
- per-call timers in the system prompt: time-varying text there breaks the cache on every call. The
  running list lives here, in a message written once;
- instructions that decide for the lead: it gets the facts and the likely next step, and judges.
"""

from __future__ import annotations

import time
from collections.abc import Callable, Sequence

from design_agent.harness import events as ev
from design_agent.harness.tasks import minutes

#: A wake-up reply that is exactly this is not posted anywhere.
QUIET = "[quiet]"
#: Set by the adapter: text a helper's report carries when it stopped at the graph's step limit.
PARTIAL_MARKER: str | None = None

#: Sources of "still running" lines, one callable per kind of background work (helpers, watches,
#: pipelines). Each takes a thread id and returns lines like "t-1a2b3c (xhigh, act 3, 12 min)".
RUNNING_PROVIDERS: list[Callable[[str], list[str]]] = []
#: Sources of scheduled check-in ids for a thread.
SCHEDULED_PROVIDERS: list[Callable[[str], list[str]]] = []

_ENDED = {ev.TASK_DONE, ev.TASK_FAILED}
_WATCH_ALERTS = {ev.WATCH_ERROR, ev.WATCH_STALLED}


def _took(event: ev.Event) -> str:
    started = float(event.data.get("started_at") or event.at)
    finished = float(event.data.get("finished_at") or event.at)
    return minutes(finished - started)


def _head(event: ev.Event) -> str:
    effort = event.data.get("effort")
    wave = event.data.get("wave")
    parts = [p for p in (effort, event.label) if p]
    return f"- {event.source} ({', '.join(parts)}{', wave ' + str(wave) if wave else ''})"


def _line(event: ev.Event) -> str:
    kind, head = event.kind, _head(event)
    if kind == ev.TASK_DONE:
        report = event.text.strip() or "(no report)"
        ended = (
            "stopped early at the graph's step limit"
            if PARTIAL_MARKER and PARTIAL_MARKER in report
            else "done"
        )
        return f"{head}: {ended} in {_took(event)}. Its report:\n{report}"
    if kind == ev.TASK_FAILED:
        return f"{head}: failed after {_took(event)}. {event.text}".rstrip()
    if kind == ev.TASK_INTERRUPTED:
        return f"{head}: interrupted by a restart after {_took(event)}. {event.text}".rstrip()
    if kind == ev.TASK_PROGRESS:
        return f"{head} reports: {event.text}"
    if kind == ev.PIPELINE_STEP:
        return f"- {event.source} ({event.label}): {event.text}"
    if kind == ev.WAKEUP_DUE:
        set_at = float(event.data.get("set_at") or event.at)
        return (
            f"- Your wake-up {event.source}, set {minutes(time.time() - set_at)} ago "
            f"({event.label}). Your note: {event.text}"
        )
    if kind == ev.WATCH_ERROR:
        return f"- {event.source} ({event.label}) failed:\n{event.text}".rstrip()
    if kind == ev.WATCH_STALLED:
        why = "timed out" if event.data.get("timeout") else "has shown no progress"
        return f"- {event.source} ({event.label}) {why}. {event.text}".rstrip()
    if kind == ev.WATCH_DONE:
        return f"- {event.source} ({event.label}) finished. {event.text}".rstrip()
    if kind == ev.WATCH_PROGRESS:
        fraction = event.data.get("fraction")
        pct = f"{round(float(fraction) * 100)}%" if fraction is not None else event.text
        if event.data.get("resumed"):
            return f"- {event.source} ({event.label}) is moving again: {event.text or pct}"
        return f"- {event.source} ({event.label}): {pct}"
    if kind == ev.JOB_ATTENTION:
        return (
            f"- {event.label or event.source} needs someone: {event.text} (the person was pinged)"
        )
    return f"- {event.kind} from {event.source} ({event.label}): {event.text}".rstrip()


def _title(events: Sequence[ev.Event]) -> str:
    kinds = {e.kind for e in events}
    if kinds & _ENDED:
        return "Background work finished"
    if ev.TASK_INTERRUPTED in kinds:
        return "Background work was interrupted"
    if kinds & _WATCH_ALERTS:
        return "A watched job needs you"
    if ev.WATCH_DONE in kinds:
        return "A watched job finished"
    if ev.JOB_ATTENTION in kinds:
        return "Someone needs to act"
    if kinds & {ev.TASK_PROGRESS, ev.PIPELINE_STEP, ev.WATCH_PROGRESS}:
        return "Progress from background work"
    if ev.WAKEUP_DUE in kinds:
        return "The wake-up you scheduled"
    return "Background update"


def render(thread_id: str, events: Sequence[ev.Event], *, guidance: bool = True) -> str:
    """The wake-up message for one delivery: the events in the order they happened. Without
    `guidance` it is only the news (for a turn the person started: they asked for something else)."""
    events = sorted(events, key=lambda e: e.at)
    ended = [e for e in events if e.kind in _ENDED]
    finished = ended + [e for e in events if e.kind == ev.TASK_INTERRUPTED]
    header = f"[Runtime notice, not from the user] {_title(events)}"
    header += f" ({len(finished)} tasks)." if len(finished) > 1 else "."
    lines = [header, *(_line(e) for e in events)]

    running = [line for provider in RUNNING_PROVIDERS for line in provider(thread_id)]
    if running:
        lines.append(
            f"Still running: {'; '.join(running)}. Each wakes you when it ends or needs you; "
            "progress notes reach you with your next turn."
        )
    if not guidance:
        return "\n".join(lines)
    kinds = {e.kind for e in events}
    if ev.TASK_INTERRUPTED in kinds:
        lines.append(
            "Resume each interrupted task now with resume_task: it continues from its saved "
            "transcript, in the same sandbox. If nothing was saved, re-issue it with start_task "
            "under the resume preamble (/skills/launch-film/briefs/resume.md), since its files and "
            "progress notes are on disk. Tell the person what happened and the new ETA."
        )
    if kinds & _WATCH_ALERTS:
        lines.append(
            "Look at what the watch reported: fix and restart the job, or tell the person what "
            "happened and what you'll do."
        )
    if ev.WAKEUP_DUE in kinds:
        lines.append(
            "Do what your note says. If work is still running, schedule the next wake-up before you "
            "end the turn; if it is done, don't."
        )
    if not finished and not kinds & (_WATCH_ALERTS | {ev.WATCH_DONE, ev.JOB_ATTENTION}):
        lines.append(
            "If this changes what the person expects, tell them in a line; otherwise reply with "
            f"exactly {QUIET}: at most a one-line status of the running work is posted."
        )
    elif not ended:
        pass
    elif running:
        lines.append(
            "Do what this result needs now: review it, or start the work that depends only on it, in "
            "the background. Leave what depends on the running work (integration, shared-file "
            "merges) until it lands. Tell the person in a line or two what landed and what comes "
            "next, with an ETA."
        )
    else:
        lines.append(
            "Nothing else is running. Review these results against the plan (a critic pass if the "
            "plan calls for one), start the next step, and tell the person where things stand and "
            "what comes next, with an ETA."
        )
        scheduled = [i for provider in SCHEDULED_PROVIDERS for i in provider(thread_id)]
        if scheduled:
            lines.append(
                f"Check-ins still scheduled: {', '.join(scheduled)}. Cancel them if the work is done."
            )
    # Without this, replies borrow the notice's vocabulary, and the people reading them are not
    # engineers.
    lines.append(
        "Whatever you tell the person, say it about the work, in a teammate's words: the tasks, "
        "watches, logs and check-ins above are yours, not theirs."
    )
    return "\n".join(lines)


def should_post(text: str) -> bool:
    """A wake-up reply is posted unless it is empty or the lead chose to stay quiet."""
    return bool(text) and text.strip() != QUIET