Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
JavaScript agentagentsai-agentdeepagentsdesignhyperframeslanggraphmanaged-agentsmotion-graphicspaperslackvideo
"""Background work: the harness's helper primitives, bound to a runtime through a `Waker`.
The primitives live in `design_agent.harness` (docs/architecture/orchestration.md). This module is
the agent's side of them:
- **`start_task`** runs one of the declared subagents through the `task` tool Deep Agents built
for this run, detached from the turn. It returns at once, so the lead replies with an ETA and
its turn ends. The helper's config is the lead's minus LangGraph's per-run internals, so it works
in the thread's own sandbox with the thread's files.
- **The lead is woken** through the runtime's `Waker` (MDA one-time schedules on the thread; the
self-hosted and local runners queue a run in-process) when a helper finishes, fails or was
interrupted by a restart, when a watched job fails, stalls or finishes, and when a check-in comes
due. A helper's `report_progress` note waits for the lead's next turn unless it is urgent or the
lead asked to follow that task closely. A reply of exactly `[quiet]` posts nothing, or one
status line where the platform posts every scheduled run (`QuietReplyMiddleware`).
- **`schedule_wakeup`** lets the lead wake itself later with a note; **`check_tasks`** and
**`cancel_task`** report and stop background work; **`resume_task`** continues a helper a
restart killed from its saved transcript (`harness.durable`).
Effort workers (`low`, `xhigh`, `max`) run only in the background: a synchronous `task` call naming
one is refused with a pointer to `start_task`. `general-purpose` stays available synchronously.
Helpers live in this process: a deploy or restart ends them. Each keeps a heartbeat record in the
store until the lead has been told how it ended, so a restart loses neither a running helper (the
sweep reports it interrupted) nor a finished one whose notice was not yet delivered.
The lead's system prompt carries nothing that changes while work runs, so the prompt cache holds:
what is running is in each notice and in `check_tasks`.
One middleware instance serves every run in the process, and each run's `task` tool runs its
subagents in that run's own sandbox, so captured task tools are keyed by run, never shared.
"""
from __future__ import annotations
import asyncio
import logging
import time
from collections import OrderedDict
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass, field
from datetime import UTC, datetime, timedelta
from typing import Annotated, Any, Literal, NotRequired, cast
from langchain.agents.middleware import AgentMiddleware, AgentState, ModelRequest, ModelResponse
from langchain.tools import ToolRuntime
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.runnables import RunnableConfig
from langchain_core.runnables.config import var_child_runnable_config
from langchain_core.tools import BaseTool, StructuredTool
from langgraph.config import get_config
from langgraph.types import Command
from design_agent.harness import durable, ledger, notices, tasks
from design_agent.harness import events as ev
from design_agent.harness.inbox import Inbox
from design_agent.harness.meter import CURRENT_TASK_ID
from design_agent.harness.protocols import HelperResult, Waker, WakeTarget
from design_agent.harness.tasks import REGISTRY, TaskRecord
from design_agent.middleware.quiet import is_watchdog_turn
_LOGGER = logging.getLogger(__name__)
#: The declared effort workers (`design_agent.subagents`). They run only in the background.
WORKER_TYPES = frozenset({"low", "xhigh", "max", "learning"})
#: `start_task`'s effort, as the subagent type that runs it: `high` is general-purpose, on the
#: lead's model and effort.
EFFORT_TYPES: dict[str, str] = {
"low": "low",
"high": "general-purpose",
"xhigh": "xhigh",
"max": "max",
"learning": "learning",
}
REFUSED_SYNC = (
"Workers run in the background, so this was not started. Use start_task with the same "
"description and effort; it returns at once, and you are woken when the work is done."
)
#: How many runs' `task` tools are kept; a finished run's entry is pushed out by newer ones.
TASK_TOOLS_KEPT = 64
#: How often a run looks for work a restart killed (housekeeping always does).
SWEEP_EVERY_SECONDS = 120.0
CHECK_IN_MARK = "<check-in"
CaptureTarget = Callable[[Any], Awaitable[WakeTarget | None]]
#: Told when a thread gains or loses background work (`active`), so an adapter can keep a
#: restart watchdog such as MDA's sentinel check-in.
Watchdog = Callable[[WakeTarget, bool], Awaitable[None]]
#: Called at the start of every lead turn with the runtime and messages (a waker confirming that
#: the turn it scheduled started).
TurnStart = Callable[[Any, list[Any]], Awaitable[None]]
def _merge(
existing: dict[str, dict[str, Any]] | None, update: dict[str, dict[str, Any]]
) -> dict[str, dict[str, Any]]:
merged = dict(existing or {})
for key, entry in update.items():
merged[key] = {**merged.get(key, {}), **entry}
return merged
class BackgroundState(AgentState[Any]):
#: What was started on this thread, so a later run (after a restart) knows a task existed even
#: when this process no longer holds it.
background_tasks: NotRequired[Annotated[dict[str, dict[str, Any]], _merge]]
#: Check-ins the lead scheduled, by id, so `cancel_task` can find one after a restart.
background_check_ins: NotRequired[Annotated[dict[str, dict[str, Any]], _merge]]
@dataclass
class BackgroundServices:
"""The process's wake-up plumbing, built once by the runtime adapter."""
waker: Waker
capture_target: CaptureTarget
watchdog: Watchdog | None = None
on_turn_start: TurnStart | None = None
#: Other sweeps a restart needs (watches, pipelines), run after the helpers' sweep.
sweepers: list[Callable[[Any], Awaitable[int]]] = field(default_factory=list)
inbox: Inbox = field(init=False)
_last_sweep: float = field(default=0.0, init=False)
_sweeping: asyncio.Task[None] | None = field(default=None, init=False)
def __post_init__(self) -> None:
self.inbox = Inbox(self.waker)
self.inbox.on_delivered(self._after_delivery)
async def attach(self, runtime: Any) -> WakeTarget | None:
"""Register where to wake this thread's lead. None outside a thread."""
target = await self.capture_target(runtime)
if target is not None:
self.inbox.set_target(target.thread_id, target)
return target
async def _after_delivery(self, batch: Sequence[ev.Event]) -> None:
"""Once the lead has heard how a helper ended, its record can go, and so can the
transcript of one that finished (a failed helper's stays, so it can be resumed)."""
for event in batch:
if event.kind not in (ev.TASK_DONE, ev.TASK_FAILED):
continue
record = REGISTRY.get(event.source)
if record is None or record.delivered:
continue
await ledger.forget(record)
if event.kind == ev.TASK_DONE and record.store is not None:
try:
await durable.TranscriptStore(record.store).delete(record.id)
except Exception as error: # noqa: BLE001 - it expires with the store's TTL
_LOGGER.warning("[background] dropping a transcript: %s", type(error).__name__)
if self.watchdog is not None and not tasks.running(record.thread_id):
box = self.inbox.box(record.thread_id)
if box is not None:
await self.watchdog(box.target, False)
async def sweep(self, store: Any) -> int:
"""Tell leads about helpers a restart killed or whose notice a restart swallowed."""
async def on_task(key: str, value: dict[str, Any]) -> None:
thread_id = str(value.get("thread_id") or "")
if not thread_id:
return
if self.inbox.box(thread_id) is None:
self.inbox.set_target(thread_id, WakeTarget(thread_id, channel=value.get("wake")))
status = str(value.get("status") or "running")
if status == "done":
kind, text = ev.TASK_DONE, str(value.get("report") or "")
elif status == "failed":
kind, text = ev.TASK_FAILED, str(value.get("error") or "")
else:
kind, text = ev.TASK_INTERRUPTED, "Its files and progress notes are on disk."
ev.BUS.publish(
ev.Event(
kind,
thread_id,
key,
label=str(value.get("label") or key),
text=text,
data={
"effort": value.get("effort"),
"wave": value.get("wave"),
"started_at": value.get("started_at"),
"finished_at": value.get("finished_at") or value.get("alive_at"),
},
)
)
async def ignore(_key: str, _value: dict[str, Any]) -> None:
return None
found = await ledger.sweep(store, on_task=on_task, on_wakeup=ignore)
for sweeper in self.sweepers:
try:
found += await sweeper(store)
except Exception as error: # noqa: BLE001 - one sweeper failing never stops the rest
_LOGGER.warning("[background] a sweeper failed: %s", type(error).__name__)
return found
def maybe_sweep(self, store: Any) -> None:
if store is None or time.time() - self._last_sweep < SWEEP_EVERY_SECONDS:
return
self._last_sweep = time.time()
async def run() -> None:
try:
await self.sweep(store)
except Exception as error: # noqa: BLE001 - the next sweep tries again
_LOGGER.warning("[background] the sweep failed: %s", type(error).__name__)
self._sweeping = asyncio.get_running_loop().create_task(run(), name="background sweep")
async def aclose(self) -> None:
"""Let a sweep in flight finish before the process's loop closes (the CLI exits)."""
if self._sweeping is not None and not self._sweeping.done():
await asyncio.wait({self._sweeping}, timeout=30)
def _field(value: object, key: str) -> Any:
if isinstance(value, Mapping):
return value.get(key)
return getattr(value, key, None)
def detached_config(config: Mapping[str, Any]) -> RunnableConfig:
"""The lead run's config without LangGraph's per-run internals or callbacks: a helper must not
write checkpoints into a run that ended. The thread id that names the sandbox stays."""
configurable = {
key: value
for key, value in dict(config.get("configurable") or {}).items()
if not key.startswith(("__pregel_", "checkpoint_"))
}
detached = {
key: value for key, value in config.items() if key not in {"configurable", "callbacks"}
}
detached["configurable"] = configurable
return cast("RunnableConfig", detached)
def detached_runtime(runtime: Any, task_id: str) -> ToolRuntime:
"""A tool runtime for a helper that outlives the lead's call: the lead's state without its
messages, its context and store, and its config without the ended run's internals."""
return ToolRuntime(
state={k: v for k, v in dict(runtime.state or {}).items() if k != "messages"},
context=runtime.context,
config=detached_config(dict(runtime.config or {})),
stream_writer=lambda *_args, **_kwargs: None,
tool_call_id=f"background-{task_id}",
store=runtime.store,
)
def _run_key(config: Mapping[str, Any] | None) -> str:
for container in ("configurable", "metadata"):
run_id = _field((config or {}).get(container), "run_id")
if run_id:
return f"run:{run_id}"
return f"thread:{_field((config or {}).get('configurable'), 'thread_id') or ''}"
def _current_config(runtime: Any = None) -> Mapping[str, Any]:
try:
return get_config()
except RuntimeError:
return dict(getattr(runtime, "config", None) or {})
def _thread_of(runtime: Any) -> str:
return str(
_field((getattr(runtime, "config", None) or {}).get("configurable"), "thread_id") or ""
)
def _report(result: object) -> str:
"""The subagent's final message, from the `Command` Deep Agents' `task` returns."""
update = getattr(result, "update", None)
messages = update.get("messages") if isinstance(update, Mapping) else None
if isinstance(messages, list) and messages:
content = getattr(messages[-1], "content", "")
return content if isinstance(content, str) else str(content)
return result if isinstance(result, str) else ""
async def _ended(record: TaskRecord) -> None:
"""Persist how the helper ended before the lead is told; a cancelled one needs no telling."""
if record.status == "cancelled":
await ledger.forget(record)
else:
await ledger.beat(record)
class BackgroundTaskMiddleware(AgentMiddleware[BackgroundState, Any, Any]):
"""The lead's background tools, task capture and the start-of-turn catch-up (module doc)."""
state_schema = BackgroundState
def __init__(self, services: BackgroundServices) -> None:
super().__init__()
self.services = services
self._task_tools: OrderedDict[str, Any] = OrderedDict()
self.tools = self._build_tools()
@property
def name(self) -> str:
return "DesignAgentBackground"
# -- tools -------------------------------------------------------------------------------
def _build_tools(self) -> list[BaseTool]:
middleware = self
async def start_task(
description: str,
effort: Literal["low", "high", "xhigh", "max"],
runtime: ToolRuntime,
label: str = "",
wave: str = "",
wake_on_progress: bool = False,
) -> Command[Any] | str:
"""Start a helper in the background and return at once.
`description` is the helper's whole prompt: a complete brief stating the role,
quality bar, inputs, the files it owns, how to check the work, budget, progress file
and how to resume (the launch-film skill has brief templates). `effort`:
- `low` for mechanical work: grabs, conversions, renders of an approved film;
- `high` for ordinary work;
- `xhigh` for substantial work to a clear brief: a build, a breakdown, a review;
- `max` for the hardest creative work: a flagship concept, a hero act.
Helpers work in this thread's computer, so they see the project's files. `label`
names the job in status lines ("act 3"); `wave` groups related tasks.
You are woken when it finishes, fails or is interrupted. Its progress notes wait for
your next turn; set `wake_on_progress` to be woken by each one. Do not poll with
check_tasks. After starting work, say what is running and when to expect it, and end
your turn.
"""
launched = await middleware.launch(
description, effort, label, wave, runtime, wake_on_progress=wake_on_progress
)
if isinstance(launched, str):
return launched
started = (
f"Started {launched.id} ({effort}, {launched.label}) in the background"
+ (f" as part of wave {launched.wave}" if launched.wave else "")
+ ". It works in this thread's computer; you will be woken when it ends or needs "
"you. If it will run longer than about 15 minutes, schedule a check-in with "
"schedule_wakeup so the person hears how it is going."
)
return Command(
update={
"messages": [ToolMessage(started, tool_call_id=runtime.tool_call_id)],
"background_tasks": {launched.id: launched.summary()},
}
)
async def check_tasks(runtime: ToolRuntime, task_id: str = "") -> str:
"""What is running in the background on this thread, and what finished with its
report. Pass `task_id` for one task's full report; leave it empty for everything."""
return middleware.status(runtime, task_id)
async def cancel_task(task_id: str, runtime: ToolRuntime) -> Command[Any] | str:
"""Stop background work by its id: a task, a watch, a pipeline, or a check-in you
scheduled. A task's files stay; nothing you cancel wakes you."""
return await middleware.cancel(runtime, task_id)
async def schedule_wakeup(
minutes: int, prompt: str, reason: str, runtime: ToolRuntime
) -> Command[Any] | str:
"""Wake yourself later on this thread, with `prompt` as a note to your future self.
Use it to keep the person informed during long work and to check on work nothing
reports on. It fires once; to keep checking in, schedule the next one when it fires,
and stop once the work is done. Pick `minutes` (1 to 1440): about 10-15 for long work
someone is following, 30-60 or more for slow or overnight work. Tasks and watches wake
you themselves when they end or need you. `prompt` holds what to check, what to tell
the person, and whether to check in again; `reason` is one short line shown in status.
If nothing has changed when it fires, reply exactly `[quiet]`: at most a one-line
status of the running work is posted.
"""
return await middleware.schedule(minutes, prompt, reason, runtime)
async def resume_task(task_id: str, runtime: ToolRuntime) -> Command[Any] | str:
"""Continue a background task a restart interrupted, from its saved transcript: same
id, effort and label, picking up where it stopped. Use it when a notice says a task
was interrupted; if nothing was saved, re-issue the brief with start_task."""
return await middleware.resume(task_id, runtime)
functions: tuple[Callable[..., Awaitable[Any]], ...] = (
start_task,
check_tasks,
cancel_task,
schedule_wakeup,
resume_task,
)
return [StructuredTool.from_function(coroutine=f, name=f.__name__) for f in functions]
# -- starting helpers -------------------------------------------------------------------
def task_tool_for(self, runtime: Any) -> Any:
"""The `task` tool this run's own model calls were offered, or None before the first."""
return self._task_tools.get(_run_key(_current_config(runtime)))
async def launch(
self,
description: str,
effort: str,
label: str,
wave: str,
runtime: Any,
*,
task_id: str | None = None,
wake_on_progress: bool = False,
) -> TaskRecord | str:
"""Start one helper; a string is the reason it could not start."""
task_tool = self.task_tool_for(runtime)
if task_tool is None:
return "Delegation is unavailable in this run; do the work yourself."
subagent_type = EFFORT_TYPES.get(effort)
if subagent_type is None:
return f"Unknown effort {effort!r}; use one of: low, high, xhigh, max."
thread_id = _thread_of(runtime)
if not thread_id:
return "Background tasks need a thread; use task instead."
target = await self.services.attach(runtime)
if target is None:
return "Background tasks need a thread; use task instead."
record = TaskRecord(
id=task_id or tasks.new_id(),
thread_id=thread_id,
effort=effort,
subagent_type=subagent_type,
label=label.strip() or description.strip().splitlines()[0][:60],
wave=wave.strip() or None,
started_at=time.time(),
meta={"wake": target.channel, "wake_on_progress": wake_on_progress},
store=getattr(runtime, "store", None),
)
detached = detached_runtime(runtime, record.id)
await ledger.beat(record)
ledger.ensure_heartbeat()
tasks.launch(
record,
lambda: self._run_helper(record, task_tool, description, detached),
on_end=_ended,
)
if self.services.watchdog is not None:
await self.services.watchdog(target, True)
return record
async def _run_helper(
self, record: TaskRecord, task_tool: Any, description: str, runtime: ToolRuntime
) -> str:
token = var_child_runnable_config.set(runtime.config)
scoped = [(var, var.set(record.id)) for var in (durable.CURRENT_TASK, CURRENT_TASK_ID)]
try:
result = await task_tool.coroutine(
description=description, subagent_type=record.subagent_type, runtime=runtime
)
except asyncio.CancelledError:
# A shutdown or cancel_task: flush what the helper did since its last save, so
# resume_task continues from its latest step. Best effort; the store may be closing.
await durable.save_on_cancel(record.id)
raise
finally:
for var, reset in reversed(scoped):
var.reset(reset)
var_child_runnable_config.reset(token)
return _report(result)
async def run_inline(
self, description: str, effort: str, label: str, wave: str, runtime: Any
) -> HelperResult:
"""Run one helper inside the caller's own task, reporting nothing itself: for code that
reports each step and wakes the lead once (pipelines). Cancelling the caller cancels it."""
subagent_type = EFFORT_TYPES.get(effort)
task_tool = self.task_tool_for(runtime)
if task_tool is None or subagent_type is None:
reason = (
"Delegation is unavailable in this run."
if subagent_type
else f"Unknown effort {effort!r}."
)
return HelperResult("", "failed", error=reason)
record = TaskRecord(
id=tasks.new_id(),
thread_id=_thread_of(runtime),
effort=effort,
subagent_type=subagent_type,
label=label.strip() or description.strip().splitlines()[0][:60],
wave=wave or None,
started_at=time.time(),
store=getattr(runtime, "store", None),
)
current = tasks.CURRENT.set(record)
try:
report = await self._run_helper(
record, task_tool, description, detached_runtime(runtime, record.id)
)
except asyncio.CancelledError:
raise
except Exception as error: # noqa: BLE001 - the pipeline reports it
return HelperResult(
record.id,
"failed",
error=f"It failed with {type(error).__name__}: {str(error)[:300]}. Its files are on disk.",
)
finally:
tasks.CURRENT.reset(current)
return HelperResult(record.id, "done", report)
# -- check-ins, status, cancel, resume ----------------------------------------------------
async def schedule(
self, minutes: int, prompt: str, reason: str, runtime: Any
) -> Command[Any] | str:
if not 1 <= minutes <= 1440:
return "Pick between 1 and 1440 minutes (24 hours)."
target = await self.services.attach(runtime)
if target is None:
return "A check-in needs a thread."
due = datetime.now(UTC) + timedelta(minutes=minutes)
note = f'{CHECK_IN_MARK} reason="{reason.strip()[:120]}">\nThe check-in you scheduled: {prompt.strip()}'
try:
schedule_id = await self.services.waker.schedule(target, due, note)
except Exception as error: # noqa: BLE001 - adapters raise their own types; the text is safe
return f"The check-in could not be scheduled: {str(error)[:200]}"
ev.BUS.publish(
ev.Event(ev.WAKEUP_SET, target.thread_id, schedule_id, label=reason.strip()[:80])
)
message = f"Scheduled {schedule_id} for {due:%H:%M UTC} (in {minutes} min): {reason.strip()}. You will be woken with your note."
return Command(
update={
"messages": [
ToolMessage(message, tool_call_id=getattr(runtime, "tool_call_id", "") or "")
],
"background_check_ins": {
schedule_id: {"due_at": due.isoformat(), "reason": reason.strip()[:120]}
},
}
)
def status(self, runtime: Any, task_id: str) -> str:
thread_id = _thread_of(runtime)
known = dict((getattr(runtime, "state", None) or {}).get("background_tasks") or {})
records = [r for r in REGISTRY.values() if r.thread_id == thread_id]
others = [
line
for provider in notices.RUNNING_PROVIDERS
if provider is not tasks.running_lines
for line in provider(thread_id)
]
if task_id:
for describer in DESCRIBERS:
described = describer(task_id, thread_id)
if described is not None:
return described
match = REGISTRY.get(task_id)
if match is None or match.thread_id != thread_id:
if known.get(task_id, {}).get("status") == "running":
return f"{task_id} was interrupted (a restart ended it); resume it with resume_task."
if task_id in known:
return f"{task_id} {known[task_id].get('status')}; its report was in the wake-up message."
return f"No task {task_id} on this thread."
if match.status == "running":
return f"{task_id} ({match.effort}, {match.label}) has been running for {tasks.minutes(time.time() - match.started_at)}."
return f"{task_id} {match.status}.\n{match.report or match.error}"
if not records and not known and not others:
return "Nothing has run in the background on this thread."
now, lines = time.time(), []
for r in records:
if r.status == "running":
lines.append(
f"- {r.id} ({r.effort}, {r.label}{', wave ' + r.wave if r.wave else ''}): running, {tasks.minutes(now - r.started_at)}"
)
else:
lines.append(
f"- {r.id} ({r.effort}, {r.label}): {r.status}; check_tasks('{r.id}') for its report"
)
for missing in sorted(set(known) - {r.id for r in records}):
entry = known[missing]
if entry.get("status") == "running":
lines.append(
f"- {missing} ({entry.get('label', '')}): interrupted by a restart; resume it with resume_task"
)
else:
lines.append(
f"- {missing} ({entry.get('label', '')}): {entry.get('status')}; its report was in the wake-up message"
)
lines += [f"- {line}" for line in others]
return "\n".join(lines)
async def cancel(self, runtime: Any, task_id: str) -> Command[Any] | str:
thread_id = _thread_of(runtime)
check_ins = dict((getattr(runtime, "state", None) or {}).get("background_check_ins") or {})
if task_id in check_ins:
await self.services.waker.cancel(task_id)
ev.BUS.publish(ev.Event(ev.WAKEUP_CANCELLED, thread_id, task_id))
return f"Cancelled check-in {task_id}."
for canceller in CANCELLERS:
handled = canceller(task_id, thread_id)
if handled is not None:
return handled
return tasks.cancel(task_id, thread_id)
async def resume(self, task_id: str, runtime: Any) -> Command[Any] | str:
for resumer in RESUMERS:
handled = await resumer(task_id, runtime)
if handled is not None:
return handled
record = REGISTRY.get(task_id)
if record is not None and record.status == "running":
return f"{task_id} is still running; it wakes you when it ends."
if not await durable.can_resume(getattr(runtime, "store", None), task_id):
return (
f"No saved transcript for {task_id}. Re-issue it with start_task using the resume "
"brief in the launch-film skill: its files and progress notes are on disk."
)
known = dict((getattr(runtime, "state", None) or {}).get("background_tasks") or {}).get(
task_id, {}
)
effort = str(known.get("effort") or (record.effort if record else "xhigh"))
label = str(known.get("label") or (record.label if record else task_id))
wave = str(known.get("wave") or "")
REGISTRY.pop(task_id, None)
launched = await self.launch(
durable.resume_brief(task_id), effort, label, wave, runtime, task_id=task_id
)
if isinstance(launched, str):
return launched
return Command(
update={
"messages": [
ToolMessage(
f"Resumed {task_id} ({effort}, {label}) from its saved transcript.",
tool_call_id=getattr(runtime, "tool_call_id", "") or "",
)
],
"background_tasks": {launched.id: launched.summary()},
}
)
# -- hooks ----------------------------------------------------------------------------------
async def abefore_agent(self, state: BackgroundState, runtime: Any) -> dict[str, Any] | None:
"""Write what finished since the last run into the thread's state (so after a restart
`check_tasks` tells finished work from interrupted work), and hand the lead what the inbox
held for its next turn, whatever started this one."""
try:
configurable = get_config().get("configurable") or {}
except RuntimeError:
return None
if self.services.on_turn_start is not None:
try:
await self.services.on_turn_start(runtime, list(state.get("messages") or []))
except Exception as error: # noqa: BLE001 - a receipt never blocks the turn
_LOGGER.warning("[background] turn-start hook failed: %s", type(error).__name__)
store = getattr(runtime, "store", None)
if store is not None and is_watchdog_turn(list(state.get("messages") or [])):
# The watchdog fires only when the process that kept postponing it is gone, so what a
# restart killed is told in this turn, which posts anyway.
try:
await self.services.sweep(store)
except Exception as error: # noqa: BLE001 - the regular sweep tries again
_LOGGER.warning("[background] the watchdog sweep failed: %s", type(error).__name__)
else:
self.services.maybe_sweep(store)
thread_id = str(configurable.get("thread_id") or "")
known = dict(state.get("background_tasks") or {})
changed = {
r.id: r.summary()
for r in REGISTRY.values()
if r.thread_id == thread_id and r.id in known and known[r.id] != r.summary()
}
update: dict[str, Any] = {"background_tasks": changed} if changed else {}
held = self.services.inbox.take_held(thread_id) if thread_id else []
if held:
update["messages"] = [HumanMessage(notices.render(thread_id, held, guidance=False))]
await self.services.inbox.delivered(held)
return update or None
async def awrap_model_call(
self,
request: ModelRequest[Any],
handler: Callable[[ModelRequest[Any]], Awaitable[ModelResponse[Any]]],
) -> ModelResponse[Any]:
# The compiled subagents live in the closure of the `task` tool Deep Agents built for this
# run; start_task runs them through it, so it is kept under this run's key. Nothing is
# added to the system prompt: it stays byte-identical while work runs.
for candidate in request.tools or []:
if getattr(candidate, "name", None) == "task":
key = _run_key(_current_config(getattr(request, "runtime", None)))
self._task_tools[key] = candidate
self._task_tools.move_to_end(key)
while len(self._task_tools) > TASK_TOOLS_KEPT:
self._task_tools.popitem(last=False)
return await handler(request)
async def awrap_tool_call(self, request: Any, handler: Callable[[Any], Awaitable[Any]]) -> Any:
call = request.tool_call
if (
call.get("name") == "task"
and (call.get("args") or {}).get("subagent_type") in WORKER_TYPES
):
return ToolMessage(REFUSED_SYNC, tool_call_id=call["id"], status="error")
return await handler(request)
#: Other kinds of background work (watches, pipelines) register how to cancel their ids: each
#: returns a message when it owns the id, None otherwise.
CANCELLERS: list[Callable[[str, str], str | None]] = []
#: ... and how to resume them (`resume_task`).
RESUMERS: list[Callable[[str, Any], Awaitable[str | None]]] = []
#: ... and how to describe one for `check_tasks(id)`.
DESCRIBERS: list[Callable[[str, str], str | None]] = []
@dataclass
class BackgroundHelpers:
"""`HelperRunner` for code that starts helpers itself (pipelines, looks, the post-job review)."""
middleware: BackgroundTaskMiddleware
runtime: Any
#: Run each helper inside the caller's own task and report nothing (pipelines).
inline: bool = False
async def start(
self, brief: str, *, effort: str, label: str = "", wave: str | None = None
) -> str:
launched = await self.middleware.launch(brief, effort, label, wave or "", self.runtime)
if isinstance(launched, str):
raise RuntimeError(launched)
return launched.id
async def run(
self, brief: str, *, effort: str, label: str = "", wave: str | None = None
) -> HelperResult:
if self.inline:
return await self.middleware.run_inline(brief, effort, label, wave or "", self.runtime)
launched = await self.middleware.launch(brief, effort, label, wave or "", self.runtime)
if isinstance(launched, str):
return HelperResult(task_id="", status="failed", error=launched)
if launched.ended is None:
return HelperResult(launched.id, "failed", error="the helper did not start")
record = await asyncio.shield(launched.ended)
return HelperResult(record.id, record.status, record.report, record.error)
async def report_progress(note: str, urgent: bool = False) -> str:
"""Tell the lead how this task is going.
Send one when a section is done, when something blocks you or moves your ETA, and before you
stop early: one or two sentences on what happened and what comes next, with a time. It reaches
the lead with its next turn. Set `urgent` only when the lead must act now: you are blocked on a
decision, or the plan no longer works.
"""
record = tasks.CURRENT.get()
if record is None:
return "This is not a background task; put it in your final report instead."
tasks.note(record, note.strip()[:600], urgent=urgent)
return "Sent to the lead."
class WorkerProgressMiddleware(AgentMiddleware[Any, Any, Any]):
"""Gives a helper `report_progress`, so the lead hears more than its final report."""
def __init__(self) -> None:
super().__init__()
self.tools = [
StructuredTool.from_function(coroutine=report_progress, name="report_progress")
]
@property
def name(self) -> str:
return "DesignAgentWorkerProgress"
def helper_store() -> Any:
"""The store of the helper whose code is running, for its transcript (`harness.durable`)."""
record = tasks.CURRENT.get()
return record.store if record is not None else None