hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/team/__init__.py

@@ -0,0 +1,28 @@
+"""
+The team of agents (HC-038, rc5).
+
+The person's named agent is the LEAD and the only one they talk to. It plans,
+hands work to specialists through ONE dispatcher (``team.dispatcher``), runs
+them in parallel (at most three at once, each with a time limit) and reports
+back in its own voice, naming who did what and which parts failed.
+
+- ``roster``     the starter team (Inbox, Calendar, Slack, Research, Writer,
+                 Repos when GitLab is connected), each with only the tools its
+                 role needs; renamed or switched off in config / ``/team``.
+- ``dispatcher`` the one dispatcher: concurrency cap, time limits, the
+                 team-wide cost caps (one cost-guard task spans the lead and
+                 its specialists), no specialist can start a specialist,
+                 failures reported as failures.
+- ``specialist`` one specialist's run: its own tool list, the same registry
+                 and approval queue as the owner's chats (every send / post /
+                 write / spend waits for Send / Edit / Cancel, labelled with
+                 the agent's name), the truth guard, repeat guard and retry
+                 budgets inside every run.
+- ``model``      the model handle a specialist talks to (explicit max output
+                 on every call; cost-guarded clients only).
+- ``status``     ``/team``: who's doing what, today's spend, stop / pause /
+                 resume, rename / on / off.
+- ``watchers``   owner-only watcher alerts in one fixed format.
+- ``morning``    the morning brief sections from whichever connectors exist.
+- ``genesis``    new specialists are proposals only; nothing activates itself.
+"""

hyperclaw/team/dispatcher.py

@@ -0,0 +1,431 @@
+"""
+The one dispatcher.
+
+Every hand-off from the lead (or from a scheduled job) to a specialist goes
+through ``Dispatcher.run``. The legacy swarm entry points
+(``hyperclaw.swarm.Swarm.dispatch`` / ``dispatch_parallel`` / ``all_hands``)
+call it too; there is no second route.
+
+Rules it enforces:
+
+- **Specialists can't start specialists.** A run started from inside a
+  specialist (any thread or task that carries its context) is refused, and a
+  requester of the form "agent:<id>" is refused as well.
+- **At most three run at once** (process-wide), **each with a time limit**.
+  A specialist still running at its limit is cancelled: it makes no further
+  model or tool call, its slot is freed, and it is reported as timed out
+  while the others carry on.
+- **One task id spans the lead and its specialists.** The run happens inside
+  the caller's cost-guard task (or a new one), and every specialist thread
+  carries that context, so the $2 per-task and $10 per-day caps cover the
+  whole team; each model call is reserved before it is made.
+- **Failures are failures.** An unknown or switched-off agent, a timeout, a
+  stop, a cost-cap stop or a fabricated claim is a failed job in the report,
+  with the reason, never a smoothed-over answer.
+- **Pause / stop.** ``pause()`` refuses new runs until ``resume()``;
+  ``stop()`` cancels every running specialist.
+
+``live()`` is what ``/team`` shows: who is doing what, since when.
+"""
+from __future__ import annotations
+
+import contextvars
+import logging
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Callable, Dict, Iterable, List, Optional, Sequence
+
+from hyperclaw.team import roster as roster_mod
+from hyperclaw.team.roster import Specialist
+from hyperclaw.team.specialist import (DONE, FAILED, REFUSED, STOPPED, TIMED_OUT, JobResult,
+                                       SpecialistRun)
+
+log = logging.getLogger("hyperclaw.team.dispatcher")
+
+# Set inside every specialist run: a dispatch from here is refused.
+_IN_SPECIALIST: contextvars.ContextVar = contextvars.ContextVar("hyperclaw_team_specialist",
+                                                                default=None)
+
+
+def in_specialist() -> Optional[str]:
+    return _IN_SPECIALIST.get()
+
+
+@dataclass
+class Job:
+    agent: str           # id or display name
+    task: str
+
+
+@dataclass
+class TeamReport:
+    task_id: str
+    results: List[JobResult] = field(default_factory=list)
+    refused: str = ""     # the whole run was refused (paused, nested, ...)
+
+    @property
+    def ok(self) -> bool:
+        return not self.refused and all(r.ok for r in self.results)
+
+    @property
+    def origins(self) -> set:
+        out = set()
+        for r in self.results:
+            out |= r.origins
+        return out
+
+    @property
+    def approvals(self) -> List[str]:
+        return [a for r in self.results for a in r.approvals]
+
+    def text(self) -> str:
+        """The plain report the lead turns into its own answer: who did what,
+        and which parts failed, word for word."""
+        if self.refused:
+            return f"The team did not run: {self.refused}"
+        lines = []
+        for r in self.results:
+            if r.ok:
+                lines.append(f"[{r.agent_name}] {r.text}")
+            else:
+                what = {TIMED_OUT: "TIMED OUT", STOPPED: "STOPPED", REFUSED: "REFUSED"}.get(
+                    r.status, "FAILED")
+                lines.append(f"[{r.agent_name}] {what}: {r.error or 'no reason recorded'}")
+            if r.approvals:
+                lines.append(f"[{r.agent_name}] waiting for the person's approval: "
+                             f"{', '.join(r.approvals)} (nothing was sent or changed)")
+        return "\n".join(lines) or "No specialist ran."
+
+
+@dataclass
+class _Live:
+    task_id: str
+    agent_id: str
+    agent_name: str
+    task: str
+    started: float
+    cancel: threading.Event
+    state: str = "waiting"          # waiting | running
+
+
+class Dispatcher:
+    def __init__(self, *, handle_factory: Optional[Callable] = None, registry=None,
+                 max_concurrent: Optional[int] = None, time_limit_s: Optional[float] = None,
+                 team: Optional[Dict[str, Specialist]] = None, lead_name: str = ""):
+        self._handle_factory = handle_factory
+        self._registry = registry
+        self._max = max_concurrent
+        self._limit = time_limit_s
+        self._team = team
+        self.lead_name = lead_name
+        self._slots_lock = threading.Lock()
+        self._slots: Optional[threading.BoundedSemaphore] = None
+        self._slots_n = 0
+        self._paused = False
+        self._live: Dict[str, _Live] = {}
+        self._live_lock = threading.Lock()
+
+    # ── settings ──
+    @property
+    def max_concurrent(self) -> int:
+        n = self._max if self._max is not None else roster_mod.max_concurrent()
+        return max(1, min(roster_mod.MAX_CONCURRENT, int(n)))
+
+    @property
+    def time_limit_s(self) -> float:
+        return float(self._limit if self._limit is not None else roster_mod.time_limit_s())
+
+    def team(self) -> Dict[str, Specialist]:
+        return dict(self._team) if self._team is not None else roster_mod.roster()
+
+    def registry(self):
+        if self._registry is None:
+            from hyperclaw import tui
+            self._registry = tui.REGISTRY
+        return self._registry
+
+    def handle_factory(self):
+        if self._handle_factory is None:
+            from hyperclaw.team.model import default_handle
+            return default_handle
+        return self._handle_factory
+
+    def _semaphore(self) -> threading.BoundedSemaphore:
+        n = self.max_concurrent
+        with self._slots_lock:
+            if self._slots is None or self._slots_n != n:
+                if self._slots is not None and self.running_count():
+                    return self._slots      # never swap the semaphore under running jobs
+                self._slots = threading.BoundedSemaphore(n)
+                self._slots_n = n
+            return self._slots
+
+    # ── control ──
+    def pause(self) -> None:
+        self._paused = True
+
+    def resume(self) -> None:
+        self._paused = False
+
+    @property
+    def paused(self) -> bool:
+        return self._paused
+
+    def stop(self) -> int:
+        """Cancel every running or waiting specialist. Returns how many."""
+        with self._live_lock:
+            items = list(self._live.values())
+        for it in items:
+            it.cancel.set()
+        return len(items)
+
+    def live(self) -> List[_Live]:
+        with self._live_lock:
+            return sorted(self._live.values(), key=lambda x: x.started)
+
+    def running_count(self) -> int:
+        with self._live_lock:
+            return sum(1 for x in self._live.values() if x.state == "running")
+
+    # ── the one route ──
+    def run(self, jobs: Sequence[Job], *, provenance: Iterable[str] = (),
+            requester: str = "owner", surface: str = "chat", request: str = "",
+            conversation: str = "") -> TeamReport:
+        """Run the jobs (in parallel, at most max_concurrent at once) and
+        return the report. Never raises for a job's failure."""
+        from hyperclaw import cost_guard
+        nested = in_specialist()
+        if nested or str(requester or "").startswith("agent:"):
+            who = nested or str(requester).split(":", 1)[1]
+            return TeamReport("", refused=f"specialists can't start specialists ({who} "
+                                          f"tried to).")
+        if self._paused:
+            return TeamReport("", refused="the team is paused (/team resume to continue).")
+        with cost_guard.task(surface=surface, request=request or "team",
+                             conversation=conversation) as t:
+            report = TeamReport(t.id)
+            team = self.team()
+            slots: List[object] = []
+            runnable = []
+            for j in jobs:
+                res = self._precheck(j, team)
+                if isinstance(res, JobResult):
+                    slots.append(res)
+                else:
+                    slots.append(len(runnable))
+                    runnable.append((j, res))
+            prov = [p for p in (provenance or ()) if isinstance(p, str)]
+            workers = []
+            for j, spec in runnable:
+                cancel = threading.Event()
+                live = _Live(t.id, spec.id, spec.name, j.task, time.time(), cancel)
+                key = f"{t.id}:{spec.id}:{uuid.uuid4().hex[:6]}"
+                run = SpecialistRun(spec, j.task, handle_factory=self.handle_factory(),
+                                    registry=self.registry(), provenance=prov,
+                                    conversation=f"team:{t.id}:{spec.id}", cancel=cancel,
+                                    lead_name=self.lead_name)
+                workers.append(_Worker(self, key, live, run, contextvars.copy_context()))
+            for w in workers:
+                w.start()
+            for w in workers:
+                w.wait()
+            # Snapshots: a specialist cancelled at its limit may still be
+            # finishing a call on its thread; the report never changes after.
+            for s in slots:
+                report.results.append(s if isinstance(s, JobResult) else workers[s].snapshot)
+            return report
+
+    def _precheck(self, j: Job, team: Dict[str, Specialist]):
+        try:
+            spec = roster_mod.resolve(j.agent, team)
+        except roster_mod.RosterError as e:
+            return JobResult(str(j.agent), str(j.agent), j.task, status=FAILED, error=str(e))
+        if not spec.enabled:
+            return JobResult(spec.id, spec.name, j.task, status=REFUSED,
+                             error=f"{spec.name} is switched off (/team on {spec.name}).")
+        if not (j.task or "").strip():
+            return JobResult(spec.id, spec.name, j.task, status=FAILED,
+                             error="no task was given.")
+        return spec
+
+    def run_callables(self, jobs: Sequence[tuple], *, surface: str = "swarm",
+                      request: str = "", requester: str = "owner") -> List[JobResult]:
+        """The legacy swarm's route (``hyperclaw.swarm``): each job is
+        (agent_id, agent_name, task, fn) where fn() returns the agent's text
+        or raises. Same rules as ``run``: no nesting, pause, at most three at
+        once, time limits, one cost-guard task, failures as failures."""
+        from hyperclaw import cost_guard
+        nested = in_specialist()
+        if nested or str(requester or "").startswith("agent:"):
+            return [JobResult(j[0], j[1], j[2], status=REFUSED,
+                              error="specialists can't start specialists.") for j in jobs]
+        if self._paused:
+            return [JobResult(j[0], j[1], j[2], status=REFUSED,
+                              error="the team is paused (/team resume to continue).")
+                    for j in jobs]
+        with cost_guard.task(surface=surface, request=request or "team") as t:
+            workers = []
+            for aid, name, task, fn in jobs:
+                cancel = threading.Event()
+                live = _Live(t.id, aid, name, task, time.time(), cancel)
+                key = f"{t.id}:{aid}:{uuid.uuid4().hex[:6]}"
+                workers.append(_Worker(self, key, live, _CallableRun(aid, name, task, fn, cancel),
+                                       contextvars.copy_context()))
+            for w in workers:
+                w.start()
+            for w in workers:
+                w.wait()
+            return [w.snapshot for w in workers]
+
+    async def arun(self, jobs: Sequence[Job], **kw) -> TeamReport:
+        import asyncio
+        return await asyncio.to_thread(self.run, jobs, **kw)
+
+    # ── bookkeeping for workers ──
+    def _register(self, key: str, live: _Live) -> None:
+        with self._live_lock:
+            self._live[key] = live
+
+    def _unregister(self, key: str) -> None:
+        with self._live_lock:
+            self._live.pop(key, None)
+
+
+class _CallableRun:
+    """A legacy swarm agent's run under the dispatcher's rules."""
+
+    def __init__(self, aid: str, name: str, task: str, fn: Callable[[], str],
+                 cancel: threading.Event):
+        self.result = JobResult(aid, name, task)
+        self.fn = fn
+        self.cancel = cancel
+
+    def run(self) -> JobResult:
+        from hyperclaw.cost_guard import CostCapReached
+        r = self.result
+        r.started = time.time()
+        try:
+            text = self.fn()
+            if self.cancel.is_set():
+                r.status = STOPPED
+            elif not (text or "").strip():
+                r.status, r.error = FAILED, "it returned no answer"
+            else:
+                r.text = text
+        except CostCapReached as e:
+            r.status, r.error = FAILED, e.headline()
+        except Exception as e:
+            log.warning("swarm agent %s failed: %s", r.agent_id, type(e).__name__,
+                        exc_info=True)
+            r.status, r.error = FAILED, f"it stopped with an internal error ({type(e).__name__})"
+        finally:
+            r.finished = time.time()
+        return r
+
+
+class _Worker:
+    """One specialist on its own daemon thread, under a slot and a deadline."""
+
+    def __init__(self, d: Dispatcher, key: str, live: _Live, run,
+                 ctx: contextvars.Context):
+        self.d, self.key, self.live, self.run, self.ctx = d, key, live, run, ctx
+        self.done = threading.Event()
+        self.started = threading.Event()
+        self.snapshot: Optional[JobResult] = None
+        self._released = False
+        self._rel_lock = threading.Lock()
+        self.sem = d._semaphore()
+        self.thread = threading.Thread(target=self._main, daemon=True,
+                                       name=f"hyperclaw-team-{live.agent_id}")
+
+    def start(self) -> None:
+        self.d._register(self.key, self.live)
+        self.thread.start()
+
+    def _release(self) -> None:
+        with self._rel_lock:
+            if not self._released:
+                self._released = True
+                self.sem.release()
+
+    def _main(self) -> None:
+        self.ctx.run(self._body)
+
+    def _body(self) -> None:
+        r = self.run.result
+        token = _IN_SPECIALIST.set(self.live.agent_id)
+        acquired = False
+        try:
+            while not acquired:
+                if self.live.cancel.is_set():
+                    r.status, r.error = STOPPED, "it was stopped before it started."
+                    return
+                acquired = self.sem.acquire(timeout=0.05)
+            self.live.state = "running"
+            self.live.started = time.time()
+            self.started.set()
+            self.run.run()
+        finally:
+            if acquired:
+                self._release()
+            _IN_SPECIALIST.reset(token)
+            self.done.set()
+            self.started.set()
+
+    def wait(self) -> None:
+        """Wait for the run, up to its time limit once it is running."""
+        limit = self.d.time_limit_s
+        r = self.run.result
+        try:
+            self.started.wait()
+            deadline = self.live.started + limit
+            while not self.done.is_set():
+                left = deadline - time.time()
+                if left <= 0:
+                    self.live.cancel.set()
+                    r.status = TIMED_OUT
+                    r.error = f"it did not finish within its {limit:g}-second limit."
+                    r.finished = time.time()
+                    self.snapshot = _copy(r)
+                    self._release()        # its slot is free; it can't make another call
+                    return
+                self.done.wait(min(left, 0.25))
+            if self.live.cancel.is_set() and r.status == DONE:
+                r.status = STOPPED
+                r.error = r.error or "it was stopped (/team stop)."
+            if r.status == STOPPED and not r.error:
+                r.error = "it was stopped (/team stop)."
+            self.snapshot = _copy(r)
+        finally:
+            if self.snapshot is None:
+                self.snapshot = _copy(r)
+            self.d._unregister(self.key)
+
+
+def _copy(r: JobResult) -> JobResult:
+    from dataclasses import replace
+    return replace(r, tools=[dict(x) for x in r.tools], approvals=list(r.approvals),
+                   origins=set(r.origins))
+
+
+# ───────────────────────── the process-wide dispatcher ─────────────────────────
+
+_DISPATCHER: Optional[Dispatcher] = None
+_D_LOCK = threading.Lock()
+
+
+def get_dispatcher() -> Dispatcher:
+    global _DISPATCHER
+    with _D_LOCK:
+        if _DISPATCHER is None:
+            _DISPATCHER = Dispatcher()
+        return _DISPATCHER
+
+
+def set_dispatcher(d: Optional[Dispatcher]) -> None:
+    """Tests and embedders: replace the process-wide dispatcher."""
+    global _DISPATCHER
+    with _D_LOCK:
+        _DISPATCHER = d

hyperclaw/team/genesis.py

@@ -0,0 +1,106 @@
+"""
+GENESIS for the team: new specialists are PROPOSALS only (rc5).
+
+A proposal is a readable package (purpose, instructions, the smallest tool
+list, model tier, a cost note, example tasks, and the evidence that it is
+needed). It is stored for the owner to read under ``/team proposals``.
+
+Nothing here activates anything: there is no activation path in this
+release, a proposal never changes the roster, and a proposal that asks for a
+send, post, write or spend tool is refused unless the owner asked for it in
+their own words (``owner_asked_for_writes``), and even then it stays a
+proposal. Activation, dry runs and versioning are later work (spec §4).
+"""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+PROPOSED = "proposed"
+DECLINED = "declined"
+
+
+@dataclass
+class Proposal:
+    name: str
+    purpose: str
+    instructions: str
+    tools: List[str]
+    tier: str = "fast"
+    cost_note: str = ""
+    examples: List[str] = field(default_factory=list)
+    evidence: str = ""
+    id: str = ""
+    created: float = 0.0
+    status: str = PROPOSED
+
+
+def _path() -> Path:
+    root = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw")).expanduser()
+    return root / "team" / "proposals.json"
+
+
+def load() -> List[Proposal]:
+    try:
+        data = json.loads(_path().read_text(encoding="utf-8"))
+        return [Proposal(**p) for p in data if isinstance(p, dict)]
+    except (OSError, ValueError, TypeError):
+        return []
+
+
+def _save(items: List[Proposal]) -> None:
+    p = _path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(".tmp")
+    tmp.write_text(json.dumps([asdict(i) for i in items], indent=2), encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, p)
+
+
+class ProposalError(ValueError):
+    pass
+
+
+def propose(name: str, purpose: str, instructions: str, tools: List[str], *,
+            evidence: str, examples: Optional[List[str]] = None, tier: str = "fast",
+            owner_asked_for_writes: bool = False, registry=None) -> Proposal:
+    """Store a proposal. Raises ProposalError for an unknown tool, a missing
+    evidence line, or a send/write tool the owner did not ask for."""
+    if not (evidence or "").strip():
+        raise ProposalError("a proposal needs evidence (what was asked, how often)")
+    if registry is None:
+        from hyperclaw import tui
+        registry = tui.REGISTRY
+    for t in tools:
+        spec = registry.get(t)
+        if spec is None:
+            raise ProposalError(f"unknown tool {t}")
+        if spec.effect != "read" and not owner_asked_for_writes:
+            raise ProposalError(f"{t} can {spec.effect}; a proposal gets no send or write tool "
+                                f"unless the person asks for it")
+        if t in ("team_delegate", "agent_start", "agent_stop", "agent_watch"):
+            raise ProposalError(f"{t} is the lead's alone; a specialist cannot have it")
+    p = Proposal(name=name.strip(), purpose=purpose.strip(), instructions=instructions.strip(),
+                 tools=list(tools), tier=tier, examples=list(examples or [])[:5],
+                 evidence=evidence.strip(), id=secrets.token_hex(4), created=time.time(),
+                 cost_note=f"model tier {tier}; runs under the same per-task and daily caps")
+    items = load()
+    items.append(p)
+    _save(items)
+    return p
+
+
+def render_pending() -> str:
+    items = [p for p in load() if p.status == PROPOSED]
+    if not items:
+        return "No proposed specialists."
+    lines = ["Proposed specialists (proposals only: none of these is on your team):"]
+    for p in items:
+        lines.append(f"- [{p.id}] {p.name}: {p.purpose} Tools: {', '.join(p.tools) or 'none'}. "
+                     f"Why: {p.evidence}")
+    return "\n".join(lines)

hyperclaw/team/lead.py

@@ -0,0 +1,110 @@
+"""
+The lead's side of the team: the ``team_delegate`` tool.
+
+Only the lead (the person's named agent, in the owner's own chats) has this
+tool. It is never offered on the specialists' surface ("swarm"), never to a
+guest chat, and the dispatcher refuses it from inside a specialist.
+
+The lead's own words (the turn guard's provenance) are handed to the
+specialists as THEIR provenance: a specialist can fetch an address only if
+it is verbatim in what the person wrote, and can never widen what the lead
+may do. The specialists' report comes back as data for the lead to answer
+from in its own voice, naming who did what and which parts failed.
+
+Connector content the specialists read (email, calendar, web, GitLab) is
+recorded against the lead's conversation as connector content, per message
+(``hyperclaw.taint``): the report cannot be saved to memory or learning as if
+it were the person's own words.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, List
+
+MAX_ASSIGNMENTS = 6
+
+LEAD_NOTE = (
+    "Answer the person in your own voice from this report. Say which specialist did each "
+    "part. Anything marked FAILED, TIMED OUT, STOPPED or REFUSED did not happen: say so "
+    "plainly. Anything waiting for approval has NOT been sent or changed.")
+
+TOOL_SCHEMA = {
+    "name": "team_delegate",
+    "description": (
+        "Hand work to specialists on your team and get their report back. They run in "
+        "parallel (at most three at once, each with a time limit) under the same cost caps as "
+        "you. Each specialist has only its own tools; anything it would send, post or write "
+        "waits for the person's approval. Use for independent parts of a request "
+        "(e.g. inbox + calendar + research). Agents: inbox, calendar, slack, research, writer, "
+        "repos (when GitLab is connected), or their names on this person's team."),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "assignments": {
+                "type": "array",
+                "description": "One entry per specialist: who and exactly what to do.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "agent": {"type": "string", "description": "Specialist id or name"},
+                        "task": {"type": "string",
+                                 "description": "The complete task for that specialist"},
+                    },
+                    "required": ["agent", "task"],
+                },
+            },
+        },
+        "required": ["assignments"],
+    },
+}
+
+
+def _assignments(args: dict) -> List[Any]:
+    from hyperclaw.team.dispatcher import Job
+    raw = args.get("assignments")
+    if isinstance(raw, str):
+        try:
+            raw = json.loads(raw)
+        except ValueError:
+            raw = None
+    if not isinstance(raw, list) or not raw:
+        raise ValueError("assignments must be a non-empty list of {agent, task}")
+    if len(raw) > MAX_ASSIGNMENTS:
+        raise ValueError(f"at most {MAX_ASSIGNMENTS} assignments at a time")
+    out = []
+    for a in raw:
+        if not isinstance(a, dict):
+            raise ValueError("each assignment is {agent, task}")
+        out.append(Job(str(a.get("agent") or ""), str(a.get("task") or "")))
+    return out
+
+
+def delegate(args: dict, *, dispatcher=None) -> str:
+    """The team_delegate tool body. Returns the report text (or an error line)."""
+    from hyperclaw import taint
+    from hyperclaw.team.dispatcher import get_dispatcher
+    from hyperclaw.tools.registry import active_guard
+    try:
+        jobs = _assignments(args or {})
+    except ValueError as e:
+        return f"Error: {e}"
+    guard = active_guard()
+    provenance = list(getattr(guard, "provenance", None) or [])
+    requester = getattr(guard, "requester", "owner")
+    conversation = getattr(guard, "conversation", "") or ""
+    d = dispatcher or get_dispatcher()
+    try:
+        from hyperclaw.naming import current_name   # the lead's display name, if set
+        d.lead_name = d.lead_name or current_name()
+    except Exception:
+        pass
+    rep = d.run(jobs, provenance=provenance, requester=requester,
+                surface=getattr(guard, "surface", "chat") or "chat",
+                request="; ".join(j.task for j in jobs)[:500], conversation=conversation)
+    if rep.refused:
+        return f"Error: the team did not run: {rep.refused}"
+    text = rep.text() + "\n\n" + LEAD_NOTE
+    if rep.origins and conversation:
+        for origin in sorted(rep.origins):
+            taint.mark(rep.text(), origin, "team_delegate", session=conversation)
+    return text